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

package/src/ghostty-terminal.ts

@@ -0,0 +1,199 @@
+/**
+ * A live in-process terminal emulator backed by Ghostty's VT core (libghostty-vt)
+ * through a flat FFI shim (native/src/shim.zig). Feed it a child process's PTY
+ * output with `write`, then read the rendered screen cell-by-cell with `readCell`
+ * to paint it anywhere - this is what lets a real `cc`/shell render inside an
+ * OpenTUI box. Load with `loadGhosttyTerminals`, which returns null when no
+ * prebuilt dylib exists for this platform (callers fall back to a herdr split).
+ */
+
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** How a cell's color arrived from Ghostty: the terminal default, an ANSI palette index, or true RGB. */
+export type GhosttyColor =
+  | { kind: "default" }
+  | { kind: "palette"; index: number }
+  | { kind: "rgb"; r: number; g: number; b: number };
+
+/** The cursor's viewport position and whether it should be drawn. */
+export interface GhosttyCursor {
+  x: number;
+  y: number;
+  visible: boolean;
+}
+
+/** One decoded screen cell: its glyph, colors, cell width, and text decorations. */
+export interface GhosttyCell {
+  /** Unicode code point; 0 = blank. */
+  codepoint: number;
+  fg: GhosttyColor;
+  bg: GhosttyColor;
+  /** Ghostty width tag: 0 = normal, 1 = double-width lead, 2 = trailing cell. */
+  width: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  inverse: boolean;
+  faint: boolean;
+  strikethrough: boolean;
+}
+
+const CVT_SYMBOLS = {
+  cvt_new: { args: [FFIType.u16, FFIType.u16], returns: FFIType.ptr },
+  cvt_free: { args: [FFIType.ptr], returns: FFIType.void },
+  cvt_write: { args: [FFIType.ptr, FFIType.ptr, FFIType.u64], returns: FFIType.void },
+  cvt_resize: { args: [FFIType.ptr, FFIType.u16, FFIType.u16], returns: FFIType.void },
+  cvt_cell: { args: [FFIType.ptr, FFIType.u16, FFIType.u32, FFIType.ptr], returns: FFIType.i32 },
+  cvt_cursor: { args: [FFIType.ptr, FFIType.ptr], returns: FFIType.void },
+} as const;
+
+type CvtLib = ReturnType<typeof dlopen<typeof CVT_SYMBOLS>>["symbols"];
+
+/** The prebuilt shim dylib for this platform, or null when none ships for it. */
+function nativeLibraryPath(): string | null {
+  const suffix = process.platform === "darwin" ? "dylib" : "so";
+  const dir = `${process.platform}-${process.arch}`;
+  const path = join(import.meta.dir, "..", "native", dir, `libcueloopvt.${suffix}`);
+
+  return existsSync(path) ? path : null;
+}
+
+/** One shared load of the VT library; null when no dylib ships or it failed to load. */
+let ghosttyFactory: GhosttyTerminalFactory | null | undefined;
+
+/**
+ * Open the Ghostty VT library for this platform, or return null when the prebuilt
+ * dylib is missing (the caller degrades to a herdr split instead of embedding).
+ * The library is opened once per process; later calls return the same factory.
+ */
+export function loadGhosttyTerminals(): GhosttyTerminalFactory | null {
+  if (ghosttyFactory !== undefined) return ghosttyFactory;
+  const path = nativeLibraryPath();
+
+  if (!path) return (ghosttyFactory = null);
+  try {
+    const lib = dlopen(path, CVT_SYMBOLS);
+
+    ghosttyFactory = new GhosttyTerminalFactory(lib.symbols);
+  } catch (error) {
+    // The file exists but failed to load (bad arch, missing symbol) - a real
+    // fault, not the expected no-prebuilt case; surface it, then degrade.
+    console.error(`cueloop: failed to load ${path}:`, error);
+    ghosttyFactory = null;
+  }
+
+  return ghosttyFactory;
+}
+
+/** Creates `GhosttyTerminal`s that share one loaded copy of the VT library. */
+export class GhosttyTerminalFactory {
+  constructor(private readonly lib: CvtLib) {}
+  /** A fresh terminal sized to cols x rows, or null if allocation failed. */
+  create(cols: number, rows: number): GhosttyTerminal | null {
+    const handle = this.lib.cvt_new(cols, rows);
+
+    return handle ? new GhosttyTerminal(this.lib, handle) : null;
+  }
+}
+
+// The flat CvtCell struct the shim writes: u32 codepoint, fg rgba-ish (4 bytes),
+// bg (4 bytes), u8 width, u8 flags, u16 pad = 16 bytes.
+const CELL_STRUCT_BYTES = 16;
+const FLAG_BOLD = 1;
+const FLAG_ITALIC = 2;
+const FLAG_UNDERLINE = 4;
+const FLAG_INVERSE = 8;
+const FLAG_FAINT = 16;
+const FLAG_STRIKETHROUGH = 32;
+
+/** A live Ghostty terminal: feed PTY bytes, read the screen, resize, free. */
+export class GhosttyTerminal {
+  private readonly out = new Uint8Array(CELL_STRUCT_BYTES);
+  private readonly outView = new DataView(this.out.buffer);
+  private readonly cursorOut = new Uint8Array(8);
+  private freed = false;
+
+  constructor(
+    private readonly lib: CvtLib,
+    private readonly handle: NonNullable<ReturnType<CvtLib["cvt_new"]>>,
+  ) {}
+
+  /** Process a chunk of the child's PTY output into the screen state. */
+  write(bytes: Uint8Array): void {
+    if (this.freed || bytes.length === 0) return;
+    this.lib.cvt_write(this.handle, ptr(bytes), BigInt(bytes.length));
+  }
+
+  /** Resize the screen (and the child's tty, via the caller) to cols x rows. */
+  resize(cols: number, rows: number): void {
+    if (this.freed) return;
+    this.lib.cvt_resize(this.handle, cols, rows);
+  }
+
+  /** The rendered cell at viewport (x, y), or null when out of range. */
+  readCell(x: number, y: number): GhosttyCell | null {
+    if (this.freed) return null;
+    if (this.lib.cvt_cell(this.handle, x, y, ptr(this.out)) !== 0) return null;
+    const flags = this.out[13]!;
+
+    return {
+      codepoint: this.outView.getUint32(0, true),
+      fg: decodeColor(this.out[7]!, this.out[4]!, this.out[5]!, this.out[6]!),
+      bg: decodeColor(this.out[11]!, this.out[8]!, this.out[9]!, this.out[10]!),
+      width: this.out[12]!,
+      bold: (flags & FLAG_BOLD) !== 0,
+      italic: (flags & FLAG_ITALIC) !== 0,
+      underline: (flags & FLAG_UNDERLINE) !== 0,
+      inverse: (flags & FLAG_INVERSE) !== 0,
+      faint: (flags & FLAG_FAINT) !== 0,
+      strikethrough: (flags & FLAG_STRIKETHROUGH) !== 0,
+    };
+  }
+
+  /**
+   * Row `y` as text: blank cells read as spaces, the trailing half of a wide
+   * glyph is skipped, and trailing spaces are trimmed.
+   */
+  rowText(y: number, cols: number): string {
+    let line = "";
+
+    for (let x = 0; x < cols; x++) {
+      const cell = this.readCell(x, y);
+
+      if (cell === null || cell.width === 2) continue;
+      line += cell.codepoint === 0 ? " " : String.fromCodePoint(cell.codepoint);
+    }
+
+    return line.trimEnd();
+  }
+
+  /** The cursor's current viewport position and visibility. */
+  readCursor(): GhosttyCursor {
+    if (this.freed) return { x: 0, y: 0, visible: false };
+    this.lib.cvt_cursor(this.handle, ptr(this.cursorOut));
+    const view = new DataView(this.cursorOut.buffer);
+
+    return {
+      x: view.getUint16(0, true),
+      y: view.getUint16(2, true),
+      visible: this.cursorOut[4] === 1,
+    };
+  }
+
+  /** Release the terminal; further calls are no-ops. Call once on teardown. */
+  free(): void {
+    if (this.freed) return;
+    this.freed = true;
+    this.lib.cvt_free(this.handle);
+  }
+}
+
+/** Decode the shim's (kind, r, g, b) color triple; palette carries its index in r. */
+function decodeColor(kind: number, r: number, g: number, b: number): GhosttyColor {
+  if (kind === 2) return { kind: "rgb", r, g, b };
+  if (kind === 1) return { kind: "palette", index: r };
+
+  return { kind: "default" };
+}

package/src/github-identity.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, expect, test } from "bun:test";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveGithubIdentity } from "./github-identity";
+
+const originalBinary = process.env.CUELOOP_GH;
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  if (originalBinary === undefined) delete process.env.CUELOOP_GH;
+  else process.env.CUELOOP_GH = originalBinary;
+  for (const directory of tempDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function stubGithubCli(script: string): string {
+  const directory = mkdtempSync(join(tmpdir(), "gh-stub-"));
+
+  tempDirectories.push(directory);
+  const path = join(directory, "gh");
+
+  writeFileSync(path, `#!/bin/sh\n${script}\n`);
+  chmodSync(path, 0o755);
+
+  return path;
+}
+
+test("reads the GitHub login and name from gh", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`printf '{"login":"markus","name":"Markus M"}'`);
+
+  expect(await resolveGithubIdentity()).toEqual({ login: "markus", name: "Markus M" });
+});
+
+test("drops a null name to undefined", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`printf '{"login":"markus","name":null}'`);
+
+  expect(await resolveGithubIdentity()).toEqual({ login: "markus" });
+});
+
+test("falls back to null when gh exits non-zero (logged out)", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`exit 1`);
+
+  expect(await resolveGithubIdentity()).toBeNull();
+});
+
+test("falls back to null when gh is not installed", async () => {
+  process.env.CUELOOP_GH = join(tmpdir(), "cueloop-absent-gh-binary");
+
+  expect(await resolveGithubIdentity()).toBeNull();
+});
+
+test("falls back to null when gh prints an unexpected shape", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`printf 'not json'`);
+
+  expect(await resolveGithubIdentity()).toBeNull();
+});

package/src/github-identity.ts

@@ -0,0 +1,41 @@
+/** The signed-in GitHub identity from the local gh tool, or null when gh cannot answer. */
+
+import * as v from "valibot";
+
+export interface GithubIdentity {
+  login: string;
+  name?: string;
+}
+
+const GithubUserSchema = v.object({
+  login: v.string(),
+  name: v.nullish(v.string()),
+});
+
+/** The gh binary is injectable so tests stub it without a real GitHub login. */
+function githubCliBinary(): string {
+  return process.env.CUELOOP_GH || "gh";
+}
+
+/** Read the authenticated GitHub login and name, or null when gh cannot answer. */
+export async function resolveGithubIdentity(): Promise<GithubIdentity | null> {
+  try {
+    const githubProcess = Bun.spawn(
+      [githubCliBinary(), "api", "user", "--jq", "{login: .login, name: .name}"],
+      { stdout: "pipe", stderr: "ignore" },
+    );
+    const [output, exitCode] = await Promise.all([
+      new Response(githubProcess.stdout).text(),
+      githubProcess.exited,
+    ]);
+
+    if (exitCode !== 0) return null;
+    const parsed = v.safeParse(GithubUserSchema, JSON.parse(output));
+
+    if (!parsed.success) return null;
+
+    return { login: parsed.output.login, name: parsed.output.name ?? undefined };
+  } catch {
+    return null;
+  }
+}

package/src/herdr.test.ts

@@ -2,50 +2,23 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { focusHerdrPane, returnPaneFor } from "./herdr";
+import { focusHerdrPane } from "./herdr";
 
 let dir: string;
-const savedEnv: Record<string, string | undefined> = {};
 
 beforeEach(() => {
   dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-"));
-  for (const k of ["HERDR_ENV", "HERDR_PANE_ID", "HERDR_BIN_PATH", "CUELOOP_RETURN_PANE"]) {
-    savedEnv[k] = process.env[k];
-    delete process.env[k];
-  }
 });
 afterEach(() => {
-  for (const [k, v] of Object.entries(savedEnv)) {
-    if (v === undefined) delete process.env[k];
-    else process.env[k] = v;
-  }
   rmSync(dir, { recursive: true, force: true });
 });
 
-describe("returnPaneFor", () => {
-  test("outside herdr there is never a return target", () => {
-    expect(returnPaneFor("w1:p1")).toBeUndefined();
-  });
-
-  test("env override wins, session meta is the fallback", () => {
-    process.env.HERDR_ENV = "1";
-    process.env.HERDR_PANE_ID = "w1:p9";
-    expect(returnPaneFor("w1:p1")).toBe("w1:p1");
-    process.env.CUELOOP_RETURN_PANE = "w1:p2";
-    expect(returnPaneFor("w1:p1")).toBe("w1:p2");
-  });
-
-  test("returning to our own pane is a no-op", () => {
-    process.env.HERDR_ENV = "1";
-    process.env.HERDR_PANE_ID = "w1:p1";
-    expect(returnPaneFor("w1:p1")).toBeUndefined();
-  });
-});
-
 describe("focusHerdrPane", () => {
   test("resolves the pane's tab and focuses it", () => {
+    // Arrange
     const log = join(dir, "calls.log");
     const stub = join(dir, "herdr");
+
     writeFileSync(
       stub,
       `#!/bin/sh
@@ -54,15 +27,17 @@ if [ "$1" = "pane" ]; then echo '{"result":{"pane":{"tab_id":"w1:t3"}}}'; fi
 `,
     );
     Bun.spawnSync(["chmod", "+x", stub]);
-    process.env.HERDR_BIN_PATH = stub;
-    expect(focusHerdrPane("w1:p1")).toBe(true);
+
+    // Assert
+    expect(focusHerdrPane(stub, "w1:p1")).toBe(true);
     const calls = readFileSync(log, "utf8").trim().split("\n");
+
     expect(calls[0]).toBe("pane get w1:p1");
     expect(calls[1]).toBe("tab focus w1:t3");
   });
 
   test("a missing binary never throws", () => {
-    process.env.HERDR_BIN_PATH = join(dir, "nope");
-    expect(focusHerdrPane("w1:p1")).toBe(false);
+    // Assert
+    expect(focusHerdrPane(join(dir, "nope"), "w1:p1")).toBe(false);
   });
 });

package/src/herdr.ts

@@ -1,33 +1,37 @@
 /**
- * First-class herdr return (#23): a review opened beside an agent should hand
- * focus back to the agent's pane when it closes, not leave the reviewer on a
- * dead tab. Detection is the ambient env contract; the return target comes
- * from CUELOOP_RETURN_PANE (set by whoever opened this pane) or the session's
- * recorded herdrPane (set by the adapter hook). Everything here is
- * best-effort: focus failures never block closing the review.
+ * First-class herdr return: a review opened beside an agent hands focus back
+ * to the agent's pane when it closes, not leaving the reviewer on a dead tab.
+ * The env contract and the return-target rule live in @cueloop/schema; this
+ * module owns the one reviewer-side action that spawns the herdr CLI. Focus
+ * is best-effort - a failure never blocks closing the review.
  */
 
-export function insideHerdr(): boolean {
-  return process.env.HERDR_ENV === "1";
-}
+import * as v from "valibot";
 
-export function returnPaneFor(sessionHerdrPane?: string): string | undefined {
-  if (!insideHerdr()) return undefined;
-  const pane = process.env.CUELOOP_RETURN_PANE ?? sessionHerdrPane;
-  // returning to our own pane would be a no-op at best
-  return pane && pane !== process.env.HERDR_PANE_ID ? pane : undefined;
-}
+const HerdrPaneSchema = v.object({
+  result: v.optional(v.object({ pane: v.optional(v.object({ tab_id: v.optional(v.string()) })) })),
+});
 
 /** Focus the tab holding the target pane. Synchronous: runs just before exit. */
-export function focusHerdrPane(paneId: string): boolean {
-  const bin = process.env.HERDR_BIN_PATH ?? "herdr";
+export function focusHerdrPane(binPath: string, paneId: string): boolean {
   try {
-    const got = Bun.spawnSync([bin, "pane", "get", paneId], { stdout: "pipe", stderr: "ignore" });
+    const got = Bun.spawnSync([binPath, "pane", "get", paneId], {
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+
     if (got.exitCode !== 0) return false;
-    const parsed = JSON.parse(got.stdout.toString()) as { result?: { pane?: { tab_id?: string } } };
-    const tab = parsed.result?.pane?.tab_id;
+    const parsed = v.safeParse(HerdrPaneSchema, JSON.parse(got.stdout.toString()));
+
+    if (!parsed.success) return false;
+    const tab = parsed.output.result?.pane?.tab_id;
+
     if (!tab) return false;
-    return Bun.spawnSync([bin, "tab", "focus", tab], { stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+
+    return (
+      Bun.spawnSync([binPath, "tab", "focus", tab], { stdout: "ignore", stderr: "ignore" })
+        .exitCode === 0
+    );
   } catch {
     return false;
   }

package/src/index.ts

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

package/src/integrations.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { OBSIDIAN_DEFAULTS } from "@cueloop/integration-obsidian";
+import { loadBundledExporters } from "./integrations";
+import type { IntegrationsConfig } from "./config";
+
+function integrations(overrides: Partial<typeof OBSIDIAN_DEFAULTS> = {}): IntegrationsConfig {
+  return { obsidian: { ...OBSIDIAN_DEFAULTS, ...overrides } };
+}
+
+describe("loadBundledExporters", () => {
+  test("composes the obsidian integration into one named exporter", async () => {
+    // Act
+    const exporters = await loadBundledExporters(integrations());
+
+    // Assert
+    expect(exporters.map((exporter) => exporter.name)).toEqual(["obsidian"]);
+  });
+
+  test("runsOn mirrors the configured export policy", async () => {
+    // Arrange
+    const onApprove = (await loadBundledExporters(integrations({ exportOn: "approved" })))[0]!;
+
+    // Assert
+    expect(onApprove.runsOn("approved")).toBeTrue();
+    expect(onApprove.runsOn("changes_requested")).toBeFalse();
+
+    // Arrange
+    const onMessage = (await loadBundledExporters(integrations({ exportOn: "message" })))[0]!;
+
+    // Assert
+    expect(onMessage.runsOn("approved")).toBeTrue();
+    expect(onMessage.runsOn("changes_requested")).toBeTrue();
+
+    // Arrange
+    const manual = (await loadBundledExporters(integrations({ exportOn: "manual" })))[0]!;
+
+    // Assert
+    expect(manual.runsOn("approved")).toBeFalse();
+    expect(manual.runsOn("changes_requested")).toBeFalse();
+  });
+});

package/src/integrations.ts

@@ -0,0 +1,32 @@
+/**
+ * Bundled integration wiring: composes the configured integrations into
+ * generic exporters plus their run policy, so the session controller depends
+ * only on the extension seam, never on an integration's own config type. This
+ * and config.ts are the only client modules that name a concrete integration.
+ */
+
+import { Registry, type Exporter } from "@cueloop/extension-api";
+import { createObsidianExtension, shouldExport } from "@cueloop/integration-obsidian";
+import type { MessageOutcome } from "@cueloop/schema";
+import type { IntegrationsConfig } from "./config";
+
+/** An exporter plus the policy deciding which messages trigger it. */
+export interface BundledExporter {
+  name: string;
+  run: Exporter;
+  runsOn(message: MessageOutcome): boolean;
+}
+
+/** Load the bundled integrations from config as generic exporters. */
+export async function loadBundledExporters(
+  integrations: IntegrationsConfig,
+): Promise<BundledExporter[]> {
+  const registry = new Registry();
+  const obsidian = integrations.obsidian;
+  const record = await registry.load("obsidian", createObsidianExtension(obsidian));
+  const run = record.exporters.get("obsidian");
+
+  if (!run) return [];
+
+  return [{ name: "obsidian", run, runsOn: (message) => shouldExport(obsidian.exportOn, message) }];
+}