@cueloop/client 0.1.0-alpha.2 → 0.1.0-alpha.20

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,104 @@ 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. */
+const GUI_WAIT_FLAGS: Record<string, string[]> = {
+  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], {
-      stdin: "inherit",
-      stdout: "inherit",
-      stderr: "inherit",
-    });
-    if (proc.exitCode !== 0) throw new Error(`editor exited ${proc.exitCode}`);
-    const next = readFileSync(path, "utf8");
+    const startedAt = now();
+    const editorProcess = Bun.spawnSync([...resolved.argv, path], { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+    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/herdr.test.ts

@@ -0,0 +1,37 @@
+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 } from "./herdr";
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("focusHerdrPane", () => {
+  test("resolves the pane's tab and focuses it", () => {
+    const log = join(dir, "calls.log");
+    const stub = join(dir, "herdr");
+    writeFileSync(
+      stub,
+      `#!/bin/sh
+echo "$@" >> "${log}"
+if [ "$1" = "pane" ]; then echo '{"result":{"pane":{"tab_id":"w1:t3"}}}'; fi
+`,
+    );
+    Bun.spawnSync(["chmod", "+x", stub]);
+    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", () => {
+    expect(focusHerdrPane(join(dir, "nope"), "w1:p1")).toBe(false);
+  });
+});

package/src/herdr.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+
+/** Focus the tab holding the target pane. Synchronous: runs just before exit. */
+export function focusHerdrPane(binPath: string, paneId: string): boolean {
+  try {
+    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;
+    if (!tab) return false;
+    return Bun.spawnSync([binPath, "tab", "focus", tab], { stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+  } catch {
+    return false;
+  }
+}

package/src/integrations.test.ts

@@ -0,0 +1,29 @@
+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 () => {
+    const exporters = await loadBundledExporters(integrations());
+    expect(exporters.map((exporter) => exporter.name)).toEqual(["obsidian"]);
+  });
+
+  test("runsOn mirrors the configured export policy", async () => {
+    const onApprove = (await loadBundledExporters(integrations({ exportOn: "approve" })))[0]!;
+    expect(onApprove.runsOn("approve")).toBeTrue();
+    expect(onApprove.runsOn("request_changes")).toBeFalse();
+
+    const onResolve = (await loadBundledExporters(integrations({ exportOn: "resolve" })))[0]!;
+    expect(onResolve.runsOn("approve")).toBeTrue();
+    expect(onResolve.runsOn("request_changes")).toBeTrue();
+
+    const manual = (await loadBundledExporters(integrations({ exportOn: "manual" })))[0]!;
+    expect(manual.runsOn("approve")).toBeFalse();
+    expect(manual.runsOn("request_changes")).toBeFalse();
+  });
+});

package/src/integrations.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 { VerdictKind } from "@cueloop/schema";
+import type { IntegrationsConfig } from "./config";
+
+/** An exporter plus the policy deciding which verdicts trigger it. */
+export interface BundledExporter {
+  name: string;
+  run: Exporter;
+  runsOn(verdict: VerdictKind): 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: (verdict) => shouldExport(obsidian.exportOn, verdict) }];
+}

package/src/key-bindings.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Binding resolution and hint generation over @opentui/keymap: config keys
+ * resolve to action names per layer, and the status-line hints derive from
+ * getActiveKeys() so rebinds surface in the hint text.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_KEYS } from "./config";
+import { KeyBindings } from "./key-bindings";
+
+function bindings(context: { overlay?: "none" | "walk" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
+  const resolver = new KeyBindings(DEFAULT_KEYS);
+  resolver.setContext({ overlay: context.overlay ?? "none", spanMode: context.spanMode ?? false });
+  return resolver;
+}
+
+describe("grammar-layer resolution", () => {
+  const table: [name: string, shift: boolean, action: string | undefined][] = [
+    ["j", false, "down"],
+    ["down", false, "down"],
+    ["k", false, "up"],
+    ["g", false, "top"],
+    ["g", true, "bottom"],
+    ["v", false, "span"],
+    ["c", false, "comment"],
+    ["s", false, "suggest"],
+    ["x", false, "cut"],
+    ["e", false, "edit"],
+    ["n", false, "next_annotation"],
+    ["p", false, "prev_annotation"],
+    ["backspace", false, "delete_annotation"],
+    ["return", false, "submit"],
+    ["enter", false, "submit"],
+    ["q", false, "quit"],
+    ["z", false, undefined],
+  ];
+  for (const [name, shift, action] of table) {
+    test(`${shift ? "shift+" : ""}${name} -> ${action}`, () => {
+      expect(bindings().resolveAction({ name, shift })).toBe(action!);
+    });
+  }
+});
+
+describe("mode layers own their keys", () => {
+  test("span mode resolves the span verbs, not the grammar", () => {
+    const resolver = bindings({ spanMode: true });
+    expect(resolver.resolveAction({ name: "l", shift: false })).toBe("span_grow");
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBe("span_comment");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("span_cancel");
+  });
+
+  test("the compose overlay only knows save and cancel", () => {
+    const resolver = bindings({ overlay: "compose" });
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("save_compose");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("cancel_overlay");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+  });
+
+  test("the submit overlay adds the verdict arrows", () => {
+    const resolver = bindings({ overlay: "submit" });
+    expect(resolver.resolveAction({ name: "left", shift: false })).toBe("cycle_verdict_left");
+    expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
+  });
+
+  test("the walk overlay owns the bracket stepping and leaves the grammar keys dead", () => {
+    const resolver = bindings({ overlay: "walk" });
+    expect(resolver.resolveAction({ name: "]", shift: false })).toBe("walk_next");
+    expect(resolver.resolveAction({ name: "[", shift: false })).toBe("walk_prev");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("walk_leave");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("walk_submit");
+    expect(resolver.resolveAction({ name: "q", shift: false })).toBe("quit");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+  });
+});
+
+describe("getActiveKeys-generated status hints", () => {
+  test("normal mode hint matches the locked string", () => {
+    expect(bindings().statusHint("normal")).toBe(
+      "j/k move · v span · drag selects · c comment · s suggest · x cut · e edit · n/p annotations · ⏎ submit · q quit",
+    );
+  });
+
+  test("card-selected hint keeps the locked Cut label", () => {
+    expect(bindings().statusHint("card")).toBe("card · e edit · x Cut · n/p cards · esc deselect · ⏎ submit");
+  });
+
+  test("span hint", () => {
+    expect(bindings({ spanMode: true }).statusHint("span")).toBe(
+      "span · l/h grow/shrink · w/b slide · $ end · c comment · s suggest · esc",
+    );
+  });
+
+  test("compose hint", () => {
+    expect(bindings({ overlay: "compose" }).statusHint("compose")).toBe("typing · ⏎ save · esc cancel");
+  });
+
+  test("submit hint", () => {
+    expect(bindings({ overlay: "submit" }).statusHint("submit")).toBe("verdict ←/→ · ⏎ submit · esc cancel");
+  });
+
+  test("walk hint", () => {
+    expect(bindings({ overlay: "walk" }).statusHint("walk")).toBe(
+      "walk · ] next (marks viewed) · [ back · esc leave walk · q quit",
+    );
+  });
+
+  test("read-only hint", () => {
+    expect(bindings().statusHint("read-only")).toBe("observer - read-only · j/k move · n/p annotations · q quit");
+  });
+
+  test("a rebound key shows its real binding in the hint", () => {
+    const resolver = new KeyBindings({ ...DEFAULT_KEYS, comment: ["m"] });
+    resolver.setContext({ overlay: "none", spanMode: false });
+    expect(resolver.resolveAction({ name: "m", shift: false })).toBe("comment");
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+    expect(resolver.statusHint("normal")).toContain("m comment");
+  });
+});