@cueloop/client 0.1.0-alpha.6 → 0.1.0-alpha.61

package/src/components/stories-app.tsx

@@ -0,0 +1,124 @@
+/**
+ * The interactive stories catalog (`bun run stories`): a left list of
+ * component modules (j/k), h/l cycling through the module's stories, 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, { useMemo, useState } from "react";
+import { createCliRenderer } from "@opentui/core";
+import { createRoot, useKeyboard } from "@opentui/react";
+import { DARK } from "../theme";
+import { ThemeProvider } from "./theme-context";
+import { loadStories, type LoadedStory } from "./story";
+import { FRAME_BORDER_STYLE } from "./primitives/frame";
+
+function StoriesApp({
+  stories,
+  onExit,
+}: {
+  stories: LoadedStory[];
+  onExit: () => void;
+}): React.ReactNode {
+  const moduleTitles = useMemo(
+    () => [...new Set(stories.map((story) => story.moduleTitle))],
+    [stories],
+  );
+  const [moduleIndex, setModuleIndex] = useState(0);
+  const [storyIndex, setStoryIndex] = useState(0);
+  const moduleTitle = moduleTitles[moduleIndex]!;
+  const moduleStories = stories.filter((story) => story.moduleTitle === moduleTitle);
+  const current = moduleStories[Math.min(storyIndex, moduleStories.length - 1)]!;
+
+  useKeyboard((key) => {
+    if (key.name === "q") onExit();
+    else if (key.name === "j" || key.name === "down") {
+      setModuleIndex((index) => Math.min(moduleTitles.length - 1, index + 1));
+      setStoryIndex(0);
+    } else if (key.name === "k" || key.name === "up") {
+      setModuleIndex((index) => Math.max(0, index - 1));
+      setStoryIndex(0);
+    } else if (key.name === "l" || key.name === "right") {
+      setStoryIndex((index) => (index + 1) % moduleStories.length);
+    } else if (key.name === "h" || key.name === "left") {
+      setStoryIndex((index) => (index - 1 + moduleStories.length) % moduleStories.length);
+    }
+  });
+
+  return (
+    <ThemeProvider theme={DARK}>
+      <box
+        style={{
+          flexDirection: "column",
+          width: "100%",
+          height: "100%",
+          backgroundColor: DARK.background,
+        }}
+      >
+        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
+          <text fg={DARK.text}>
+            <span fg={DARK.accent}>cueloop stories</span>
+            <span fg={DARK.textDim}>
+              {" "}
+              · {moduleTitle} / {current.storyName}
+            </span>
+          </text>
+        </box>
+        <box style={{ flexDirection: "row", flexGrow: 1 }}>
+          <box
+            style={{
+              width: 28,
+              backgroundColor: DARK.panel,
+              flexDirection: "column",
+              paddingLeft: 1,
+              paddingTop: 1,
+            }}
+          >
+            {moduleTitles.map((title, index) => (
+              <text key={title} fg={index === moduleIndex ? DARK.accent : DARK.textMuted}>
+                {index === moduleIndex ? "▸ " : "  "}
+                {title}
+              </text>
+            ))}
+          </box>
+          <box
+            style={{
+              flexGrow: 1,
+              flexDirection: "column",
+              border: true,
+              borderStyle: FRAME_BORDER_STYLE,
+              borderColor: DARK.border,
+            }}
+            title={` ${current.storyName} (${moduleStories.indexOf(current) + 1}/${moduleStories.length}) `}
+          >
+            {/* remount per story so component-local state never leaks across */}
+            <box
+              key={`${moduleTitle}/${current.storyName}`}
+              style={{ flexGrow: 1, flexDirection: "column" }}
+            >
+              {current.story.render()}
+            </box>
+          </box>
+        </box>
+        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
+          <text fg={DARK.textDim}>j/k component · h/l story · q quit</text>
+        </box>
+      </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,98 @@
+/** 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: "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<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,75 @@
+/**
+ * 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/prototype. */
+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.endsWith(".prototype.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,102 @@
+/**
+ * Code highlighting tokens: the theme's named colors projected onto tree-sitter
+ * capture names. One group -> color map is the single source of truth, feeding
+ * both the native code renderable (via a cached SyntaxStyle per theme) and the
+ * diff sheet's per-row spans. Unknown languages simply render unstyled -
+ * highlighting is an enhancement, never a blocker.
+ */
+
+import {
+  SyntaxStyle,
+  infoStringToFiletype,
+  extensionToFiletype,
+  basenameToFiletype,
+} 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;
+}
+
+/** A diff/code file path -> tree-sitter filetype, by basename then extension. */
+export function filetypeForPath(path: string): string | undefined {
+  const basename = path.split("/").pop() ?? path;
+  const byBasename = basenameToFiletype.get(basename);
+
+  if (byBasename) return byBasename;
+  const dotIndex = basename.lastIndexOf(".");
+
+  if (dotIndex <= 0) return undefined;
+
+  return extensionToFiletype.get(basename.slice(dotIndex + 1).toLowerCase());
+}
+
+interface SyntaxGroupStyle {
+  fg: string;
+  italic?: boolean;
+}
+
+/** The one group -> style map, keyed by tree-sitter capture name. */
+function syntaxGroupStyles(theme: Theme): Record<string, SyntaxGroupStyle> {
+  return {
+    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 },
+  };
+}
+
+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(syntaxGroupStyles(theme));
+
+  syntaxStyleCache.set(theme, style);
+
+  return style;
+}
+
+/** The foreground for a tree-sitter capture group; undefined when unstyled. */
+export function colorForSyntaxGroup(group: string, theme: Theme): string | undefined {
+  const styles = syntaxGroupStyles(theme);
+  const direct = styles[group];
+
+  if (direct) return direct.fg;
+  // capture names are dotted (e.g. "keyword.control"); match the broadest prefix
+  const base = group.split(".")[0]!;
+
+  return styles[base]?.fg;
+}

package/src/components/terminal-pane.test.tsx

@@ -0,0 +1,40 @@
+/** The embedded terminal renderable runs a real PTY child through Ghostty's VT and paints its screen; a live `printf` child must show up in the OpenTUI frame. Skipped where no prebuilt libghostty-vt ships for the platform. */
+
+import { describe, expect, test } from "bun:test";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { waitForText } from "../test-support";
+import {
+  embeddedTerminalAvailable,
+  registerTerminalPane,
+  TerminalPaneRenderable,
+} from "./terminal-pane";
+
+registerTerminalPane();
+
+describe("TerminalPaneRenderable", () => {
+  test.skipIf(!embeddedTerminalAvailable())(
+    "paints a live child process's output into the box",
+    async () => {
+      // Arrange / Act - a child that prints a known line
+      const setup = await testRender(
+        React.createElement("terminalPane", {
+          command: "/bin/sh",
+          args: ["-c", "printf 'HELLO-EMBED\\n'; sleep 5"],
+          style: { width: 40, height: 6 },
+        }),
+        { width: 40, height: 6 },
+      );
+
+      // Assert - the child's output reaches the painted frame via Ghostty
+      await waitForText(setup, "HELLO-EMBED");
+      setup.renderer.destroy();
+    },
+  );
+
+  test("exposes availability + the renderable class", () => {
+    // Assert - the module loads and reports platform support honestly
+    expect(typeof embeddedTerminalAvailable()).toBe("boolean");
+    expect(TerminalPaneRenderable).toBeDefined();
+  });
+});