dd-console

Локальная веб-консоль для наблюдения за выполнением dd-flow и dd-eval.

Один локальный сервер, два раздела — Flows и Evals, отдельные экраны детализации и навигация через breadcrumbs. Из execution эвала можно перейти во вложенный flow, затем в работу, сессию и её события.

Статус: реализован первый локальный read-only выпуск. Сервер слушает только 127.0.0.1, не запускает команды раннеров и не меняет их данные.

• План реализации: архитектура, экраны, API и приёмка
• Следующий этап: подробный план нового UI, тем и метрик
• Перепроверка готовности UI-плана и внесённые дополнения
• Очередь работ первого выпуска
• Исследование существующих раннеров
• Поддерживаемые источники и версии
• DTO, freshness и безопасное отображение
• Фактическая приёмка и известные ограничения

Первый выпуск — живое наблюдение и просмотр истории. Раннеры сохраняют управление выполнением и своими данными; закрытие консоли не останавливает запуски. Управление pause/resume/stop запланировано следующим этапом.

Запуск

Требуется Node.js 26 и macOS. Проверки выполнены на macOS. В корне репозитория:

npm install
npm run check
npm run start:open

npm start запускает сервер без открытия браузера; npm run start:open — с открытием. Оба скрипта сначала собирают приложение. Дополнительные параметры передаются после --, например npm start -- --port 8080.

Для разработки нового интерфейса: npm run dev. Команда собирает backend, запускает его и Vite на свободных портах 127.0.0.1 и выводит адрес frontend в startup receipt (url). API проксируется к backend; frontend обновляется через HMR. Dev использует временный console home и не меняет реестр/daemon production-консоли. Producer homes читаются обычным read-only способом. Изменение backend исходников вызывает сборку и перезапуск; ошибка компиляции сохраняет предыдущий backend. Ctrl+C завершает оба сервера и удаляет временное состояние. Пакету, установленному из npm, Vite и отдельный frontend-процесс не требуются.

serve добавляет доступные по умолчанию ~/.dd-flow и ~/.dd-eval в ~/.dd-console/sources.json, затем печатает URL. Для другого расположения используйте --flow-home и --eval-home, либо управляйте реестром явно:

dd-console sources add --kind flow --path /path/to/dd-flow-home
dd-console sources add --kind eval --path /path/to/dd-eval-home
dd-console sources list
dd-console sources remove SRC-…

Реестр записывается атомарно и блокируется на время изменения. Если файл повреждён, console оставляет его как есть и сообщает ошибку вместо перезаписи. Остановите foreground-сервер Ctrl-C.

Установленный пакет использует ту же команду:

npm install -g @deksden-com/dd-console
dd-console start --open

До первой публикации пакет можно установить из созданного npm pack tarball; инструкции выпуска приведены ниже. API не предназначен для удалённого доступа, а браузер не получает пути source и raw evidence. Для Flow используются короткие read-only транзакции SQLite с существующим WAL. Данные БД не меняются; служебные SHM read-marks обслуживает SQLite. Копирования живого DB/WAL нет.

Файлы читаются через дескрипторы каталогов (openat/O_NOFOLLOW), а локальные locks используют flock. Для этих POSIX API используется пакет koffi. История событий доступна страницами; filters/sort/cursors сохраняются в URL. Артефакты receipt/stdout/stderr открываются в собственном экране с breadcrumbs. Preview ограничен 256 KiB за фрагмент, следующий фрагмент доступен по ссылке.

Повторная проверка поставки: npm run pack:check после npm run build. Отчёт об исправлениях ревью.

Для новых Eval dd-eval публикует рядом с events.jsonl файл observation.json (dd-eval/observation@1). Он даёт консоли сохранённое состояние Eval и executions без обращения к живому runner. Исторические Eval без этой проекции остаются доступными, но имеют явную отметку о частичном наблюдении.

Список Flows объединяет самостоятельные запуски из Flow-источников и RUN из manifest-declared executions Eval с проверенным managed-runtime.json. Фильтр «Запущен через → Eval» оставляет только вложенные запуски. В строке видны полный RUN ID, проект, источник и ссылки на Eval/execution. Одинаковые RUN ID в разных runtime остаются отдельными записями. Удалённые или неподтверждённые runtime не восстанавливаются по догадке; старые статусы отражают сохранённые данные.

Local Eval home registry

~/.dd-eval/homes.json is the shared registry, independent of DD_EVAL_HOME. The version 1 document contains schema_version: 1 and homes entries with id, canonical root, label, created_at and disabled fields. Creating an Eval or requesting continuation registers its home automatically. An explicit removal stays disabled until explicitly added again.

dd-eval homes list
dd-eval homes add --path /absolute/path/to/eval-home --label qualification
dd-eval homes remove --id SRC-...

The console reads the registry on each request, keeps unavailable sources visible, and deduplicates it against its own sources. Local source removal overrides registry discovery in that console. A new home requires no console restart. Registry mutations use a process-owned lock and atomic replacement; malformed registry data is preserved and reported instead of reset.

CLI и фоновый сервер

После публикации пакет устанавливается глобально:

npm install -g @deksden-com/dd-console
dd-console                 # сервер в терминале; Ctrl-C останавливает его
dd-console start --open    # сервер в фоне; завершение команды оставляет его работающим
dd-console status          # состояние, URL
dd-console stop            # дождаться завершения сервера и освобождения locks
dd-console restart         # заменить процесс актуальной сборкой

По умолчанию используется http://127.0.0.1:50036; --port и DD_CONSOLE_PORT меняют порт. --port 0 выбирает свободный порт. serve — явный вариант запуска в переднем плане. start повторно использует текущую сборку, при изменении ревизии заменяет её; restart всегда заменяет процесс и сохраняет текущий порт, если новый не указан. --json возвращает машиночитаемый результат. status возвращает код 1, если сервер остановлен или не отвечает. Остановка завершается успешно, даже если сервер уже остановлен.

Один сервер на DD_CONSOLE_HOME (по умолчанию ~/.dd-console). server.json хранит PID, URL, уникальную идентичность процесса и версию сборки; перед отправкой сигнала CLI сверяет идентичность с /healthz. Устаревший PID чужого процесса не получает сигнал. Вывод фонового процесса сохраняется в ~/.dd-console/server.log. Фоновый режим не устанавливает системную службу: после перезагрузки компьютера нужно снова выполнить dd-console start. Закрытие браузера не останавливает сервер.

В checkout доступны npm run start:background, npm run stop, npm run restart, npm run status. Команды запуска собирают актуальную ревизию. Установленный npm CLI запускается из любого каталога без TypeScript и пересборки.

Выпуск через Changesets

npm run changeset          # описание изменения и тип semver bump
npm run version:release    # версии, CHANGELOG.md, package-lock.json
npm run release            # сборка и публикация версий через Changesets

Release console в GitHub Actions запускается вручную на main: при наличии changeset создаёт/обновляет PR с версиями и changelog; после слияния этого PR повторный запуск публикует пакет. Проверки CLI и установки tarball выполняются перед публикацией. CI проверяет пакет на macOS; Linux не поддерживается.

Для публикации настройте npm Trusted Publisher для deksden-com/dd-console, workflow release.yml. Первая публикация нового пакета требует npm-аккаунта с правом публикации в scope @deksden-com; после создания пакета можно настроить Trusted Publisher. В GitHub включите разрешение Actions создавать pull requests. Описания следующих изменений добавляются в .changeset/. После version:release они переносятся в CHANGELOG.md, версия обновляется, а применённые файлы changeset удаляются. Уже применённые изменения повторно версионировать не нужно.

Локальная публикация читает NPM_ACCESS_TOKEN из игнорируемого .env. Процесс авторизации, ротации и публикации проверенного tarball описан в npm release runbook.

Новый интерфейс на React, shadcn/ui и Tailwind открывается по умолчанию при запуске dd-console. Дополнительная переменная DD_CONSOLE_UI не требуется. Тема по умолчанию — системная; выбор светлой или тёмной темы сохраняется в браузере.

Переключатели «Светлая», «Тёмная» и «Системная» находятся внизу боковой навигации. На узком экране они также доступны в верхней панели и внутри меню навигации. «Системная» следует настройке macOS; выбор сохраняется после перезагрузки страницы.

Если источник недоступен, откройте экран «Источники» и его диагностику, затем проверьте зарегистрированный home командой dd-console sources list. После восстановления доступности каталога повторите чтение в интерфейсе. Ошибка чтения не означает, что все запуски завершились с ошибкой, и не требует изменения их статусов. Если недоступна сама веб-страница, проверьте dd-console status --json и выполните dd-console restart; у foreground-сервера сначала завершите прежний процесс через Ctrl-C, затем запустите dd-console снова.

Согласование статусов и ремонт старых записей: runbook.