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

package/src/session-controller.ts

@@ -24,14 +24,15 @@ import { Registry, type Exporter } from "@cueloop/extension-api";
 import { createObsidianExtension, shouldExport, type ObsidianConfig } from "@cueloop/integration-obsidian";
 import { buildDisplay, nextWorkBlock, type DisplayBlock } from "./view";
 import { diffRowAnchor, diffRows, type DiffRow } from "./view-diff";
+import { firstUnviewedIndex, walkFiles, type WalkFile } from "./walk";
 import { editInEditor } from "./editor";
 import { focusHerdrPane, returnPaneFor } from "./herdr";
 import { persistAutoClose, type AutoClose, type CueloopConfig } from "./config";
 
 /**
  * Post-submit lifecycle (a review pane should hand you back to the agent,
- * not linger): idle → prompt (auto-close off: offer the choice) or
- * counting (configured delay) → exit. esc dismisses to the resolved view.
+ * not linger): idle → counting (a visible countdown, the default) → exit.
+ * esc dismisses to the resolved view; a remembers the countdown as default.
  */
 export type Completion =
   | { phase: "idle" }
@@ -39,6 +40,9 @@ export type Completion =
   | { phase: "counting"; remaining: number }
   | { phase: "dismissed" };
 
+/** Seconds the completion overlay counts down before it hands back. */
+export const DEFAULT_AUTO_CLOSE = 5;
+
 export interface ControllerSnapshot {
   session: ReviewSession | null;
   inbox: ReviewSession[] | null;
@@ -50,6 +54,12 @@ export interface ControllerSnapshot {
    * hand-off - the reconciliation banner count. 0 = no banner.
    */
   editOrphanCount: number;
+  /**
+   * The guided walk's cursor (diff sessions): which wizard step is on
+   * screen. index === file count is the end card. null = not walking; the
+   * viewed set itself rides the session record, so leaving loses nothing.
+   */
+  walk: { index: number } | null;
 }
 
 export interface ReviewControllerOptions {
@@ -76,6 +86,8 @@ export interface ReviewController {
   /** Derived projections, cached per session identity. */
   display(): DisplayBlock[];
   rows(): DiffRow[];
+  /** The walk's step list, derived from the diff rows. */
+  files(): WalkFile[];
   working(): string;
   /** Open a session from the inbox. */
   open(id: string): void;
@@ -92,6 +104,13 @@ export interface ReviewController {
   updateAnnotation(id: string, body: string): void;
   removeAnnotation(id: string): void;
   setWorkingCopy(content: string | undefined): void;
+  /** Enter the guided walk at the first unviewed file (diff sessions). */
+  walkStart(): void;
+  /** Mark the current file viewed (persists with the session) and advance. */
+  walkForward(): void;
+  walkBack(): void;
+  /** Leave the walk; the viewed set stays on the session record. */
+  walkLeave(): void;
   /** Resolve the review, run the export, start the completion hand-back. */
   submit(verdict: VerdictKind, summary: string): void;
   /** Close the review and, inside herdr, bounce focus back to the agent. */
@@ -116,6 +135,7 @@ class Controller implements ReviewController {
     error: null,
     completion: { phase: "idle" },
     editOrphanCount: 0,
+    walk: null,
   };
   private listeners = new Set<() => void>();
   private autoClose: AutoClose = "off";
@@ -125,7 +145,11 @@ class Controller implements ReviewController {
   private countdown: TimerHandle | undefined;
   /** Projections keyed by session identity so renders reuse one computation. */
   private derivedFor: ReviewSession | null = null;
-  private derived: { display: DisplayBlock[]; rows: DiffRow[] } = { display: [], rows: [] };
+  private derived: { display: DisplayBlock[]; rows: DiffRow[]; files: WalkFile[] } = {
+    display: [],
+    rows: [],
+    files: [],
+  };
 
   constructor(private readonly opts: ReviewControllerOptions) {
     this.readOnly = opts.readOnly ?? false;
@@ -198,9 +222,11 @@ class Controller implements ReviewController {
     const s = this.snap.session;
     if (this.derivedFor === s) return;
     this.derivedFor = s;
+    const rows = s && s.artifact.type === "diff" ? diffRows(s.artifact.content) : [];
     this.derived = {
       display: s ? buildDisplay(s.artifact.content, s.workingCopy) : [],
-      rows: s && s.artifact.type === "diff" ? diffRows(s.artifact.content) : [],
+      rows,
+      files: walkFiles(rows),
     };
   }
 
@@ -214,6 +240,11 @@ class Controller implements ReviewController {
     return this.derived.rows;
   }
 
+  files(): WalkFile[] {
+    this.ensureDerived();
+    return this.derived.files;
+  }
+
   working(): string {
     const s = this.snap.session;
     return s ? (s.workingCopy ?? s.artifact.content) : "";
@@ -247,6 +278,7 @@ class Controller implements ReviewController {
 
   // ── verbs ───────────────────────────────────
   open(id: string): void {
+    this.locallyViewed.clear();
     const cached = this.snap.inbox?.find((s) => s.id === id);
     if (cached) this.update({ session: cached });
     else void this.refreshSession(id);
@@ -361,12 +393,59 @@ class Controller implements ReviewController {
     this.apply(this.client!.sessionSetWorkingCopy(session.id, content));
   }
 
+  // ── the guided walk ─────────────────────────
+  // Marks sent but possibly not yet reflected in the session snapshot; the
+  // union keeps the walk title truthful and rapid advances from losing marks.
+  private locallyViewed = new Set<string>();
+
+  private viewedSet(): Set<string> {
+    return new Set([...(this.snap.session?.viewedPaths ?? []), ...this.locallyViewed]);
+  }
+
+  walkStart(): void {
+    const session = this.snap.session;
+    if (!session || session.artifact.type !== "diff") return;
+    const files = this.files();
+    if (files.length === 0) return this.setStatus("nothing to walk - the diff is empty");
+    // resume at the first unviewed file; a finished walk reopens on the end card
+    this.update({ walk: { index: firstUnviewedIndex(files, this.viewedSet()) } });
+  }
+
+  walkForward(): void {
+    const walk = this.snap.walk;
+    const session = this.snap.session;
+    if (!walk || !session) return;
+    const files = this.files();
+    const current = files[walk.index];
+    if (!current) return; // already on the end card
+    // advancing IS the viewed mark: the step is complete once you move past
+    // it; the daemon verb merges, so only the new path travels
+    if (!this.viewedSet().has(current.path)) {
+      this.locallyViewed.add(current.path);
+      this.apply(this.client!.sessionSetViewed(session.id, [current.path]));
+    }
+    this.update({ walk: { index: walk.index + 1 } });
+  }
+
+  walkBack(): void {
+    const walk = this.snap.walk;
+    if (!walk) return;
+    this.update({ walk: { index: Math.max(0, walk.index - 1) } });
+  }
+
+  walkLeave(): void {
+    if (this.snap.walk) this.update({ walk: null });
+  }
+
   submit(verdict: VerdictKind, summary: string): void {
     const session = this.snap.session;
     if (!session) return;
+    this.walkLeave();
     this.client!.sessionResolve(session.id, verdict, summary)
       .then((resolved) => {
-        this.update({ session: resolved, status: `review submitted - ${verdict.replace("_", " ")}` });
+        // The completion overlay heading already states the verdict, so the
+        // status line stays empty here - only export/error messages fill it.
+        this.update({ session: resolved, status: "" });
         // notes-vault export: guarded by config, default is manual (no-op)
         const obsidian = this.obsidian;
         const exporter = this.exporters.get("obsidian");
@@ -375,14 +454,13 @@ class Controller implements ReviewController {
             this.setStatus(r.success && r.path ? `exported to ${r.path}` : `export failed: ${r.error ?? "unknown"}`);
           });
         }
-        // hand the reviewer back to the agent: prompt or count down per config;
-        // inside herdr with a known return pane, closing is the default
+        // Hand the reviewer back to the agent. The default is a visible
+        // countdown from DEFAULT_AUTO_CLOSE that closes on its own; esc stays,
+        // a remembers the choice. A configured delay overrides; 0 closes now.
         const delay = this.autoClose;
-        const returns = returnPaneFor(resolved.artifact.meta.herdrPane) !== undefined;
         if (delay === 0) this.finishReview();
         else if (typeof delay === "number") this.startCounting(delay);
-        else if (returns) this.startCounting(3);
-        else this.update({ completion: { phase: "prompt" } });
+        else this.startCounting(DEFAULT_AUTO_CLOSE);
       })
       .catch((e: unknown) => this.setStatus(String(e instanceof Error ? e.message : e)));
   }
@@ -407,13 +485,13 @@ class Controller implements ReviewController {
   }
 
   optInAutoClose(): void {
-    // opt in: close in 3s from now on, persisted to the user config
+    // Remember the default countdown for future submits, persisted to the user
+    // config. The countdown is already running; this only makes it the default.
     try {
-      persistAutoClose(3);
+      persistAutoClose(DEFAULT_AUTO_CLOSE);
     } catch {
       // a read-only config dir must not block closing the review
     }
-    this.autoClose = 3;
-    this.startCounting(3);
+    this.autoClose = DEFAULT_AUTO_CLOSE;
   }
 }

package/src/theme.ts

@@ -27,6 +27,25 @@ export interface Theme {
   backdrop: string;
 }
 
+/**
+ * The dimmed variant behind the walk wizard: every reading color drops to
+ * the dim token so the file list stays legible context, not competition.
+ * Layout tokens (backgrounds, cursor) keep their values.
+ */
+export function dimmedTheme(theme: Theme): Theme {
+  return {
+    ...theme,
+    text: theme.textDim,
+    textMuted: theme.textDim,
+    accent: theme.textDim,
+    green: theme.textDim,
+    red: theme.textDim,
+    blue: theme.textDim,
+    insFg: theme.textDim,
+    delFg: theme.textDim,
+  };
+}
+
 export const DARK: Theme = {
   bg: "#1f1f29",
   panel: "#1a1a23",

package/src/walk.test.ts

@@ -0,0 +1,110 @@
+/** Pure walk projections: file steps, resume index, viewed counts, notes. */
+
+import { describe, expect, test } from "bun:test";
+import type { Annotation } from "@cueloop/schema";
+import { diffRows } from "./view-diff";
+import { firstUnviewedIndex, noteForFile, viewedCount, walkFiles, WALK_PREVIEW_ROWS } from "./walk";
+
+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,3 +1,4 @@
+ export const a = 1;
+-export const b = 2;
++export const b = 3;
++export const c = 4;
+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,8 @@
+-gone
++one
++two
++three
++four
++five
++six
++seven
+`;
+
+const rows = diffRows(PATCH);
+const files = walkFiles(rows);
+
+describe("walkFiles", () => {
+  test("one step per changed file, in patch order, with counted stats", () => {
+    expect(files.map((file) => file.path)).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
+    expect(files[0]).toMatchObject({ added: 2, removed: 1 });
+    expect(files[1]).toMatchObject({ added: 1, removed: 1 });
+    expect(files[2]).toMatchObject({ added: 7, removed: 1 });
+  });
+
+  test("previews carry signed changed lines and cap at the preview budget", () => {
+    expect(files[0]!.preview).toEqual([
+      { sign: "-", text: "export const b = 2;" },
+      { sign: "+", text: "export const b = 3;" },
+      { sign: "+", text: "export const c = 4;" },
+    ]);
+    expect(files[2]!.preview.length).toBe(WALK_PREVIEW_ROWS);
+    expect(files[2]!.preview[0]).toEqual({ sign: "-", text: "gone" });
+  });
+});
+
+describe("firstUnviewedIndex", () => {
+  test("starts at the first file when nothing is viewed", () => {
+    expect(firstUnviewedIndex(files, new Set())).toBe(0);
+  });
+
+  test("skips viewed files - a resumed review lands on its first gap", () => {
+    expect(firstUnviewedIndex(files, new Set(["src/a.ts"]))).toBe(1);
+    expect(firstUnviewedIndex(files, new Set(["src/a.ts", "src/b.ts"]))).toBe(2);
+    // a viewed file later in the list does not block the earlier gap
+    expect(firstUnviewedIndex(files, new Set(["src/c.ts"]))).toBe(0);
+  });
+
+  test("all viewed resumes on the end card, not the first file", () => {
+    expect(firstUnviewedIndex(files, new Set(["src/a.ts", "src/b.ts", "src/c.ts"]))).toBe(files.length);
+  });
+});
+
+describe("viewedCount", () => {
+  test("counts only paths present in the current file set", () => {
+    expect(viewedCount(files, new Set(["src/a.ts", "src/gone-in-rev-2.ts"]))).toBe(1);
+  });
+});
+
+describe("noteForFile", () => {
+  const note = (path: string, body: string): Annotation => ({
+    id: `a_${path}`,
+    kind: "note",
+    anchor: { quote: path, prefix: "", suffix: "" },
+    body,
+    createdAt: "now",
+  });
+
+  test("finds the note anchored at the file path", () => {
+    const annotations = [note("src/a.ts", "Renames b and adds c."), note("src/b.ts", "Swaps the line.")];
+    expect(noteForFile(annotations, "src/b.ts")).toBe("Swaps the line.");
+    expect(noteForFile(annotations, "src/c.ts")).toBeUndefined();
+  });
+
+  test("ignores non-note annotations that happen to quote the path", () => {
+    const comment: Annotation = {
+      id: "a_1",
+      kind: "comment",
+      anchor: { quote: "src/a.ts", prefix: "", suffix: "" },
+      body: "not a note",
+      createdAt: "now",
+    };
+    expect(noteForFile([comment], "src/a.ts")).toBeUndefined();
+  });
+});

package/src/walk.ts

@@ -0,0 +1,65 @@
+/**
+ * Guided-walk projections (#83): pure helpers over the diff row model - no
+ * IO, no React. The walk steps through the changed files in patch order;
+ * which files were seen lives on the session record (viewedPaths), which
+ * file is on screen is view state in the session controller.
+ */
+
+import type { Annotation } from "@cueloop/schema";
+import type { DiffRow } from "./view-diff";
+
+/** One wizard step: a changed file with its stats and a short diff preview. */
+export interface WalkFile {
+  path: string;
+  added: number;
+  removed: number;
+  /** The first changed lines, signed (+/-), for the card's diff preview. */
+  preview: { sign: "+" | "-"; text: string }[];
+}
+
+/** Preview lines per card: enough to recognize the change, never a full diff. */
+export const WALK_PREVIEW_ROWS = 5;
+
+/** Collapse the diff rows into one walk step per changed file, in patch order. */
+export function walkFiles(rows: DiffRow[]): WalkFile[] {
+  const files: WalkFile[] = [];
+  const byPath = new Map<string, WalkFile>();
+  for (const row of rows) {
+    let file = byPath.get(row.file);
+    if (!file) {
+      file = { path: row.file, added: 0, removed: 0, preview: [] };
+      byPath.set(row.file, file);
+      files.push(file);
+    }
+    if (row.t !== "add" && row.t !== "del") continue;
+    if (row.t === "add") file.added += 1;
+    else file.removed += 1;
+    if (file.preview.length < WALK_PREVIEW_ROWS) {
+      file.preview.push({ sign: row.t === "add" ? "+" : "-", text: row.text.replace(/\n$/, "") });
+    }
+  }
+  return files;
+}
+
+/**
+ * Where the walk resumes: the first file not yet marked viewed. All files
+ * viewed = the end card (index === files.length), so a finished walk reopens
+ * on its summary instead of restarting.
+ */
+export function firstUnviewedIndex(files: WalkFile[], viewedPaths: ReadonlySet<string>): number {
+  const index = files.findIndex((file) => !viewedPaths.has(file.path));
+  return index === -1 ? files.length : index;
+}
+
+/** Viewed count against the CURRENT file set - stale paths never inflate it. */
+export function viewedCount(files: WalkFile[], viewedPaths: ReadonlySet<string>): number {
+  return files.filter((file) => viewedPaths.has(file.path)).length;
+}
+
+/**
+ * The agent's note for a file: an annotation with kind "note" whose anchor
+ * quote is the file path (the note contract in the shared review core).
+ */
+export function noteForFile(annotations: Annotation[], path: string): string | undefined {
+  return annotations.find((annotation) => annotation.kind === "note" && annotation.anchor.quote === path)?.body;
+}