git-ents.gitmain
⌘K
foforge
web-workbench-plan.adoc5.5 KBhistorycomment on this file

Web Workbench Plan

Redesign and feature plan for ents-web (and its seams into serve, the CLI, and ents-lens), agreed 2026-07-13. Direction: the "workbench" (Proposal C) — git ents serve is git status for review and ticketing, a view command, not a place. The editor (Zed via ents-lens) is the primary surface; the web page is a one-click escalation, and the two deep-link at each other. Features that only make sense in "a place" (presence, notifications, out-of-repo state) are off-thesis.

Visual iteration happens in the owner’s claude.ai/design project ("Design System"), seeded from the real ents.css with three shell proposals and two full-page workbench mocks (pages/workbench-dashboard.html, pages/workbench-code.html; sources under /tmp/ents-design). Implementation of Phase C waits for that iteration to settle, because the rail-and-panes shell restructures pages::layout enough that landing page-level work first means doing it twice.

Decision gates (owner)

  • Design settlement — pick/refine the workbench shell in Claude Design; Phase C starts after.

  • Mergeweb-ui-polish (six commits, gates green) into the phase branch; the agent worktree and the two dev servers (ports 4880/4881) are cleaned up then.

Phase A: independent substance (no shell dependency)

Parallel-safe, each its own commit; land on web-ui-polish or a successor branch.

  • serve prints http://<repo-dir>.localhost:<port> instead of 127.0.0.1*.localhost resolves in-browser (RFC 6761) and is a secure context, so no hosts file, no DNS, no "Not secure" chip. Verified live 2026-07-13. Safari caveat documented (system resolver; one /etc/hosts line). Opening the browser is Phase D’s --web work.

  • Fix the commit diff view repeating every subdirectory as its own entry in the changed-file list.

  • Effect adder: form + POST route (there is currently no way to add an effect from the web).

  • Toolchain importer: form + POST route mirroring the CLI recipe flow.

  • Key-for-<member-id>: <oid> trailer written by comment-resolve mutations, binding the resolver’s member id to their key blob oid at resolve time (provenance in the chain). Receive/model work + spec rule + Tracey coverage; surfaces later in the UI as provenance display.

  • Member autocomplete: a datalist/endpoint over refs/meta/member/* usable by forms now and the palette later (complete by id or name).

  • Parity fixes deferred from the unreadable-entities work: CLI and lens comment list paths still skip unreadables silently; forge NotFound on web detail pages still maps to HTTP 500.

Phase B: verdict enum

Decided 2026-07-13: reviews get a hard enum verdict in the model (unlike issue/comment state, which stays an open vocabulary). Replace the review form’s datalist with a strict select over the variants; update model.review docs/spec accordingly; migrate any existing review data forward manually (no legacy read path, per repo policy).

Phase C: workbench shell (after design settlement)

  • Replace the tab shell in pages::layout with the icon rail (Dashboard / Code / Review / Tickets / Threads; governance and account at the rail’s bottom) plus top bar: repo name, branch pill, search box (palette placeholder), identity chip.

  • Master–detail panes, SSR-friendly (every selection is a real URL; the list pane always renders): file tree left / padded blob right; commits list left / diff right; tickets list left / ticket + in-pane composer right (replaces the separate new-issue page).

  • Dashboard (home): working-tree lane (changed files with +/− stats via gix status, snapshot action), needs-attention feed (unresolved threads, reviews awaiting the signer’s verdict), open tickets, history with Scoped-Commits scope chips colored per scope.

  • Theme pass: brighter surfaces both schemes (per the mocks' proposal-c.css), content padding on blob/diff panes, SSH keys as an identity card (key type badge, fingerprint, truncated middle) instead of a table row.

Phase D: tool-not-app verbs

Decided 2026-07-13: --web is a global git ents option, not a per-subcommand verb.

  • git ents --web standalone opens the homepage — the Dashboard.

  • Any read operation with --web (commits, issue show 42, members list, …​) opens the corresponding page instead of printing.

  • Any mutating operation with --web performs the mutation exactly as the CLI does (same signing, same gate), then opens the resulting entity’s page — --web never moves a mutation into the browser.

  • Serve lifecycle: reuse a running instance if one answers for this repo on the expected port; otherwise spawn detached. A --web-spawned serve exits after an idle timeout (a foreground git ents serve never does), keeping the view-command promise.

  • Mutating CLI commands print the localhost URL of what they created even without --web.

  • --app flag: open in the browser’s chromeless app-mode window.

  • Deep links both ways: web line numbers link zed:// (or zed path:line); ents-lens gains an "open in browser" code action per thread.

Phase E: palette

⌘K jump-to endpoint over files, commits, tickets, members (reuses Phase A autocomplete); progressive enhancement over the search box — the real "menu" of the workbench.

Gates

Per repo convention: cargo nextest run (workspace), clippy clean, fmt, Tracey coverage for any spec-rule additions (Phase A trailer, Phase B vocabulary), visual verification via headless Firefox screenshots against a running serve before commit.