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

package/src/diff-syntax.ts

@@ -0,0 +1,179 @@
+/**
+ * Syntax highlighting for diff rows: tree-sitter token colors mapped onto the
+ * diff sheet's hand-rolled rows, so annotation cards still interleave. A hunk is
+ * highlighted as a contiguous fragment (its context+addition lines as the new
+ * side, context+deletion lines as the old side) - never per single line, which
+ * would lose the multi-line grammar context - and the resulting token spans are
+ * mapped back to each row in line-relative columns. Async: the shared tree-sitter
+ * client resolves off the render path, so callers draw unstyled first.
+ */
+
+import { getTreeSitterClient, type SimpleHighlight } from "@opentui/core";
+import type { DiffRow } from "./view-diff";
+import { filetypeForPath } from "./components/syntax-highlight";
+
+/** A syntax-colored run within one row, in line-relative columns [start, end). */
+export interface SyntaxSpan {
+  start: number;
+  end: number;
+  group: string;
+}
+
+function stripTrailingNewline(text: string): string {
+  return text.replace(/\n$/, "");
+}
+
+interface HighlightJob {
+  filetype: string;
+  source: string;
+  /** Row index for each line of `source`, in order. */
+  rowIndexByLine: number[];
+}
+
+/**
+ * Split diff rows into per-hunk highlight jobs, one per side. A hunk's rows are
+ * contiguous file lines, so each side reconstructs to valid code; file/hunk
+ * header rows and files without a known filetype are skipped.
+ */
+export function highlightJobs(rows: DiffRow[]): HighlightJob[] {
+  const jobs: HighlightJob[] = [];
+  let oldLines: string[] = [];
+  let newLines: string[] = [];
+  let oldRowIndexByLine: number[] = [];
+  let newRowIndexByLine: number[] = [];
+  let filetype: string | undefined;
+
+  const flush = (): void => {
+    if (filetype) {
+      if (oldLines.length)
+        jobs.push({ filetype, source: oldLines.join("\n"), rowIndexByLine: oldRowIndexByLine });
+      if (newLines.length)
+        jobs.push({ filetype, source: newLines.join("\n"), rowIndexByLine: newRowIndexByLine });
+    }
+    oldLines = [];
+    newLines = [];
+    oldRowIndexByLine = [];
+    newRowIndexByLine = [];
+  };
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+    const row = rows[rowIndex]!;
+
+    if (row.kind === "file" || row.kind === "hunk") {
+      flush();
+      filetype = row.kind === "file" ? filetypeForPath(row.file) : filetype;
+      continue;
+    }
+    const text = stripTrailingNewline(row.text);
+
+    if (row.kind === "ctx" || row.kind === "del") {
+      oldLines.push(text);
+      oldRowIndexByLine.push(rowIndex);
+    }
+    if (row.kind === "ctx" || row.kind === "add") {
+      newLines.push(text);
+      newRowIndexByLine.push(rowIndex);
+    }
+  }
+  flush();
+
+  return jobs;
+}
+
+/**
+ * Resolve one source's flat, possibly-overlapping token highlights into
+ * per-line spans. Offsets are absolute into `source`; later highlights win on
+ * overlap, and a highlight is clamped to the line its start falls on.
+ */
+export function spansByLine(source: string, highlights: SimpleHighlight[]): SyntaxSpan[][] {
+  const lineStarts: number[] = [0];
+
+  for (let index = 0; index < source.length; index++) {
+    if (source[index] === "\n") lineStarts.push(index + 1);
+  }
+  const lineOf = (offset: number): number => {
+    let low = 0;
+    let high = lineStarts.length - 1;
+
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+
+      if (lineStarts[mid]! <= offset) low = mid;
+      else high = mid - 1;
+    }
+
+    return low;
+  };
+  // Per-line char->group, later highlights overriding, then coalesce into spans.
+  const groupsByLine: Array<Array<string | undefined>> = lineStarts.map((start, line) => {
+    const end = line + 1 < lineStarts.length ? lineStarts[line + 1]! - 1 : source.length;
+
+    return Array.from({ length: Math.max(0, end - start) }, () => undefined);
+  });
+
+  for (const [start, rawEnd, group] of highlights) {
+    // A capture can span newlines (block comments, template literals); color the
+    // covered columns on every line it crosses, not just the starting line. Offsets
+    // past the source (byte offsets from a multi-byte line) clamp to its end, or the
+    // walk below would sit on the last line forever.
+    const end = Math.min(rawEnd, source.length);
+    let cursor = Math.max(0, start);
+
+    while (cursor < end) {
+      const line = lineOf(cursor);
+      const lineStart = lineStarts[line]!;
+      const lineEnd = line + 1 < lineStarts.length ? lineStarts[line + 1]! - 1 : source.length;
+      const chars = groupsByLine[line]!;
+      const to = Math.min(end, lineEnd) - lineStart;
+
+      for (let column = cursor - lineStart; column < to; column++) chars[column] = group;
+      cursor = lineEnd + 1;
+    }
+  }
+
+  return groupsByLine.map((chars) => {
+    const spans: SyntaxSpan[] = [];
+
+    for (let column = 0; column < chars.length; column++) {
+      const group = chars[column];
+
+      if (group === undefined) continue;
+      const previous = spans[spans.length - 1];
+
+      if (previous && previous.group === group && previous.end === column)
+        previous.end = column + 1;
+      else spans.push({ start: column, end: column + 1, group });
+    }
+
+    return spans;
+  });
+}
+
+/**
+ * Highlight the diff's rows and return the token spans per row index. Rows in a
+ * file with no known filetype, and any row while highlighting is still resolving,
+ * are absent - the caller renders those unstyled.
+ */
+export async function highlightDiffRows(rows: DiffRow[]): Promise<Map<number, SyntaxSpan[]>> {
+  const spansByRow = new Map<number, SyntaxSpan[]>();
+  const jobs = highlightJobs(rows);
+
+  if (!jobs.length) return spansByRow;
+  const client = getTreeSitterClient();
+
+  await client.initialize();
+  for (const job of jobs) {
+    const result = await client.highlightOnce(job.source, job.filetype);
+
+    if (!result.highlights) continue;
+    const lineSpans = spansByLine(job.source, result.highlights);
+
+    job.rowIndexByLine.forEach((rowIndex, line) => {
+      const spans = lineSpans[line];
+
+      if (spans && spans.length) spansByRow.set(rowIndex, spans);
+    });
+  }
+
+  return spansByRow;
+}

package/src/discussions.ts

@@ -0,0 +1,79 @@
+/**
+ * Discussions: the conversations an annotated surface hosts inline. A root
+ * annotation, its replies, and the span they mark, grouped so two roots on the
+ * very same text read as one conversation. Pure over the resolved marks, so the
+ * plan thread view and the diff sheet group the same way.
+ */
+
+import type { Annotation, Thread } from "@cueloop/schema";
+import type { Mark } from "./view-plan";
+import { comparePositions, type TextSpan } from "./thread-selection";
+
+/** One conversation: a root annotation, its replies, and the span they mark. */
+export interface Discussion {
+  key: string;
+  /** The annotation replies attach to. */
+  rootId: string;
+  /** The block the card renders under: where the span ends. */
+  blockIndex: number;
+  span: TextSpan;
+  annotations: Annotation[];
+}
+
+export function spanKey(span: TextSpan): string {
+  return `${span.start.blockIndex}:${span.start.char}:${span.end.blockIndex}:${span.end.char}`;
+}
+
+/**
+ * Roots group by the span they resolved to (two roots on the very same text
+ * read as one conversation); replies join the discussion their replyTo names, or
+ * stand as roots when that root is gone.
+ */
+export function discussionsFrom(session: Thread, marks: Map<number, Mark[]>): Discussion[] {
+  const byId = new Map(session.annotations.map((annotation) => [annotation.id, annotation]));
+  const spanOf = new Map<string, TextSpan>();
+
+  for (const [displayIndex, blockMarks] of marks) {
+    for (const mark of blockMarks) {
+      if (!mark.annotationId || spanOf.has(mark.annotationId)) continue;
+      spanOf.set(
+        mark.annotationId,
+        mark.span ?? {
+          start: { blockIndex: displayIndex, char: mark.start },
+          end: { blockIndex: displayIndex, char: mark.end },
+        },
+      );
+    }
+  }
+  const resolved = [...spanOf.keys()].map((id) => byId.get(id)!).filter(Boolean);
+  const isRoot = (annotation: Annotation): boolean =>
+    annotation.replyTo === undefined || !spanOf.has(annotation.replyTo);
+  const grouped = new Map<string, Discussion>();
+  const discussionOfRoot = new Map<string, Discussion>();
+
+  for (const annotation of resolved.filter(isRoot)) {
+    const span = spanOf.get(annotation.id)!;
+    const key = spanKey(span);
+    const discussion = grouped.get(key) ?? {
+      key,
+      rootId: annotation.id,
+      blockIndex: span.end.blockIndex,
+      span,
+      annotations: [],
+    };
+
+    discussion.annotations.push(annotation);
+    grouped.set(key, discussion);
+    discussionOfRoot.set(annotation.id, discussion);
+  }
+  for (const annotation of resolved.filter((candidate) => !isRoot(candidate))) {
+    discussionOfRoot.get(annotation.replyTo!)?.annotations.push(annotation);
+  }
+  for (const discussion of grouped.values()) {
+    discussion.annotations.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  }
+
+  return [...grouped.values()].toSorted((left, right) =>
+    comparePositions(left.span.start, right.span.start),
+  );
+}

package/src/editor.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { editInEditor, resolveEditor, resolveEditorCommand } from "./editor";
+
+describe("resolveEditor", () => {
+  test("a clean environment falls back to nano so editing always works", () => {
+    // Assert
+    expect(resolveEditor(undefined, {})).toBe("nano");
+  });
+
+  test("the environment chain wins in order: CUELOOP_EDITOR, VISUAL, EDITOR", () => {
+    // Assert
+    expect(resolveEditor(undefined, { EDITOR: "vim", VISUAL: "code", CUELOOP_EDITOR: "hx" })).toBe(
+      "hx",
+    );
+    expect(resolveEditor(undefined, { EDITOR: "vim", VISUAL: "code" })).toBe("code");
+    expect(resolveEditor(undefined, { EDITOR: "vim" })).toBe("vim");
+  });
+
+  test("the [ui] editor config overrides the environment", () => {
+    // Assert
+    expect(resolveEditor("code --wait", { EDITOR: "vim" })).toBe("code --wait");
+  });
+});
+
+describe("resolveEditorCommand", () => {
+  test("a known GUI editor gets its wait flag appended and is trusted to wait", () => {
+    // Assert
+    expect(resolveEditorCommand("code")).toEqual({ argv: ["code", "--wait"], waits: true });
+    expect(resolveEditorCommand("subl")).toEqual({
+      argv: ["subl", "--new-window", "--wait"],
+      waits: true,
+    });
+  });
+
+  test("an existing wait flag is not duplicated", () => {
+    // Assert
+    expect(resolveEditorCommand("code --wait").argv).toEqual(["code", "--wait"]);
+  });
+
+  test("a terminal editor is left alone and trusted to hold the tty", () => {
+    // Assert
+    expect(resolveEditorCommand("vim")).toEqual({ argv: ["vim"], waits: true });
+  });
+
+  test("an unknown editor is neither flagged nor trusted to wait", () => {
+    // Assert
+    expect(resolveEditorCommand("my-editor")).toEqual({ argv: ["my-editor"], waits: false });
+  });
+});
+
+describe("editInEditor", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "cueloop-edit-test-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  /** A runnable editor stub with a chosen base name and body. */
+  function stubEditor(name: string, body: string): string {
+    const script = join(dir, name);
+
+    writeFileSync(script, `#!/bin/sh\n${body}\n`);
+    chmodSync(script, 0o755);
+
+    return script;
+  }
+
+  const instant = (): (() => number) => {
+    let value = 0;
+
+    return () => (value += 5);
+  };
+
+  test("an editor that changes the file reports the new content", () => {
+    // Act
+    const result = editInEditor("old", "plan.md", {
+      editor: stubEditor("writer.sh", `printf 'new' > "$1"`),
+    });
+
+    // Assert
+    expect(result).toEqual({ content: "new", changed: true });
+  });
+
+  test("a fast, unchanged return opens the gate; confirming re-reads the saved file", () => {
+    // Arrange
+    let askedLabel = "";
+
+    // Act
+    const result = editInEditor("keep", "plan.md", {
+      editor: stubEditor("gui-like.sh", "exit 0"),
+      now: instant(),
+      confirmSaved: (label, path) => {
+        askedLabel = label;
+        writeFileSync(path, "saved in the GUI");
+
+        return true;
+      },
+    });
+
+    // Assert
+    expect(askedLabel).toContain("gui-like.sh");
+    expect(result).toEqual({ content: "saved in the GUI", changed: true });
+  });
+
+  test("declining the gate keeps the original content", () => {
+    // Act
+    const result = editInEditor("keep", "plan.md", {
+      editor: stubEditor("gui-like.sh", "exit 0"),
+      now: instant(),
+      confirmSaved: () => false,
+    });
+
+    // Assert
+    expect(result).toEqual({ content: "keep", changed: false });
+  });
+
+  test("a terminal editor that makes no change never opens the gate", () => {
+    // Arrange
+    let asked = false;
+
+    // Act
+    const result = editInEditor("keep", "plan.md", {
+      editor: stubEditor("vi", "exit 0"),
+      now: instant(),
+      confirmSaved: () => {
+        asked = true;
+
+        return true;
+      },
+    });
+
+    // Assert
+    expect(asked).toBeFalse();
+    expect(result).toEqual({ content: "keep", changed: false });
+  });
+
+  test("a nonzero editor exit throws", () => {
+    // Assert
+    expect(() => editInEditor("x", "plan.md", { editor: stubEditor("fail.sh", "exit 3") })).toThrow(
+      "editor exited 3",
+    );
+  });
+});

package/src/editor.ts

@@ -1,7 +1,11 @@
 /**
- * File-level edit mode = the $EDITOR hand-off (#22, #11): write the working
- * copy to a temp file, run the user's editor on it, read the result back.
- * Tests point CUELOOP_EDITOR at a non-interactive command.
+ * File-level edit mode = the editor hand-off: write the working copy to a temp
+ * file, run the reviewer's editor on it, read the result back. Editing must
+ * work with zero configuration, so the resolution chain ends in a terminal
+ * fallback that is always present. A GUI editor launched without a wait flag
+ * forks and returns instantly, losing the edit silently; known GUI editors get
+ * their wait flag applied, and any editor that still returns right away with an
+ * untouched file drops to a confirm gate rather than discarding the work.
  */
 
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -13,20 +17,146 @@ export interface EditResult {
   changed: boolean;
 }
 
-export function editInEditor(content: string, filename = "plan.md"): EditResult {
-  const editor = process.env.CUELOOP_EDITOR ?? process.env.VISUAL ?? process.env.EDITOR;
-  if (!editor) throw new Error("no editor: set $EDITOR (or $CUELOOP_EDITOR)");
+/** Present on every POSIX system, so a clean shell can still edit. */
+const DEFAULT_EDITOR = "nano";
+
+/** GUI editors fork and return immediately unless given their wait flag. */
+interface GuiWaitFlags {
+  [editor: string]: string[];
+}
+
+const GUI_WAIT_FLAGS: GuiWaitFlags = {
+  code: ["--wait"],
+  "code-insiders": ["--wait"],
+  codium: ["--wait"],
+  cursor: ["--wait"],
+  windsurf: ["--wait"],
+  subl: ["--new-window", "--wait"],
+  sublime_text: ["--new-window", "--wait"],
+  zed: ["--wait"],
+  bbedit: ["--wait"],
+  mate: ["--wait"],
+  gedit: ["--wait"],
+  kate: ["--block"],
+  idea: ["--wait"],
+  webstorm: ["--wait"],
+};
+
+/** Editors that hold the terminal themselves - never GUI, never a wait gate. */
+const TERMINAL_EDITORS = new Set([
+  "vi",
+  "vim",
+  "nvim",
+  "nano",
+  "pico",
+  "emacs",
+  "emacsclient",
+  "micro",
+  "hx",
+  "helix",
+  "kak",
+  "ed",
+  "joe",
+  "mcedit",
+]);
+
+export interface ResolvedEditor {
+  argv: string[];
+  /** True when this editor blocks the hand-off until the file is closed - a
+   * terminal editor, or a known GUI editor with its wait flag applied. */
+  waits: boolean;
+}
+
+/** The editor to run: [ui] editor, then the environment chain, then nano. */
+export function resolveEditor(
+  configuredEditor: string | undefined,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const candidates = [configuredEditor, env.CUELOOP_EDITOR, env.VISUAL, env.EDITOR];
+
+  return candidates.find((candidate) => candidate && candidate.trim())?.trim() ?? DEFAULT_EDITOR;
+}
+
+function editorBaseName(command: string): string {
+  return (command.split(/[\\/]/).pop() ?? command).toLowerCase();
+}
+
+/** Split the editor string and apply a GUI wait flag when we know one. */
+export function resolveEditorCommand(rawEditor: string): ResolvedEditor {
+  const parts = rawEditor.trim().split(/\s+/);
+  const base = editorBaseName(parts[0] ?? "");
+
+  if (TERMINAL_EDITORS.has(base)) return { argv: parts, waits: true };
+  const waitFlags = GUI_WAIT_FLAGS[base];
+
+  if (waitFlags) {
+    const alreadyWaits = parts.some(
+      (part) => part === "--wait" || part === "-w" || part === "--block",
+    );
+
+    return { argv: alreadyWaits ? parts : [...parts, ...waitFlags], waits: true };
+  }
+
+  return { argv: parts, waits: false };
+}
+
+/** A fast return with an untouched file means the editor probably did not wait. */
+const NO_WAIT_THRESHOLD_MS = 1000;
+
+function suspectsNoWait(resolved: ResolvedEditor, elapsedMs: number, unchanged: boolean): boolean {
+  if (resolved.waits) return false; // holds the terminal or has a wait flag - trust the exit
+  if (!unchanged) return false; // edits landed, so it waited after all
+
+  return elapsedMs < NO_WAIT_THRESHOLD_MS;
+}
+
+export interface EditHandOff {
+  /** Editor from [ui] editor config; overrides the environment. */
+  editor?: string;
+  env?: Record<string, string | undefined>;
+  /** Confirm gate for a suspected no-wait return; true re-reads the file. */
+  confirmSaved?: (editorLabel: string, path: string) => boolean;
+  now?: () => number;
+}
+
+/** Prompt on the released terminal during the suspend window. */
+function promptSaved(editorLabel: string, path: string): boolean {
+  const answer = prompt(
+    `${editorLabel} returned immediately and the plan is unchanged - a GUI editor needs its wait flag. Save and close ${path}, then press Enter to load your edits (or type n to skip):`,
+  );
+
+  return answer !== null && answer.trim().toLowerCase() !== "n";
+}
+
+export function editInEditor(
+  content: string,
+  filename = "plan.md",
+  handOff: EditHandOff = {},
+): EditResult {
+  const env = handOff.env ?? process.env;
+  const now = handOff.now ?? Date.now;
+  const resolved = resolveEditorCommand(resolveEditor(handOff.editor, env));
   const dir = mkdtempSync(join(tmpdir(), "cueloop-edit-"));
   const path = join(dir, filename);
+
   writeFileSync(path, content);
   try {
-    const proc = Bun.spawnSync([...editor.split(" "), path], {
+    const startedAt = now();
+    const editorProcess = Bun.spawnSync([...resolved.argv, path], {
       stdin: "inherit",
       stdout: "inherit",
       stderr: "inherit",
     });
-    if (proc.exitCode !== 0) throw new Error(`editor exited ${proc.exitCode}`);
-    const next = readFileSync(path, "utf8");
+
+    if (editorProcess.exitCode !== 0) throw new Error(`editor exited ${editorProcess.exitCode}`);
+    let next = readFileSync(path, "utf8");
+
+    if (suspectsNoWait(resolved, now() - startedAt, next === content)) {
+      const confirm = handOff.confirmSaved ?? promptSaved;
+
+      if (confirm(resolved.argv[0] ?? "the editor", path)) next = readFileSync(path, "utf8");
+    }
+
     return { content: next, changed: next !== content };
   } finally {
     rmSync(dir, { recursive: true, force: true });

package/src/ghostty-terminal.test.ts

@@ -0,0 +1,85 @@
+/** The libghostty-vt FFI wrapper round-trips VT: fed bytes come back as decoded cells with colors and attributes. Skipped where no prebuilt dylib ships for the platform. */
+
+import { describe, expect, test } from "bun:test";
+import { loadGhosttyTerminals } from "./ghostty-terminal";
+
+const factory = loadGhosttyTerminals();
+
+describe("ghostty-terminal FFI", () => {
+  test("reports platform support without throwing", () => {
+    // Assert - null on unsupported platforms, a factory where a dylib ships
+    expect(factory === null || factory.create !== undefined).toBe(true);
+  });
+
+  test.skipIf(!factory)("writes VT bytes and reads back decoded cells", () => {
+    // Arrange
+    const term = factory!.create(80, 24)!;
+
+    expect(term).not.toBeNull();
+
+    // Act - plain text then bold + palette-green "GO"
+    term.write(new TextEncoder().encode("hi\x1b[1;32mGO\x1b[0m"));
+    const cells = [0, 1, 2, 3].map((x) => term.readCell(x, 0));
+
+    // Assert - glyphs decode, the row reads as text, and the green run is bold on ANSI palette index 2
+    expect(
+      cells.map((c) => (c?.codepoint ? String.fromCodePoint(c.codepoint) : " ")).join(""),
+    ).toBe("hiGO");
+    expect(term.rowText(0, 80)).toBe("hiGO");
+    expect(cells[2]!.bold).toBe(true);
+    expect(cells[2]!.fg).toEqual({ kind: "palette", index: 2 });
+    term.free();
+  });
+
+  test.skipIf(!factory)("tracks the cursor position as text is written", () => {
+    // Arrange
+    const term = factory!.create(80, 24)!;
+
+    // Act
+    term.write(new TextEncoder().encode("abc"));
+
+    // Assert - cursor advanced past the three glyphs on row 0
+    const cursor = term.readCursor();
+
+    expect(cursor.y).toBe(0);
+    expect(cursor.x).toBe(3);
+    term.free();
+  });
+
+  test.skipIf(!factory)(
+    "preserves the native screen contract across resize and styled text",
+    () => {
+      // Arrange
+      const term = factory!.create(8, 2)!;
+
+      // Act - resize first, then write RGB colors, every supported style, and a wide glyph
+      term.resize(6, 3);
+      term.write(
+        new TextEncoder().encode(
+          "\x1b[38;2;12;34;56;48;2;78;90;123;1;3;4;7;9mA\x1b[0m\x1b[2mF\x1b[0m\u754c",
+        ),
+      );
+
+      // Assert - the flat native ABI retains cell data and rejects coordinates outside the viewport
+      expect(term.readCell(0, 0)).toEqual({
+        codepoint: 0x41,
+        fg: { kind: "rgb", r: 12, g: 34, b: 56 },
+        bg: { kind: "rgb", r: 78, g: 90, b: 123 },
+        width: 0,
+        bold: true,
+        italic: true,
+        underline: true,
+        inverse: true,
+        faint: false,
+        strikethrough: true,
+      });
+      expect(term.readCell(1, 0)?.faint).toBe(true);
+      expect(term.readCell(2, 0)?.codepoint).toBe("\u754c".codePointAt(0));
+      expect(term.readCell(2, 0)?.width).toBe(1);
+      expect(term.readCell(3, 0)?.width).toBe(2);
+      expect(term.readCell(6, 0)).toBeNull();
+      expect(term.readCell(0, 3)).toBeNull();
+      term.free();
+    },
+  );
+});