omp-conductor 0.14.0 → 0.15.0

package/src/wizard-ui.ts

@@ -0,0 +1,249 @@
+/**
+ * The presentation surface the setup wizard ({@link setup-wizard.ts}) codes
+ * against. Nothing about it is terminal-specific: any driver that satisfies this
+ * exact shape can drive the wizard, and today that driver is the terminal
+ * `omp-conductor setup` verb (#309 deleted the in-session dialog).
+ *
+ * Three of the four methods are prompt-bearing. The load-bearing contracts,
+ * each of which the wizard already relies on and a future refactor would break
+ * silently:
+ *
+ *   - `input` resolves the placeholder on an empty submit ("Enter accepts what
+ *     you see"), so a re-run that Enters through a prompt re-affirms the shown
+ *     default instead of blanking it.
+ *   - `select` resolves the chosen option's **label**, never its index — the
+ *     label *is* the config value for the closed-vocabulary questions, so a
+ *     lookup table that disagreed with the vocabulary it was built from would
+ *     corrupt the written config.
+ *   - `select` honours `dialogOptions.initialIndex` so a bare Enter re-affirms
+ *     the current setting (see the "cannot be a confirm" note in the wizard).
+ *   - `confirm` is `y/N`, defaulting to no.
+ *
+ * Every prompt resolves `undefined` when the operator dismisses it (Ctrl-C /
+ * EOF), which every wizard caller already treats as the cancel path
+ * (`Cancelled`). The terminal UI guarantees the readline interface is closed on
+ * every exit path so the verb cannot hang the terminal.
+ */
+export interface WizardUi {
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+  /**
+   * Yes/no. `undefined` means the operator *dismissed* the prompt rather than
+   * answering it, which is a different thing from "no": the wizard turns it into
+   * `Cancelled` and abandons the run. Collapsing the two is how Ctrl-C at a
+   * confirm used to record a silent "no" and carry on to the next question.
+   */
+  confirm(title: string, message: string): Promise<boolean | undefined>;
+  /** Single-line text prompt. `undefined` dismisses it; an empty submit accepts
+   *  the placeholder. */
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+  /** Numbered single-choice list. Resolves the chosen option's label, or
+   *  `undefined` when dismissed. */
+  select(
+    title: string,
+    options: { label: string; description?: string }[],
+    dialogOptions?: { initialIndex?: number },
+  ): Promise<string | undefined>;
+}
+
+import { createInterface, type Interface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import type { Readable, Writable } from "node:stream";
+
+/**
+ * A `WizardUi` over a real terminal — or a pipe, which is how the verb is
+ * scripted in tests — backed by `node:readline/promises`.
+ *
+ * **One interface for the whole wizard, closed once.** The first version of this
+ * created and closed a readline interface per prompt, on the theory that
+ * releasing stdin after each question could not leak. It cannot: closing a
+ * readline interface ends the shared stdin stream, so the *second* prompt of a
+ * piped run had no readable input left and the run hung indefinitely — the exact
+ * failure this comment used to claim it prevented. The interface therefore lives
+ * as long as the wizard, and {@link TerminalUi.close} releases it once, from the
+ * caller's `finally`.
+ *
+ * Dismissal is the interface's own `close`: `rl.question()` on an exhausted
+ * stream never settles on its own, so EOF (a script that ran out of answers) and
+ * Ctrl-C both close the interface, and the line reader turns that into the
+ * `undefined` every wizard caller reads as cancel.
+ *
+ * `io` exists so the contracts below can be tested in-process against a pipe
+ * rather than only through a spawned CLI; production callers pass nothing.
+ */
+export interface TerminalUi extends WizardUi {
+  /** Releases stdin. Idempotent; call it from a `finally`. */
+  close(): void;
+}
+
+export function terminalUi(io: { input?: Readable; output?: Writable } = {}): TerminalUi {
+  const input = io.input ?? stdin;
+  const output = io.output ?? stdout;
+  const rl: Interface = createInterface({ input, output });
+  let closed = false;
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    rl.close();
+  };
+  // Ctrl-C is a cancel, not a signal to the whole process: closing the interface
+  // makes every pending and subsequent prompt resolve `undefined`, which the
+  // wizard already turns into `Cancelled`.
+  rl.once("SIGINT", close);
+
+  // Lines are buffered as they arrive rather than read on demand, because on a
+  // non-TTY stdin readline drains the whole pipe at once and emits `line` for
+  // every one of them immediately. `rl.question()` only captures the line that
+  // arrives *after* it is called, so a scripted run lost every answer that had
+  // already flown past and then hit EOF — three prompts resolving `undefined`
+  // and a wizard that cancelled itself. Buffering makes a pipe and a terminal
+  // behave the same: nothing is read before it is asked for, nothing is lost.
+  const buffered: string[] = [];
+  let waiting: ((value: string | undefined) => void) | undefined;
+  let ended = false;
+  const deliver = (value: string | undefined): boolean => {
+    const resolve = waiting;
+    if (resolve === undefined) return false;
+    waiting = undefined;
+    resolve(value);
+    return true;
+  };
+  rl.on("line", (text: string) => {
+    if (!deliver(text)) buffered.push(text);
+  });
+  rl.once("close", () => {
+    ended = true;
+    deliver(undefined);
+  });
+
+  /** One line, or `undefined` when the operator dismissed the prompt. */
+  const line = async (query: string): Promise<string | undefined> => {
+    if (closed && buffered.length === 0) return undefined;
+    output.write(query);
+    const ready = buffered.shift();
+    if (ready !== undefined) return ready;
+    if (ended) return undefined;
+    return await new Promise<string | undefined>((resolve) => {
+      waiting = resolve;
+    });
+  };
+
+  return {
+    close,
+    notify(message) {
+      output.write(`${message}\n`);
+    },
+    async confirm(title, message) {
+      for (;;) {
+        const answer = await line(`${title} — ${message} (y/N) `);
+        // Dismissal is NOT "no". Ctrl-C or EOF here means the operator left, and
+        // reporting `false` made the interview march on to the next question with
+        // a silent "no" recorded — so `Ctrl-C abandons the run` was untrue for
+        // every yes/no prompt. The wizard turns this into `Cancelled`.
+        if (answer === undefined) return undefined;
+        const a = answer.trim().toLowerCase();
+        if (a === "y" || a === "yes") return true;
+        // Enter is still the safe answer: no, and the interview continues.
+        if (a === "n" || a === "no" || a === "") return false;
+        output.write("Please answer y or n.\n");
+      }
+    },
+    async input(title, placeholder) {
+      const query =
+        placeholder !== undefined && placeholder.length > 0 ? `${title} [${placeholder}]: ` : `${title}: `;
+      const answer = await line(query);
+      if (answer === undefined) return undefined;
+      // "Enter accepts what you see": an empty submit keeps the placeholder.
+      return answer.trim().length === 0 ? (placeholder ?? "") : answer;
+    },
+    async select(title, options, dialogOptions) {
+      output.write(`${title}\n`);
+      options.forEach((o, i) => {
+        output.write(`  ${i + 1}. ${o.label}${o.description !== undefined ? ` — ${o.description}` : ""}\n`);
+      });
+      const initial = dialogOptions?.initialIndex ?? 0;
+      const defaultLabel = options[initial]?.label ?? "";
+      for (;;) {
+        const answer = await line(
+          `Select 1-${options.length} [${initial + 1} = ${defaultLabel}] (Enter keeps it, Ctrl-C cancels): `,
+        );
+        if (answer === undefined) return undefined;
+        const a = answer.trim();
+        if (a === "") return defaultLabel; // a bare Enter re-affirms the current row
+        const n = Number(a);
+        if (Number.isInteger(n)) {
+          const picked = options[n - 1];
+          if (picked !== undefined) return picked.label;
+        }
+        output.write(`Please enter a number between 1 and ${options.length}.\n`);
+      }
+    },
+  };
+}
+
+/**
+ * The test seam: a `WizardUi` driven by a script keyed by a substring of each
+ * prompt's title.
+ *
+ * **Anything unscripted takes the answer an operator gets by pressing Enter** —
+ * an empty `input` (which the wizard reads as "accept the shown default"), `no`
+ * on a `confirm`, and the row the caller put the cursor on for a `select`. That
+ * leniency is deliberate and is itself the thing under test: "Enter accepts what
+ * you see" is the contract the whole wizard is built on, so a test that has to
+ * script an answer is a test whose default moved. Throwing on an unscripted
+ * prompt would make that property untestable.
+ *
+ * Asking an *unintended* question is caught a stronger way instead: the suite
+ * pins the full ordered list of prompts, so a question that appears or vanishes
+ * fails on the transcript rather than on a missing script entry.
+ *
+ *   - `input`: the scripted string, else `""` (Enter → the wizard's fallback).
+ *   - `confirm`: the scripted boolean, else `false`. `null` dismisses the prompt
+ *     (`undefined`), which the wizard reads as cancel — the same spelling
+ *     `select` uses.
+ *   - `select`: a number picks that option's **label**; a string matches an
+ *     offered label by prefix; `null` dismisses the prompt (`undefined`, which
+ *     the wizard reads as cancel); unscripted takes `initialIndex`'s label.
+ *   - An array answers successive prompts sharing the same title; the last entry
+ *     repeats.
+ */
+export interface ScriptedAnswers {
+  input?: Record<string, string>;
+  confirm?: Record<string, boolean | boolean[] | null>;
+  select?: Record<string, string | number | null>;
+}
+
+export function scriptedUi(script: ScriptedAnswers = {}): WizardUi {
+  const seen = new Map<string, number>();
+  const answer = <T>(table: Record<string, T> | undefined, title: string): T | undefined => {
+    for (const [key, value] of Object.entries(table ?? {})) {
+      if (!title.includes(key)) continue;
+      if (!Array.isArray(value)) return value;
+      const n = seen.get(key) ?? 0;
+      seen.set(key, n + 1);
+      return (value[Math.min(n, value.length - 1)] ?? value.at(-1)) as T;
+    }
+    return undefined;
+  };
+
+  return {
+    notify() {
+      /* recorded by the caller's wrapper when a test asserts on notices */
+    },
+    async confirm(title) {
+      const scripted = answer(script.confirm, title);
+      if (scripted === null) return undefined;
+      return Array.isArray(scripted) ? false : (scripted ?? false);
+    },
+    async input(title) {
+      return answer(script.input, title) ?? "";
+    },
+    async select(title, options, dialogOptions) {
+      const chosen = answer(script.select, title);
+      if (chosen === null) return undefined;
+      if (typeof chosen === "number") return options[chosen]?.label;
+      if (typeof chosen === "string") return options.find((o) => o.label.startsWith(chosen))?.label ?? chosen;
+      // Enter: the row the caller put the cursor on.
+      return options[dialogOptions?.initialIndex ?? 0]?.label;
+    },
+  };
+}

package/src/worker.ts

@@ -609,7 +609,12 @@ function field(source: unknown, key: string): unknown {
 }
 
 /** Flatten an assistant message's content blocks to their plain text. */
-function reportText(content: unknown): string {
+/**
+ * The newest assistant text, flattened out of whatever block shape the harness
+ * sent. Exported for ./setup-probe.ts, which collects a probe's answer the same
+ * way a worker's report is collected — one spelling, so the two cannot drift.
+ */
+export function reportText(content: unknown): string {
   if (typeof content === "string") return content.trim();
   const blocks: readonly unknown[] = Array.isArray(content) ? content : [];
   const parts: string[] = [];