@cueloop/client 0.1.0-alpha.15 → 0.1.0-alpha.16

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@cueloop/daemon": "0.1.0-alpha.15",
-    "@cueloop/extension-api": "0.1.0-alpha.15",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.15",
-    "@cueloop/schema": "0.1.0-alpha.15",
+    "@cueloop/daemon": "0.1.0-alpha.16",
+    "@cueloop/extension-api": "0.1.0-alpha.16",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.16",
+    "@cueloop/schema": "0.1.0-alpha.16",
     "@opentui/core": "^0.5.1",
     "@opentui/keymap": "0.5.1",
     "@opentui/react": "^0.5.1",

package/src/App.tsx

@@ -16,9 +16,10 @@
 import React, { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
 import type { Clock } from "@opentui/core";
-import { type ReviewSession, type VerdictKind } from "@cueloop/schema";
+import { isAgentNote, type ReviewSession, type VerdictKind } from "@cueloop/schema";
 import { displayText, marksByDisplay, spanKey, startSpan, type Mark, type SpanState } from "./view";
-import { DARK } from "./theme";
+import { noteForFile, viewedCount } from "./walk";
+import { DARK, dimmedTheme } from "./theme";
 import { DEFAULT_KEYS, loadConfig } from "./config";
 import { returnPaneFor } from "./herdr";
 import { createReviewController } from "./session-controller";
@@ -34,6 +35,7 @@ import { VERDICTS } from "./components/ConfirmCard";
 import { CompletionOverlay } from "./components/CompletionOverlay";
 import { InboxList } from "./components/InboxList";
 import { ComposeBar } from "./components/ComposeBar";
+import { WalkWizard } from "./components/WalkWizard";
 
 export interface AppProps {
   home?: string;
@@ -55,8 +57,13 @@ type Mode =
   | { m: "railEdit"; id: string; text: string }
   | { m: "submit"; verdict: VerdictKind; summary: string };
 
+/** Reviewer-authored annotations only: agent notes never count as feedback. */
+function reviewerAnnotations(session: ReviewSession) {
+  return session.annotations.filter((annotation) => !isAgentNote(annotation));
+}
+
 function defaultVerdict(session: ReviewSession): VerdictKind {
-  return session.annotations.length || session.workingCopy !== undefined ? "request_changes" : "approve";
+  return reviewerAnnotations(session).length || session.workingCopy !== undefined ? "request_changes" : "approve";
 }
 
 export function App({ home, sessionId, readOnly = false, onExit, clock }: AppProps): React.ReactNode {
@@ -69,7 +76,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
     controller.connect();
     return () => controller.close();
   }, [controller]);
-  const { session, inbox, status, error, completion, editOrphanCount } = useSyncExternalStore(
+  const { session, inbox, status, error, completion, editOrphanCount, walk } = useSyncExternalStore(
     controller.subscribe,
     controller.getSnapshot,
     controller.getSnapshot,
@@ -127,6 +134,11 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
   const resolved = session?.status === "resolved";
   const isDiff = session?.artifact.type === "diff";
 
+  // ── the guided walk's view model ────────────
+  const walkFileList = controller.files();
+  const walking = isDiff && walk !== null;
+  const viewedPaths = useMemo(() => new Set(session?.viewedPaths ?? []), [session]);
+
   // driving needs committed layout, so it runs after render; any transition
   // out of span mode clears the renderer selection (compose paints its own
   // mark, and a mouse drag never changes the mode, so it survives)
@@ -267,6 +279,14 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
         const next = idx === -1 ? 0 : (idx + (intent.t === "nextAnn" ? 1 : -1) + anns.length) % anns.length;
         return void selectCardFromDocument(anns[next]!.id);
       }
+      case "walkStart":
+        return controller.walkStart();
+      case "walkForward":
+        return controller.walkForward();
+      case "walkBack":
+        return controller.walkBack();
+      case "walkLeave":
+        return controller.walkLeave();
       case "removeAnnotation":
         if (focusedAnn) {
           controller.removeAnnotation(focusedAnn);
@@ -319,7 +339,9 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
           ? "completion-prompt"
           : completion.phase === "counting"
             ? "completion-counting"
-            : "none";
+            : walking
+              ? "walk"
+              : "none";
 
   useKeyboard((key) => {
     const state: KeyState = {
@@ -332,6 +354,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
       hasInboxItems: !!inbox?.length,
       annotationCount: session?.annotations.length ?? 0,
       hasFocusedAnnotation: focusedAnn !== undefined,
+      walkAtEnd: walk !== null && walk.index >= walkFileList.length,
       cursorAnnotatable: isDiff
         ? rows[cursor] !== undefined && rows[cursor]!.t !== "file" && rows[cursor]!.t !== "hunk"
         : !!display[cursor]?.work,
@@ -365,7 +388,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
   }
 
   const s = session!;
-  const pendingCount = s.annotations.length + (s.workingCopy !== undefined ? 1 : 0);
+  const pendingCount = reviewerAnnotations(s).length + (s.workingCopy !== undefined ? 1 : 0);
 
   if ((completion.phase === "prompt" || completion.phase === "counting") && s.verdict) {
     return (
@@ -432,8 +455,13 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
       ? {
           verdict: mode.verdict,
           summary: mode.summary,
-          annotationCount: s.annotations.length,
-          blockingCount: s.annotations.filter(annotationBlocking).length,
+          annotationCount: reviewerAnnotations(s).length,
+          blockingCount: reviewerAnnotations(s).filter(annotationBlocking).length,
+          // walk coverage keeps partial passes honest at the verdict
+          viewedSummary:
+            isDiff && s.viewedPaths !== undefined
+              ? `${viewedCount(walkFileList, viewedPaths)}/${walkFileList.length} files viewed`
+              : undefined,
           onInput: (summary: string) => {
             liveInput.current = summary;
             setMode({ ...mode, summary });
@@ -475,9 +503,11 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
         ? "span"
         : mode.m === "compose" || mode.m === "railEdit"
           ? "compose"
-          : focusedAnn !== undefined
-            ? "card"
-            : "normal";
+          : walking
+            ? "walk"
+            : focusedAnn !== undefined
+              ? "card"
+              : "normal";
   const railWidth = terminalWidth >= 100 ? 34 : 28;
 
   return (
@@ -486,7 +516,14 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
         <Breadcrumb items={headerItems} />
         <box style={{ flexGrow: 1, flexDirection: "row" }}>
           {isDiff ? (
-            <DiffSheet rows={rows} cursor={cursor} annotations={s.annotations} focusedAnnotationId={focusedAnn} />
+            // the sheet dims to reading-quiet colors while the wizard has focus
+            <DiffSheet
+              rows={rows}
+              cursor={cursor}
+              annotations={s.annotations}
+              focusedAnnotationId={focusedAnn}
+              theme={walking ? dimmedTheme(theme) : undefined}
+            />
           ) : (
             <PlanSheet
               ref={planSheetRef}
@@ -530,6 +567,24 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
         ) : (
           <StatusBar>{keyBindings.statusHint(hintMode)}</StatusBar>
         )}
+        {walking && walk !== null ? (
+          <WalkWizard
+            files={walkFileList}
+            index={walk.index}
+            viewedPaths={viewedPaths}
+            note={
+              walkFileList[walk.index] !== undefined
+                ? noteForFile(s.annotations, walkFileList[walk.index]!.path)
+                : undefined
+            }
+            terminalWidth={terminalWidth}
+            onSubmitRequest={() => {
+              dispatch({ t: "walkLeave" });
+              dispatch({ t: "openSubmit" });
+            }}
+            onBack={() => dispatch({ t: "walkBack" })}
+          />
+        ) : null}
       </box>
     </ThemeProvider>
   );

package/src/App.walk.test.tsx

@@ -0,0 +1,208 @@
+/**
+ * The guided walk in the virtual terminal (#83): 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 - 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 () => {
+    const setup = await renderApp();
+    await press(setup, "w");
+    await waitForText(setup, "file 1 of 3 · 0 viewed");
+    expect(setup.captureCharFrame()).toContain("src/a.ts");
+    expect(setup.captureCharFrame()).toContain("+1 -1");
+
+    await press(setup, "]");
+    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"));
+
+    // [ steps back; the revisited card shows its viewed marker
+    await press(setup, "[");
+    await waitForText(setup, "file 1 of 3 · 1 viewed");
+    expect(setup.captureCharFrame()).toContain("· viewed");
+    await press(setup, "]");
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+
+    await press(setup, "]");
+    await waitForText(setup, "file 3 of 3 · 2 viewed");
+    await press(setup, "]");
+    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"]);
+
+    // the end card's return leaves the walk and opens the rail confirm
+    await press(setup, "enter");
+    await waitForText(setup, "submit review");
+    expect(setup.captureCharFrame()).toContain("3/3 files viewed");
+    await press(setup, "enter");
+    await waitForState(setup, () => server.core.sessionGet(session.id).status === "resolved");
+  });
+
+  test("esc keeps progress and w resumes at the first unviewed file", async () => {
+    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");
+
+    await press(setup, "escape");
+    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");
+
+    await press(setup, "w");
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+  });
+
+  test("a half-walked review resumes across App instances via the daemon", async () => {
+    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();
+
+    // a fresh client reads the viewed set back from the session record
+    const second = await renderApp();
+    await press(second, "w");
+    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
+  }, 15_000);
+
+  test("the agent-note block renders only for files carrying a note", async () => {
+    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();
+    await press(setup, "w");
+    await waitForText(setup, "file 1 of 3");
+    expect(setup.captureCharFrame()).not.toContain("agent note");
+
+    await press(setup, "]");
+    await waitForText(setup, "agent note");
+    expect(setup.captureCharFrame()).toContain("Swaps the stale line for the new constant.");
+
+    // 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");
+    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 () => {
+    const setup = await renderApp();
+    // 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);
+
+    await press(setup, "w");
+    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 () => {
+    server.core.sessionResolve(session.id, "approve", "");
+    const setup = await renderApp();
+    await waitForText(setup, "resolved");
+    await press(setup, "w");
+    await waitForText(setup, "review submitted - read-only");
+    expect(setup.captureCharFrame()).not.toContain("file 1 of 3");
+  });
+});

package/src/components/ConfirmCard.stories.tsx

@@ -20,3 +20,18 @@ export const RequestChanges: Story = {
   expectedColors: [DARK.red],
   size: { width: 40, height: 14 },
 };
+
+export const WithViewedSummary: Story = {
+  render: () => (
+    <ConfirmCard
+      verdict="approve"
+      summary=""
+      annotationCount={1}
+      blockingCount={0}
+      viewedSummary="2/3 files viewed"
+      {...callbacks}
+    />
+  ),
+  expectedColors: [DARK.green, DARK.textDim],
+  size: { width: 40, height: 14 },
+};

package/src/components/ConfirmCard.tsx

@@ -28,6 +28,11 @@ export interface ConfirmCardProps {
   summary: string;
   annotationCount: number;
   blockingCount: number;
+  /**
+   * The guided walk's honest coverage line for diff sessions, e.g.
+   * "2/3 files viewed". Undefined = no walk data, the row does not render.
+   */
+  viewedSummary?: string;
   onInput: (summary: string) => void;
   onSelectVerdict: (verdict: VerdictKind) => void;
   onSubmit: () => void;
@@ -76,6 +81,7 @@ export function ConfirmCard({
   summary,
   annotationCount,
   blockingCount,
+  viewedSummary,
   onInput,
   onSelectVerdict,
   onSubmit,
@@ -86,12 +92,13 @@ export function ConfirmCard({
   return (
     <Card
       title=" submit review "
-      contentRows={CONFIRM_CONTENT_ROWS}
+      contentRows={CONFIRM_CONTENT_ROWS + (viewedSummary !== undefined ? 1 : 0)}
       borderColor={tokens.accent}
       marginRight={1}
       theme={theme}
     >
       <text fg={tokens.textDim}>{`${annotationCount} annotations · ${blockingCount} blocking`}</text>
+      {viewedSummary !== undefined ? <text fg={tokens.textDim}>{viewedSummary}</text> : null}
       <box style={{ height: 1 }} />
       <VerdictSelector verdict={verdict} onSelectVerdict={onSelectVerdict} theme={theme} />
       <box style={{ height: 1 }} />

package/src/components/WalkWizard.stories.tsx

@@ -0,0 +1,89 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { WalkFile } from "../walk";
+import type { Story, StoryMeta } from "./story";
+import { WalkWizard } from "./WalkWizard";
+
+export const meta: StoryMeta = { title: "WalkWizard" };
+
+const FILES: WalkFile[] = [
+  {
+    path: "packages/daemon/src/store.ts",
+    added: 12,
+    removed: 3,
+    preview: [
+      { sign: "+", text: "const viewed = new Set<string>();" },
+      { sign: "+", text: "record.viewedPaths = [...viewed];" },
+      { sign: "-", text: "// viewed tracking lives in the client only" },
+    ],
+  },
+  {
+    path: "packages/client/src/walk.ts",
+    added: 48,
+    removed: 0,
+    preview: [{ sign: "+", text: "export function firstUnviewedIndex(files, viewed) {" }],
+  },
+  { path: "packages/schema/src/types.ts", added: 3, removed: 0, preview: [{ sign: "+", text: "viewedPaths?: string[];" }] },
+];
+
+const noop = (): void => {};
+
+export const FirstFile: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={0}
+      viewedPaths={new Set()}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the main card wears the accent border; stats carry the +/- colors
+  expectedColors: [DARK.accent, DARK.green, DARK.red, DARK.insFg, DARK.delFg],
+};
+
+export const WithAgentNote: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={1}
+      viewedPaths={new Set(["packages/daemon/src/store.ts"])}
+      note="New module: pure helpers that pick the next unviewed file. No IO, unit tested."
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the agent-note block wears the plain gray border token, not the accent
+  expectedColors: [DARK.accent, DARK.border, DARK.textMuted],
+};
+
+export const EndCard: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={3}
+      viewedPaths={new Set(FILES.map((file) => file.path))}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the end card wears the green border and the solid submit button
+  expectedColors: [DARK.green, DARK.accent, DARK.accentInk],
+};
+
+export const EndCardPartialPass: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={3}
+      viewedPaths={new Set(["packages/daemon/src/store.ts"])}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  expectedColors: [DARK.green],
+};