diff --git a/ui/AGENTS.md b/ui/AGENTS.md new file mode 100644 index 000000000..9fd6a7291 --- /dev/null +++ b/ui/AGENTS.md @@ -0,0 +1,81 @@ +# UI agent rules + +These rules supplement the repository root's AGENTS.md. Its authority, service +boundaries, security invariants, Beads workflow and commit gate still apply. +CLAUDE.md points here so both agents use one policy. + +## Scope + +The dashboard is Vue 3, TypeScript, Pinia and Vue Router, with Tailwind and +vendored shadcn-vue components backed by Reka UI. It talks to the control plane +through src/lib/api.ts. The server owns contracts, authorization and durable +state; the UI presents them and submits operator choices. + +- Fix broken behavior with the smallest complete change. Finish existing + features before adding new ones. Do not add an abstraction or dependency for + a few lines of code. +- Read the affected callers and existing components before editing. Keep + feature state and behavior in its feature folder; shared code must have real + consumers. Do not extract production helpers solely to make them testable. +- Preserve server vocabulary and typed wire values. Do not invent local status, + action or model catalogs when the server supplies them. +- Keep requests in src/lib/api.ts and shared live updates in the existing store. + Preserve its authentication, CSRF, timeout and error handling. +- Keep unavailable, loading, empty and failed states distinct. Show failures + where they occur; an unreadable list must not look like an empty one. +- Async views must discard stale responses after their task, attempt or route + changes. A setting must save through the API and show its applied state. + +## Components and interaction + +- Reuse components/ui and surrounding composition patterns before writing new + markup. Keep vendored components local; use npx shadcn-vue@latest for CLI work + instead of adding the generator and its dependency tree to the application. +- Use semantic theme tokens, existing variants and cn() for conditional classes. + Support both themes, compact density and reduced motion. +- Keep controls compact and contextual. Use on-demand panels and inline + hover/focus icon actions rather than permanent chrome. Do not repeat labels + in explanatory text or add controls without working behavior. +- Preserve keyboard operation, visible focus, accessible names, dialog titles + and table semantics. A hover action must also be reachable by keyboard. +- Keep filtering and pagination consistent with the server. State limitations + such as sorting only loaded rows when they affect the operator's decision. + +## Tests + +The default is no new test. Add one for a reproduced bug or a change to a +security boundary or workflow contract, following the root policy. A regression +must fail on the relevant assertion before the fix. + +- Test observable behavior with realistic inputs. Do not test source text, + imports, wiring, constants, defaults, type shapes, CSS classes, copied labels, + fakes or call order. A fake may support a behavior test; it is not the subject. +- Use one table-driven test per behavior. Extend its cases rather than adding + tests for each branch. Retain meaningful edge cases; reducing the count alone + is not a cleanup. +- Keep tests fast and cheap to maintain. Test helpers and fixtures belong in + test/, never in production code solely for tests. +- For mirrored control-plane validators, extend the shared fixture at + internal/app/controlplane/testdata/dashboard-validators.json rather than + duplicating accept/reject cases in UI-only tests. +- Use browser checks for rendered behavior. Matching a Vue file with a regex + does not verify what the user sees. Mocked API checks verify UI behavior, not + live service integration; report that distinction. + +## Verification and delivery + +```bash +npm test # behavior tests +npm run typecheck # TypeScript and Vue checks +npm run build # rebuild the embedded dashboard +npm audit # after dependency changes +``` + +- Run task check from the repository root before committing; stage only the + task's own paths. Follow the root's commit and push rules. +- ui/dist is embedded and committed. Regenerate it for source changes; never + edit it by hand. Test-only edits do not need new dashboard assets. +- Reuse a running dev server for browser checks. Verify changed interactions, + not just a screenshot or successful HTTP response. +- Track work and follow-ups in Beads. Keep rules here only when they change a + decision; do not add task history or Markdown TODO lists. diff --git a/ui/CLAUDE.md b/ui/CLAUDE.md new file mode 120000 index 000000000..47dc3e3d8 --- /dev/null +++ b/ui/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/ui/test/activity-group.test.ts b/ui/test/activity-group.test.ts index 55f9c193d..2f7083e44 100644 --- a/ui/test/activity-group.test.ts +++ b/ui/test/activity-group.test.ts @@ -1,107 +1,27 @@ import assert from "node:assert/strict"; import test from "node:test"; - -const { groupActivity, groupKey } = - await import("../src/dashboard/activity-group.ts"); - +import { groupActivity } from "../src/dashboard/activity-group.ts"; import type { ActivityEvent } from "../src/dashboard/state.ts"; -function ev( - kind: string, - taskID: number | undefined, - detail: string, - at = 1000, -): ActivityEvent { - return { kind, task_id: taskID, detail, at }; -} +const event = (kind: string, task_id: number | undefined, detail: string): ActivityEvent => + ({ kind, task_id, detail, at: 1000 }); -test("consecutive events sharing detail and task collapse into one group", () => { - const events = [ - ev("session-memory", undefined, "cycle 9"), - ev("session-memory", undefined, "cycle 9"), - ev("session-memory", undefined, "cycle 9"), +test("activity groups only consecutive events with the same detail and task", () => { + const cases: Array<{ name: string; events: ActivityEvent[]; counts: number[] }> = [ + { name: "repeated detail", events: [event("memory", undefined, "cycle"), event("memory", undefined, "cycle")], counts: [2] }, + { name: "different details", events: [event("stage", 7, "build"), event("stage", 7, "plan")], counts: [1, 1] }, + { name: "singleton", events: [event("stage", 7, "build")], counts: [1] }, + { name: "different tasks", events: [event("stage", 7, "build"), event("stage", 9, "build")], counts: [1, 1] }, + { name: "interleaved kinds", events: [event("curator", 7, "cycle"), event("memory", 7, "cycle")], counts: [2] }, + { name: "separated repeats", events: [event("stage", 7, "build"), event("stage", 9, "build"), event("stage", 7, "build")], counts: [1, 1, 1] }, + { name: "missing kind", events: [{ detail: "a", at: 1000 }, { detail: "a", at: 1001 }], counts: [2] }, ]; - const groups = groupActivity(events); - assert.equal(groups.length, 1); - assert.equal(groups[0].count, 3); - // The newest event (first in the feed) represents the group. - assert.equal(groups[0].representative.detail, "cycle 9"); - assert.equal(groups[0].events.length, 3); -}); - -test("the same kind with different details does not collapse", () => { - const events = [ - ev("stage_finished", 7, "build"), - ev("stage_finished", 7, "plan"), - ]; - const groups = groupActivity(events); - assert.equal(groups.length, 2); -}); - -test("a singleton stays a plain one-count group", () => { - const groups = groupActivity([ev("stage_finished", 7, "build")]); - assert.equal(groups.length, 1); - assert.equal(groups[0].count, 1); - assert.equal(groups[0].events.length, 1); -}); - -test("a different task breaks the run", () => { - const events = [ - ev("runner_run", 7, "a"), - ev("runner_run", 9, "b"), - ev("runner_run", 7, "c"), - ]; - const groups = groupActivity(events); - assert.equal(groups.length, 3); - for (const group of groups) assert.equal(group.count, 1); -}); - -test("a different kind breaks the run when the detail differs", () => { - const events = [ - ev("session-memory", undefined, "a"), - ev("runner_run", undefined, "b"), - ev("session-memory", undefined, "c"), - ]; - const groups = groupActivity(events); - assert.equal(groups.length, 3); -}); - -test("an interleave of kinds sharing one detail and task collapses", () => { - // A background cycle emits one event per internal step; the kinds differ - // but the cycle is one run of noise. - const events = [ - ev("curator_action", undefined, "session-memory"), - ev("session-memory", undefined, "session-memory"), - ev("curator_run", undefined, "session-memory"), - ev("curator_action", undefined, "session-memory"), - ]; - const groups = groupActivity(events); - assert.equal(groups.length, 1); - assert.equal(groups[0].count, 4); - assert.equal(groups[0].label, "curator_action"); -}); - -test("the same detail on a different task breaks the run", () => { - const events = [ - ev("runner_run", 7, "building"), - ev("runner_run", 9, "building"), - ]; - const groups = groupActivity(events); - assert.equal(groups.length, 2); -}); - -test("a missing kind resolves to the same label an unset row shows", () => { - const events: ActivityEvent[] = [ - { detail: "a", at: 1000 }, - { detail: "a", at: 1001 }, - ]; - const groups = groupActivity(events); - assert.equal(groups.length, 1); - assert.equal(groups[0].label, "event"); -}); - -test("groupKey separates detail and task", () => { - assert.notEqual(groupKey("runner_run", 7), groupKey("runner_run", 9)); - assert.equal(groupKey("runner_run", 7), groupKey("runner_run", 7)); - assert.equal(groupKey("runner_run", 0), groupKey("runner_run", undefined)); + for (const { name, events, counts } of cases) { + const groups = groupActivity(events); + assert.deepEqual(groups.map((group) => group.count), counts, name); + assert.deepEqual(groups.flatMap((group) => group.events), events, `${name}: preserve order and every event`); + for (const group of groups) { + assert.equal(group.representative, group.events[0], `${name}: newest event represents its group`); + } + } }); diff --git a/ui/test/byte-size-input.test.ts b/ui/test/byte-size-input.test.ts index 5eae285f4..dbf674e57 100644 --- a/ui/test/byte-size-input.test.ts +++ b/ui/test/byte-size-input.test.ts @@ -2,7 +2,6 @@ import assert from "node:assert/strict"; import test from "node:test"; import { - BYTES_PER_MB, bytesToMB, mbToBytes, } from "../src/components/ui/byte-size-input/bytes.ts"; @@ -11,7 +10,6 @@ import { // as whole bytes. A binary interpretation (2^20) would inflate every stored // value by ~4.9%: ten entered megabytes would become 10_485_760 bytes. test("entered megabytes store as whole decimal bytes", () => { - assert.equal(BYTES_PER_MB, 1_000_000); assert.equal(mbToBytes(10), 10_000_000); assert.equal(mbToBytes(0.1), 100_000); assert.equal(mbToBytes(1.5), 1_500_000); @@ -39,4 +37,4 @@ test("the byte count survives a display round trip unchanged", () => { for (const bytes of stored) { assert.equal(mbToBytes(bytesToMB(bytes)), bytes, `round trip of ${bytes}`); } -}); \ No newline at end of file +}); diff --git a/ui/test/chat-attachment.test.ts b/ui/test/chat-attachment.test.ts index dd7662f4c..6e1b94610 100644 --- a/ui/test/chat-attachment.test.ts +++ b/ui/test/chat-attachment.test.ts @@ -1,13 +1,8 @@ import assert from "node:assert/strict"; -import { readFile } from "node:fs/promises"; import test from "node:test"; import { mediaDetail, mediaLabel, type ChatMedia } from "../src/chat/attachment.ts"; -// The transcript cannot show an attachment's bytes -- they are turn-scoped and -// never reach a browser -- so the label is the entire rendering. It reuses the -// placeholder vocabulary the channels write into a message's text, so a photo -// reads the same whether its metadata survived or only its note did. test("an attachment is labelled in the channel's own placeholder vocabulary", () => { const cases: Array<[ChatMedia, string]> = [ [{ type: "image", mime_type: "image/jpeg" }, "[photo]"], @@ -23,9 +18,6 @@ test("an attachment is labelled in the channel's own placeholder vocabulary", () } }); -// The label says what arrived; the detail says what is known about it, which -// is the metadata persistence kept. Nothing here is fetchable, and nothing -// here is invented from a file id. test("the detail names the metadata that survived persistence", () => { assert.equal( mediaDetail({ @@ -41,33 +33,3 @@ test("the detail names the metadata that survived persistence", () => { assert.equal(mediaDetail({ type: "audio", duration: 12 }), "12 s"); assert.equal(mediaDetail({ type: "document" }), ""); }); - -// A file id is a platform download handle, not an address: a chip that linked -// it would 404. The chip links out only when the attachment itself carried a -// URL, and the transcript reaches the label and the URL through this module. -test("the transcript renders attachments from metadata, never from a file id", async () => { - const chip = await readFile( - new URL("../src/chat/ChatAttachment.vue", import.meta.url), - "utf8", - ); - assert.match(chip, /mediaLabel\(attachment\)/, "the chip shows the label"); - assert.match(chip, /mediaDetail\(attachment\)/, "the chip carries the metadata detail"); - assert.match(chip, /:href="attachment\.url"/, "the only link target is a URL the attachment had"); - assert.doesNotMatch(chip, /file_?id/i, "a file id is a handle, not a link target"); - - const bubble = await readFile( - new URL("../src/chat/ChatBubble.vue", import.meta.url), - "utf8", - ); - assert.match(bubble, /ChatAttachment/, "the bubble renders the attachment chips"); - - const transcript = await readFile( - new URL("../src/chat/ChatTranscript.vue", import.meta.url), - "utf8", - ); - assert.match( - transcript, - /media: message\.media \|\| \[\]/, - "a recorded message's attachments reach the bubble", - ); -}); diff --git a/ui/test/connection.test.ts b/ui/test/connection.test.ts deleted file mode 100644 index 8ae340b30..000000000 --- a/ui/test/connection.test.ts +++ /dev/null @@ -1,15 +0,0 @@ -import assert from "node:assert/strict"; -import test from "node:test"; - -import { connectionStatus } from "../src/lib/connection.ts"; - -test("the connection pill names the stream state", () => { - for (const [state, label, tone] of [ - ["live", "Connected", "ok"], - ["connecting", "Connecting", "warn"], - ["reconnecting", "Connecting", "warn"], - ["unavailable", "Disconnected", "danger"], - ] as const) { - assert.deepEqual(connectionStatus(state), { label, tone }, state); - } -}); diff --git a/ui/test/container-runtime-keys.test.ts b/ui/test/container-runtime-keys.test.ts deleted file mode 100644 index 888c7ba0f..000000000 --- a/ui/test/container-runtime-keys.test.ts +++ /dev/null @@ -1,54 +0,0 @@ -import assert from "node:assert/strict"; -import { readFile } from "node:fs/promises"; -import test from "node:test"; - -/** - * The keys of the container-runtime-policies document. - * - * internal/app/controlplane/containerRuntimePolicies owns this shape and - * normalises every stored document to it (archie-core-qna6). These are the keys - * the control plane serves, so they are the keys the page must bind. - */ -const documentKeys = [ - "image", - "max_concurrency", - "max_uptime", - "volume_ttl", - "pull_policy", - "network", -]; - -/** The Go-cased spellings the wire carried before archie-core-qna6. */ -const retiredKeys = ["Image", "MaxConcurrency", "MaxUptime", "VolumeTTL", "PullPolicy", "Network"]; - -test("the container runtime page binds the document's own keys", async () => { - const page = await readFile( - new URL("../src/settings/ContainerRuntimePage.vue", import.meta.url), - "utf8", - ); - // Only the template binds fields; the script's own reads go through the - // `runtime` ref, whose `.value` is not a document key. - const template = page.slice(page.indexOf("