orchestrator/docs/architecture/adr/adr-0040-lite-interactive-installer.md

work_item, stage, author_agent, status, created_at, model_used

work_item	stage	author_agent	status	created_at	model_used
ORCH-104	architecture	architect	proposed	2026-06-11	claude-opus-4-8

adr-0040: Интерактивный installer Lite-тиража — scripts/setup_lite.py (ORCH-104)

Статус

Proposed

Контекст

Эпик ORCH-10 закрыт по обоим типам, но асимметрично: Type B — Bundled имеет инструмент (scripts/bootstrap_bundle.py, ORCH-103/adr-0038), Type A — Lite — только документ (docs/deployment/LITE_SETUP.md, ORCH-102/adr-0037: 13 разделов, ~30+ ручных команд, ~20 обязательных ключей). Порог входа Lite высок: оператор вручную собирает значения, которые машина определяет сама; ошибки конфигурации проявляются поздно (на smoke, не в момент ввода). Бизнес-запрос Владельца: один установочный файл — выполняет установку, запрашивает данные в момент установки, сканирует систему с офером доустановки, при нескольких инсталляциях Plane/Gitea даёт выбрать.

Сквозной характер: серия канонов тиража (adr-0035 onboarding → adr-0036 10-common → adr-0037 Lite-док → adr-0038 Bundled) дополняется слоем «Lite-инструмент»; вводятся нормативы, обязательные для будущих операторских CLI платформы и любого агента, меняющего шаги тиража. Детальный пакет решений (D1…D12, исходы OQ-1…OQ-6 ТЗ) — work-item ADR: docs/work-items/ORCH-104/06-adr/ADR-001-setup-lite-interactive-installer.md.

Решение

1. Новый операторский CLI scripts/setup_lite.py (имя зеркалит LITE_SETUP.md): python stdlib-only wizard, автоматизирующий маршрут LITE_SETUP §2–§12 — скан предусловий хоста с офером доустановки (per-package consent, закрытый набор менеджеров apt-get/dnf/yum/zypper, re-check после установки, иначе MANUAL), discovery docker-инсталляций Plane/Gitea (строго image-префиксы makeplane/*/gitea/gitea*; 0 → ручной ввод + подсказка про Bundled, 1 → префилл, ≥2 → выбор; «ввести вручную» всегда; never-block), интерактивный сбор ключей §4.2 с немедленной верификацией каждого значения фактическим вызовом (Plane/Gitea API, Telegram getMe; лимит 3 попытки → MANUAL), автодетект хост-параметров, сборка .env/.env.watchdog от канонов-example (webhook-секреты — строго кирпич gen_secrets.py), подъём ровно орк+watchdog + health, регистрация проекта строго кирпичом onboard_project.py (plan→согласие→apply→verify), итоговый отчёт PASS/FAIL/MANUAL + exit 0/2/1.
2. Wizard-контракт consent-gated мутаций (норматив для интерактивных операторских CLI): режимы — семейные plan/apply/verify, но дефолт — apply (бизнес-цель «одна команда»); отступление от plan-default семейства безопасно по построению и допускается ТОЛЬКО при четырёх структурных гарантиях: (а) фаза 0 apply ≡ plan (read-only скан + печать плана + явный вопрос «продолжить?»), (б) ранний guard чужих конфигов до первого вопроса, (в) per-action consent на каждую мутацию с печатью точной команды (отказ → честный MANUAL), (г) non-TTY без явного --yes → немедленный exit 2 (зависание/мутации исключены). Инструменты без per-action consent (bootstrap_bundle) обязаны сохранять plan-default.
3. Маркер managed-файла — норматив примирения идемпотентного resume с защитой чужих конфигов: первая строка собранного скриптом .env* — фиксированный комментарий # managed by scripts/setup_lite.py (ORCH-104); существующий файл без маркера → отказ exit 2 (без --force), с маркером → resume-ensure (дозаполнение без перетирания значений).
4. Headless-канал — env-prefill + явный --yes (не answers-file: секреты на диске вне .env запрещены): значения берутся из переменных окружения процесса с каноническими именами ключей .env.example; верификация обязательна и в headless; отсутствие обязательного значения → exit 2, не молчаливый дефолт.
5. Webhook Plane CE (Lite-инсталляция заказчика): Path A (UI) — рекомендация (manual-checkpoint с верификацией либо честный MANUAL «проверка — smoke §11»); Path Б (SQL INSERT в Postgres Plane) — офер строго при предусловиях: docker-Plane + подтверждённый пользователем контейнер БД + согласие с показом SQL + идемпотентный INSERT + обязательная пост-верификация; только INSERT/SELECT; ввод валидируется (анти-инъекция); сбой → fail-safe в Path A. (Отличие от Bundled adr-0038, где bootstrap владеет инсталляцией и пишет безусловно.)
6. Машинная охрана нормативов тиража: C-1 ORCH-100 (идентичные токены орка/watchdog → отказ шага), §6.4/D10 ORCH-009 (непустые branch_protections на main → FAIL с лечением, удаление — никогда), guard ORCH-058 (ORCH_STAGING_PORT == прод-порт → fail-closed), когерентная тройка прод-порта — одной чистой функцией.
7. Канон не форкается; норматив сопровождения расширен: LITE_SETUP.md получает подраздел ### 1.1. Быстрый путь (пиннинг «13 разделов в порядке» цел байт-в-байт; ручной маршрут — канон и fallback для MANUAL-шагов); footer-норматив NFR-5: «меняешь шаги тиража → обнови LITE_SETUP.md и scripts/setup_lite.py в том же PR». Канон-знания в скрипте запрещены структурно: кирпичи — только субпроцессами; имён Plane-статусов в скрипте нет вообще (зеркало FORBIDDEN_STATUS_NEEDLES); smoke — ссылкой на §11.
8. Анти-дрейф — постоянная CI-гарантия: tests/test_setup_lite_script.py (ast stdlib-only, зеркала delete/status-needle-наборов, кирпичи упомянуты, unit чистых функций: вердикты скана, классификатор discovery, когерентность портов, рендер env с маркером, builder onboard-аргументов, step-движок/resume, exit-контракт, дефолт apply, секрет-гигиена транскрипта) + аддитивный тест в tests/test_lite_setup_doc.py (скрипт упомянут в доке; существующие ассерты и кортеж SECTIONS не правятся).

Что НЕ меняется

src/**, корневой docker-compose.yml, Dockerfile, .env.example, .env.watchdog.example, кирпичи gen_secrets.py/onboard_project.py/bootstrap_bundle.py, deploy/**, onboarding/**; STAGE_TRANSITIONS, состав QG_CHECKS, семантика check_*, machine-verdict ключи, схема БД — байт-в-байт. Kill-switch не вводится (активация — только явный запуск оператора; паттерн ORCH-009/102/103). Прод-контейнер в рамках задачи не рестартуется.

Альтернативы

• plan-дефолт (строгий D5 ORCH-009/103) — отвергнуто для wizard-инструмента: воспроизводит порог, который задача убирает; безопасность дана гарантиями п.2, а не выбором режима.
• State-файл прогресса / answers-file / файл-отчёт — отвергнуты: новые артефакты = новые поверхности дрейфа и утечки; реальность как источник resume + env-prefill + stdout покрывают те же кейсы.
• Безусловная SQL-автоматизация webhook (как Bundled) — отвергнуто: в Lite БД Plane — чужая прод-инсталляция (см. п.5).
• Новый раздел LITE_SETUP / перенумерация — отвергнуто: ломает пиннинг «13 разделов» и внешние §-ссылки; подраздел §1.1 даёт то же бесплатно.

Последствия

• Порог входа Lite: «прочитай 13 разделов» → «запусти один файл»; ошибки конфигурации ловятся в момент ввода; число обращений «не взлетело» падает.
• Платформа получает переиспользуемые нормативы: wizard-контракт consent-gated мутаций (п.2), маркер managed-файла (п.3), headless-канал env-prefill+--yes (п.4) — для будущих операторских CLI.
• Цена: двойной источник маршрута (док+скрипт) — под нормативом same-PR и анти-дрейф тестами; дефолт apply расходится с семейством — зафиксировано явным тест-ассертом с обоснованием.
• Откат: удалить скрипт, тест-модуль, §1.1/footer и аддитивный тест — состояние 1:1 (scripts+docs+tests, без миграций).

Связи

adr-0037 (ORCH-102 — канон LITE_SETUP: автоматизируемый маршрут и пиннинг структуры), adr-0038 (ORCH-103 — bootstrap-паттерн: step-движок, manual-checkpoint, no-delete, кирпичи субпроцессами), adr-0036 (ORCH-101 — «дефолт=боевое», gen_secrets, guard ORCH-058), adr-0035 (ORCH-009 — onboarding-CLI: 22 статуса, D10 branch protection), adr-0033 (ORCH-100 — C-1 независимые Telegram-каналы). Детально — docs/work-items/ORCH-104/06-adr/ADR-001-setup-lite-interactive-installer.md, 07-infra-requirements.md, 10-tech-risks.md.