# Site Engine Движок сайтов на Markdown + YAML: страницы собираются из **layouts** и **fragments**, контент и структура живут в файлах, результат — статический сайт. Подключение агента по MCP — часть архитектуры (этап M3). Документы проекта лежат в `docs/`: ТЗ v0.1, архитектурное ревью и журнал принятых решений (ADR-001…006). Код следует журналу решений. ## Быстрый старт ```bash 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//` и симлинк `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/ # 112 тестов: ядро, сборка, безопасность, запись, вход в админку └── 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-проверки, правила сайта │ └── 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 (вход, выход, обзор), шаблоны, routes-адаптер └── mcp/ # перечень инструментов MVP (M3) ``` ## Вход в админку Самый простой вариант: **один администратор, без ролей**, логин и хеш пароля задаются переменными окружения, БД для входа не нужна. ```bash 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`. ## Что реализовано | Этап | Состояние | |---|---| | M0 Контракт и прототип | Готово: формат файлов, модель блоков, load → validate → render, CLI, 15 фрагментов, сайт-пример | | M1 Публикуемый движок | Частично: маршруты, ссылки, редиректы, sitemap, атомарная публикация, откат (`services/publish.py`), превью страницы через CLI. Нет: превью по токену, 404-страница из коробки, тема | | M2 Коллекции, заявки, доступ | Частично: коллекции, display templates, запросы, формы (разметка, версия формы в релизе), **вход одного администратора с аудитом входов и обзорная страница админки**. Нет: роли, приём заявок, outbox, аудит правок | | M3 MCP и редактор | `ContentService` с `if_match`, блокировкой и историей готов; нет редактора страниц, `patch_page`, changeset, MCP-сервера | | M4 | Не начат | ## Что проверено, а что нет Тесты и сборка примера выполнялись в окружении без сети: ядро (`core/`, `build/`, `parsing/`, `storage/`, `services/`) и вся логика админки (`web/admin/handlers.py`, шаблоны, вход, CSRF, заголовки) запущены и покрыты 112 тестами. Тонкий 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/@<версия>.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/.yaml`, записи в `content//*.md`, при необходимости `display/.yaml`. - **Новое правило сайта:** запись в `site.yaml: rules` (сейчас `require_fragment` для коллекции и `require_field` для форм). ## Известные ограничения M0 - Поле `props` в шаблоне — объект `Props`: `props.items` читает поле «items», а не метод словаря. - `layout.extends` проверяется на существование, наследование шаблонов делается обычным `{% extends 'layout/' %}`. - CSS и JS собираются в один бандл с хешем в имени; минификации и изоляции по страницам пока нет. - Нет приёма заявок, редактора и MCP: сетевая поверхность записи включается только вместе с контуром «вход, роли, аудит, лимиты» (ADR-006). Вход уже есть, роли и аудит правок будут вместе с редактором.