Return structured JSON errors with request IDs, log unexpected exceptions with tracebacks, and show HTTP and network failures in the admin UI without losing unsaved source. Preserve publication errors when release listing also fails, handle cancelled preview promises, and add regression tests, browser failure scenarios, and updated API documentation.
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 не трогает.
Расширенный пример для проверки перед возможным переносом сайта — examples/ai-studio, также на схеме версии 1: услуги, сценарии, кейсы, обложки, связи и понятные схемы полей. Проверка: site-engine validate examples/ai-studio, сборка: site-engine build examples/ai-studio --out /tmp/ai-studio-dist, браузерная приёмка: PYTHONPATH=src python scripts/qa_ai_studio.py. studio-site остаётся базовой фикстурой; отдельный запуск нового примера описан в его README.
Структура проекта
site-engine/
├── pyproject.toml # зависимости ядра и extras: server, mcp, images, dev
├── Makefile Dockerfile # Dockerfile — для M2+ (админка, формы, MCP)
├── docs/ # ТЗ, ревью, журнал решений
├── examples/studio-site/ # сайт-пример из SiteMap.md (услуги, формы, коллекция, редирект)
├── .env.example # переменные окружения для админки
├── tests/ # 206 тестов: ядро, сборка, безопасность, запись, вход и редактор
└── 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)
Запуск в Docker
Один том /data, в нём три каталога. Всё, что важно сохранить, лежит на хосте в ./data.
| На хосте | В контейнере | Что это |
|---|---|---|
data/site |
/data/site |
Ваш сайт: site.yaml, pages/, content/, фрагменты. Его правит редактор |
data/dist |
/data/dist |
Опубликованные релизы и симлинк current |
data/state |
/data/state |
Состояние входа и журнал audit.jsonl |
docker build -t site-engine .
docker run --rm -it site-engine site-engine hash-password # спросит пароль, напечатает хеш
docker run --rm site-engine site-engine gen-secret # ключ подписи сессий
cp .env.example .env # впишите хеш и ключ
mkdir -p data && cp -r examples/studio-site data/site # или положите свой сайт в data/site
docker run -d --name site-engine -p 8181:8000 --env-file .env -v "$PWD/data:/data" site-engine
Админка: http://localhost:8181/admin/ (на обзоре сверху показаны абсолютные пути, которыми пользуется приложение), опубликованный сайт: http://localhost:8181/. Проверка того, что видит контейнер:
docker logs site-engine # строка «site-engine: site=/data/site, dist=/data/dist, state=/data/state, admin=on»
docker exec site-engine env | grep '^SITE_' # SITE_ROOT, SITE_DIST, SITE_STATE_DIR должны начинаться с /data/
Если вместо /data/... там относительные пути (examples/studio-site, dist), эти строки остались в вашем .env от старой версии: удалите SITE_ROOT, SITE_DIST, SITE_STATE_DIR из .env, так как значения из --env-file перекрывают значения из образа. При старте приложение само пишет об этом предупреждение.
Правила для .env при docker run --env-file:
- Без кавычек. Docker не снимает их, они станут частью значения.
- Без комментариев в конце строки.
KEY=value # текстдаёт значение «value # текст». - Знак
$в хеше экранировать не нужно. (Дляdocker composeи его.envего нужно удваивать:$$.)
Приложение проверяет эти значения строго: хеш, ключ, логин, флаг Secure и host с лишними символами не принимаются молча, /admin/ не включается, а в docker logs пишется причина.
| Симптом | Причина |
|---|---|
/admin/ даёт 404 |
Не заданы SITE_ADMIN_PASSWORD_HASH и SITE_SECRET_KEY, ключ короче 32 символов или в значении кавычки или комментарий; причина в docker logs: «админка отключена: …» |
| «Сайт не загружен» на обзоре | В data/site нет site.yaml или том не смонтирован; на обзоре виден абсолютный путь, который проверял движок |
| Опубликованного сайта нет на хосте | Том не смонтирован (-v "$PWD/data:/data"): релизы лежат внутри контейнера и пропадут вместе с ним |
| После ввода пароля снова страница входа | Cookie с флагом Secure не принимается по http:// с адреса не localhost: поставьте SITE_COOKIE_SECURE=0 |
Ответ 422 с "loc": ["query","request"] |
Образ собран из версии до исправления: пересоберите docker build |
Контейнер работает от root, поэтому файлы в data/ на Linux будут принадлежать root. Чтобы этого избежать, добавьте --user "$(id -u):$(id -g)".
Вход в админку
Самый простой вариант: один администратор, без ролей, логин и хеш пароля задаются переменными окружения, БД для входа не нужна.
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 страниц, блоков и записей проверяются регулярным выражением и поиском в реестре, до пути на диске недоступны; пассивное превью использует iframe без scripts, интерактивное — отдельный origin и только nonce bridge; в аудит попадают id и тип действия, но не содержимое.
Что работает иначе, чем можно ожидать:
- Обычные формы и локальный htmx. Порядок блоков меняется кнопками ↑/↓, элементы списков добавляются через «пустую строку» формы. htmx 2.0.11 поставляется в
src/site_engine/web/admin/static/и включает существующийhx-boost; источник, лицензия и SHA-256 — в VENDOR.md. Без JS сохраняются обычные формы. CDN и Node-сборка не нужны; SortableJS пока не подключён. Конфигурация запрещает eval, скрипты из ответов и сторонние запросы, отключает сохранение HTML в localStorage и разрешает показ HTML-ошибок 4xx. Новый редактор использует HTML-фрагменты htmx, общий буфер в памяти и явный Save; без JS доступна обычная форма исходника.
Развитие админки описано в 001 — Antirion Rework: htmx/Jinja → HTML UI → серверный API-клиент → типизированный JSON API FastAPI → сервисы. JSON API, общий буфер Конструктора/«Эксперта», ручной Save и интерактивное превью реализованы. Контракт, env и запуск второго процесса: runtime.md; приёмка: verification.md.
- Конструктор пересобирает YAML после предупреждения: комментарии и форматирование могут измениться. «Эксперт» и переходы режимов без правок сохраняют точный исходник. «Применить к буферу» не пишет файл; «Сохранить документ» записывает весь документ с CAS, историей и аудитом. До Save исходник можно скачать.
- Ассеты выбираются по пути из подсказки, загрузки файлов в редакторе пока нет.
- Блоки перемещаются кнопками ↑/↓ или перед указанным ID. Между регионами/слотами действует проверка схемы; циклы и изменение fixed-блоков запрещены.
- Запись коллекции со «лишним» ключом, которого нет в схеме, нельзя сохранить в статусе
published, пока ключ не уберут из файла: так требует ADR-003.
Что реализовано
| Этап | Состояние |
|---|---|
| M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 встроенных фрагментов, сайт-пример; отдельный steps поставляется с ai-studio |
| M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (services/publish.py), превью страницы через CLI. Превью по токену реализовано в 001; нет 404-страницы из коробки и системы публичных тем |
| M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), вход одного администратора с аудитом входов и обзорная страница админки. Аудит Save/create/publish/rollback реализован; нет ролей, приёма заявок и outbox |
| M3 MCP и редактор | Готово: редактор страниц, блоков и записей на ContentService, предпросмотр, публикация и откат из админки. Нет: patch_page, changeset (rename, delete), MCP-сервера, перетаскивания, загрузки файлов |
| M4 | Не начат |
Что проверено, а что нет
Приёмка 001 включает полную регрессию ядра/CLI/админки, настоящий FastAPI, JSON-контракт и ASGI-клиент, Chromium на двух origin, адаптивные экраны и установленный wheel без design/. Воспроизводимые команды, результаты и ограничения: verification.md. Docker/proxy deployment, БД и MCP-сервер не запускались. Ядро сохраняет dataclass; Pydantic используется на границе API.
Соответствие журналу решений
| Решение | Где в коде |
|---|---|
| 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 встроенных фрагментов, локальный steps в ai-studio, editorial, requires только feature.* |
builtin/fragments/, examples/ai-studio/fragments/steps/, 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.