Skip to content

docs(web): Add web console spec, design and tasks - #108

Merged
4ndreello merged 3 commits into
mainfrom
docs/web-console-spec
Sep 23, 2026
Merged

4ndreello merged 3 commits into
mainfrom
docs/web-console-spec

Conversation

@4ndreello

Copy link
Copy Markdown
Owner

Planning artifacts for moving setup and usage to the browser. No code changes; this PR is spec.md, design.md and tasks.md under .specs/features/web-console/.

What the spec commits to:

  • One local HTTP server in the CLI process, extracted from codedeck review, serving review, usage and setup. codedeck ui opens a home that links only to registered routes. The daemon stays HTTP-free.
  • codedeck setup on an interactive terminal opens the web setup. The terminal wizard stays, frozen, behind --tui. Without a TTY, setup keeps today's exit 1, so agents never block on a server.
  • codedeck usage --web opens a usage page with the same filters as the CLI and every breakdown, including byOrigin from feat(usage): Capture orchestrator usage through a source ledger #103. --json, usage <run-id>, --backfill and the statusline path keep their contracts.
  • Writes are protected by a per-start token delivered in the opened URL (exchanged for a per-port cookie), a Host allowlist, an Origin check, and frame-ancestors 'none'.
  • Before the web setup, a pure setup planner is extracted and reused by the wizard, with the existing wizard and batch tests unchanged. Catalog validation stays outside the planner, and web apply validates only changed bindings against getBatchModels.
  • Page logic lives in plain functions tested in vitest, plus a node:vm test that runs the inline script with an empty context, so there are no DOM dependencies.

Decisions made while writing, open to change:

  • setup without a TTY keeps exit 1 instead of serving the web.
  • A model typed by hand that is not in the catalog saves through the web only with an explicit per-role confirmation, mirroring the wizard's second Enter.

Size: 93 requirements, 19 tasks, each with its own tests and a scoped gate command (no npm test). A coverage matrix maps each code layer to its test file.

Validation:

validate_spec: 0 error(s), 0 warning(s) in .specs/features/web-console/spec.md
validate_tasks: 0 error(s), 1 warning(s) in .specs/features/web-console/tasks.md
  WARN  T19: Tests: none (README-only task)

Two independent reviews ran against the code. The first found 14 issues, the largest being that the draft turned setup without a TTY into a server that never exits. The second confirmed all 14 fixed and found 4 more, including a merge gate that could never pass because #103 landed as a squash. All are addressed in the last two commits.

Out of scope: removing the TUI wizard or the usage TUI, HTTP in the daemon, remote access, profile management beyond --profile, and any frontend tooling.

4ndreello and others added 3 commits September 22, 2026 23:09
Define phased requirements, architecture and implementation tasks for the local web console while preserving current terminal and batch contracts.

Co-Authored-By: Codex <noreply@openai.com>
@sonarqubecloud

Copy link
Copy Markdown

@4ndreello
4ndreello merged commit 35555b6 into main Sep 23, 2026
6 of 7 checks passed
@4ndreello
4ndreello deleted the docs/web-console-spec branch September 23, 2026 02:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant