@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.101

package/src/diff/walk.ts

@@ -0,0 +1,73 @@
+/**
+ * Guided-walk projections: 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;
+  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.kind !== "add" && row.kind !== "del") continue;
+    if (row.kind === "add") file.added += 1;
+    else file.removed += 1;
+    if (file.preview.length < WALK_PREVIEW_ROWS) {
+      file.preview.push({
+        sign: row.kind === "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;
+}

package/src/index.ts

@@ -1,2 +1,31 @@
-export { runClient, type RunClientOptions } from "./run";
-export { serveClient, type ServeHandle, type ServeOptions } from "./serve";
+export { runClient, type RunClientOptions } from "./app/run";
+export { snapshotWorkbench, type RepoDiff } from "./workbench/workbench-snapshot";
+export {
+  defaultLayout,
+  pairLayout,
+  planLayout,
+  pullRequestReviewLayout,
+  reviewLayout,
+  type LaunchLayout,
+} from "./app/launch-layout";
+export {
+  diffRowAnchor,
+  diffRows,
+  diffRowText,
+  fileRowRange,
+  resolveReviewAnchorRow,
+  type DiffRow,
+} from "./diff/view-diff";
+export { loadConfig, type ReviewWorkspaceMode } from "./settings/config";
+export { serveClient, type ServeHandle, type ServeOptions } from "./app/serve";
+export { App, type AppProps } from "./app/App";
+export {
+  collaboratorAnnotations,
+  mergeFromShare,
+  publishShare,
+  pullShare,
+  pushShare,
+  shareIdFromLine,
+  type ShareResult,
+  type ShareTarget,
+} from "./integrations/share";

package/src/integrations/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/integrations/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/integrations/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/integrations/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/integrations/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/integrations/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/integrations/components/ExtensionZone.stories.tsx

@@ -0,0 +1,28 @@
+import React from "react";
+import { ClientExtensionRegistry } from "../client-extension-registry";
+import type { Story, StoryMeta } from "../../stories/story";
+import { ExtensionZone } from "./ExtensionZone";
+
+export const meta: StoryMeta = { title: "Extensions/ExtensionZone" };
+
+const registry = new ClientExtensionRegistry();
+
+void registry.load("example", (api) => {
+  api.registerSection({
+    id: "summary",
+    zone: "threads.sidebar",
+    title: "Summary",
+    Component: () => <text>Two pending Threads</text>,
+  });
+});
+
+export const SidebarSection: Story = {
+  render: () => (
+    <ExtensionZone
+      zone="threads.sidebar"
+      registry={registry}
+      context={{ workspace: "/repo", threadId: null }}
+    />
+  ),
+  size: { width: 32, height: 8 },
+};

package/src/integrations/components/ExtensionZone.tsx

@@ -0,0 +1,145 @@
+import React, { useEffect, useMemo, useSyncExternalStore } from "react";
+import type { ExtensionUIContext } from "@cueloop/extension-api/client";
+import type {
+  ClientExtensionRegistry,
+  ClientExtensionSnapshot,
+} from "../client-extension-registry";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+import { IconButton } from "../../ui/components/primitives/IconButton";
+import { NERD } from "../../ui/components/primitives/icons";
+
+/** Subscribe to the client extension registry without coupling extensions to React state. */
+export function useClientExtensionSnapshot(
+  registry: ClientExtensionRegistry,
+): ClientExtensionSnapshot {
+  return useSyncExternalStore(registry.subscribe, registry.snapshot, registry.snapshot);
+}
+
+interface VisibleContributions<T> {
+  items: T[];
+  errors: string[];
+}
+
+/** Evaluate visibility without letting one extension remove another's UI. */
+export function visibleContributions<
+  T extends {
+    key: string;
+    value: { when?: (context: ExtensionUIContext) => boolean };
+  },
+>(contributions: readonly T[], context: ExtensionUIContext): VisibleContributions<T> {
+  const items: T[] = [];
+  const errors: string[] = [];
+
+  for (const contribution of contributions) {
+    try {
+      if (!contribution.value.when || contribution.value.when(context)) items.push(contribution);
+    } catch (error) {
+      errors.push(`Extension ${contribution.key} visibility failed: ${String(error)}`);
+    }
+  }
+
+  return { items, errors };
+}
+
+type VisibilityContribution = {
+  key: string;
+  value: { when?: (context: ExtensionUIContext) => boolean };
+};
+
+class ExtensionRenderBoundary extends React.Component<
+  { children: React.ReactNode; onError?: (message: string) => void },
+  { failed: boolean }
+> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: Error): void {
+    console.error("Client extension rendering failed", error);
+    this.props.onError?.(`Extension rendering failed: ${error.message}`);
+  }
+
+  render(): React.ReactNode {
+    if (this.state.failed) return <text>Extension failed</text>;
+
+    return this.props.children;
+  }
+}
+
+/** Render host-framed sections, host buttons, or the selected workspace view. */
+export function ExtensionZone(props: {
+  zone: "threads.sidebar" | "thread.header" | "workspace.panels";
+  registry: ClientExtensionRegistry;
+  context: ExtensionUIContext;
+  selectedViewId?: string | null;
+  onError?: (message: string) => void;
+}): React.ReactNode {
+  const { zone, registry, context, selectedViewId, onError } = props;
+  const snapshot = useClientExtensionSnapshot(registry);
+  const theme = useComponentTheme();
+  const { workspace, threadId } = context;
+  const visibility = useMemo(() => {
+    const contributions: readonly VisibilityContribution[] =
+      zone === "threads.sidebar"
+        ? snapshot.sections
+        : zone === "thread.header"
+          ? snapshot.actions
+          : [];
+
+    return visibleContributions(contributions, { workspace, threadId });
+  }, [zone, snapshot, workspace, threadId]);
+
+  useEffect(() => {
+    for (const error of visibility.errors) onError?.(error);
+  }, [visibility, onError]);
+
+  const visibleKeys = new Set(visibility.items.map(({ key }) => key));
+
+  if (zone === "threads.sidebar") {
+    return snapshot.sections
+      .filter(({ key }) => visibleKeys.has(key))
+      .map(({ key, value }) => (
+        <box key={key} style={{ flexDirection: "column", maxHeight: 8, flexShrink: 0 }}>
+          <text fg={theme.textDim}>{value.title}</text>
+          <ExtensionRenderBoundary onError={onError}>
+            {React.createElement(value.Component, { context })}
+          </ExtensionRenderBoundary>
+        </box>
+      ));
+  }
+
+  if (zone === "thread.header") {
+    return snapshot.actions
+      .filter(({ key }) => visibleKeys.has(key))
+      .map(({ key, value }) => (
+        <IconButton
+          key={key}
+          glyph={value.glyph ?? NERD.kebab}
+          tip={value.label}
+          onPress={() => {
+            try {
+              void Promise.resolve(value.onPress(context)).catch((error) => {
+                console.error(`Client extension action failed: ${key}`, error);
+                onError?.(`Extension action failed: ${value.label}`);
+              });
+            } catch (error) {
+              console.error(`Client extension action failed: ${key}`, error);
+              onError?.(`Extension action failed: ${value.label}`);
+            }
+          }}
+          marginRight={1}
+          theme={theme}
+        />
+      ));
+  }
+
+  const selected = snapshot.views.find(({ key }) => key === selectedViewId);
+
+  return selected ? (
+    <ExtensionRenderBoundary key={selected.key} onError={onError}>
+      {React.createElement(selected.value.Component, { context })}
+    </ExtensionRenderBoundary>
+  ) : null;
+}

package/src/integrations/components/ShareDialog.agent.test.tsx

@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { DARK } from "../../appearance/theme";
+import { press, waitForText } from "../../testing/test-support";
+import { ShareDialog } from "./ShareDialog";
+import { newWizardDraft, shareDialogStore } from "./share-dialog-store";
+import type { NewShareLink } from "../../thread/thread-controller";
+
+for (const enabled of [false, true])
+  test(`share agent toggle is ${enabled ? "opt-in" : "hidden"}`, async () => {
+    const created: NewShareLink[] = [];
+
+    shareDialogStore.getState().reset();
+    shareDialogStore.getState().openWizard(newWizardDraft("Review"));
+    const setup = await testRender(
+      <ShareDialog
+        isOpen
+        isOwner
+        agentAvailable={enabled}
+        links={[]}
+        threadName="Review"
+        theme={DARK}
+        onCreateLink={(input) => created.push(input)}
+        onUpdateLink={() => {}}
+        onDeleteLink={() => {}}
+        onCopyLink={() => {}}
+        onClose={() => {}}
+      />,
+      { width: 100, height: 26 },
+    );
+
+    try {
+      await waitForText(setup, "link name");
+      expect(shareDialogStore.getState().wizard?.agentEnabled ?? false).toBe(false);
+      expect(setup.captureCharFrame().includes("Allow agent messages")).toBe(enabled);
+      await press(setup, "down");
+      await press(setup, "down");
+      if (enabled) {
+        await press(setup, " ");
+        await press(setup, "down");
+      }
+      await press(setup, "enter");
+      expect(created).toHaveLength(1);
+      expect(created[0]?.agentEnabled).toBe(enabled ? true : undefined);
+    } finally {
+      setup.renderer.destroy();
+      shareDialogStore.getState().reset();
+    }
+  });