@spec-box/sdd 0.6.4 → 0.7.1

package/docs/design.md

@@ -300,7 +300,7 @@ Delivery narrative. При вердикте `готово` ревьюер пиш
           verify-1.md
         changeset.json       # запечатанный change-set после implement: пути и дайджест дифа
         log.md               # тегированный журнал: [CODE] [RULE] [TASK] [HUMAN]
-        runs/
+        runs/                # до архивации; в архив не переносится (archive.runs: true оставляет)
           r7/
             packet.json      # пакет роли
             result.md        # ответ роли с блоком sbox-result
@@ -368,7 +368,7 @@ runs:
 
 ### Архивация до мержа
 
-Архивация происходит на фазе deliver, внутри пул-реквеста. CLI применяет дельты к истине `specs`, переносит папку изменения в `changes/archive/` с датой и коммитит всё в ветку изменения. Шаг атомарный: все проверки (каталог архива, валидность дельт) выполняются до записи, затронутые файлы истины снимаются в снимок, после применения истина проверяется на дубликаты требований и сценариев, и любая ошибка откатывает файлы к снимку. Применение дельт идемпотентно (повтор `ADDED` с тем же содержимым пропускается, с другим содержимым это ошибка), поэтому повторный запуск после сбоя даёт тот же результат, что однократный успешный. Ревьюер пул-реквеста видит три дифа вместе: код, тесты и истину спецификаций.
+Архивация происходит на фазе deliver, внутри пул-реквеста. CLI применяет дельты к истине `specs`, переносит папку изменения в `changes/archive/` с датой и коммитит всё в ветку изменения. Шаг атомарный: все проверки (каталог архива, валидность дельт) выполняются до записи, затронутые файлы истины снимаются в снимок, после применения истина проверяется на дубликаты требований и сценариев, и любая ошибка откатывает файлы к снимку. Применение дельт идемпотентно (повтор `ADDED` с тем же содержимым пропускается, с другим содержимым это ошибка), поэтому повторный запуск после сбоя даёт тот же результат, что однократный успешный. Ревьюер пул-реквеста видит три дифа вместе: код, тесты и истину спецификаций. Папка `runs/` в архив не переносится: ответы ролей и квитанции остаются в истории ветки изменения, а всё, что нужно после доставки, уже в `change.yaml` (список запусков со временем и стоимостью, `delivery_narrative` ревьюера). Опция `archive.runs: true` сохраняет папку в архиве.
 
 Если ревью пул-реквеста требует правок, работают два пути. Правки только в коде идут через `sbox change resume`: папка остаётся в архиве, реализатор получает замечания, фазы verify и review повторяются. Правки в спецификациях идут через `sbox change reopen`: CLI восстанавливает затронутые файлы истины из базовой ветки, возвращает папку из архива и переводит изменение в фазу plan.
 
@@ -459,7 +459,7 @@ runs:
 
 ### Метрики решателя
 
-Команда `sbox metrics` считает по `change.yaml` и receipt запусков: время агентов по фазам, ожидание человека на гейтах, число запусков, стоимость (для headless-запусков), возвраты и отклонения отчётов, вмешательства (отклонённые гейты, `resume`, вопросы к человеку, отклонённые отчёты), признак автономного прохождения и оценку результата человеком (`sbox change rate`). Сводка по всем изменениям даёт долю автономных, медианы времени и запусков, среднюю оценку и число вмешательств на изменение. Ничего не хранится отдельно: метрики восстанавливаются из файлов изменения.
+Команда `sbox metrics` считает по `change.yaml` (список запусков с временем и стоимостью переживает архивацию) и по receipt запусков, пока папка `runs/` есть: время агентов по фазам, ожидание человека на гейтах, число запусков, стоимость (для headless-запусков), возвраты и отклонения отчётов, вмешательства (отклонённые гейты, `resume`, вопросы к человеку, отклонённые отчёты), признак автономного прохождения и оценку результата человеком (`sbox change rate`). Сводка по всем изменениям даёт долю автономных, медианы времени и запусков, среднюю оценку и число вмешательств на изменение. Ничего не хранится отдельно: метрики восстанавливаются из файлов изменения.
 
 ### Как контекст попадает к агенту
 
@@ -731,7 +731,7 @@ interface HostMaterials {
 }
 ```
 
-Команда `sbox host install --target claude` генерирует `.claude/skills/sbox-*/SKILL.md` и `.claude/agents/sbox-<role>.md`; для Codex генерируются `.codex/agents/*.toml` и раздел в `AGENTS.md`. Все сгенерированные файлы тонкие: они вызывают `sbox next` и `sbox report`, а определения ролей остаются в одном месте. Повторный запуск обновляет файлы, ручные правки в них не предполагаются.
+Команда `sbox host install --target claude | codex` копирует скиллы из единого источника `assets/skills` (`sbox-run`, `sbox-approve`, `sbox-browser`) в раскладку хоста и генерирует агентов: для Claude Code `.claude/agents/sbox-<role>.md`, где скиллы из `metadata.roles` подключены полем `skills`, потому что субагенты не видят скиллы проекта сами; для Codex сейчас ставятся только скиллы без привязки к хосту (`sbox-approve`, `sbox-browser`) в `.agents/skills`, а `sbox-run` помечен `metadata.hosts: [claude]`, потому что его текст опирается на субагентов Claude Code; агенты ролей и раздел `AGENTS.md` для Codex появятся на этапе 4. Описания агентов берутся из фронтматтера `description` файлов ролей, каркас агента из `assets/hosts/claude/agent.md`, набор инструментов из `runner.claude.allowedTools` и `readOnlyTools` конфига, как в headless-режиме. Все сгенерированные файлы тонкие: они вызывают `sbox next` и `sbox report`, а определения ролей остаются в одном месте. Повторный запуск обновляет файлы, ручные правки в них не предполагаются.
 
 ### Отчёты тестов
 
@@ -743,6 +743,17 @@ interface TestReportAdapter {
 
 Реализации: jest (он же vitest с репортёром json), playwright; testplane и storybook позже. Сопоставление сценариев с тестами по ключам (название capability, требования, сценария) повторяет алгоритм spec-box, поэтому состояние автоматизации совпадает с тем, что показывает бэкенд spec-box. В OpenSpec-проекте тот же алгоритм даёт покрытие сценариев без бэкенда.
 
+### Браузер для проверки интерфейса
+
+Сборка и статические проверки не доказывают, что изменение работает, а роли в headless-режиме лишены браузерных инструментов хоста. Поэтому пакет ставит второй бинарник `sbox-browser`: управляемый Chrome с командами для агентов и людей. Пакет не скачивает браузер при установке (`puppeteer-core`, а не `puppeteer`); установка отдельная и необязательная.
+
+- **Браузер.** Порядок поиска исполняемого файла: флаг `--executable`, переменная `SBOX_BROWSER_EXECUTABLE`, `browser.executable` в конфиге, кэш инструмента `~/.sbox/browser/cache`, кэш puppeteer других проектов, системный Chrome по каналам, известные пути Chromium, Edge и Brave, имена в PATH. Явно заданный путь, которого нет, это ошибка, а не переход к поиску. `sbox-browser install [--browser chrome | chrome-headless-shell | chromium] [--build stable | beta | buildId] [--cache-dir <dir>]` скачивает сборку через `@puppeteer/browsers` в кэш инструмента, `installed` и `uninstall` управляют кэшем, `doctor` показывает выбор и кандидатов. `sbox doctor` проекта добавляет проверку браузера предупреждением. Настройки: секция `browser` конфига (`executable`, `headless`, `profile`, `baseUrl`, `cacheDir`, `viewport`, `timeoutMs`, `idleMinutes`), переменные `SBOX_BROWSER_HOME` (каталог инструмента), `SBOX_BROWSER_EXECUTABLE`, `SBOX_BROWSER_HEADLESS`, `SBOX_BROWSER_PROFILE`, `SBOX_BROWSER_BASE_URL`, `SBOX_BROWSER_CACHE_DIR`, глобальные флаги `--session`, `--profile`, `--timeout`, `--cwd`; порядок: флаги → окружение → конфиг → умолчания. Прерванная установка (папка без бинарника) переустанавливается.
+- **Сессия.** Первая команда страницы поднимает демон: фоновый процесс с браузером и локальным сокетом (unix-сокет, на Windows именованный канал) в `~/.sbox/browser/sessions/<имя>`. Клиент отправляет одну команду в JSON-строке и получает ответ; демон исполняет команды последовательно. Между вызовами сохраняются вкладки, страница, куки, буферы консоли и сети. Демон завершается по `stop`, по простою между командами (`browser.idleMinutes`, по умолчанию 30; во время долгой команды таймер не срабатывает, значения больше 35791 минут отключают самозавершение) или при потере браузера. Имя сессии занимается атомарной блокировкой до запуска браузера, поэтому два одновременных автозапуска не поднимают два Chrome; `ping` и `stop` отвечают вне очереди команд, так что занятый демон не считается мёртвым, а `stop` прерывает долгое ожидание. Уход клиента (таймаут, Ctrl+C) отменяет его команду в очереди. След мёртвого процесса удаляется при следующем обращении, а `stop` посылает сигнал только процессу, чья командная строка это демон данной сессии. `--session <имя>` даёт независимые браузеры.
+- **Вход человеком.** `sbox-browser login <url> --profile <имя>` открывает окно с постоянным профилем (user-data-dir в `~/.sbox/browser/profiles/<имя>`), человек входит и подтверждает Enter, либо `--until <селектор>` / `--until-url <шаблон>` завершают вход автоматически. Дальше та же сессия работает под входом, а после `stop` любая headless-сессия с этим профилем (флаг `--profile` или `browser.profile` в конфиге) получает те же куки. Перенос входа в CI или на другую машину: `state save <файл>` выгружает куки браузера и storage текущей страницы, `state load` восстанавливает; файл содержит секреты и не коммитится.
+- **Команды для агента.** `goto`, `back`, `reload`, `snapshot` (дерево доступности с ролями, именами, состояниями и ссылками `[eN]` на интерактивные элементы), действия `click`, `fill`, `type`, `press`, `select`, `check`, `upload`, `hover`, `scroll`, ожидания `wait` (элемент, текст, адрес, условие, пауза), чтение `text`, `html`, `attr`, `value`, `count`, `exists`, `eval`, доказательства `screenshot`, `console --errors`, `requests` (ответы 4xx/5xx и неудачные запросы), окружение `cookies`, `viewport`, `dialog`, `auth`, `headers`, вкладки `pages` и `page new | switch | close`. Цель действия это ссылка из снимка либо селектор: CSS, `text=`, `aria=`, `xpath=`. Ссылки нумеруются при каждом снимке; исчезнувший элемент даёт ошибку `BROWSER_REF_STALE` с подсказкой сделать снимок заново, `exists` по ссылке проверяет живой элемент. Диалог `beforeunload` подтверждается всегда, иначе политика `dismiss` отменяла бы любую навигацию. `eval` сначала исполняет код как есть (выражение или список инструкций), а при синтаксической ошибке из-за `return` или `await` как тело async-функции. Все команды поддерживают `--json`, ошибки приходят в общем конверте диагностики с кодами `BROWSER_*`.
+- **В процессе изменения.** Верификатор обязан проверить затронутую страницу через `sbox-browser`, если `testing.md` описывает запуск: ошибки консоли и ответы 4xx/5xx на ней это FAIL, скриншот прикладывается как доказательство; без профиля для страницы, требующей входа, это пробел с окружением «вход в приложение». Исследователь и тестировщик используют снимок, чтобы зафиксировать тексты, элементы и маршруты; автотесты пишутся на инструментах проекта. Пакет каждой роли содержит подсказку `commands.browser`. Категория `testing.md` получила раздел «Проверка интерфейса в браузере»: базовый URL, профиль входа, дымовые маршруты.
+- **Безопасность.** Профили, файлы состояния, скриншоты и журналы демонов лежат в `~/.sbox/browser`, вне репозитория продукта; в репозиторий попадает только конфиг без секретов. Демон слушает локальный сокет, доступный только пользователю.
+
 ## 12. CLI и архитектура кода
 
 ### Команды
@@ -762,6 +773,7 @@ interface TestReportAdapter {
 | Доставка | `deliver [--check] [--keep-draft]`, `gates poll` | Чеклист готовности и доставка: intent, архив, коммит с ключом, push, пул-реквест; опрос гейтов в комментариях пул-реквеста |
 | Среда | `ci install --target github \| docker` | Шаблоны workflows GitHub Actions (запуск @spec-box/sdd и тесты с JSON-отчётом) и Dockerfile |
 | Знания | `route`, `distill`, `wiki lint` | План чтения wiki, дистилляция журнала, проверка wiki |
+| Браузер | `sbox-browser install \| installed \| uninstall \| doctor \| login \| start \| stop \| status \| state \| goto \| snapshot \| click …` | Отдельный бинарник: управляемый Chrome для проверки интерфейса агентами и людьми, см. раздел 11 |
 
 Все команды поддерживают `--json` и выводят ровно один JSON-документ в stdout. Диагностика в едином конверте: `severity`, `code`, `message`, `target`, `fix`. Человекочитаемый вывод идёт в stderr. Контракт взят из OpenSpec, потому что агенты уже умеют с ним работать.
 
@@ -780,6 +792,7 @@ packages/
     tests-jest/ tests-playwright/ tests-testplane/ tests-storybook/
   roles/         определения ролей и схема артефактов по умолчанию
   cli/           команды, вывод, конфиг
+  browser/       sbox-browser: демон, клиент, команды страницы, снимок, поиск и установка браузера
 ```
 
 На первом этапе это один npm-пакет с такой раскладкой каталогов. Разделение на пакеты происходит, когда появляется второй потребитель ядра (например, GitHub Action или бот).
@@ -788,6 +801,7 @@ packages/
 
 - Node.js 22 LTS, TypeScript в strict-режиме, ESM.
 - Схема артефактов, роли и категории документации хранятся как данные (YAML и Markdown), а не как код, чтобы проект мог их переопределять без сборки.
+- Скиллы хостов тоже данные: единый источник `assets/skills/<имя>.md` с фронтматтером `name`, `description` и `metadata.roles`. Адаптер хоста при `init --host` и `host install` копирует файл без изменений в раскладку хоста (Claude Code: `.claude/skills/<имя>/SKILL.md`, Codex: `.agents/skills/<имя>/SKILL.md`) и подключает скилл ролям из `metadata.roles` средствами хоста. Текст скилла в коде адаптера запрещён; новый хост это новая строка в таблице раскладок, а не новый текст. Проект заменяет или добавляет скилл файлом `.sbox/skills/<имя>.md`. Хосты равноправны: возможность, сделанная для одного хоста, либо покрывает остальные, либо явно записана в план.
 - Парсер spec-box-YAML переиспользует модель из `@spec-box/sync`, парсер OpenSpec-Markdown свой, без зависимости от пакета `@fission-ai/openspec`: он меняет формат каждые несколько недель, а нам нужен стабильный внутренний контракт. Если `openspec` установлен в проекте, `sbox validate` дополнительно вызывает `openspec validate` и показывает его диагностику.
 - Тесты ядра на фикстурах: репозиторий-образец в каждом формате спецификаций, прогон машины состояний с записанными ответами ролей. Адаптеры сред тестируются контрактными тестами с заглушками.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-box/sdd",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "description": "@spec-box/sdd: автономная реализация продуктовых фич ИИ-агентами",
   "type": "module",
   "license": "MIT",
@@ -13,7 +13,8 @@
     "url": "https://github.com/spec-box/sdd/issues"
   },
   "bin": {
-    "sbox": "bin/sbox.js"
+    "sbox": "bin/sbox.js",
+    "sbox-browser": "bin/sbox-browser.js"
   },
   "files": [
     "bin",
@@ -23,7 +24,7 @@
     "docs/design.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.12"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -31,13 +32,16 @@
     "dev": "tsx src/cli/main.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "tsc -p tsconfig.json && vitest run"
+    "prepublishOnly": "tsc -p tsconfig.json && vitest run",
+    "dev:browser": "tsx src/browser/cli.ts"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.268",
+    "@puppeteer/browsers": "^3.2.3",
     "commander": "^15.0.0",
     "fast-glob": "^3.3.3",
     "picomatch": "^4.0.7",
+    "puppeteer-core": "^25.12.0",
     "yaml": "^2.9.0",
     "zod": "^4.6.2"
   },
@@ -56,7 +60,9 @@
     "codex",
     "autonomous-development",
     "sdd",
-    "spec-driven-development"
+    "spec-driven-development",
+    "puppeteer",
+    "browser-automation"
   ],
   "publishConfig": {
     "access": "public",