Site Engine
Движок сайтов на Markdown + YAML: страницы собираются из layouts и fragments, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3).
Документы проекта лежат в docs/: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений.
Быстрый старт
pip install -e ".[dev]" # ядру нужны jinja2, PyYAML, markdown-it-py, click
site-engine validate examples/studio-site
site-engine build examples/studio-site --out /tmp/studio-dist
site-engine preview examples/studio-site drafts/next > /tmp/draft.html
site-engine fragments # 15 встроенных фрагментов
make test # или: pytest
Результат сборки: OUT/<build_id>/ и симлинк OUT/current, который переключается атомарно. Неудачная сборка current не трогает.
Структура проекта
site-engine/
├── pyproject.toml # зависимости ядра и extras: server, mcp, images, dev
├── Makefile Dockerfile # Dockerfile — для M2+ (админка, формы, MCP)
├── docs/ # ТЗ, ревью, журнал решений
├── examples/studio-site/ # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
├── .env.example # переменные окружения для админки
├── tests/ # 178 тестов: ядро, сборка, безопасность, запись, вход и редактор
└── src/site_engine/
├── cli.py # validate · build · preview · fragments
├── errors.py # Issue/Report: код, путь к полю, серьёзность, подсказка
├── core/
│ ├── values.py # Literal | Binding | LinkRef | Query (ADR-002)
│ ├── models.py # Block, Page, Entry, Fragment, Layout, Collection…
│ ├── registry.py # чистая загрузка каталога сайта в память (ADR-001)
│ ├── routes.py # нормализация маршрутов, таблица, коллизии
│ ├── resolve.py # привязки, ссылки, запросы MVP
│ ├── validate.py # workspace-проверки, release-проверки, правила сайта
│ ├── draft_check.py # проверка при сохранении: новый текст файла против реестра
│ ├── page_ops.py # добавить, переместить, удалить блок по id в сыром front matter
│ └── render.py # Jinja SandboxedEnvironment, разрешение props по схеме
├── build/pipeline.py # load → validate → render → релиз → атомарный current
├── parsing/ # безопасный YAML, front matter, Markdown (raw HTML выключен)
├── storage/ # safe_join, atomic_write, SiteLock, .engine/history
├── services/ # auth (вход админа), ContentService (if_match, история), publish; stubs: changeset, forms
├── builtin/ # base.css и 15 фрагментов ядра (ADR-006)
├── db/ # SQLAlchemy-модели служебных таблиц (M2)
├── web/ # FastAPI-фабрика; admin/: handlers (вход, обзор), editor (страницы, блоки, записи, публикация), forms, шаблоны, routes-адаптер
└── mcp/ # перечень инструментов MVP (M3)
Вход в админку
Самый простой вариант: один администратор, без ролей, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.
site-engine hash-password # спросит пароль (от 12 символов) и напечатает scrypt-хеш
site-engine gen-secret # ключ подписи сессий
cp .env.example .env # впишите SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY
SITE_COOKIE_SECURE=0 uvicorn site_engine.web.app:create_app --factory --env-file .env # локально по http
Без SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY (не короче 32 символов) /admin/ не включается вообще: нет пароля — нет входа. После входа /admin/ показывает страницы сайта со статусами, коллекции и результат проверки (только чтение; редактор — следующий шаг).
| Мера | Как сделано |
|---|---|
| Пароль | scrypt (N=2^15, r=8, p=1), соль на каждый хеш, сравнение за постоянное время |
| Сессия | Подписанная cookie se_session: HttpOnly, SameSite=Strict, Secure (выключается только SITE_COOKIE_SECURE=0), Path=/admin, срок SITE_SESSION_HOURS (по умолчанию 8) |
| Выход | Увеличивает «эпоху» в .engine/auth_epoch: все выданные cookie сразу недействительны, в том числе украденные |
| Перебор | 5 неудач за 15 минут блокируют IP (429 + Retry-After), общий порог 30 на все адреса; хеш считается и при неверном логине, поэтому по времени логин не угадать |
| CSRF | POST принимается только с Origin или Referer того же хоста; выход дополнительно требует токен, привязанный к сессии |
| Заголовки | CSP без inline, frame-ancestors 'none', no-store, X-Frame-Options: DENY, nosniff |
| Аудит | .engine/audit.jsonl: вход, неудача, блокировка, выход; без паролей и без введённого логина |
Ограничения этого варианта:
- Один пользователь, роль всегда
admin; таблицыusersиapi_tokensизdb/models.pyпока не используются. - Окно попыток хранится в памяти процесса: при нескольких воркерах у каждого свой счётчик, после перезапуска он обнуляется.
- За обратным прокси
request.client.host— адрес прокси, поэтому ограничение по IP работает как общее. Доверие кX-Forwarded-Forнужно включать явно (задача M2). - Выход завершает все сессии администратора сразу, отдельного списка устройств нет.
- Отдельная смена пароля: сгенерировать новый хеш и перезапустить сервис; чтобы разлогинить всех, поменяйте
SITE_SECRET_KEY.
Редактор
После входа в /admin/ доступны страницы, контент и публикация. Все правки идут через ContentService: блокировка сайта, if_match по хешу файла, проверка синтаксиса, история в .engine/history/, атомарная запись. Редактор пишет только в pages/ и content/; фрагменты, layouts, схемы и site.yaml через него изменить нельзя.
| Экран | Что умеет |
|---|---|
| Страницы | Список со статусами и адресами; создание черновика (путь, заголовок, layout) |
| Страница | Заголовок, статус, layout, адрес, описание, текст Markdown; блоки по регионам и слотам: добавить, ↑/↓, скрыть и показать, удалить; предпросмотр в изолированном фрейме; список проблем страницы |
| Блок | Форма строится из манифеста фрагмента: текст, Markdown, число, список, группа, выбор, ссылка (страница, запись, адрес), запрос к коллекции, ассет; у каждого поля поле «привязка» (entry.title, page.body…); якорь, заметка, скрыть, requires по флагам сайта |
| Контент | Записи коллекций: поля по схеме, статус, текст Markdown, создание черновика, предпросмотр |
| Публикация | Сборка релиза, список релизов, возврат к прежнему релизу |
Гарантии, которые проверены тестами:
- Без потерь. Форма открывается из файла и отправляется обратно без изменений: у каждого блока примера, всех страниц и записей YAML остаётся тем же по смыслу. Неизвестные ключи не пропадают, привязки сохраняются.
- Конфликты. Если файл изменили в другом окне, правка получит 409, а чужие изменения не будут перезаписаны.
- Проверка при сохранении. Нельзя сохранить неизвестный фрагмент, несуществующий layout, блок в закреплённый регион, значение не того типа,
{{ }}в данных, привязку к чужому корню. Пропуск обязательного поля не блокирует сохранение (ADR-003), но он виден в «Проверке страницы», и сборка релиза с ним не пройдёт; опубликованный сайт при этом не меняется. - Безопасность. Каждый POST требует CSRF-токен и Origin своего хоста; id страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; предпросмотр отдаётся в
sandbox-фрейме с CSP без скриптов; в аудит попадают id и тип действия, но не содержимое.
Что работает иначе, чем можно ожидать:
- Без JS. Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. Скачать htmx и SortableJS в окружении без сети было нельзя, поэтому редактор целиком работает на обычных формах. Если положить
htmx.min.jsвsrc/site_engine/web/admin/static/, админка включитhx-boostсама (проверено только разметкой, с настоящим htmx не запускалось). - Первая правка файла переформатирует его YAML в блочный стиль:
{id: b_1, fragment: hero}станет несколькими строками. Смысл и порядок ключей сохраняются. - Ассеты выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
- Блоки не переносятся между регионами, только внутри своего списка.
- Запись коллекции со «лишним» ключом, которого нет в схеме, нельзя сохранить в статусе
published, пока ключ не уберут из файла: так требует ADR-003.
Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (services/publish.py), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), вход одного администратора с аудитом входов и обзорная страница админки. Нет: роли, приём заявок, outbox, аудит правок |
| M3 MCP и редактор | Готово: редактор страниц, блоков и записей на ContentService, предпросмотр, публикация и откат из админки. Нет: patch_page, changeset (rename, delete), MCP-сервера, перетаскивания, загрузки файлов |
| M4 | Не начат |
Что проверено, а что нет
Тесты и сборка примера выполнялись в окружении без сети: ядро (core/, build/, parsing/, storage/, services/) и вся логика админки (web/admin/handlers.py, editor.py, forms.py, шаблоны, вход, CSRF, заголовки) запущены и покрыты 178 тестами, включая сквозные через HTML-формы. Тонкий FastAPI-адаптер web/admin/routes.py проверен на подставном модуле fastapi, а web/app.py, db/, mcp/ и Dockerfile только компиляцией и чтением: FastAPI, SQLAlchemy и MCP SDK в окружении не было. Ядро намеренно не зависит от pydantic: ошибки должны нести путь к полю (pages/index.md:regions.main[b_hero].props.title), а валидация задаётся манифестами фрагментов. Pydantic нужен на границах API (web, mcp).
Соответствие журналу решений
| Решение | Где в коде |
|---|---|
| ADR-001: сборка не читает SQLite | core/registry.load_site, build/pipeline.build_site |
ADR-002: 4 вида значений, bind, запросы MVP |
core/values.py, core/resolve.py; {{ }} в данных запрещены (validate.py) |
| ADR-003: draft / release / live, версия формы в релизе | validate_workspace vs validate_release, _forms/<id>@<версия>.json, switch_current |
ADR-004: if_match, блокировка сайта, история |
services/content.py, storage/locks.py, storage/history.py |
| ADR-005: границы доверия | SandboxedEnvironment, Markdown без raw HTML, safe_join, токены темы, YAML без алиасов |
ADR-006: 15 фрагментов, editorial, requires только feature.* |
builtin/fragments/, models.Page.editorial, render._feature_on |
Как расширять
- Новый фрагмент: папка
fragments/<имя>/сайта сfragment.yaml,template.html.j2, необязательнымstyle.css.idплоский и уникальный, затенение встроенных запрещено. - Новая коллекция:
collections/<id>.yaml, записи вcontent/<id>/*.md, при необходимостиdisplay/<id>.yaml. - Новое правило сайта: запись в
site.yaml: rules(сейчасrequire_fragmentдля коллекции иrequire_fieldдля форм).
Известные ограничения M0
- Поле
propsв шаблоне — объектProps:props.itemsчитает поле «items», а не метод словаря. layout.extendsпроверяется на существование, наследование шаблонов делается обычным{% extends 'layout/<id>' %}.- CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет.
- Нет приёма заявок и MCP: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006). Вход, аудит правок и редактор уже есть; роли и приём заявок остаются на M2.