@cueloop/client 0.1.0-alpha.9 → 0.1.0-alpha.90

package/src/app-view-model.ts

@@ -0,0 +1,168 @@
+import type { Dispatch, MutableRefObject, SetStateAction } from "react";
+import type { Thread, MessageOutcome } from "@cueloop/schema";
+import type { Mode } from "./intent-dispatch";
+import type { Intent, KeyState } from "./keymap";
+import type { Completion } from "./thread-controller";
+import type { WalkFile } from "./walk";
+import type { QuickAction } from "./config";
+import { viewedCount } from "./walk";
+import type { ConfirmCardProps } from "./components/ConfirmCard";
+import type { BreadcrumbItem } from "./components/Breadcrumb";
+
+export function computeRoleCapabilities(
+  readOnly: boolean,
+  role: "owner" | "observer" | "collaborator",
+) {
+  const observer = readOnly || role === "observer";
+
+  return { observer, isOwner: !observer && role === "owner" };
+}
+
+export function deriveReviewFlags(session: Thread | null) {
+  return {
+    isDiff: session?.artifact.type === "diff",
+    isPrototype: session?.artifact.type === "prototype",
+    resolved: session?.status === "resolved",
+  };
+}
+
+export function isWalking(isDiff: boolean, walk: { index: number } | null): boolean {
+  return isDiff && walk !== null;
+}
+
+/**
+ * A prototype renders as a kitty pixel mockup only in the opt-in experimental mode:
+ * the flag is on and the artifact carries an HTML entry. Otherwise it is the default
+ * markdown design doc, rendered through the thread/markdown path.
+ */
+export function isPixelPrototypeMode(
+  isPrototype: boolean,
+  prototypePixels: boolean,
+  prototypePath: string | undefined,
+): boolean {
+  return isPrototype && prototypePixels && Boolean(prototypePath);
+}
+
+export function resolveOverlay(
+  mode: Mode,
+  completionPhase: Completion["phase"],
+  walking: boolean,
+): KeyState["overlay"] {
+  if (mode.type === "compose" || mode.type === "railEdit") return "compose";
+  if (mode.type === "submit") return "submit";
+  if (mode.type === "confirmDelete") return "confirm";
+  if (
+    mode.type === "rename" ||
+    mode.type === "renameThread" ||
+    mode.type === "nameSelf" ||
+    mode.type === "treePrompt"
+  )
+    return "prompt";
+  if (mode.type === "spanActions") return "spanActions";
+  if (completionPhase === "prompt") return "completion-prompt";
+  if (completionPhase === "counting") return "completion-counting";
+  if (walking) return "walk";
+
+  return "none";
+}
+
+export function isCompletionOverlayPhase(
+  completion: Completion,
+): completion is { phase: "prompt" } | { phase: "counting"; remaining: number } {
+  return completion.phase === "prompt" || completion.phase === "counting";
+}
+
+export function buildHeaderItems(params: {
+  session: Thread;
+  resolved: boolean;
+  observer: boolean;
+  role: "owner" | "observer" | "collaborator";
+}): BreadcrumbItem[] {
+  const { session, resolved, observer, role } = params;
+
+  return [
+    { label: "cueloop", tone: "accent" },
+    ...(resolved
+      ? [
+          {
+            label: `resolved: ${session.message!.outcome.replace("_", " ")}`,
+            tone: "green" as const,
+          },
+        ]
+      : []),
+    ...(observer ? [{ label: "observer", tone: "dim" as const }] : []),
+    ...(role === "collaborator"
+      ? [{ label: "shared · your notes save as you go", tone: "dim" as const }]
+      : []),
+    {
+      label: `${session.artifact.meta.title ?? session.artifact.meta.planPath ?? session.id} · rev ${session.revisions.length}`,
+      tone: "dim",
+    },
+    { label: `submitted by ${session.artifact.meta.agent ?? "unknown"}`, tone: "dim" },
+  ];
+}
+
+export function buildRenderFlags(params: {
+  session: Thread;
+  isOwner: boolean;
+  isDiff: boolean;
+  isPixelPrototype: boolean;
+  resolved: boolean;
+  menuDialog: "keybinds" | "settings" | null;
+  resolvedIds: Set<string>;
+}) {
+  const { session, isOwner, isDiff, isPixelPrototype, resolved, menuDialog, resolvedIds } = params;
+
+  return {
+    showOwnerActions: isOwner && !isDiff && !resolved,
+    showDiffRefresh:
+      !resolved &&
+      (session.artifact.meta.prRefreshHeadSha !== undefined ||
+        (session.artifact.type === "diff" &&
+          session.artifact.meta.vcsChangeId !== undefined &&
+          session.artifact.meta.workbench !== true)),
+    prototypeCanComment: isOwner && !resolved,
+    chromeHidden: menuDialog !== null,
+    prototypePath: session.artifact.meta.prototypePath ?? "",
+    // a markdown prototype interleaves resolved cards like a plan; only the pixel mockup opts out
+    railResolvedIds: isDiff || isPixelPrototype ? null : resolvedIds,
+  };
+}
+
+interface DraftHandlerDeps {
+  liveInput: MutableRefObject<string>;
+  setMode: Dispatch<SetStateAction<Mode>>;
+  dispatch: (intent: Intent) => void;
+}
+
+export function buildSubmitConfirmState(
+  deps: DraftHandlerDeps & {
+    mode: Mode;
+    isDiff: boolean;
+    session: Thread;
+    walkFileList: WalkFile[];
+    viewedPaths: Set<string>;
+    quickActions: QuickAction[];
+  },
+): Omit<ConfirmCardProps, "theme"> | null {
+  const { mode, isDiff, session, walkFileList, viewedPaths, liveInput, setMode, dispatch } = deps;
+
+  if (mode.type !== "submit") return null;
+
+  return {
+    message: mode.message,
+    summary: mode.summary,
+    quickActions: deps.quickActions,
+    viewedSummary:
+      isDiff && session.viewedPaths !== undefined
+        ? `${viewedCount(walkFileList, viewedPaths)}/${walkFileList.length} files viewed`
+        : undefined,
+    onInput: (summary: string) => {
+      liveInput.current = summary;
+      setMode({ ...mode, summary });
+    },
+    onSelectMessage: (message: MessageOutcome) => setMode({ ...mode, message }),
+    onSubmit: () => dispatch({ type: "submitMessage" }),
+    onCancel: () => dispatch({ type: "closeOverlay" }),
+  };
+}

package/src/attribution.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import type { Identity } from "@cueloop/schema";
+import { ANONYMOUS_LABEL, resolveDisplayName, shortHandle } from "./attribution";
+
+describe(shortHandle, () => {
+  test("shortens an ssh fingerprint to a stable handle", () => {
+    // Arrange / Act / Assert
+    expect(shortHandle("SHA256:1a2b3c4d5e6f")).toBe("1a2b3c4d");
+    expect(shortHandle("SHA256:1a2b3c4d5e6f")).toBe(shortHandle("SHA256:1a2b3c4d5e6f"));
+  });
+});
+
+describe(resolveDisplayName, () => {
+  const named: Identity[] = [{ id: "SHA256:abc", provider: "ssh", name: "Al" }];
+  const unnamed: Identity[] = [{ id: "SHA256:abc", provider: "ssh" }];
+
+  test("a local rename override wins over everything", () => {
+    // Arrange / Act
+    const label = resolveDisplayName("SHA256:abc", named, { "SHA256:abc": "Alex" });
+
+    // Assert
+    expect(label).toBe("Alex");
+  });
+
+  test("falls back to name, then anonymous, then the short handle", () => {
+    // Arrange / Act / Assert
+    expect(resolveDisplayName("SHA256:abc", named, {})).toBe("Al");
+    expect(resolveDisplayName("SHA256:abc", unnamed, {})).toBe(ANONYMOUS_LABEL);
+    expect(resolveDisplayName("SHA256:1a2b3c4d5e", [], {})).toBe("1a2b3c4d");
+  });
+});

package/src/attribution.ts

@@ -0,0 +1,42 @@
+/**
+ * Attribution labels for annotations. An annotation's `author` is an identity
+ * id (an SSH fingerprint today). The rail resolves it against the share's
+ * participant registry and the planner's local rename overrides; ADR 0006.
+ */
+
+import type { Identity } from "@cueloop/schema";
+
+const FINGERPRINT_PREFIX = "SHA256:";
+
+/** Shown for a known participant who chose not to give a name. */
+export const ANONYMOUS_LABEL = "-- anonymous --";
+
+/** A short, stable handle from a raw author id when no name is known. */
+export function shortHandle(authorId: string): string {
+  const base = authorId.startsWith(FINGERPRINT_PREFIX)
+    ? authorId.slice(FINGERPRINT_PREFIX.length)
+    : authorId;
+
+  return base.slice(0, 8) || authorId;
+}
+
+/**
+ * The rail label for an author id: a local rename wins, then the collaborator's
+ * own name, then anonymous for a known-but-unnamed participant, then a short
+ * handle for an id we hold no identity for.
+ */
+export function resolveDisplayName(
+  authorId: string,
+  participants: Identity[] | undefined,
+  overrides: Record<string, string>,
+): string {
+  const override = overrides[authorId];
+
+  if (override) return override;
+  const identity = participants?.find((participant) => participant.id === authorId);
+
+  if (identity?.name) return identity.name;
+  if (identity) return ANONYMOUS_LABEL;
+
+  return shortHandle(authorId);
+}

package/src/client-extension-registry.test.tsx

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import React from "react";
+import { ClientExtensionRegistry } from "./client-extension-registry";
+
+const Component = () => <></>;
+
+describe("client extension registry", () => {
+  test("registers each contribution and removes it on disposal", async () => {
+    const registry = new ClientExtensionRegistry();
+    const before = registry.snapshot();
+    let notifications = 0;
+    const unsubscribe = registry.subscribe(() => notifications++);
+    const loaded = await registry.load("example", (api) => {
+      api.registerSection({ id: "summary", zone: "threads.sidebar", title: "Summary", Component });
+      api.registerAction({ id: "open", zone: "thread.header", label: "Open", onPress() {} });
+      api.registerView({ id: "details", zone: "workspace.panels", title: "Details", Component });
+    });
+
+    expect(registry.snapshot()).not.toBe(before);
+    expect(registry.snapshot().sections.map(({ key }) => key)).toEqual(["example:summary"]);
+    expect(registry.snapshot().actions.map(({ key }) => key)).toEqual(["example:open"]);
+    expect(registry.snapshot().views.map(({ key }) => key)).toEqual(["example:details"]);
+    loaded.dispose();
+    unsubscribe();
+    expect(registry.snapshot().sections).toEqual([]);
+    expect(registry.snapshot().actions).toEqual([]);
+    expect(registry.snapshot().views).toEqual([]);
+    expect(notifications).toBe(6);
+  });
+
+  test("rolls back a factory that fails after registering", async () => {
+    const registry = new ClientExtensionRegistry();
+
+    await registry.load("broken", (api) => {
+      api.registerSection({ id: "summary", zone: "threads.sidebar", title: "Summary", Component });
+      throw new Error("boom");
+    });
+
+    expect(registry.snapshot().sections).toEqual([]);
+    expect(registry.errors[0]).toContain("boom");
+  });
+
+  test("a disposed registration cannot remove a later registration with the same ID", async () => {
+    const registry = new ClientExtensionRegistry();
+    let first: { dispose(): void } | undefined;
+
+    await registry.load("example", (api) => {
+      first = api.registerSection({
+        id: "summary",
+        zone: "threads.sidebar",
+        title: "Old",
+        Component,
+      });
+      first.dispose();
+      api.registerSection({ id: "summary", zone: "threads.sidebar", title: "New", Component });
+    });
+    first?.dispose();
+
+    expect(registry.snapshot().sections[0]?.value.title).toBe("New");
+  });
+});

package/src/client-extension-registry.ts

@@ -0,0 +1,159 @@
+import { pathToFileURL } from "node:url";
+import * as React from "react";
+import { useKeyboard } from "@opentui/react";
+import * as v from "valibot";
+import { discoverInstalledExtensionPackages } from "@cueloop/extension-api/installed-packages";
+import type {
+  ClientExtensionAPI,
+  ClientExtensionFactory,
+  ExtensionUIDisposable,
+  ThreadHeaderAction,
+  ThreadSidebarSection,
+  WorkspacePanelView,
+} from "@cueloop/extension-api/client";
+
+interface OwnedContribution<T> {
+  key: string;
+  value: T;
+}
+
+/** A stable snapshot lets React subscribe without rebuilding contribution arrays on every render. */
+export interface ClientExtensionSnapshot {
+  sections: readonly OwnedContribution<ThreadSidebarSection>[];
+  actions: readonly OwnedContribution<ThreadHeaderAction>[];
+  views: readonly OwnedContribution<WorkspacePanelView>[];
+  lastError: string | null;
+}
+
+/** Client extension registrations are isolated by package and disposed on load failure. */
+export class ClientExtensionRegistry {
+  private readonly listeners = new Set<() => void>();
+  private readonly sections = new Map<string, ThreadSidebarSection>();
+  private readonly actions = new Map<string, ThreadHeaderAction>();
+  private readonly views = new Map<string, WorkspacePanelView>();
+  private current: ClientExtensionSnapshot = {
+    sections: [],
+    actions: [],
+    views: [],
+    lastError: null,
+  };
+  readonly errors: string[] = [];
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+
+    return () => this.listeners.delete(listener);
+  };
+
+  readonly snapshot = (): ClientExtensionSnapshot => this.current;
+
+  private changed(): void {
+    this.current = {
+      sections: [...this.sections].map(([key, value]) => ({ key, value })),
+      actions: [...this.actions].map(([key, value]) => ({ key, value })),
+      views: [...this.views].map(([key, value]) => ({ key, value })),
+      lastError: this.errors.at(-1) ?? null,
+    };
+    for (const listener of this.listeners) listener();
+  }
+
+  private add<T extends { id: string; zone: string }>(
+    map: Map<string, T>,
+    owner: string,
+    contribution: T,
+    zone: string,
+  ): ExtensionUIDisposable {
+    if (!/^[a-z][a-z0-9-]*$/.test(contribution.id))
+      throw new Error(`Client extension invalid contribution ID: ${contribution.id}`);
+    if (contribution.zone !== zone)
+      throw new Error(`Client extension ${owner}:${contribution.id} must use zone ${zone}`);
+    const key = `${owner}:${contribution.id}`;
+
+    if (this.sections.has(key) || this.actions.has(key) || this.views.has(key))
+      throw new Error(`Client extension duplicate contribution: ${key}`);
+    map.set(key, contribution);
+    this.changed();
+
+    return {
+      dispose: () => {
+        if (map.get(key) === contribution) {
+          map.delete(key);
+          this.changed();
+        }
+      },
+    };
+  }
+
+  reportError(message: string): void {
+    this.errors.push(message);
+    this.changed();
+  }
+
+  /** Load one client factory and remove all of its registrations if it fails. */
+  async load(owner: string, factory: ClientExtensionFactory): Promise<ExtensionUIDisposable> {
+    const registrations: ExtensionUIDisposable[] = [];
+    const api: ClientExtensionAPI = {
+      react: React,
+      useKeyboard,
+      registerSection: (section) => {
+        const registration = this.add(this.sections, owner, section, "threads.sidebar");
+
+        registrations.push(registration);
+
+        return registration;
+      },
+      registerAction: (action) => {
+        const registration = this.add(this.actions, owner, action, "thread.header");
+
+        registrations.push(registration);
+
+        return registration;
+      },
+      registerView: (view) => {
+        const registration = this.add(this.views, owner, view, "workspace.panels");
+
+        registrations.push(registration);
+
+        return registration;
+      },
+    };
+
+    try {
+      await factory(api);
+    } catch (error) {
+      for (const registration of registrations) registration.dispose();
+      this.reportError(`Client extension ${owner}: ${String(error)}`);
+    }
+
+    return {
+      dispose: () => {
+        for (const registration of registrations) registration.dispose();
+      },
+    };
+  }
+}
+
+/** Import only the client entry points of installed extension packages. */
+export async function loadInstalledClientExtensions(
+  registry: ClientExtensionRegistry,
+  installRoot?: string,
+): Promise<void> {
+  const discovery = discoverInstalledExtensionPackages(installRoot);
+
+  for (const error of discovery.errors) registry.reportError(error);
+  for (const extension of discovery.packages) {
+    if (!extension.clientEntry) continue;
+
+    try {
+      const module: unknown = await import(pathToFileURL(extension.clientEntry).href);
+      const parsed = v.safeParse(v.object({ default: v.function() }), module);
+
+      if (!parsed.success) throw new Error("client entry point must export a default factory");
+      await registry.load(extension.name, async (api) => {
+        await parsed.output.default(api);
+      });
+    } catch (error) {
+      registry.reportError(`Client extension ${extension.name}: ${String(error)}`);
+    }
+  }
+}

package/src/clipboard.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { clipboardCommands } from "./clipboard";
+
+describe(clipboardCommands, () => {
+  test("uses pbcopy on macOS", () => {
+    // Assert
+    expect(clipboardCommands("darwin")).toEqual([["pbcopy"]]);
+  });
+
+  test("uses clip.exe on Windows", () => {
+    // Assert
+    expect(clipboardCommands("win32")).toEqual([["clip.exe"]]);
+  });
+
+  test("prefers wayland, then X11 tools on Linux", () => {
+    // Act
+    const commands = clipboardCommands("linux");
+
+    // Assert
+    expect(commands[0]).toEqual(["wl-copy"]);
+    expect(commands.map((command) => command[0])).toEqual(["wl-copy", "xclip", "xsel"]);
+  });
+});

package/src/clipboard.ts

@@ -0,0 +1,33 @@
+/**
+ * Best-effort system clipboard. Each platform has its own tool; we try them in
+ * order and report whether one worked, so the caller can fall back to printing
+ * the line (the over-SSH case, where no clipboard tool exists). Mirrors how
+ * herdr confirms a copy.
+ */
+
+/** The clipboard-write commands to try, most-preferred first, for this platform. */
+export function clipboardCommands(platform: NodeJS.Platform = process.platform): string[][] {
+  if (platform === "darwin") return [["pbcopy"]];
+  if (platform === "win32") return [["clip.exe"]];
+
+  return [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]];
+}
+
+/** Copy `text` to the clipboard; false when no tool is available or all fail. */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  for (const command of clipboardCommands()) {
+    try {
+      const proc = Bun.spawn(command, {
+        stdin: Buffer.from(text),
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+
+      if ((await proc.exited) === 0) return true;
+    } catch {
+      // tool not installed - try the next one
+    }
+  }
+
+  return false;
+}

package/src/components/AnnotatableFileView.stories.tsx

@@ -0,0 +1,42 @@
+import React from "react";
+import { SCHEMA_VERSION, type Thread } from "@cueloop/schema";
+import { DARK } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { AnnotatableFileView } from "./AnnotatableFileView";
+
+export const meta: StoryMeta = { title: "Surfaces/AnnotatableFileView" };
+
+const SAMPLE = `export function add(a: number, b: number): number {\n  return a + b;\n}\n`;
+
+const SESSION: Thread = {
+  schemaVersion: SCHEMA_VERSION,
+  id: "ses_story",
+  workspace: { repoRoot: "/repo", branch: "main" },
+  artifact: { type: "plan", content: "# Plan\n", meta: {} },
+  revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00Z" }],
+  annotations: [],
+  message: null,
+  status: "pending",
+  createdAt: "2026-01-01T00:00:00Z",
+};
+
+const noop = (): void => {};
+
+export const Loaded: Story = {
+  render: () => (
+    <AnnotatableFileView
+      path="src/add.ts"
+      loadContents={() => Promise.resolve(SAMPLE)}
+      session={SESSION}
+      quickActions={[]}
+      observer={false}
+      onAddComment={noop}
+      onReply={noop}
+      onUpdateAnnotation={noop}
+      onExit={noop}
+      theme={DARK}
+    />
+  ),
+  expectedColors: [DARK.textDim],
+  size: { width: 60, height: 12 },
+};

package/src/components/AnnotatableFileView.test.tsx

@@ -0,0 +1,102 @@
+/**
+ * A project file is its own annotation surface: selecting a line and typing leaves a comment whose
+ * anchor quotes that file line, handed up as an Anchor the app persists with a file target.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import React from "react";
+import { SCHEMA_VERSION, type Anchor, type Thread } from "@cueloop/schema";
+import { AnnotatableFileView } from "./AnnotatableFileView";
+import { DARK } from "../theme";
+import { dragText, typeText, pressKey, waitForText } from "../test-support";
+
+const SAMPLE = "export function add(a: number, b: number) {\n  return a + b;\n}\n";
+
+function planSession(): Thread {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_plan",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: [],
+    message: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+}
+
+const noop = (): void => {};
+
+describe("AnnotatableFileView", () => {
+  test("commenting a file line hands up an anchor that quotes the line", async () => {
+    const onAddComment = mock((_anchor: Anchor, _body: string) => {});
+    const setup = await testRender(
+      <AnnotatableFileView
+        path="src/add.ts"
+        loadContents={() => Promise.resolve(SAMPLE)}
+        session={planSession()}
+        quickActions={[]}
+        observer={false}
+        onAddComment={onAddComment}
+        onReply={noop}
+        onUpdateAnnotation={noop}
+        onExit={noop}
+        theme={DARK}
+      />,
+      { width: 64, height: 12 },
+    );
+
+    // Act - select the middle line, type a comment, send it
+    await waitForText(setup, "return a + b");
+    await dragText(setup, "return a + b", "return a + b", "return a + b".length);
+    await typeText(setup, "why not reduce?");
+    await pressKey(setup, "RETURN", { meta: true });
+
+    // Assert - the surface built an anchor quoting the file line and handed it up with the body
+    expect(onAddComment).toHaveBeenCalled();
+    const [anchor, body] = onAddComment.mock.calls[0]!;
+    expect(anchor.quote).toContain("return a + b");
+    expect(body).toContain("why not reduce?");
+
+    setup.renderer.destroy();
+  });
+
+  test("a head-side (deleted-line) note never rebinds onto the current file", async () => {
+    const session = planSession();
+    // a note left on the removed side of this file: the worktree view must not show it
+    session.annotations = [
+      {
+        id: "h1",
+        kind: "comment",
+        anchor: { quote: "return a + b", prefix: "", suffix: "" },
+        target: { kind: "file", path: "src/add.ts", rev: "head" },
+        body: "deleted-side note",
+        createdAt: "2026-01-01T00:00:00Z",
+      },
+    ];
+    const setup = await testRender(
+      <AnnotatableFileView
+        path="src/add.ts"
+        loadContents={() => Promise.resolve(SAMPLE)}
+        session={session}
+        quickActions={[]}
+        observer={false}
+        onAddComment={noop}
+        onReply={noop}
+        onUpdateAnnotation={noop}
+        onExit={noop}
+        theme={DARK}
+      />,
+      { width: 64, height: 12 },
+    );
+
+    await waitForText(setup, "return a + b");
+
+    // Assert - the current file shows, but the head-side note is not attached to it
+    expect(setup.captureCharFrame()).not.toContain("deleted-side note");
+
+    setup.renderer.destroy();
+  });
+});