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

package/src/components/story-fixtures.ts

@@ -0,0 +1,90 @@
+/** Shared fixture data for the stories catalog: one plan session, one diff. */
+
+import type { Annotation, ReviewSession } from "@cueloop/schema";
+import { buildDisplay, marksByDisplay } from "../view-plan";
+import { diffRows } from "../view-diff";
+
+export const FIXTURE_PLAN = `# Migration Plan
+
+## Context
+
+The daemon persists sessions to disk atomically.
+
+## Steps
+
+- move the store
+- add recovery
+
+\`\`\`ts
+export function persist(session: Session): void {
+  // one JSON document per session
+  writeAtomically(pathFor(session.id), serialize(session));
+}
+\`\`\`
+`;
+
+export const FIXTURE_PATCH = `diff --git a/src/store.ts b/src/store.ts
+index 111..222 100644
+--- a/src/store.ts
++++ b/src/store.ts
+@@ -1,4 +1,4 @@
+ export class Store {
+-  private items = [];
++  private items = new Map();
+ }
+`;
+
+export const FIXTURE_ANNOTATIONS: Annotation[] = [
+  {
+    id: "a_story_1",
+    kind: "comment",
+    anchor: { quote: "persists sessions", prefix: "The daemon ", suffix: " to disk" },
+    body: "Which daemon owns this?",
+    createdAt: "2026-01-01T00:00:00Z",
+  },
+  {
+    id: "a_story_2",
+    kind: "suggestion",
+    anchor: { quote: "move the store", prefix: "", suffix: "" },
+    body: "move the store behind one interface",
+    createdAt: "2026-01-01T00:00:01Z",
+  },
+];
+
+export function fixturePlanSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: "1",
+    id: "s_story_plan",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: FIXTURE_PLAN, meta: { title: "Migration Plan", agent: "agent/worker-3" } },
+    revisions: [{ revision: 1, content: FIXTURE_PLAN, submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: FIXTURE_ANNOTATIONS,
+    status: "pending",
+    ...overrides,
+  } as ReviewSession;
+}
+
+export function fixtureDiffSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: "1",
+    id: "s_story_diff",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "diff", content: FIXTURE_PATCH, meta: { title: "working tree", agent: "agent/worker-3" } },
+    revisions: [{ revision: 1, content: FIXTURE_PATCH, submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: [],
+    status: "pending",
+    ...overrides,
+  } as ReviewSession;
+}
+
+export function fixtureDisplay() {
+  return buildDisplay(FIXTURE_PLAN);
+}
+
+export function fixtureMarks() {
+  return marksByDisplay(FIXTURE_ANNOTATIONS, fixtureDisplay());
+}
+
+export function fixtureDiffRows() {
+  return diffRows(FIXTURE_PATCH);
+}

package/src/components/story.ts

@@ -0,0 +1,66 @@
+/**
+ * The story contract. Every component file in components/ ships a
+ * colocated *.stories.tsx that exports `meta` plus named Story objects.
+ * The catalog IS the regression suite: stories.test.tsx walks every story,
+ * snapshots its char frame, and asserts declared colors against the styled
+ * spans; the `bun run stories` TUI renders the same objects interactively.
+ */
+
+import type React from "react";
+
+export interface StoryMeta {
+  /** Catalog path, e.g. "primitives/Card". */
+  title: string;
+}
+
+export interface Story {
+  render: () => React.ReactNode;
+  /**
+   * Colors (hex tokens) that must appear among the rendered frame's styled
+   * spans - the color regression net for color-bearing stories.
+   */
+  expectedColors?: string[];
+  /** Virtual terminal size; defaults to 80x24. */
+  size?: { width: number; height: number };
+}
+
+export interface LoadedStory {
+  moduleTitle: string;
+  storyName: string;
+  story: Story;
+}
+
+export function isStory(value: unknown): value is Story {
+  return typeof value === "object" && value !== null && typeof (value as Story).render === "function";
+}
+
+/** Import every *.stories.tsx next to the components and flatten the exports. */
+export async function loadStories(): Promise<LoadedStory[]> {
+  const glob = new Bun.Glob("**/*.stories.tsx");
+  const files = [...glob.scanSync({ cwd: import.meta.dir })].sort();
+  const loaded: LoadedStory[] = [];
+  for (const file of files) {
+    const moduleExports = (await import(`${import.meta.dir}/${file}`)) as Record<string, unknown>;
+    const meta = moduleExports["meta"] as StoryMeta | undefined;
+    const moduleTitle = meta?.title ?? file.replace(/\.stories\.tsx$/, "");
+    for (const [exportName, exported] of Object.entries(moduleExports)) {
+      if (exportName === "meta" || !isStory(exported)) continue;
+      loaded.push({ moduleTitle, storyName: exportName, story: exported });
+    }
+  }
+  return loaded;
+}
+
+/** Component files that must carry stories: every .tsx that is not a story/test. */
+export function componentFilesMissingStories(): string[] {
+  const componentGlob = new Bun.Glob("**/*.tsx");
+  const files = [...componentGlob.scanSync({ cwd: import.meta.dir })];
+  const missing: string[] = [];
+  for (const file of files) {
+    if (file.endsWith(".stories.tsx") || file.endsWith(".test.tsx")) continue;
+    if (file === "stories-app.tsx") continue;
+    const storiesSibling = file.replace(/\.tsx$/, ".stories.tsx");
+    if (!files.includes(storiesSibling)) missing.push(file);
+  }
+  return missing;
+}

package/src/components/syntax-highlight.ts

@@ -0,0 +1,57 @@
+/**
+ * Code highlighting tokens: the theme's named tokens projected onto
+ * tree-sitter capture names for the native code renderable. One SyntaxStyle
+ * per theme object, cached, so every code block on screen shares a handle.
+ * Unknown languages simply render unstyled - highlighting is an enhancement,
+ * never a blocker.
+ */
+
+import { SyntaxStyle, infoStringToFiletype } from "@opentui/core";
+import type { Theme } from "../theme";
+
+/** Markdown fence info -> tree-sitter filetype, with the aliases we accept. */
+export function filetypeFor(language?: string): string | undefined {
+  const info = (language ?? "").toLowerCase();
+  if (!info) return undefined;
+  const aliases: Record<string, string> = {
+    ts: "typescript",
+    js: "javascript",
+    py: "python",
+    rb: "ruby",
+    rs: "rust",
+    sh: "bash",
+    shell: "bash",
+    zsh: "bash",
+    yml: "yaml",
+  };
+  return infoStringToFiletype(aliases[info] ?? info) ?? aliases[info] ?? info;
+}
+
+const syntaxStyleCache = new WeakMap<Theme, SyntaxStyle>();
+
+export function syntaxStyleFor(theme: Theme): SyntaxStyle {
+  const cached = syntaxStyleCache.get(theme);
+  if (cached) return cached;
+  const style = SyntaxStyle.fromStyles({
+    default: { fg: theme.textMuted },
+    comment: { fg: theme.textDim, italic: true },
+    string: { fg: theme.green },
+    number: { fg: theme.blue },
+    constant: { fg: theme.blue },
+    boolean: { fg: theme.blue },
+    keyword: { fg: theme.accent },
+    operator: { fg: theme.textDim },
+    punctuation: { fg: theme.textDim },
+    function: { fg: theme.text },
+    method: { fg: theme.text },
+    type: { fg: theme.blue },
+    constructor: { fg: theme.blue },
+    variable: { fg: theme.textMuted },
+    property: { fg: theme.textMuted },
+    parameter: { fg: theme.textMuted },
+    tag: { fg: theme.accent },
+    attribute: { fg: theme.blue },
+  });
+  syntaxStyleCache.set(theme, style);
+  return style;
+}

package/src/components/theme-context.stories.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+import { DARK, type Theme } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { ThemeProvider } from "./theme-context";
+import { Card } from "./primitives/Card";
+
+export const meta: StoryMeta = { title: "theme-context" };
+
+/** A high-contrast variant to prove tokens flow through the provider. */
+const HIGH_CONTRAST: Theme = { ...DARK, accent: "#00ffff", elevated: "#000000", border: "#ffffff" };
+
+export const ContextDefault: Story = {
+  render: () => (
+    <Card title=" default dark theme " contentRows={1}>
+      <text>no provider needed</text>
+    </Card>
+  ),
+  expectedColors: [DARK.elevated],
+};
+
+export const ProviderSwap: Story = {
+  render: () => (
+    <ThemeProvider theme={HIGH_CONTRAST}>
+      <Card title=" provider theme " contentRows={1} borderColor={HIGH_CONTRAST.accent}>
+        <text>tokens come from the provider</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff", "#000000"],
+};
+
+export const PropOverride: Story = {
+  render: () => (
+    <ThemeProvider theme={DARK}>
+      <Card title=" prop-overridden theme " contentRows={1} theme={HIGH_CONTRAST} borderColor={HIGH_CONTRAST.accent}>
+        <text>the theme prop beats the context</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff"],
+};

package/src/components/theme-context.tsx

@@ -0,0 +1,30 @@
+/**
+ * Provider theming for the component system. The context default is the
+ * built-in dark theme, so embedding a component (or rendering a story) needs
+ * no provider at all. One ThemeProvider swap switches the live theme; every
+ * component also accepts an optional `theme` prop that overrides the context
+ * for explicit control. Components consume named tokens only - a hardcoded
+ * color inside components/ is a review rejection.
+ */
+
+import React, { createContext, useContext } from "react";
+import { DARK, type Theme } from "../theme";
+
+const ThemeContext = createContext<Theme>(DARK);
+
+export function ThemeProvider({ theme, children }: { theme: Theme; children: React.ReactNode }): React.ReactNode {
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): Theme {
+  return useContext(ThemeContext);
+}
+
+/**
+ * Token resolution for a component: the explicit `theme` prop wins over the
+ * provider context, which defaults to the built-in dark theme.
+ */
+export function useComponentTheme(override?: Theme): Theme {
+  const contextTheme = useContext(ThemeContext);
+  return override ?? contextTheme;
+}

package/src/components/truncate-text.ts

@@ -0,0 +1,6 @@
+/** Truncate text to one line of at most maxLength characters, ellipsis-terminated. */
+
+export function truncateToSingleLine(value: string, maxLength: number): string {
+  const oneLine = value.replace(/\n/g, " ");
+  return oneLine.length > maxLength ? oneLine.slice(0, maxLength - 1) + "…" : oneLine;
+}

package/src/config.test.ts

@@ -2,57 +2,180 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { DEFAULT_KEYS, actionFor, loadConfig } from "./config";
+import { DEFAULT_KEYS, actionFor, loadConfig, persistAuthorName, persistReviewState, persistReviewWidth } from "./config";
+import { REVIEW_DEFAULT_WIDTH, REVIEW_MAX_WIDTH } from "./review-panel";
 import { DARK } from "./theme";
 
 describe("loadConfig", () => {
   test("defaults when no file exists", () => {
-    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
-    expect(c.keys["comment"]).toEqual(["c"]);
-    expect(c.theme.accent).toBe(DARK.accent);
+    // Act
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+
+    // Assert
+    expect(config.keys["comment"]).toEqual(["c"]);
+    expect(config.theme.accent).toBe(DARK.accent);
   });
 
   test("user config rebinds actions and overrides theme tokens", () => {
+    // Arrange
     const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-"));
     const path = join(dir, "config.toml");
     writeFileSync(
       path,
       `[keys]\ncomment = "a"\nsubmit = ["return", "S"]\n\n[theme]\naccent = "#ff0000"\n`,
     );
+
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.keys["comment"]).toEqual(["a"]);
-      expect(c.keys["submit"]).toEqual(["return", "S"]);
-      expect(c.keys["cut"]).toEqual(["x"]); // untouched defaults survive
-      expect(c.theme.accent).toBe("#ff0000");
-      expect(c.theme.green).toBe(DARK.green);
+      // Act
+      const config = loadConfig({ userConfigPath: path });
+
+      // Assert
+      expect(config.keys["comment"]).toEqual(["a"]);
+      expect(config.keys["submit"]).toEqual(["return", "S"]);
+      expect(config.keys["cut"]).toEqual(["x"]); // untouched defaults survive
+      expect(config.theme.accent).toBe("#ff0000");
+      expect(config.theme.green).toBe(DARK.green);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
   test("repo config layers over user config", () => {
+    // Arrange
     const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg2-"));
     const user = join(dir, "user.toml");
     const repoRoot = join(dir, "repo");
     writeFileSync(user, `[keys]\ncomment = "a"\n`);
     Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
     writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[keys]\ncomment = "z"\n`);
+
     try {
-      const c = loadConfig({ userConfigPath: user, repoRoot });
-      expect(c.keys["comment"]).toEqual(["z"]);
+      // Act
+      const config = loadConfig({ userConfigPath: user, repoRoot });
+
+      // Assert
+      expect(config.keys["comment"]).toEqual(["z"]);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
   test("broken config never blocks a review", () => {
+    // Arrange
     const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg3-"));
     const path = join(dir, "config.toml");
     writeFileSync(path, "not [valid toml");
+
+    try {
+      // Act
+      const config = loadConfig({ userConfigPath: path });
+
+      // Assert
+      expect(config.keys["comment"]).toEqual(["c"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("[ui] parses auto_close and the editor override", () => {
+    // Arrange
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg4-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\nauto_close = 3\neditor = "code --wait"\n`);
+
+    try {
+      // Act
+      const config = loadConfig({ userConfigPath: path });
+
+      // Assert
+      expect(config.ui.autoClose).toBe(3);
+      expect(config.ui.editor).toBe("code --wait");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("[ui] editor defaults to undefined and ignores a blank value", () => {
+    // Arrange
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg5-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\neditor = "   "\n`);
+
+    try {
+      // Assert
+      expect(loadConfig({ userConfigPath: "/nonexistent/config.toml" }).ui.editor).toBeUndefined();
+      expect(loadConfig({ userConfigPath: path }).ui.editor).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("[ui] review panel defaults to an expanded rail at the default width", () => {
+    // Act
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+
+    // Assert
+    expect(config.ui.reviewState).toBe("expanded");
+    expect(config.ui.reviewWidth).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("[ui] parses review_width (clamped) and review_state", () => {
+    // Arrange
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg6-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\nreview_width = 999\nreview_state = "compact"\n`);
+
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.keys["comment"]).toEqual(["c"]);
+      // Act
+      const config = loadConfig({ userConfigPath: path });
+
+      // Assert
+      expect(config.ui.reviewWidth).toBe(REVIEW_MAX_WIDTH); // out-of-range width clamps
+      expect(config.ui.reviewState).toBe("compact");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("[ui] ignores an unknown review_state and a non-numeric width", () => {
+    // Arrange
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg7-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\nreview_width = "wide"\nreview_state = "sideways"\n`);
+
+    try {
+      // Act
+      const config = loadConfig({ userConfigPath: path });
+
+      // Assert
+      expect(config.ui.reviewWidth).toBe(REVIEW_DEFAULT_WIDTH);
+      expect(config.ui.reviewState).toBe("expanded");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("persistReviewWidth and persistReviewState round-trip through the config file", () => {
+    // Arrange
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg8-"));
+    const path = join(dir, "config.toml");
+
+    try {
+      // Act
+      persistReviewWidth(42, path);
+      persistReviewState("hidden", path);
+
+      // Assert
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.ui.reviewWidth).toBe(42);
+      expect(config.ui.reviewState).toBe("hidden");
+
+      // a second write replaces the key in place rather than appending a duplicate
+      // Act
+      persistReviewWidth(30, path);
+
+      // Assert
+      expect(loadConfig({ userConfigPath: path }).ui.reviewWidth).toBe(30);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -61,45 +184,58 @@ describe("loadConfig", () => {
 
 describe("integrations.obsidian config", () => {
   test("defaults when the section is absent", () => {
-    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
-    expect(c.integrations.obsidian.vault).toBeUndefined();
-    expect(c.integrations.obsidian.folder).toBe("cueloop");
-    expect(c.integrations.obsidian.filenameFormat).toBe("{YYYY}-{MM}-{DD} - {title}");
-    expect(c.integrations.obsidian.separator).toBe("space");
-    expect(c.integrations.obsidian.exportOn).toBe("manual");
+    // Act
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+
+    // Assert
+    expect(config.integrations.obsidian.vault).toBeUndefined();
+    expect(config.integrations.obsidian.folder).toBe("cueloop");
+    expect(config.integrations.obsidian.filenameFormat).toBe("{YYYY}-{MM}-{DD} - {title}");
+    expect(config.integrations.obsidian.separator).toBe("space");
+    expect(config.integrations.obsidian.exportOn).toBe("manual");
   });
 
   test("user config sets the section; invalid enum values are ignored", () => {
+    // Arrange
     const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-obs-"));
     const path = join(dir, "config.toml");
     writeFileSync(
       path,
       `[integrations.obsidian]\nvault = "/notes/vault"\nfolder = "plans"\nexportOn = "approve"\nseparator = "comma"\n`,
     );
+
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.integrations.obsidian.vault).toBe("/notes/vault");
-      expect(c.integrations.obsidian.folder).toBe("plans");
-      expect(c.integrations.obsidian.exportOn).toBe("approve");
-      expect(c.integrations.obsidian.separator).toBe("space"); // invalid value falls back
-      expect(c.keys["comment"]).toEqual(["c"]); // other sections untouched
+      // Act
+      const config = loadConfig({ userConfigPath: path });
+
+      // Assert
+      expect(config.integrations.obsidian.vault).toBe("/notes/vault");
+      expect(config.integrations.obsidian.folder).toBe("plans");
+      expect(config.integrations.obsidian.exportOn).toBe("approve");
+      expect(config.integrations.obsidian.separator).toBe("space"); // invalid value falls back
+      expect(config.keys["comment"]).toEqual(["c"]); // other sections untouched
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
   });
 
   test("repo config layers over user config for the section", () => {
+    // Arrange
     const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-obs2-"));
     const user = join(dir, "user.toml");
     const repoRoot = join(dir, "repo");
     writeFileSync(user, `[integrations.obsidian]\nvault = "/user/vault"\nexportOn = "resolve"\n`);
     Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
     writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[integrations.obsidian]\nfolder = "repo-plans"\n`);
+
     try {
-      const c = loadConfig({ userConfigPath: user, repoRoot });
-      expect(c.integrations.obsidian.vault).toBe("/user/vault"); // user layer survives
-      expect(c.integrations.obsidian.exportOn).toBe("resolve");
-      expect(c.integrations.obsidian.folder).toBe("repo-plans"); // repo layer wins
+      // Act
+      const config = loadConfig({ userConfigPath: user, repoRoot });
+
+      // Assert
+      expect(config.integrations.obsidian.vault).toBe("/user/vault"); // user layer survives
+      expect(config.integrations.obsidian.exportOn).toBe("resolve");
+      expect(config.integrations.obsidian.folder).toBe("repo-plans"); // repo layer wins
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -108,9 +244,39 @@ describe("integrations.obsidian config", () => {
 
 describe("actionFor", () => {
   test("resolves keys and shifted keys to actions", () => {
+    // Assert
     expect(actionFor(DEFAULT_KEYS, "j", false)).toBe("down");
     expect(actionFor(DEFAULT_KEYS, "g", true)).toBe("bottom"); // G
     expect(actionFor(DEFAULT_KEYS, "return", false)).toBe("submit");
     expect(actionFor(DEFAULT_KEYS, "zz", false)).toBeUndefined();
   });
 });
+
+describe("[authors] rename map", () => {
+  test("loads quoted fingerprint keys", () => {
+    // Arrange
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-authors-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[authors]\n"SHA256:abc+def/gh" = "Alex"\n`);
+
+    // Act
+    const config = loadConfig({ userConfigPath: path });
+
+    // Assert
+    expect(config.authors["SHA256:abc+def/gh"]).toBe("Alex");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("persistAuthorName round-trips and updates a fingerprint id in place", () => {
+    // Arrange
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-authors2-"));
+    const path = join(dir, "config.toml");
+
+    // Act / Assert
+    persistAuthorName("SHA256:abc+def/gh", "Alex", path);
+    expect(loadConfig({ userConfigPath: path }).authors["SHA256:abc+def/gh"]).toBe("Alex");
+    persistAuthorName("SHA256:abc+def/gh", "Alexa", path);
+    expect(loadConfig({ userConfigPath: path }).authors["SHA256:abc+def/gh"]).toBe("Alexa");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});