Files
archie/docs/prds/vue-migration-checklist.md
T
sam e832b8ef0c docs(prds): normalise statuses and remove writing dated to its own day
Three defects the first sweep left behind, each caught by a rule the guard
did not yet have.

Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones
were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e).
Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both
changelogs living in the one field the other rules exempt. Every PRD now
declares Draft, Approved or Finalised and nothing else; five that declared
nothing now declare one. A revision number moves to **Revision:**, a pointer
to the authoritative document to **Authority:**, and what a past revision
changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still
resolves.

Stale cross-references. "Supersedes the 2026-09-03 open question", "this
bullet previously said", "an earlier draft of this document claimed" all point
at text the reader cannot see, because it was replaced. A supersede marker
survives only when it names a file, a section or a symbol that can be found.

Temporal hedges. 100 uses of today, currently and right now across 31 files.
Each dates its sentence to the day it was written: "[notify] today is one
webhook URL, read in one place" stops being true the moment this design lands,
while still reading as the premise it rests on.

The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel
resolved 2026-09-22" smuggled a dated status into the one line the rules did
not read; the exemption is now a Date holding only a date and a Status holding
only one of the three.
2026-09-22 00:38:35 +10:00

271 lines
16 KiB
Markdown

# Preact → Vue 3 + shadcn-vue migration checklist
**Status:** Approved
**Date:** 2026-09-20
**Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure)
**Bootstrap commit:** `e18fb8b2`
The Preact dashboard was deleted, not ported incrementally. This is the list of
what has to exist again, what must not be lost on the way, and the contracts
that break silently if missed.
Deleted source is recoverable at `git show e18fb8b2^:ui/src/<path>`. Every
claim below was cross-checked against that tree; where a number is a live
measurement rather than something recoverable from git, it says so.
## Invariants that outlive the framework
These are not features; they are things other processes depend on. Breaking one
does not show up as a broken page.
- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build
must keep unhashed `assets/index.{js,css}`: dist/ lives in git, and
hashed names orphan a file on every rebuild.
- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the
route table and `TestDashboardPagesRegistryCoversEveryRoute` parses
`ui/src/router/index.ts` to hold them in step. The parser needs
`const routes = [` on its own line, `path: "..."` on a single line per
route, and `nav: false` on any entry the registry should skip. That guard
caught a stale `/chat` entry earlier.
- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**
`X-Archie-CSRF: 1` and `Content-Type: application/json`. The server
returns 403 without the first and 415 without the second
(`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends
neither. This is the single most likely thing to silently break every
write after the port.
- [x] **History routing.** `createWebHistory`, `base: "/"`. Legacy `#/path`
links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate
chip should emit `/tasks`; the Go side already stores bare paths.
- [ ] **Capability gating.** `GET /api/capabilities`
(`internal/webui/api_capabilities.go`) returns a `sections` map of ten
booleans: chat, logs, skills, curators, channels, captures, mappings,
bindings, and workflows/settings which are always true. A route whose
section is false must be hidden, not rendered empty. **Fail open**: on a
failed or null response hide nothing — the old client used a bare
`.catch(() => {})` for exactly this. A page that says "unavailable" is
recoverable; a nav entry that vanished is not.
- [ ] **`LOG_LEVELS`** in `base/log-row.jsx` is a wire contract, not a display
list: the CSV level filter is matched server-side by `splitCSV` in
`internal/webui/api_tasks_logs.go`. A value mismatch breaks filtering
with no error.
- [ ] **SSE lifecycle.** Three streams, all `id: <n>\ndata: <json>\n\n` except
chat which omits the id:
`/events` (task lifecycle, `sse.go`, supports `?since=` and
`Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same
resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed
delta/tool/media/navigate). Each must be closed on unmount or the app
leaks a connection per navigation. Preact used an `archie:teardown`
event; Vue should use `onUnmounted`.
> **On tests.** Per Sam's call, the 43-file suite was not ported and tests
> return when there is behaviour worth pinning. Flagging one exception for when
> that moment comes: the deleted `ui/test/api-client.test.js` classified every
> API method as mutation/read/stream/url and asserted the right headers per
> class. It is the only cheap guard on the CSRF contract above. (It did **not**
> text-scan for a second `fetch()` — that check was deliberately removed
> upstream for testing the file's wording rather than its behaviour.)
## Phase 1 — Foundation
- [x] **Theme.** `css/tokens.css` was a complete two-theme semantic token set
(`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Mapped
onto Tailwind v4's `@theme` in `src/style.css`; the second system was not
kept.
- [x] **`color-scheme`.** `[data-theme="dark"] { color-scheme: dark }` and the
light equivalent. Without it the UA paints light scrollbars and light
native controls inside the dark app. Fixed; trivially lost.
- [x] **Contrast values.** The violet palette moved these off the values pinned
here, so they were recomputed against its own backgrounds instead of
carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light
(4.87:1, AA), and `--fg-muted` `#B9AECB` / `#635B6B` (9.28:1 and 5.70:1).
The invariant the pin existed for holds; the values are the palette's.
- [x] **API client** (`base/api.jsx` → `src/lib/api.ts`). Keep `ApiError`
carrying `status`, and the 401/4xx/5xx classification callers branch on
(`classifyActionError`). `GET /api/bindings/{id}` and
`GET /api/mappings/{id}` exist server-side but were never called — do not
add clients for them without a reason.
- [x] **App shell** — the real source is `main.jsx` (410 lines), not just CSS.
Beyond the topbar and outlet it carries:
- [x] **Jump-to search**: Enter navigates to the first nav label matching the
typed prefix; Escape closes the field and calls `preventDefault` so it
does not also close the chat panel, which has its own Escape handler.
- [x] **`soon: true` nav entries** — greyed, labelled, non-navigable. An
affordance, not dead code.
- [x] **`loadTaskMeta()` at boot**, which re-renders the mounted route once
`/api/task-meta` lands so freeze-dried defaults are replaced.
- [x] **Route keying**: keyed on path + params but deliberately **not** the
query string, so a query-only change (a task-detail tab switch) does
not remount and lose state, while two different `:id`s do get fresh
instances.
- [x] `.shell` has `backdrop-filter`, making it a containing block for
`position: fixed` — the chat launcher must render outside it.
- [ ] **CSS inventory.** `layout.css` was reassessed rather than ported whole.
The command bar is a Vue component styled with Tailwind like every other
surface inside the shell, so it emits none of that file's `.topbar`,
`.nav`, `.topbar-search` or `.icon-btn` classes: only the frame those
rules bounded is kept (`body` canvas, `.shell`, `.main`, and the 900px
collapse), and the topbar/nav rules with their 1500px and 1270px
breakpoints were deleted as unconsumed. The command bar's own responsive
behaviour is the components' business, so "port from this file" applies
to the frame and, later, the chat dock, not to class names. Still to
port, when the pages that use them exist: `card.css`
(`.card`/`.grid-2`/`.grid-4`), `page.css`
(`.page-head`/`.page-title`/`.page-sub`/`.page-actions`), `pill.css` (the
ok/warn/danger/info/idle definitions a Badge port must match), and the
chat dock and morph Phases 3 and 5 describe. `base.css`,
`responsive.css` and `_main.css`'s import order are ported.
- [x] **Theme toggle** and its persistence.
## Phase 2 — Shared primitives
| Was | Is |
|---|---|
| `base/pill.jsx` | `Badge`, with five status variants (`ok`, `warn`, `danger`, `info`, `idle`) over the palette's status tokens |
| `base/statTile.jsx` | `base/StatTile.vue`: full `Card` composition (`CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`), `base/Sparkline.vue`, and the `goodDirection` trend logic |
| `base/icons.jsx` | **Not ported as a module.** Its string-keyed lookup is the pattern shadcn-vue's rules name as wrong, so icons come from `@lucide/vue` at the call site |
| `base/gauge.jsx` | `base/Gauge.vue` and `base/SegmentBar.vue`, both ported. The gauge's `aria-label` announces the rounded percentage, which closes `86au` |
| `base/log-row.jsx` | `base/LogRow.vue` over `lib/log.ts` (`LOG_LEVELS`, `levelKind`, `shortTime`, `fmtValue`) |
| `base/format.jsx` | `lib/format.ts` (`ago`, `compact`) |
| `base/task-meta.jsx` | `lib/task-meta.ts`; Vue's reactivity replaces the manual boot-time re-render the Preact module needed |
Two decisions worth not re-litigating:
- The pill's dot did not come across to `Badge`. The Badge's own shape is the
affordance, and the same variant now covers things that are not status pills
(a trend indicator), where a dot reads as noise.
- The five bespoke glyphs (`dashboard`, `mappings`, `bindings`, `curators`,
`memory`) are not drawn yet because nothing consumes them: the navigation is
text with tooltips. If a page needs one, it becomes its own component at that
point rather than a glyph table waiting for a caller.
- [x] **Copy verbatim.** `dashboard/activity-detail.ts`, `chat/command-scroll.ts`,
`workflows/workflow-rows.ts`, `logs/logs-empty.ts`, and `lib/stream-state.ts`.
- [x] `base/uuid.jsx` → `src/lib/uuid.ts`.
- [x] `routing.jsx` is superseded by vue-router. Not ported.
## Phase 3 — Pages
In dependency order. Each is `git show e18fb8b2^:ui/src/<folder>/`. File counts
verified against the deletion diff.
Ported as named components, not as one file per page: see
`docs/prds/dashboard-port-brief.md#componentisation`. A page file composes and
holds nothing, shared state lives in a module beside it, and a lookup that maps
a string to a component is not written.
- [x] **Dashboard.** Health row, Throughput tiles, Token outlook, Live activity
table, the time-of-day `greeting()`, and the click-through from an
activity row to its task. The setup panel branches on the state machine
rather than on "is setup present", which had shown a 100% checklist where
the complete state belongs.
- [x] **Tasks.** List, filters, row actions, detail page with tab bar, stage
rail, changed files, attempt config, task logs, timeline, debug view.
Both interaction contracts survive: detail `tab`/`attempt` is written with
`router.replace` (never a hash, and replace so a tab click adds no history
entry and does not remount), and the list's reduced-motion-aware
scroll-to-row reveal for deep links. `1q89`'s column priority is applied.
One deliberate deviation: the list's inline timeline expansion is gone,
since the row now opens `/tasks/:id` and that page owns the timeline; the
phone layout's stacked cards are not reproduced and the table scrolls
inside its own container instead.
- [ ] **Chat.** In progress.
- [x] **Configuration**, split into the six `/system/*` routes the approved
design names, with the editable-vs-read-only dual mode intact: this
composition serves a published snapshot, so the pages say they are
read-only rather than rendering controls that cannot work.
- [x] **Logs.** Filters, live tail, pause. A 503 on the stream renders as
"Log stream unavailable" with the reason, not as a permanent
"reconnecting".
- [x] **Event inspector / captures.**
- [x] **Field mappings**, including the mapping editor. Its `mappingPreview`
`capture_id` is a number: the wire type is int64 and a JSON string is
rejected.
- [x] **Playbook bindings**, including the binding editor.
- [x] **Workflows**, keeping the "No stage data yet" state and omitting the
Start-work form when the endpoint serves no definitions (`3tij`).
- [x] **Skills**, **Curators**, **Channels.** Capability-gated and hidden on the
reference deployment, so all three were verified by their own empty state.
Every page was rendered against the running daemon at 1440x900 and 720px, with
no horizontal page scroll at either width.
## Phase 4 — Navigation restructure
Approved in `docs/prds/dashboard-navigation-groups.md`; build it during the
port rather than porting the flat bar first.
- [x] Five top-level items: Dashboard, Work, Agent, Events, System.
- [x] Rename under their group: Inspector, Mappings, Bindings.
- [x] Per-item hover tooltips carrying a one-line description.
- [x] Configuration splits into `/system/{status,appearance,tasks,models,repos,advanced}`.
- [x] `/settings` redirects to `/system/status` — it is in bookmarks and in the
Go route registry.
- [x] Add Logs to the nav. It was never in it.
- [x] Preserve the `soon:` entry treatment.
- [x] The theme control moves off the topbar and onto `/system/appearance`. Two
switches for one preference is two places to look and one of them to be
wrong; `components/topbar/ThemeToggle.vue` is deleted, not orphaned.
- [x] Update `dashboard_tools.go` for every new route in the same change. The
registry already carried all sixteen, so its parity test has been passing
throughout; it is the check that a route cannot be added here and
forgotten there.
## Phase 5 — Behaviour a naive port loses
This behaviour exists only in the deleted tree.
The implementation source for nearly all of it is
`git show e18fb8b2^:ui/src/css/layout.css` plus `main.jsx` and `chat/chat.jsx`.
- [ ] **Chat is a FAB, not a route.** No `/chat`, no nav entry, no topbar icon.
- [ ] **The panel grows out of the launcher**: collapsed to a pill over the
button, expanding with scale, border-radius and position interpolating
together; contents fade in after the shape arrives.
- [ ] **No scrim, no scroll lock.** The page stays readable and clickable.
- [ ] **No close button** — the FAB is the only toggle, and stays visible on
mobile where the panel becomes a sheet.
- [ ] Escape closes the panel **and returns focus to the launcher**; the dock
carries `aria-expanded`/`aria-controls`/`aria-hidden`.
- [ ] Header shows the open conversation's name (`panelTitle`).
- [ ] New chat = `message-circle-plus`, in the header.
- [ ] Slash palette is the only command surface; it floats above the input and
scrolls to keep the arrow-key selection visible.
- [ ] Settings popover closes on outside pointerdown and focus-out.
- [ ] Stop renders only while streaming; composer stays writeable and focused
during a send.
- [ ] Bubbles carry no speaker label.
- [ ] **Topbar cannot clip.** The nav is the only shrinkable region; search
collapses below 1500px; nav wraps below 1270px; sheet mode at 720px;
edge-to-edge at 900px. Previously the utility cluster was unreachable
between 1221px and ~1582px: measured at 1440x900, `.topbar-end` ended at
x=1515 against a shell edge of 1409, so 106px carrying the avatar, theme
toggle and documentation button was clipped with no scroll affordance.
That figure is a live measurement, not recoverable from git.
- [ ] **Live activity detail is clamped** to one line with the full payload on
the title. Unclamped it made the dashboard 7,481px tall.
- [ ] **HEALTH cards take their own height** (`align-items: start`).
- [ ] **Workflow rows merge** definitions with statistics.
- [ ] **Log stream reports `unavailable`** from `readyState`, not a permanent
"reconnecting".
- [ ] **Unconfigured capabilities say so** (501 → "Not configured on this
deployment") rather than rendering nothing.
- [ ] **Operator cards on Configuration**: update install/defer, dangerous
action approvals. Both absent when their endpoint 501s.
## Known-open, carry forward
Open beads against the old UI that the port should satisfy rather than
reintroduce: `1q89` (tasks column priority, wrapping row actions), `to2y`
(three empty-state treatments; Field mappings dead-ends), `gl96` (Logs missing
from nav), `86au` (gauge `aria-label` announces an unrounded percentage),
`6m8r` (mobile KPI cards push content below the fold; 89 sub-44px targets),
`ggqo` (config page width — moot once Configuration splits), `3tij`
(`/api/workflows` serves no definitions, so "Start work" never renders),
`oif3` (Reload Telegram, blocked on `ry4k`).
## Not doing
- Porting the 43 test files. Tests return when there is behaviour worth pinning
rather than a port to re-assert. `task test:ui` is a `vue-tsc` typecheck
meanwhile. See the note under Invariants for the one exception worth
reconsidering first.