@deksden-com/dd-console 0.0.0-stage → 0.2.0

package/docs/research.md

@@ -0,0 +1,82 @@
+# Веб-панели dd-eval и dd-flow: исследование и предложение
+
+Историческое исследование. Окончательное решение — отдельный репозиторий deksden-com/dd-console; актуальные решения и этапы находятся в [плане реализации](implementation-plan.md). Предложения ниже о размещении внутри dd-flow-cli заменены этим решением.
+
+Дата: 2026-09-13. Исследованы локальные чистые checkout: dd-eval `dffd25e`, dd-flow-cli `eb2cb97` (package version 0.9.0-beta.54). Это анализ текущего кода, не проверка всех установленных движков и не испытание работающего UI. Раннеры не запускались и не изменялись.
+
+## Рекомендация
+
+Одна локальная веб-консоль с двумя разделами — Flows и Evals — и переходом из execution эвала в соответствующий RUN. Существующие раннеры остаются владельцами выполнения. Консоль читает их состояние и журнал; закрытие браузера или перезапуск сервера наблюдения не влияет на выполнение.
+
+Начать с наблюдения: список запусков, детали, стадии/работы, сессии, события, проверки, результаты, причины ожидания и свежесть данных. Управление добавить отдельным этапом через существующие команды с их request ID и проверками состояния.
+
+## Что уже есть
+
+| Область | Источник в репозитории | Что можно использовать |
+|---|---|---|
+| Flow dashboards | dd-flow-cli/src/services/dashboard.ts; dashboard-targets.ts | Global/project/protocol HTML и JSON, навигация, состояния, очереди, планы, usage. Это генерируемые локальные страницы; живой HTTP API требует добавления. |
+| Flow RUN | dd-flow-cli/src/services/runs.ts; run-projection.ts | Список RUN, run.json, timeline.jsonl, sessions, works, зависимости, попытки и прогресс плана. |
+| Flow controller | dd-flow-cli/src/services/run-controller-state.ts | Controller ID, generation, status, stage, сессии, ошибка, события в SQLite. |
+| Хранилище Flow | dd-flow-cli/src/storage/database.ts; runtime/context.ts | Уже существует read_existing: SQLite readOnly и query_only. |
+| Eval | dd-eval/lib/runner.mjs: runnerStatus, runnerControlStatus | manifest, результаты executions, pending operations, последняя sequence/time, живое наблюдение и runner attempts. |
+| Eval journal | dd-eval/lib/runner-events.mjs | events.jsonl, нормализованный envelope, sequence, операции, cancel/control и восстановление проекции. |
+| Связь Eval → Flow | runnerControlStatus; executions/<id>/managed-runtime.json | Проверяемые project_root, runtime_root, run_id. Каждый execution использует свой dd-flow-home. |
+
+Структуры событий различаются: eval имеет sequence в envelope; flow timeline использует timestamp/event/run_id, без обязательного sequence. Нельзя объявить их одним журналом и сортировкой по времени восстановить причинность.
+
+## Какие экраны нужны
+
+1. **Обзор.** Активные и завершённые запуски, фильтры по проекту/harness/статусу; текущая работа, последнее событие, длительность, явная причина ожидания. В первую очередь показывать запуски, требующие внимания.
+2. **Flow RUN.** Стадии с попытками и возвратами, дерево работ и зависимостей, связанные сессии и роли, harness и наблюдаемая модель, проверки/ревью, merge-состояние, журнал событий. Для новых flow показывать works даже там, где legacy current_stage отсутствует.
+3. **Eval run.** Case, checkpoint, версии/хеши движка и определения; список executions и их результатов; вложенный flow каждого execution; candidate, Judge и evidence как отдельные состояния. Отсутствующий Judge не равен нулевому score.
+4. **Диагностика.** Что выполнялось последним, активная операция, наблюдаемое состояние провайдера, fallback/recovery, насколько свежи данные, ссылки на разрешённые артефакты. Полные transcripts подгружать только по запросу и с ограничением объёма.
+
+Не показывать условные «73% выполнения» без определимого знаменателя: retries и дополнительные работы меняют объём. Полезнее текущая стадия, количество завершённых работ/проверок и время в текущем состоянии.
+
+## Архитектура первого выпуска
+
+Browser → локальный сервер наблюдения → два адаптера чтения:
+
+- Flow: совместимые JSON-проекции и read-only чтение существующего хранилища.
+- Eval: manifest/journal/results и проверенные ссылки на вложенные runtime.
+
+Предлагаемая упаковка: сервер и существующий HTML renderer развивать в dd-flow-cli; dd-eval публикует компактный версионируемый контракт наблюдения. Это рекомендация, ещё не существующие команды или API. Не импортировать большой runner.mjs в UI и не делать dd-flow зависимым от исходников dd-eval. Для первого вертикального среза достаточно чтения текущего формата через небольшой адаптер; несовместимую версию явно показывать как unsupported.
+
+Пример будущих read endpoints: GET /api/flows, /api/flows/:id, /api/evals, /api/evals/:id, /api/events?cursor=… . Реальная идентичность должна включать runtime/home и project, а не только короткий RUN ID. Сервер выдаёт opaque source ID; браузер не задаёт произвольные пути к БД или shell-команды.
+
+Первый работающий срез: polling раз в 2 секунды для выбранного запуска, реже для обзора; общий серверный кэш между вкладками и ограничение параллелизма. Измерить задержки на реальном журнале до выбора окончательных интервалов. runnerStatus вызывает несколько дочерних команд, поэтому его нельзя запускать для каждого RUN каждой вкладкой каждые 2 секунды. Разделить дешёвое чтение журнала и редкие bounded live probes.
+
+Затем SSE для доставки изменений: начальный snapshot с revision/cursor, дальнейшие изменения, восстановление после reconnect. Eval cursor может включать sequence; Flow нужен собственный source cursor (например, journal generation + byte offset), поскольку timestamp не уникален. При замене/усечении файла — reset и новый snapshot. Порядок гарантируется внутри источника; общий timeline показывает корреляцию, не выдуманный глобальный порядок.
+
+SSE поддерживает переподключение и Last-Event-ID, но сервер сам должен реализовать replay/reset. Источник: [HTML Standard — Server-sent events](https://html.spec.whatwg.org/dev/server-sent-events.html). Один поток на страницу; команды управления позднее идут отдельными HTTP запросами.
+
+На старте достаточно Node HTTP, существующего HTML и browser JS. Новая БД, очередь сообщений и UI framework не нужны для проверки ценности. При росте интерактивности решение о компонентах принимать отдельно.
+
+## Важные ограничения из кода
+
+- refreshRunSessionProjection пишет БД и файлы; recalculateFlowRunUsage пересчитывает usage и вызывает обновление проекции. Просмотр страницы не должен незаметно вызывать такие операции. Для каждого переиспользуемого reader нужен аудит вызовов; read_existing защищает от случайной записи.
+- Глобальный dashboard использует опубликованные project summaries: удобен для обзора, но не гарантирует свежесть отдельного RUN.
+- Eval использует изолированные движки. Новая консоль не должна мигрировать их БД или заменять закреплённый runtime. Нужны проверка версий, read-only доступ и частичная доступность при несовместимости.
+- runnerControlStatus прямо отмечает: независимые snapshots не являются общим доказательством settlement. UI обязан различать requested, observed, settled, unknown; «stop запрошен» не превращается в «остановлен».
+- last_event_at — время последнего события, не heartbeat. Отсутствие новых событий не доказывает зависание.
+- DTO должны выдавать разрешённые поля. Controller и merge записи содержат owner/lease tokens; сырые DB rows и manifest не следует пересылать целиком. Логи экранировать, артефакты отдавать только внутри разрешённых корней с проверкой realpath.
+- По умолчанию loopback, проверка Host/Origin. Удалённый доступ и права пользователей — отдельное расширение. Для будущих mutations потребуются защита запросов, сохранённый request ID, expected generation и durable receipt.
+
+## Варианты
+
+| Вариант | Выигрыш | Ограничение |
+|---|---|---|
+| Расширить статические HTML | Минимум изменений, удобно для завершённых отчётов | Не решает полноценно живое наблюдение и переходы между runtime |
+| Локальная общая консоль — рекомендуется | Переиспользует данные, единая навигация Eval → Flow, небольшой первый выпуск | Требует аккуратных reader contracts и индекса источников |
+| Отдельный центральный сервис | Несколько машин, история и командный доступ | Нужны collectors, доставка, авторизация, хранение и эксплуатация; пока требования не подтверждены |
+
+## Последовательность реализации и приёмка
+
+1. Проверить readers на одном текущем Flow, одном Eval с вложенными execution и одном старом несовместимом runtime. Зафиксировать компактные DTO, freshness и identity. Проверить отсутствие записей в runtime.
+2. Собрать живой read-only вертикальный срез: overview → Eval → execution → Flow → work/session → event. Polling, фильтры, bounded journal tail, артефакты. Это уже первый полезный выпуск.
+3. Проверить поведение на running/waiting/failed/recovery/completed, повторной попытке стадии и пропавшем runtime; затем SSE и reconnect, если polling недостаточен.
+4. Добавлять pause/resume/stop только через существующую механику раннеров. В UI сначала request receipt, затем подтверждённый результат; повторный запрос не дублирует действие.
+
+Критерии первого выпуска: обновления видны с согласованной задержкой; старый/недоступный источник не ломает обзор; eval-child link точен; неизвестные данные не маскируются под успех или ноль; открытие и закрытие панели не меняет ход выполнения; большие журналы читаются порциями; журнал и состояние не меняются из-за просмотра.
+
+Перед реализацией остаётся определить продуктовый приоритет: только локальная машина или удалённые раннеры; достаточно ли наблюдения в первом выпуске; нужны ли полные диалоги агентов или события и артефакты. Для данного предложения приняты локальный доступ, наблюдение первым этапом, события/артефакты с подробностями по запросу.

package/docs/work-plan.md

@@ -0,0 +1,88 @@
+# Очередь работ dd-console
+
+> Ревью 2026-09-13 и последующие исправления: [отчёт и проверяемые результаты](implementation-review.md).
+
+Источник решений: [полный план реализации](implementation-plan.md). Этот файл
+отражает фактический статус первого локального выпуска; дальнейшие пункты —
+очередь для production hardening и масштабирования.
+
+## Первый выпуск: локальная консоль наблюдения
+
+### 1. Проверить данные и закрепить контракты
+
+- [x] Проверить актуальные версии и инструкции dd-flow-cli/dd-eval перед изменениями; закреплены commits и версия в `docs/compatibility.md`.
+- [x] Подготовить обезличенные contract fixtures: самостоятельный Flow, Eval с несколькими executions, повтор стадии, failed/recovery, WAL и недоступный runtime; каталог — `test/fixtures/README.md`.
+- [x] Зафиксировать идентичности source/project/run/work/session и связь Eval → execution → Flow в `docs/compatibility.md`; direct derived link после restart покрыт тестом.
+- [x] Описать DTO, availability/freshness, поддерживаемые версии и доступность полей каждого экрана в `docs/data-contract.md` и `docs/compatibility.md`.
+- [x] Проверить getters на побочные записи: Flow reader использует короткую read-only транзакцию SQLite/WAL; тест подтверждает неизменность основной БД и WAL; Eval использует producer-owned observation export.
+- [x] Проверить, что чтение fixtures не меняет runtime: contract test проверяет основную SQLite и WAL, а реальный Flow прошёл before/after fingerprint без изменений; readers не импортируют runner и не запускают subprocess.
+- [x] Закрепить producer-owned observation export Eval с last_sequence; без него полный live Eval не считать реализованным.
+- [x] Проверить Flow WAL fixture и различить missing store от пустого: transaction reader включает committed WAL; SHM обслуживается SQLite, а empty `runs` store остаётся available. Поддерживаемая revision закреплена в `docs/compatibility.md`.
+
+Выход: данные для экранов доступны и проверяемы; пробелы контракта перечислены до разработки интерфейса.
+
+### 2. Каркас приложения и навигация
+
+- [x] Создать один Node/TypeScript пакет с build/test и упаковкой web assets.
+- [x] Реализовать foreground-команду serve, выбор порта, loopback, URL/JSON receipt и --open.
+- [x] Добавить регистрацию источников и минимальное API чтения.
+- [x] Добавить sources list/add/remove, пустой старт, registry lock и сохранение повреждённого config.
+- [x] Проверить derived source в прямой ссылке после перезапуска сервера.
+- [x] Собрать общий каркас экранов, routes, breadcrumbs, состояния ошибок и пустого списка.
+- [x] Проверить direct links, refresh и Back/Forward на Flow/Eval деталях.
+- [x] Реализовать visual shell: операционный журнал, системная типографика, адаптивные таблицы и статусы.
+
+Выход: запускаемый сервер и проходимая навигация на fixtures, без имитации реального выполнения.
+
+### 3. Самостоятельные Flows
+
+- [x] Подключить список и детали RUN к reader.
+- [x] Сделать детализацию работ, зависимостей и сохранённой стадии.
+- [x] Сделать сессии, проверки, события и зарегистрированные артефакты.
+- [x] Показывать missing/unknown явно; configured/observed model различать. Manifest model маркируется configured, а absent producer fact — «observed: не подтверждена».
+- [x] Пройти полный путь от списка до причины и обратно на реальном сохранённом RUN: 22 works, 21 sessions и 48 checks; результаты — `docs/acceptance.md`.
+
+Выход: консоль полезна для исследования самостоятельного Flow.
+
+### 4. Evals и вложенные Flows
+
+- [x] Подключить список EVAL, параметры запуска и executions.
+- [x] Показать candidate/Judge/evidence отдельно от статуса выполнения Flow, включая безопасные summary и отдельные экраны execution/events.
+- [x] Подключить изолированные runtime по проверенным managed-runtime связям.
+- [x] Сохранить контекст Eval в breadcrumbs при переходе в Flow/Work/Session, включая прямую ссылку и refresh.
+- [x] Проверить одинаковые короткие RUN ID в разных источниках и недоступный вложенный runtime: identity включает source/project/run, а path-escaping execution не создаёт nested Flow link.
+
+Выход: единый путь EVAL → execution → Flow → работа → сессия работает на реальных данных.
+
+### 5. Живое наблюдение
+
+- [x] Добавить polling выбранного экрана и обзора без обращения к runner.
+- [x] Разделить доступность источника, свежесть последнего факта и статус выполнения в API source metadata и header деталей.
+- [x] Добавить общий кэш readers, bounded JSONL tail и pagination списков.
+- [x] Вынести list/detail SQLite чтение в bounded workers; проверить cold start, deadlines, cache/queue limits и snapshot pagination.
+- [x] Обработать неполную последнюю строку и повреждённую строку журнала; rotation/truncation покрыты отдельным тестом.
+- [x] Сохранять focus и прокрутку при polling/Back; события не прокручивают страницу принудительно. Раскрывающихся деталей в текущем UI нет.
+
+Выход: ход выполнения виден без ручного обновления страницы и без вмешательства в раннер.
+
+### 6. Приёмка и поставка
+
+- [x] Пройти сценарии приёмки из основного плана и записать фактические результаты в `docs/acceptance.md`, включая live append <5 s.
+- [x] Проверить чтение без записи, границы доступа к артефактам и экранирование контента; результаты записаны в `docs/acceptance.md`.
+- [x] Проверить три параллельных клиента и 100 МиБ journal: bounded-tail fixture вернула последний event и /healthz за <5 с (фактически ~163 мс на macOS fixture). Задержка появления append проверена в Chromium/WebKit.
+- [x] Проверить клавиатуру, breadcrumbs, прямые Flow/Eval links, возврат позиции чтения и узкое окно в Chromium и WebKit через Playwright.
+- [x] Проверить запуск из упакованного/установленного пакета без соседних checkout через clean tarball install.
+- [x] Описать установку, sources, порты, остановку сервера и ограничения совместимости в README и contract docs.
+- [x] Проверить Node 26/macOS, pack из другого cwd, включение HTML/CSS и preview/download policy через `npm pack --dry-run` и clean install smoke.
+
+Выход: первый выпуск готов к использованию; публикация пакета выполняется отдельным согласованным действием.
+
+## Порядок интеграции
+
+Работать в feature-ветках dd-console, с небольшими PR по этапам. Изменения контрактов раннеров оформлять отдельными PR в соответствующие репозитории и проверять совместимость до подключения в консоли. Не переносить бизнес-логику выполнения в интерфейс. Не менять закреплённые движки исторических eval для удобства чтения.
+
+Проверки этого среза и поставки повторяются командами `npm run check` и `npm run pack:check`.
+
+## После первого выпуска
+
+Pause/resume/stop с точным scope и подтверждённым результатом операции. Затем по потребности — SSE, расширенные transcripts, запуск новых заданий и удалённые источники. Эти пункты не входят в критерии первого выпуска.

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@deksden-com/dd-console",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "dd-console": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "scripts": {
+    "prestart": "npm run build",
+    "start": "node dist/cli.js serve",
+    "prestart:open": "npm run build",
+    "start:open": "node dist/cli.js serve --open",
+    "start:background": "npm run build && node scripts/start-background.mjs",
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.json && node scripts/copy-assets.mjs && node scripts/write-build-info.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:browser": "npm run build && playwright test",
+    "check": "npm run typecheck && npm test && npm run test:browser",
+    "pack:check": "node scripts/pack-smoke.mjs",
+    "stop": "node dist/cli.js stop",
+    "restart": "npm run build && node dist/cli.js restart",
+    "status": "node dist/cli.js status",
+    "changeset": "changeset",
+    "version:release": "changeset version && npm install --package-lock-only",
+    "release": "npm run build && changeset publish",
+    "prepack": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@playwright/test": "^1.63.0",
+    "@types/node": "^24.10.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "koffi": "^3.2.1"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "description": "Local web console for dd-flow and dd-eval runners",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deksden-com/dd-console.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}