@cueloop/client 0.1.0-alpha.3 → 0.1.0-alpha.30

package/src/App.test.tsx

@@ -1,8 +1,4 @@
-/**
- * Virtual-terminal component tests (tier 2): the real App over a real
- * in-process daemon in a temp home. Char-frame assertions + mock keys -
- * the whole review loop drivable without a terminal.
- */
+/** Virtual-terminal component tests (tier 2): the real App over a real in-process daemon in a temp home. Char-frame assertions + mock keys - the whole review loop drivable without a terminal. */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
@@ -13,6 +9,7 @@ import { testRender } from "@opentui/react/test-utils";
 import { DaemonServer } from "@cueloop/daemon";
 import type { ReviewSession } from "@cueloop/schema";
 import { App } from "./App";
+import { press, typeText as type, waitForState, waitForText } from "./test-support";
 
 const PLAN = `# Migration Plan
 
@@ -49,78 +46,72 @@ async function renderApp(sessionId?: string) {
     width: 120,
     height: 32,
   });
-  // let the async daemon connect + first fetch land
-  for (let i = 0; i < 40 && !setup.captureCharFrame().includes("cueloop"); i++) {
-    await Bun.sleep(25);
-    await setup.renderOnce();
-  }
-  await setup.renderOnce();
+  // the async daemon connect + first fetch land within the frame wait
+  await waitForText(setup, "cueloop");
   return setup;
 }
 
-type Setup = Awaited<ReturnType<typeof renderApp>>;
-
-/** Drive one key press: letters type as text; named keys use KeyCodes ids. */
-async function press(setup: Setup, k: string): Promise<void> {
-  if (k === "enter") setup.mockInput.pressKey("RETURN");
-  else if (k === "escape") setup.mockInput.pressKey("ESCAPE");
-  else if (k === "backspace") setup.mockInput.pressKey("BACKSPACE");
-  else if (k === "left") setup.mockInput.pressKey("ARROW_LEFT");
-  else if (k === "right") setup.mockInput.pressKey("ARROW_RIGHT");
-  else await type(setup, k);
-  await Bun.sleep(15);
-  await setup.renderOnce();
-}
-
-async function type(setup: Setup, text: string): Promise<void> {
-  await setup.mockInput.typeText(text);
-  await Bun.sleep(15);
-  await setup.renderOnce();
-}
-
 describe("plan rendering", () => {
   test("renders the plan with headings, list markers, and the rail", async () => {
+    // Arrange
     const setup = await renderApp();
+
+    // Assert
     const frame = setup.captureCharFrame();
     expect(frame).toContain("Migration Plan");
     expect(frame).toContain("Context");
     expect(frame).toContain("persists sessions to disk atomically");
     expect(frame).toContain("- move the store");
-    expect(frame).toContain("REVIEW (0)");
+    expect(frame).toContain("Review (0)");
     expect(frame).toContain("Submit review (0)");
   });
 });
 
 describe("keyboard grammar", () => {
   test("j/k moves the cursor glyph between blocks", async () => {
+    // Arrange
     const setup = await renderApp();
+
+    // Act
     await press(setup, "j");
     await press(setup, "j");
     await setup.renderOnce();
+
+    // Assert
     const lines = setup.captureCharFrame().split("\n");
-    const cursorLine = lines.find((l) => l.includes("▎"))!;
+    const cursorLine = lines.find((line) => line.includes("▎"))!;
     expect(cursorLine).toContain("persists sessions");
   });
 
   test("comment flow: c types a body, ⏎ saves to the daemon", async () => {
+    // Arrange
     const setup = await renderApp();
+
+    // Act
     await press(setup, "j");
     await press(setup, "j");
     await press(setup, "c");
     await setup.renderOnce();
-    expect(setup.captureCharFrame()).toContain("COMMENT ON");
+
+    // Assert
+    await waitForText(setup, 'comment on "The daemon');
+
+    // Act
     await type(setup, "Define atomically.");
     await press(setup, "enter");
-    await Bun.sleep(80);
-    await setup.renderOnce();
+
+    // Assert
+    await waitForText(setup, "COMMENT");
     const stored = server.core.sessionGet(session.id);
     expect(stored.annotations.length).toBe(1);
     expect(stored.annotations[0]!.body).toBe("Define atomically.");
-    expect(setup.captureCharFrame()).toContain("COMMENT");
   });
 
   test("span mode: v + l selects words, c anchors the exact span", async () => {
+    // Arrange
     const setup = await renderApp();
+
+    // Act
     await press(setup, "j");
     await press(setup, "j");
     await press(setup, "v");
@@ -128,24 +119,31 @@ describe("keyboard grammar", () => {
     await press(setup, "c");
     await type(setup, "Which daemon?");
     await press(setup, "enter");
-    await Bun.sleep(80);
+
+    // Assert
+    await waitForState(setup, () => server.core.sessionGet(session.id).annotations.length === 1);
     const stored = server.core.sessionGet(session.id);
     expect(stored.annotations[0]!.anchor.quote).toBe("The daemon");
   });
 
   test("x cuts a block into the working copy; x restores it", async () => {
+    // Arrange
     const setup = await renderApp();
     // move to "- move the store" (h1, h2, p, h2 = 4 steps in)
     for (let i = 0; i < 4; i++) await press(setup, "j");
+
+    // Act
     await press(setup, "x");
-    await Bun.sleep(80);
-    await setup.renderOnce();
+
+    // Assert
+    await waitForText(setup, "[cut]");
     expect(server.core.sessionGet(session.id).workingCopy).not.toContain("move the store");
-    expect(setup.captureCharFrame()).toContain("[cut]");
+
+    // Act
     await press(setup, "x");
-    await Bun.sleep(80);
-    await setup.renderOnce();
-    expect(server.core.sessionGet(session.id).workingCopy).toBeUndefined();
+
+    // Assert
+    await waitForState(setup, () => server.core.sessionGet(session.id).workingCopy === undefined);
   });
 
   test("e runs $EDITOR on the working copy and tracks the diff", async () => {
@@ -154,12 +152,15 @@ describe("keyboard grammar", () => {
     Bun.spawnSync(["chmod", "+x", script]);
     process.env.CUELOOP_EDITOR = script;
     try {
+      // Arrange
       const setup = await renderApp();
+
+      // Act
       await press(setup, "e");
-      await Bun.sleep(150);
-      await setup.renderOnce();
+
+      // Assert
+      await waitForText(setup, "[edited]");
       expect(server.core.sessionGet(session.id).workingCopy).toContain("very atomically");
-      expect(setup.captureCharFrame()).toContain("[edited]");
     } finally {
       delete process.env.CUELOOP_EDITOR;
     }
@@ -167,51 +168,69 @@ describe("keyboard grammar", () => {
 });
 
 describe("submit", () => {
-  test("⏎ opens the verdict bar; verdict + summary resolve the session", async () => {
+  test("⏎ opens the rail confirm card; verdict + summary resolve the session", async () => {
+    // Arrange
     const setup = await renderApp();
     await press(setup, "j");
     await press(setup, "j");
     await press(setup, "c");
     await type(setup, "Needs a phase list.");
     await press(setup, "enter");
-    await Bun.sleep(80);
+    await waitForText(setup, "Review (1)");
+
+    // Act
     await press(setup, "enter"); // open submit
-    await setup.renderOnce();
-    expect(setup.captureCharFrame()).toContain("[Request changes]");
+
+    // Assert
+    await waitForText(setup, "[Changes]");
+
+    // Act
     await type(setup, "Expand the steps.");
     await press(setup, "enter");
-    await Bun.sleep(120);
-    await setup.renderOnce();
+
+    // Assert
+    await waitForText(setup, "feedback sent");
     const stored = server.core.sessionGet(session.id);
     expect(stored.status).toBe("resolved");
     expect(stored.verdict!.kind).toBe("request_changes");
     expect(stored.verdict!.feedback).toContain("Needs a phase list.");
-    expect(setup.captureCharFrame()).toContain("resolved: request changes");
+    // submit hands the reviewer back to the agent via the completion overlay
+    expect(setup.captureCharFrame()).toContain("feedback sent");
   });
 
   test("approve via ←/→ verdict cycling", async () => {
+    // Arrange
     const setup = await renderApp();
+
+    // Act
     await press(setup, "enter");
-    await setup.renderOnce();
-    expect(setup.captureCharFrame()).toContain("[Approve]"); // no pending items → approve default
+
+    // Assert
+    await waitForText(setup, "[Approve]"); // no pending items → approve default
+
+    // Act
     await press(setup, "enter");
-    await Bun.sleep(120);
+
+    // Assert
+    await waitForState(setup, () => server.core.sessionGet(session.id).verdict !== undefined);
     expect(server.core.sessionGet(session.id).verdict!.kind).toBe("approve");
   });
 });
 
 describe("inbox", () => {
   test("inbox mode renders and opens a session", async () => {
+    // Arrange
     const setup = await testRender(<App home={home} />, { width: 120, height: 32 });
-    for (let i = 0; i < 40 && !setup.captureCharFrame().includes("inbox"); i++) {
-      await Bun.sleep(25);
-      await setup.renderOnce();
-    }
+    await waitForText(setup, "inbox");
+
+    // Assert
     expect(setup.captureCharFrame()).toContain("inbox (1 pending)");
     expect(setup.captureCharFrame()).toContain("Migration Plan");
+
+    // Act
     await press(setup, "enter");
-    await Bun.sleep(80);
-    await setup.renderOnce();
-    expect(setup.captureCharFrame()).toContain("Submit review (0)");
+
+    // Assert
+    await waitForText(setup, "Submit review (0)");
   });
 });

package/src/App.walk.test.tsx

@@ -0,0 +1,265 @@
+/** The guided walk in the virtual terminal: the wizard steps every changed file with a plain progress title, ] marks viewed and persists with the session, esc keeps progress, w resumes at the first unviewed file (across App instances via the daemon round-trip), the agent-note block renders only for files carrying a note, and the end card hands over to the submit confirm with the honest viewed count. */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { DaemonServer } from "@cueloop/daemon";
+import type { ReviewSession } from "@cueloop/schema";
+import { App } from "./App";
+import { DARK } from "./theme";
+import { press, waitForState, waitForText, waitForTextGone } from "./test-support";
+
+const PATCH = `diff --git a/src/a.ts b/src/a.ts
+index 111..222 100644
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,2 +1,2 @@
+ export const a = 1;
+-export const b = 2;
++export const b = 3;
+diff --git a/src/b.ts b/src/b.ts
+index 333..444 100644
+--- a/src/b.ts
++++ b/src/b.ts
+@@ -1,2 +1,2 @@
+ // header
+-old line
++new line
+diff --git a/src/c.ts b/src/c.ts
+index 555..666 100644
+--- a/src/c.ts
++++ b/src/c.ts
+@@ -1,1 +1,2 @@
+ keep
++added tail
+`;
+
+let home: string;
+let server: DaemonServer;
+let session: ReviewSession;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-walk-"));
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  session = server.core.sessionCreate({
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "diff", content: PATCH, meta: { title: "working tree" } },
+  });
+});
+afterEach(() => {
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+async function renderApp() {
+  const setup = await testRender(<App home={home} sessionId={session.id} />, { width: 120, height: 34 });
+  // Wait for session content, not just the chrome: pressing w before the diff
+  // loads drops the walk intent (no session, no diff view) and hangs the test.
+  await waitForText(setup, "src/a.ts");
+  return setup;
+}
+
+type Setup = Awaited<ReturnType<typeof renderApp>>;
+
+/** Foreground colors (hex) of every styled span containing the needle. */
+function foregroundsOf(setup: Setup, needle: string): string[] {
+  const foregrounds: string[] = [];
+  for (const line of setup.captureSpans().lines) {
+    for (const span of line.spans) {
+      if (!span.text.includes(needle)) continue;
+      const [red, green, blue] = span.fg.toInts();
+      foregrounds.push("#" + [red, green, blue].map((part) => part.toString(16).padStart(2, "0")).join(""));
+    }
+  }
+  return foregrounds;
+}
+
+describe("the guided walk", () => {
+  test("w walks all three files: progress title, persisted marks, end card, submit hand-over", async () => {
+    // Arrange
+    const setup = await renderApp();
+
+    // Act
+    await press(setup, "w");
+
+    // Assert
+    await waitForText(setup, "file 1 of 3 · 0 viewed");
+    expect(setup.captureCharFrame()).toContain("src/a.ts");
+    expect(setup.captureCharFrame()).toContain("+1 -1");
+
+    // Act
+    await press(setup, "]");
+
+    // Assert
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+    // the viewed mark rides the session record, not the client
+    await waitForState(setup, () => (server.core.sessionGet(session.id).viewedPaths ?? []).includes("src/a.ts"));
+
+    // Act
+    // [ steps back; the revisited card shows its viewed marker
+    await press(setup, "[");
+
+    // Assert
+    await waitForText(setup, "file 1 of 3 · 1 viewed");
+    expect(setup.captureCharFrame()).toContain("· viewed");
+
+    // Act
+    await press(setup, "]");
+
+    // Assert
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+
+    // Act
+    await press(setup, "]");
+
+    // Assert
+    await waitForText(setup, "file 3 of 3 · 2 viewed");
+
+    // Act
+    await press(setup, "]");
+
+    // Assert
+    await waitForText(setup, "walk complete");
+    expect(setup.captureCharFrame()).toContain("every file viewed (3/3)");
+    expect(server.core.sessionGet(session.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
+
+    // Act
+    // the end card's return leaves the walk and opens the rail confirm
+    await press(setup, "enter");
+
+    // Assert
+    await waitForText(setup, "submit review");
+    expect(setup.captureCharFrame()).toContain("3/3 files viewed");
+
+    // Act
+    await press(setup, "enter");
+
+    // Assert
+    await waitForState(setup, () => server.core.sessionGet(session.id).status === "resolved");
+  });
+
+  test("esc keeps progress and w resumes at the first unviewed file", async () => {
+    // Arrange
+    const setup = await renderApp();
+    await press(setup, "w");
+    await waitForText(setup, "file 1 of 3 · 0 viewed");
+    await press(setup, "]");
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+
+    // Act
+    await press(setup, "escape");
+
+    // Assert
+    await waitForTextGone(setup, "file 2 of 3");
+    // the sheet is back at full strength: no wizard card on screen
+    expect(setup.captureCharFrame()).not.toContain("· 1 viewed");
+
+    // Act
+    await press(setup, "w");
+
+    // Assert
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+  });
+
+  test("a half-walked review resumes across App instances via the daemon", async () => {
+    // Arrange
+    const first = await renderApp();
+    await press(first, "w");
+    await waitForText(first, "file 1 of 3 · 0 viewed");
+    await press(first, "]");
+    await press(first, "]");
+    await waitForText(first, "file 3 of 3 · 2 viewed");
+    await waitForState(first, () => (server.core.sessionGet(session.id).viewedPaths ?? []).length === 2);
+    first.renderer.destroy();
+
+    // Act
+    // a fresh client reads the viewed set back from the session record
+    const second = await renderApp();
+    await press(second, "w");
+
+    // Assert
+    await waitForText(second, "file 3 of 3 · 2 viewed");
+    expect(second.captureCharFrame()).toContain("src/c.ts");
+    // two full App boots with daemon round-trips need more than the default
+    // budget, and the whole-suite publish lane has timed even 15s out; give the
+    // double-boot chain generous headroom so runner load cannot flake it.
+  }, 30_000);
+
+  test("the agent-note block renders only for files carrying a note", async () => {
+    // Arrange
+    server.core.sessionAnnotate(session.id, {
+      id: "note-b",
+      kind: "note",
+      anchor: { quote: "src/b.ts", prefix: "", suffix: "" },
+      body: "Swaps the stale line for the new constant.",
+    });
+    const setup = await renderApp();
+
+    // Act
+    await press(setup, "w");
+
+    // Assert
+    await waitForText(setup, "file 1 of 3");
+    expect(setup.captureCharFrame()).not.toContain("agent note");
+
+    // Act
+    await press(setup, "]");
+
+    // Assert
+    await waitForText(setup, "agent note");
+    expect(setup.captureCharFrame()).toContain("Swaps the stale line for the new constant.");
+
+    // Act
+    // a note is agent context, not reviewer feedback: it neither counts nor
+    // flips the default verdict, and never comes back in the feedback doc
+    await press(setup, "escape");
+    await waitForTextGone(setup, "agent note");
+    await press(setup, "enter");
+    await waitForText(setup, "0 annotations");
+    await press(setup, "enter");
+
+    // Assert
+    await waitForState(setup, () => server.core.sessionGet(session.id).status === "resolved");
+    const resolved = server.core.sessionGet(session.id);
+    expect(resolved.verdict!.kind).toBe("approve");
+    expect(resolved.verdict!.feedback).not.toContain("Swaps the stale line");
+  });
+
+  test("the sheet dims behind the wizard; the preview keeps the diff colors", async () => {
+    // Arrange
+    const setup = await renderApp();
+
+    // Assert
+    // before the walk the sheet's added line wears the insertion color
+    await waitForText(setup, "+new line");
+    expect(foregroundsOf(setup, "+new line")).toContain(DARK.insFg);
+
+    // Act
+    await press(setup, "w");
+
+    // Assert
+    await waitForText(setup, "file 1 of 3 · 0 viewed");
+    // dimmed: the sheet line drops to the dim token...
+    expect(foregroundsOf(setup, "+new line")).toEqual([DARK.textDim]);
+    // ...while the wizard preview keeps the insertion color
+    expect(foregroundsOf(setup, "+export const b = 3;")).toContain(DARK.insFg);
+  });
+
+  test("walking a resolved review answers read-only", async () => {
+    // Arrange
+    server.core.sessionResolve(session.id, "approve", "");
+    const setup = await renderApp();
+    await waitForText(setup, "resolved");
+
+    // Act
+    await press(setup, "w");
+
+    // Assert
+    await waitForText(setup, "review submitted - read-only");
+    expect(setup.captureCharFrame()).not.toContain("file 1 of 3");
+  });
+});

package/src/attribution.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import type { Identity } from "@cueloop/schema";
+import { ANONYMOUS_LABEL, resolveDisplayName, shortHandle } from "./attribution";
+
+describe(shortHandle, () => {
+  test("shortens an ssh fingerprint to a stable handle", () => {
+    // Arrange / Act / Assert
+    expect(shortHandle("SHA256:1a2b3c4d5e6f")).toBe("1a2b3c4d");
+    expect(shortHandle("SHA256:1a2b3c4d5e6f")).toBe(shortHandle("SHA256:1a2b3c4d5e6f"));
+  });
+});
+
+describe(resolveDisplayName, () => {
+  const named: Identity[] = [{ id: "SHA256:abc", provider: "ssh", name: "Al" }];
+  const unnamed: Identity[] = [{ id: "SHA256:abc", provider: "ssh" }];
+
+  test("a local rename override wins over everything", () => {
+    // Arrange / Act
+    const label = resolveDisplayName("SHA256:abc", named, { "SHA256:abc": "Alex" });
+
+    // Assert
+    expect(label).toBe("Alex");
+  });
+
+  test("falls back to name, then anonymous, then the short handle", () => {
+    // Arrange / Act / Assert
+    expect(resolveDisplayName("SHA256:abc", named, {})).toBe("Al");
+    expect(resolveDisplayName("SHA256:abc", unnamed, {})).toBe(ANONYMOUS_LABEL);
+    expect(resolveDisplayName("SHA256:1a2b3c4d5e", [], {})).toBe("1a2b3c4d");
+  });
+});

package/src/attribution.ts

@@ -0,0 +1,32 @@
+/**
+ * Attribution labels for annotations. An annotation's `author` is an identity
+ * id (an SSH fingerprint today). The rail resolves it against the share's
+ * participant registry and the planner's local rename overrides; ADR 0006.
+ */
+
+import type { Identity } from "@cueloop/schema";
+
+const FINGERPRINT_PREFIX = "SHA256:";
+
+/** Shown for a known participant who chose not to give a name. */
+export const ANONYMOUS_LABEL = "-- anonymous --";
+
+/** A short, stable handle from a raw author id when no name is known. */
+export function shortHandle(authorId: string): string {
+  const base = authorId.startsWith(FINGERPRINT_PREFIX) ? authorId.slice(FINGERPRINT_PREFIX.length) : authorId;
+  return base.slice(0, 8) || authorId;
+}
+
+/**
+ * The rail label for an author id: a local rename wins, then the collaborator's
+ * own name, then anonymous for a known-but-unnamed participant, then a short
+ * handle for an id we hold no identity for.
+ */
+export function resolveDisplayName(authorId: string, participants: Identity[] | undefined, overrides: Record<string, string>): string {
+  const override = overrides[authorId];
+  if (override) return override;
+  const identity = participants?.find((participant) => participant.id === authorId);
+  if (identity?.name) return identity.name;
+  if (identity) return ANONYMOUS_LABEL;
+  return shortHandle(authorId);
+}

package/src/clipboard.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { clipboardCommands } from "./clipboard";
+
+describe(clipboardCommands, () => {
+  test("uses pbcopy on macOS", () => {
+    // Assert
+    expect(clipboardCommands("darwin")).toEqual([["pbcopy"]]);
+  });
+
+  test("uses clip.exe on Windows", () => {
+    // Assert
+    expect(clipboardCommands("win32")).toEqual([["clip.exe"]]);
+  });
+
+  test("prefers wayland, then X11 tools on Linux", () => {
+    // Act
+    const commands = clipboardCommands("linux");
+
+    // Assert
+    expect(commands[0]).toEqual(["wl-copy"]);
+    expect(commands.map((command) => command[0])).toEqual(["wl-copy", "xclip", "xsel"]);
+  });
+});

package/src/clipboard.ts

@@ -0,0 +1,26 @@
+/**
+ * Best-effort system clipboard. Each platform has its own tool; we try them in
+ * order and report whether one worked, so the caller can fall back to printing
+ * the line (the over-SSH case, where no clipboard tool exists). Mirrors how
+ * herdr confirms a copy.
+ */
+
+/** The clipboard-write commands to try, most-preferred first, for this platform. */
+export function clipboardCommands(platform: NodeJS.Platform = process.platform): string[][] {
+  if (platform === "darwin") return [["pbcopy"]];
+  if (platform === "win32") return [["clip.exe"]];
+  return [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]];
+}
+
+/** Copy `text` to the clipboard; false when no tool is available or all fail. */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  for (const command of clipboardCommands()) {
+    try {
+      const proc = Bun.spawn(command, { stdin: Buffer.from(text), stdout: "ignore", stderr: "ignore" });
+      if ((await proc.exited) === 0) return true;
+    } catch {
+      // tool not installed - try the next one
+    }
+  }
+  return false;
+}