@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/components/session-tree.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import type { Thread, WorkspaceKey } from "@cueloop/schema";
+import { groupInbox, projectName } from "./session-tree";
+
+function session(id: string, title: string, rootCommit?: string, remote?: string): Thread {
+  const workspace: WorkspaceKey = { repoRoot: `/home/dev/${id}-checkout`, branch: "main" };
+  if (rootCommit !== undefined) workspace.rootCommit = rootCommit;
+  if (remote !== undefined) workspace.remote = remote;
+
+  return {
+    schemaVersion: "1",
+    id,
+    workspace,
+    artifact: { type: "plan", content: `# ${title}\n`, meta: { title } },
+    revisions: [],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+describe("projectName", () => {
+  test("prefers the remote basename and strips the .git suffix", () => {
+    // Arrange
+    const workspace: WorkspaceKey = {
+      repoRoot: "/tmp/whatever",
+      branch: "main",
+      remote: "git@github.com:acme/widget.git",
+    };
+
+    // Act
+    const name = projectName(workspace);
+
+    // Assert
+    expect(name).toBe("widget");
+  });
+
+  test("falls back to the working-tree folder name when there is no remote", () => {
+    // Arrange
+    const workspace: WorkspaceKey = { repoRoot: "/home/dev/cueloop", branch: "main" };
+
+    // Act
+    const name = projectName(workspace);
+
+    // Assert
+    expect(name).toBe("cueloop");
+  });
+});
+
+describe("groupInbox", () => {
+  test("splits repo-bound threads into Projects and the rest into Threads", () => {
+    // Arrange
+    const sessions = [
+      session("a", "Read the repo", "root-1", "git@github.com:acme/widget.git"),
+      session("b", "A loose idea"),
+    ];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions);
+
+    // Assert
+    const labels = rows.map((row) => `${row.kind}:${"label" in row ? row.label : row.id}`);
+    expect(labels).toEqual([
+      "section:Projects",
+      "project:widget",
+      "thread:a",
+      "section:Threads",
+      "thread:b",
+    ]);
+    expect(ordered.map((s) => s.id)).toEqual(["a", "b"]);
+  });
+
+  test("collapses threads sharing a root commit into one project", () => {
+    // Arrange
+    const sessions = [
+      session("a", "First", "root-1", "git@github.com:acme/widget.git"),
+      session("b", "Second", "root-1", "git@github.com:acme/widget.git"),
+    ];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions);
+
+    // Assert
+    const projectRows = rows.filter((row) => row.kind === "project");
+    expect(projectRows).toHaveLength(1);
+    expect(ordered).toHaveLength(2);
+  });
+
+  test("selectionIndex on each thread matches its position in ordered", () => {
+    // Arrange
+    const sessions = [session("a", "One", "root-1"), session("b", "Two")];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions);
+
+    // Assert
+    for (const row of rows) {
+      if (row.kind === "thread") expect(ordered[row.selectionIndex]!.id).toBe(row.id);
+    }
+  });
+
+  test("omits the Projects section when nothing is repo-bound", () => {
+    // Arrange
+    const sessions = [session("a", "Loose one"), session("b", "Loose two")];
+
+    // Act
+    const { rows } = groupInbox(sessions);
+
+    // Assert
+    expect(rows.some((row) => row.kind === "section" && row.label === "Projects")).toBe(false);
+    expect(rows.some((row) => row.kind === "section" && row.label === "Threads")).toBe(true);
+  });
+
+  test("a pinned thread lifts into a Pinned section at the top, out of its normal group", () => {
+    // Arrange - one repo-bound thread, one standalone; pin the repo-bound one
+    const sessions = [session("a", "Pinned one", "root-1"), session("b", "Loose two")];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions, new Set(["a"]));
+
+    // Assert - Pinned is the first section and holds thread a; a is gone from Projects
+    const sections = rows
+      .filter((row) => row.kind === "section")
+      .map((row) => (row.kind === "section" ? row.label : ""));
+
+    expect(sections[0]).toBe("Pinned");
+    expect(sections).not.toContain("Projects"); // its only member was pinned away
+    expect(ordered[0]!.id).toBe("a"); // the cursor walks pinned threads first
+    const pinnedThreadIds = rows.filter((row) => row.kind === "thread").map((row) => row.id);
+
+    expect(pinnedThreadIds).toEqual(["a", "b"]);
+  });
+});

package/src/components/session-tree.ts

@@ -0,0 +1,108 @@
+/**
+ * Groups the pending inbox into Projects and Threads for the sidebar. Threads
+ * whose workspace carries a rootCommit gather under their project (keyed by that
+ * commit, so moving or re-cloning the repo never forks it); the rest are
+ * standalone Threads. The flat `ordered` sequence is what the inbox cursor
+ * walks, so the keyboard grammar keeps a single index across the two groups.
+ */
+
+import type { Thread, WorkspaceKey } from "@cueloop/schema";
+
+/** A repo's display name: the remote basename when present, else the working-tree folder name. */
+export function projectName(workspace: WorkspaceKey): string {
+  const { remote, repoRoot } = workspace;
+
+  if (remote !== undefined) {
+    const cleaned = remote.replace(/\.git$/, "").replace(/\/+$/, "");
+    const base = cleaned
+      .split(/[/:]/)
+      .filter((part) => part.length > 0)
+      .at(-1);
+    if (base !== undefined) return base;
+  }
+
+  const dir = repoRoot
+    .replace(/\/+$/, "")
+    .split("/")
+    .filter((part) => part.length > 0)
+    .at(-1);
+
+  return dir ?? repoRoot;
+}
+
+export type InboxRow =
+  | { kind: "section"; id: string; label: string }
+  | { kind: "project"; id: string; label: string }
+  | { kind: "thread"; id: string; session: Thread; selectionIndex: number };
+
+export interface GroupedInbox {
+  rows: InboxRow[];
+  /** Threads in display order; the inbox cursor indexes this. */
+  ordered: Thread[];
+}
+
+function threadTitle(session: Thread): string {
+  return session.artifact.meta.title ?? session.id;
+}
+
+interface ProjectGroup {
+  name: string;
+  sessions: Thread[];
+}
+
+/** Group pending sessions into Pinned, then Projects (by root commit), then standalone Threads. */
+export function groupInbox(
+  sessions: readonly Thread[],
+  pinnedIds?: ReadonlySet<string>,
+): GroupedInbox {
+  const pinned: Thread[] = [];
+  const projects = new Map<string, ProjectGroup>();
+  const standalone: Thread[] = [];
+
+  for (const session of sessions) {
+    if (pinnedIds?.has(session.id) === true) {
+      pinned.push(session);
+      continue;
+    }
+
+    const key = session.workspace.rootCommit;
+    if (key === undefined) {
+      standalone.push(session);
+      continue;
+    }
+
+    const existing = projects.get(key);
+    if (existing !== undefined) existing.sessions.push(session);
+    else projects.set(key, { name: projectName(session.workspace), sessions: [session] });
+  }
+
+  const rows: InboxRow[] = [];
+  const ordered: Thread[] = [];
+  const pushThread = (session: Thread): void => {
+    rows.push({ kind: "thread", id: session.id, session, selectionIndex: ordered.length });
+    ordered.push(session);
+  };
+
+  if (pinned.length > 0) {
+    rows.push({ kind: "section", id: "section:pinned", label: "Pinned" });
+    for (const session of pinned) pushThread(session);
+  }
+
+  const projectEntries = [...projects.entries()].sort((a, b) => a[1].name.localeCompare(b[1].name));
+  if (projectEntries.length > 0) {
+    rows.push({ kind: "section", id: "section:projects", label: "Projects" });
+    for (const [key, project] of projectEntries) {
+      rows.push({ kind: "project", id: `project:${key}`, label: project.name });
+      for (const session of project.sessions) pushThread(session);
+    }
+  }
+
+  if (standalone.length > 0) {
+    rows.push({ kind: "section", id: "section:threads", label: "Threads" });
+    for (const session of standalone) pushThread(session);
+  }
+
+  return { rows, ordered };
+}
+
+export { threadTitle };

package/src/components/stories-app.tsx

@@ -0,0 +1,184 @@
+/**
+ * The interactive stories catalog (`bun run stories`): a nested tree of
+ * component modules on the left (j/k to move, h/l to fold or open) and the
+ * selected story rendered live in the preview pane. The same story objects
+ * back the snapshot harness - what this TUI shows is what the tests assert.
+ */
+
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { createCliRenderer, type ScrollBoxRenderable } from "@opentui/core";
+import { createRoot, useKeyboard } from "@opentui/react";
+import { DARK } from "../theme";
+import { ThemeProvider } from "./theme-context";
+import { buildStoryTree, loadStories, type LoadedStory } from "./story";
+import { PaneGrid } from "./PaneGrid";
+import { ShellHeader } from "./ShellHeader";
+import { Tree } from "./primitives/Tree";
+import { NERD } from "./primitives/icons";
+import { allFolderIds, flattenTree } from "./primitives/tree-model";
+
+interface StoriesAppProps {
+  stories: LoadedStory[];
+  onExit: () => void;
+}
+
+function StoriesApp({ stories, onExit }: StoriesAppProps): React.ReactNode {
+  const treeNodes = useMemo(() => buildStoryTree(stories), [stories]);
+  const storiesById = useMemo(
+    () => new Map(stories.map((story) => [`${story.moduleTitle}/${story.storyName}`, story])),
+    [stories],
+  );
+  const firstStoryId = `${stories[0]!.moduleTitle}/${stories[0]!.storyName}`;
+
+  const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(() =>
+    allFolderIds(treeNodes),
+  );
+  const [selectedId, setSelectedId] = useState(firstStoryId);
+  const [openedId, setOpenedId] = useState(firstStoryId);
+  const [treeOpen, setTreeOpen] = useState(true);
+
+  const rows = flattenTree(treeNodes, { expandedIds });
+  const selectedRow = rows.find((row) => row.id === selectedId) ?? rows[0];
+  const opened = storiesById.get(openedId);
+  const sidebarScroll = useRef<ScrollBoxRenderable | null>(null);
+
+  // keep the moving selection inside the scrolled viewport
+  useEffect(() => {
+    try {
+      sidebarScroll.current?.scrollChildIntoView(`tree-row-${selectedId}`);
+    } catch {
+      // reveal is best-effort; the selection state is already correct
+    }
+  }, [selectedId]);
+
+  const openStory = (id: string): void => {
+    if (storiesById.has(id)) setOpenedId(id);
+  };
+
+  const toggleFolder = (id: string): void => {
+    setExpandedIds((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+
+      return next;
+    });
+  };
+
+  const expandFolder = (id: string): void => {
+    setExpandedIds((current) => new Set(current).add(id));
+  };
+
+  const collapseFolder = (id: string): void => {
+    setExpandedIds((current) => {
+      const next = new Set(current);
+      next.delete(id);
+
+      return next;
+    });
+  };
+
+  const moveSelection = (delta: number): void => {
+    const index = rows.findIndex((row) => row.id === selectedId);
+    const nextIndex = Math.max(0, Math.min(rows.length - 1, index + delta));
+    const nextRow = rows[nextIndex];
+    if (nextRow !== undefined) setSelectedId(nextRow.id);
+  };
+
+  useKeyboard((key) => {
+    if (key.name === "q") onExit();
+    else if (key.name === "j" || key.name === "down") moveSelection(1);
+    else if (key.name === "k" || key.name === "up") moveSelection(-1);
+    else if (selectedRow === undefined) return;
+    else if (key.name === "l" || key.name === "right") {
+      if (selectedRow.isFolder) expandFolder(selectedRow.id);
+      else openStory(selectedRow.id);
+    } else if (key.name === "h" || key.name === "left") {
+      if (selectedRow.isFolder) collapseFolder(selectedRow.id);
+    } else if (key.name === "return" || key.name === "space") {
+      if (selectedRow.isFolder) toggleFolder(selectedRow.id);
+      else openStory(selectedRow.id);
+    }
+  });
+
+  return (
+    <ThemeProvider theme={DARK}>
+      <PaneGrid
+        theme={DARK}
+        mainHeader={
+          <ShellHeader
+            theme={DARK}
+            leftIcons={[{ glyph: NERD.settings }]}
+            leftLabel="cueloop storybook"
+            inspectorOpen={treeOpen}
+            onToggleInspector={treeOpen ? undefined : () => setTreeOpen(true)}
+          />
+        }
+        inspectorHeader={
+          <ShellHeader
+            theme={DARK}
+            inspectorOpen={treeOpen}
+            onToggleInspector={() => setTreeOpen(false)}
+          />
+        }
+        main={
+          opened !== undefined ? (
+            <scrollbox style={{ flexGrow: 1, paddingLeft: 1, paddingTop: 1 }} focused={false}>
+              {/* remount per story so component-local state never leaks across */}
+              <box key={openedId} style={{ flexDirection: "column" }}>
+                {opened.story.render()}
+              </box>
+            </scrollbox>
+          ) : (
+            <box style={{ flexGrow: 1, paddingLeft: 1, paddingTop: 1 }}>
+              <text fg={DARK.textDim}>Select a story</text>
+            </box>
+          )
+        }
+        inspectorWidth={34}
+        inspector={
+          treeOpen ? (
+            <box style={{ flexDirection: "column", flexGrow: 1, paddingTop: 1 }}>
+              <scrollbox ref={sidebarScroll} style={{ flexGrow: 1 }} focused={false}>
+                <Tree
+                  nodes={treeNodes}
+                  expandedIds={expandedIds}
+                  selectedId={selectedId}
+                  theme={DARK}
+                  onSelect={(id) => {
+                    setSelectedId(id);
+                    openStory(id);
+                  }}
+                  onToggle={(id) => {
+                    setSelectedId(id);
+                    toggleFolder(id);
+                  }}
+                />
+              </scrollbox>
+            </box>
+          ) : undefined
+        }
+        footer={
+          <box style={{ height: 1, paddingLeft: 1 }}>
+            <text fg={DARK.textDim}>j/k move · h/l fold or open · enter open · q quit</text>
+          </box>
+        }
+      />
+    </ThemeProvider>
+  );
+}
+
+if (import.meta.main) {
+  const stories = await loadStories();
+  const renderer = await createCliRenderer();
+
+  createRoot(renderer).render(
+    <StoriesApp
+      stories={stories}
+      onExit={() => {
+        renderer.destroy();
+        queueMicrotask(() => process.exit(0));
+      }}
+    />,
+  );
+}

package/src/components/stories.test.tsx

@@ -0,0 +1,66 @@
+/**
+ * The catalog IS the regression suite: every exported story renders in
+ * a virtual terminal, its char frame snapshots, and its declared colors must
+ * appear among the styled spans. A component file without a colocated
+ * stories file fails the harness, so the safety net cannot silently thin.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import { RGBA } from "@opentui/core";
+import { componentFilesMissingStories, loadStories } from "./story";
+import { allowEventLoopUpdates } from "../test-support";
+
+const stories = await loadStories();
+
+/** Hex of a painted color; undefined for unpainted (transparent) spans. */
+function hexOf(color: RGBA | null | undefined): string | undefined {
+  if (!color) return undefined;
+  const [red, green, blue] = color.toInts();
+
+  return "#" + [red, green, blue].map((part) => part!.toString(16).padStart(2, "0")).join("");
+}
+
+describe("stories catalog", () => {
+  test("every component file ships stories", () => {
+    expect(componentFilesMissingStories()).toEqual([]);
+  });
+
+  test("the catalog is not empty", () => {
+    expect(stories.length).toBeGreaterThan(0);
+  });
+
+  for (const { moduleTitle, storyName, story } of stories) {
+    test(`${moduleTitle}/${storyName} renders, snapshots, and carries its colors`, async () => {
+      // Arrange
+      const size = story.size ?? { width: 80, height: 24 };
+
+      // Act
+      const setup = await testRender(story.render(), size);
+
+      allowEventLoopUpdates();
+      await setup.waitForVisualIdle();
+      const frame = setup.captureCharFrame();
+
+      // Assert
+      expect(frame).toMatchSnapshot(`${moduleTitle}/${storyName}`);
+      if (story.expectedColors?.length) {
+        const seenColors = new Set<string>();
+
+        for (const line of setup.captureSpans().lines) {
+          for (const span of line.spans) {
+            const foregroundHex = hexOf(span.fg);
+            const backgroundHex = hexOf(span.bg);
+
+            if (foregroundHex) seenColors.add(foregroundHex);
+            if (backgroundHex) seenColors.add(backgroundHex);
+          }
+        }
+        for (const expectedColor of story.expectedColors) {
+          expect(seenColors).toContain(expectedColor.toLowerCase());
+        }
+      }
+      setup.renderer.destroy();
+    });
+  }
+});

package/src/components/story-fixtures.ts

@@ -0,0 +1,102 @@
+/** Shared fixture data for the stories catalog: one plan session, one diff. */
+
+import type { Annotation, Thread } 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: "comment",
+    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<Thread> = {}): Thread {
+  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,
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+export function fixtureDiffSession(overrides: Partial<Thread> = {}): Thread {
+  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: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+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-tree.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import { buildStoryTree, type LoadedStory } from "./story";
+import type { TreeNode } from "./primitives/tree-model";
+
+/** A story object whose render is never invoked in these structural tests. */
+const STUB = { render: () => null };
+
+function story(moduleTitle: string, storyName: string): LoadedStory {
+  return { moduleTitle, storyName, story: STUB };
+}
+
+function childLabels(node: TreeNode): string[] {
+  return (node.children ?? []).map((child) => child.label);
+}
+
+describe("buildStoryTree", () => {
+  test("splits moduleTitle on / into nested folders keyed by their path", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Layout/AppShell", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+
+    // Assert
+    expect(tree.map((node) => [node.id, node.label])).toEqual([
+      ["Primitives", "Primitives"],
+      ["Layout", "Layout"],
+    ]);
+    expect(tree[0]!.children!.map((node) => node.id)).toEqual(["Primitives/Tree"]);
+  });
+
+  test("groups sibling components under one shared parent folder", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Primitives/Card", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+
+    // Assert
+    expect(tree).toHaveLength(1);
+    expect(childLabels(tree[0]!)).toEqual(["Tree", "Card"]);
+  });
+
+  test("nests to the full depth of the moduleTitle path", () => {
+    // Arrange
+    const stories = [story("A/B/C", "Only")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const a = tree[0]!;
+    const b = a.children![0]!;
+
+    // Assert
+    expect([a.id, b.id]).toEqual(["A", "A/B"]);
+    expect(b.children![0]!.id).toBe("A/B/C");
+  });
+
+  test("adds each story as a leaf keyed `${moduleTitle}/${storyName}` under its component", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Empty"), story("Primitives/Tree", "Deep")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const component = tree[0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("Primitives/Tree");
+    expect(component.children!.map((leaf) => [leaf.id, leaf.label])).toEqual([
+      ["Primitives/Tree/Empty", "Empty"],
+      ["Primitives/Tree/Deep", "Deep"],
+    ]);
+  });
+
+  test("hoists a component with a single story of its own name into one leaf row", () => {
+    // Arrange
+    const stories = [story("Primitives/Card", "Card")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const hoisted = tree[0]!.children![0]!;
+
+    // Assert
+    expect(hoisted.children).toBeUndefined();
+    expect(hoisted.id).toBe("Primitives/Card/Card");
+    expect(hoisted.label).toBe("Card");
+  });
+
+  test("keeps the folder when its single story differs from the component name", () => {
+    // Arrange
+    const stories = [story("Primitives/Card", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const component = tree[0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("Primitives/Card");
+    expect(component.children!.map((leaf) => leaf.id)).toEqual(["Primitives/Card/Default"]);
+  });
+});