@cueloop/client 0.1.0-alpha.4 → 0.1.0-alpha.41

package/src/diff-intraline.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, test } from "bun:test";
+import { intralineRunsByRow, wordLevelChanges, type IntralineRun } from "./diff-intraline";
+import type { DiffRow } from "./view-diff";
+
+function line(kind: DiffRow["kind"], text: string): DiffRow {
+  return { kind, text, file: "a.ts" };
+}
+
+function joinText(runs: IntralineRun[]): string {
+  return runs.map((run) => run.text).join("");
+}
+
+function changedText(runs: IntralineRun[]): string {
+  return runs
+    .filter((run) => run.changed)
+    .map((run) => run.text)
+    .join("");
+}
+
+describe("wordLevelChanges", () => {
+  test("marks only the changed word and stays whitespace-lossless", () => {
+    // Arrange
+    const oldText = "const foo = 1";
+    const newText = "const foo = 2";
+
+    // Act
+    const changes = wordLevelChanges(oldText, newText);
+
+    // Assert
+    expect(
+      changes
+        .filter((change) => change.kind === "common")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe("const foo = ");
+    expect(
+      changes
+        .filter((change) => change.kind === "removed")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe("1");
+    expect(
+      changes
+        .filter((change) => change.kind === "added")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe("2");
+    // old text reconstructs from common + removed, new text from common + added
+    expect(
+      changes
+        .filter((change) => change.kind !== "added")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe(oldText);
+    expect(
+      changes
+        .filter((change) => change.kind !== "removed")
+        .map((change) => change.text)
+        .join(""),
+    ).toBe(newText);
+  });
+});
+
+describe("intralineRunsByRow", () => {
+  test("pairs a deletion with its addition and highlights the changed word on each side", () => {
+    // Arrange
+    const rows = [
+      line("ctx", "unchanged"),
+      line("del", "const foo = 1"),
+      line("add", "const foo = 2"),
+    ];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    const deletionRuns = runsByRow.get(1)!;
+    const additionRuns = runsByRow.get(2)!;
+    expect(joinText(deletionRuns)).toBe("const foo = 1");
+    expect(joinText(additionRuns)).toBe("const foo = 2");
+    expect(changedText(deletionRuns)).toBe("1");
+    expect(changedText(additionRuns)).toBe("2");
+  });
+
+  test("omits context rows and rows with no counterpart", () => {
+    // Arrange
+    const rows = [line("ctx", "keep me"), line("add", "brand new line")];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(runsByRow.size).toBe(0);
+  });
+
+  test("pairs only min(deletions, additions); the surplus stays a plain row", () => {
+    // Arrange - two deletions, one addition
+    const rows = [line("del", "alpha one"), line("del", "beta two"), line("add", "alpha ONE")];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(runsByRow.has(0)).toBe(true); // first deletion pairs with the addition
+    expect(runsByRow.has(1)).toBe(false); // second deletion has no counterpart
+    expect(runsByRow.has(2)).toBe(true);
+    expect(changedText(runsByRow.get(0)!)).toBe("one");
+    expect(changedText(runsByRow.get(2)!)).toBe("ONE");
+  });
+
+  test("a fully rewritten single line marks the whole line changed on both sides", () => {
+    // Arrange - a lone deletion opposite a lone addition is unambiguously one edit
+    const rows = [line("del", "aaa"), line("add", "zzz")];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(changedText(runsByRow.get(0)!)).toBe("aaa");
+    expect(changedText(runsByRow.get(1)!)).toBe("zzz");
+  });
+
+  test("in a shifted block, alignment matches the real counterpart, not by position", () => {
+    // Arrange - "beta gamma" is modified and an unrelated line sits at each end;
+    // positional pairing would word-diff "alpha" against "beta gamma delta"
+    const rows = [
+      line("del", "alpha"),
+      line("del", "beta gamma"),
+      line("add", "beta gamma delta"),
+      line("add", "zulu"),
+    ];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    // the modified pair is found and word-diffed
+    expect(runsByRow.has(1)).toBe(true); // "beta gamma"
+    expect(runsByRow.has(2)).toBe(true); // "beta gamma delta"
+    expect(changedText(runsByRow.get(2)!).trim()).toBe("delta");
+    // the genuinely unrelated lines stay whole-line
+    expect(runsByRow.has(0)).toBe(false); // "alpha"
+    expect(runsByRow.has(3)).toBe(false); // "zulu"
+  });
+
+  test("in a multi-line block, related positional pairs still highlight the changed word", () => {
+    // Arrange - a same-shape 2x2 edit: each row lines up with its counterpart
+    const rows = [
+      line("del", "one two"),
+      line("del", "three four"),
+      line("add", "one TWO"),
+      line("add", "three FOUR"),
+    ];
+
+    // Act
+    const runsByRow = intralineRunsByRow(rows);
+
+    // Assert
+    expect(changedText(runsByRow.get(0)!)).toBe("two");
+    expect(changedText(runsByRow.get(1)!)).toBe("four");
+    expect(changedText(runsByRow.get(2)!)).toBe("TWO");
+    expect(changedText(runsByRow.get(3)!)).toBe("FOUR");
+  });
+});

package/src/diff-intraline.ts

@@ -0,0 +1,132 @@
+/**
+ * Intra-line word diff: the char-precise "what changed within this line" engine
+ * shared by the plan tracked-changes view and the diff review sheet. Backed by
+ * jsdiff diffWordsWithSpace, so it is punctuation-aware and whitespace-lossless:
+ * the run values always concatenate back to the exact inputs, which keeps quote
+ * anchors intact. Supersedes the coarse LCS wordDiff.
+ */
+
+import { diffWordsWithSpace } from "diff";
+import { lcsDiff } from "@cueloop/schema";
+import type { DiffRow } from "./view-diff";
+
+export type WordChangeKind = "common" | "added" | "removed";
+
+/** One word-level change between two strings; text is verbatim (lossless). */
+export interface WordChange {
+  text: string;
+  kind: WordChangeKind;
+}
+
+/** Word-level changes between two strings, whitespace-lossless and ordered. */
+export function wordLevelChanges(oldText: string, newText: string): WordChange[] {
+  return diffWordsWithSpace(oldText, newText).map((change) => ({
+    text: change.value,
+    kind: change.added ? "added" : change.removed ? "removed" : "common",
+  }));
+}
+
+/** One rendered segment of a diff row: changed marks the intra-line change. */
+export interface IntralineRun {
+  text: string;
+  changed: boolean;
+}
+
+function stripTrailingNewline(text: string): string {
+  return text.replace(/\n$/, "");
+}
+
+/**
+ * Char-precise intra-line runs for modified diff rows. Within a change block - a
+ * run of deletions immediately followed by additions - lines are aligned to their
+ * real counterpart (see alignedPairs) and each matched pair is word-diffed so the
+ * removed/added words are marked changed. Rows with no counterpart (pure add, pure
+ * delete, or an unmatched line in a shifted block) are omitted, so the caller
+ * renders those as a single run. Each row's runs concatenate back to that row's text.
+ */
+export function intralineRunsByRow(rows: DiffRow[]): Map<number, IntralineRun[]> {
+  const runsByRow = new Map<number, IntralineRun[]>();
+  let index = 0;
+  while (index < rows.length) {
+    if (rows[index]!.kind !== "del") {
+      index++;
+      continue;
+    }
+    const deletionStart = index;
+    while (index < rows.length && rows[index]!.kind === "del") index++;
+    const additionStart = index;
+    while (index < rows.length && rows[index]!.kind === "add") index++;
+    const deletionTexts = rows
+      .slice(deletionStart, additionStart)
+      .map((row) => stripTrailingNewline(row.text));
+    const additionTexts = rows
+      .slice(additionStart, index)
+      .map((row) => stripTrailingNewline(row.text));
+    for (const [deletionOffset, additionOffset] of alignedPairs(deletionTexts, additionTexts)) {
+      const changes = wordLevelChanges(
+        deletionTexts[deletionOffset]!,
+        additionTexts[additionOffset]!,
+      );
+      runsByRow.set(deletionStart + deletionOffset, sideRuns(changes, "removed"));
+      runsByRow.set(additionStart + additionOffset, sideRuns(changes, "added"));
+    }
+  }
+  return runsByRow;
+}
+
+/** Lines this similar (word-set overlap) are treated as the same line edited. */
+const SIMILAR_MIN_WORD_OVERLAP = 0.3;
+
+/** Whether two lines are the same line edited, by case-insensitive word-set
+ *  overlap - the matching gate, distinct from the case-sensitive word diff. */
+function linesSimilar(oldText: string, newText: string): boolean {
+  const words = (text: string) => new Set(text.toLowerCase().split(/\s+/).filter(Boolean));
+  const oldWords = words(oldText);
+  const newWords = words(newText);
+  if (oldWords.size === 0 && newWords.size === 0) return true;
+  let intersection = 0;
+  for (const word of oldWords) if (newWords.has(word)) intersection++;
+  const union = oldWords.size + newWords.size - intersection;
+  return union === 0 ? true : intersection / union >= SIMILAR_MIN_WORD_OVERLAP;
+}
+
+/**
+ * Pair each modified line with the addition it became. A lone deletion opposite
+ * a lone addition is one edit (always paired). Otherwise align the lines by
+ * similarity, order-preserving (LCS over `linesSimilar`), so an inserted, removed,
+ * or shifted line finds its real counterpart instead of mispairing by position -
+ * unmatched lines get no pair and render whole-line. Returns [deletionOffset,
+ * additionOffset] pairs into the block.
+ */
+function alignedPairs(deletionTexts: string[], additionTexts: string[]): Array<[number, number]> {
+  if (deletionTexts.length === 1 && additionTexts.length === 1) return [[0, 0]];
+  const pairs: Array<[number, number]> = [];
+  let deletionOffset = 0;
+  let additionOffset = 0;
+  for (const op of lcsDiff(deletionTexts, additionTexts, linesSimilar)) {
+    if (op.kind === "ctx") {
+      pairs.push([deletionOffset, additionOffset]);
+      deletionOffset++;
+      additionOffset++;
+    } else if (op.kind === "del") {
+      deletionOffset++;
+    } else {
+      additionOffset++;
+    }
+  }
+  return pairs;
+}
+
+/** Runs for one side of a word diff: common plus this side's changes, adjacent
+ *  runs of equal changed-ness coalesced so highlighting stays as few spans. */
+function sideRuns(changes: WordChange[], side: "added" | "removed"): IntralineRun[] {
+  const runs: IntralineRun[] = [];
+  for (const change of changes) {
+    if (change.kind !== "common" && change.kind !== side) continue;
+    const changed = change.kind === side;
+    const last = runs[runs.length - 1];
+    if (last && last.changed === changed) last.text += change.text;
+    else runs.push({ text: change.text, changed });
+  }
+  return runs;
+}

package/src/diff-syntax.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import { highlightJobs, spansByLine } from "./diff-syntax";
+import type { DiffRow } from "./view-diff";
+import type { SimpleHighlight } from "@opentui/core";
+
+function row(kind: DiffRow["kind"], text: string, file = "src/x.ts"): DiffRow {
+  return { kind, text, file };
+}
+
+describe("spansByLine", () => {
+  test("maps absolute offsets to line-relative spans", () => {
+    // Arrange
+    const source = "const x = 1;\nfoo";
+    const highlights: SimpleHighlight[] = [
+      [0, 5, "keyword"],
+      [6, 7, "variable"],
+      [13, 16, "variable"],
+    ];
+
+    // Act
+    const lineSpans = spansByLine(source, highlights);
+
+    // Assert
+    expect(lineSpans[0]).toEqual([
+      { start: 0, end: 5, group: "keyword" },
+      { start: 6, end: 7, group: "variable" },
+    ]);
+    expect(lineSpans[1]).toEqual([{ start: 0, end: 3, group: "variable" }]);
+  });
+
+  test("spreads a capture that crosses newlines onto every line it covers", () => {
+    // Arrange - one capture spanning both lines, as a block comment would
+    const source = "aa\nbb";
+    const highlights: SimpleHighlight[] = [[0, 5, "comment"]];
+
+    // Act
+    const lineSpans = spansByLine(source, highlights);
+
+    // Assert
+    expect(lineSpans[0]).toEqual([{ start: 0, end: 2, group: "comment" }]);
+    expect(lineSpans[1]).toEqual([{ start: 0, end: 2, group: "comment" }]);
+  });
+
+  test("resolves overlapping captures with later winning", () => {
+    // Arrange
+    const source = "foo";
+    const highlights: SimpleHighlight[] = [
+      [0, 3, "variable"],
+      [0, 3, "type"],
+    ];
+
+    // Act
+    const lineSpans = spansByLine(source, highlights);
+
+    // Assert
+    expect(lineSpans[0]).toEqual([{ start: 0, end: 3, group: "type" }]);
+  });
+});
+
+describe("highlightJobs", () => {
+  test("reconstructs old and new sides of a hunk with row indices", () => {
+    // Arrange
+    const rows = [
+      row("file", "src/x.ts", "src/x.ts"),
+      row("hunk", "@@ -1,2 +1,2 @@"),
+      row("ctx", "const a = 1;"),
+      row("del", "const b = 2;"),
+      row("add", "const b = 3;"),
+    ];
+
+    // Act
+    const jobs = highlightJobs(rows);
+
+    // Assert
+    // old side = context + deletion; new side = context + addition
+    expect(jobs).toEqual([
+      { filetype: "typescript", source: "const a = 1;\nconst b = 2;", rowIndexByLine: [2, 3] },
+      { filetype: "typescript", source: "const a = 1;\nconst b = 3;", rowIndexByLine: [2, 4] },
+    ]);
+  });
+
+  test("skips files with no known filetype", () => {
+    // Arrange
+    const rows = [
+      row("file", "notes/thing.unknownext", "notes/thing.unknownext"),
+      row("hunk", "@@"),
+      row("add", "whatever"),
+    ];
+
+    // Act
+    const jobs = highlightJobs(rows);
+
+    // Assert
+    expect(jobs).toEqual([]);
+  });
+});

package/src/diff-syntax.ts

@@ -0,0 +1,154 @@
+/**
+ * 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, end, 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.
+    let cursor = 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/editor.test.ts

@@ -0,0 +1,143 @@
+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",
+    );
+  });
+});