catherd-cli 0.2.1 → 1.1.0

package/src/entry/mcp/server.ts

@@ -0,0 +1,88 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { errorMessage } from "../../domain/errors.ts";
+import { log } from "../../infra/log.ts";
+import { startNotifier } from "../../services/notifier.ts";
+import type { Deps } from "../../services/ports.ts";
+import { reconcileAll } from "../../services/reconcile.ts";
+import { defaultDeps } from "../deps.ts";
+import { registerDispatchTools } from "./dispatch-tools.ts";
+import { registerLaneTools } from "./lane-tools.ts";
+import { registerProtocolTools } from "./protocol-tools.ts";
+import { sdkToolError, toolOf } from "./result.ts";
+import { registerRunTools } from "./run-tools.ts";
+import { registerSetupTools } from "./setup-tools.ts";
+
+type Handler = (...args: unknown[]) => CallToolResult | Promise<CallToolResult>;
+
+/** Spec §10.2: every tool call is logged with its duration and outcome (the error code), never its input. */
+function logToolCalls(server: McpServer): void {
+  const register = server.registerTool.bind(server) as unknown as (
+    n: string,
+    c: unknown,
+    h: Handler,
+  ) => unknown;
+  (server as unknown as { registerTool: typeof register }).registerTool = (name, config, handler) =>
+    register(name, config, async (...args: unknown[]) => {
+      const started = Date.now();
+      const r = await handler(...args);
+      const code = r.isError ? (r.structuredContent as { code?: string } | undefined)?.code : undefined;
+      log(r.isError ? "warn" : "info", "tool", {
+        tool: name,
+        ms: Date.now() - started,
+        ok: !r.isError,
+        code,
+      });
+      return r;
+    });
+}
+
+export function buildServer(deps: Deps = defaultDeps()): McpServer {
+  const server = new McpServer({ name: "catherd", version: deps.version });
+  logToolCalls(server);
+  // The SDK validates input before a tool's `handle` runs and reports a failure through this (private)
+  // method as plain text; test/entry/mcp.test.ts fails loudly if an SDK upgrade renames it. The wrapper
+  // above never sees such a call, so it is logged here (spec §10.2: every call), by the tool it names.
+  (server as unknown as { createToolError: typeof sdkToolError }).createToolError = (message) => {
+    const r = sdkToolError(message);
+    const code = (r.structuredContent as { code?: string } | undefined)?.code;
+    log("warn", "tool", { tool: toolOf(message), ok: false, code });
+    return r;
+  };
+  registerRunTools(server, deps);
+  registerLaneTools(server, deps);
+  registerDispatchTools(server, deps);
+  registerSetupTools(server, deps);
+  registerProtocolTools(server, deps);
+  return server;
+}
+
+/**
+ * Spec §4.7: connect first, so the client never waits on a scan; then reconcile every run. Spec §3.4: the notifier
+ * starts before reconcile, so what reconcile settles is announced, and scans for the rest once it is done.
+ */
+export async function startMcpServer(): Promise<void> {
+  const deps = defaultDeps();
+  // which of the session's variables this server got (never their values): the live check of spec §3.9
+  log("info", "session", {
+    sessionId: Boolean(deps.session?.sessionId),
+    hostSessionId: Boolean(deps.session?.hostSessionId),
+    socket: Boolean(deps.session?.socketPath),
+    token: Boolean(deps.session?.token),
+  });
+  const notifier = startNotifier(deps);
+  await buildServer(deps).connect(new StdioServerTransport());
+  try {
+    const r = await reconcileAll(deps);
+    const shown = r.warnings.length;
+    for (const w of r.warnings) console.error(`catherd: ${w}`);
+    void r.done.then(() => {
+      for (const w of r.warnings.slice(shown)) console.error(`catherd: ${w}`);
+    });
+  } catch (e) {
+    console.error(`catherd: reconcile failed: ${errorMessage(e)}`);
+  }
+  // whatever finished unread while no server ran, or finished under another server (spec §3.4)
+  void notifier.scan();
+}

package/src/entry/mcp/setup-tools.ts

@@ -0,0 +1,81 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CatherdError } from "../../domain/errors.ts";
+import { PROFILE_NAME, ProfilePatchSchema } from "../../domain/profile.ts";
+import { ROLES } from "../../domain/roles.ts";
+import { gitToplevel } from "../../infra/git.ts";
+import type { Deps } from "../../services/ports.ts";
+import { handle } from "./result.ts";
+
+const PROFILE = z.string().regex(PROFILE_NAME).optional();
+const REPO = z.string().min(1).optional();
+
+/**
+ * The git toplevel of `repo` (default: this server's directory, null outside a repository). A `repo`
+ * given outside a repository is refused, as run_start does: never the global profile in its stead.
+ */
+const toplevel = async (repo: string | undefined): Promise<string | null> => {
+  const top = await gitToplevel(repo ?? process.cwd());
+  if (top === null && repo !== undefined)
+    throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
+      fix: "pass the path of the repository, or leave repo out for the active profile",
+    });
+  return top;
+};
+
+export function registerSetupTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "catalog_query",
+    {
+      description:
+        "Models catherd can place, with capabilities, the roles they can fill, their scored rungs (backend:model#effort), any 'treat like', their cost under the billing of `repo`'s profile, and whether this account's last listing offers them (`listed: false`: it does not); `enabled: false` rungs are unscored. Scored models first. opencode's models are as listed in `repo` (default: this server's directory), as route sees them there.",
+      inputSchema: {
+        repo: z.string().min(1).optional(),
+        role: z.enum(ROLES).optional(),
+        backend: z.string().optional(),
+        text: z.string().optional(),
+        scored_only: z.boolean().default(false),
+        limit: z.number().int().min(1).max(500).default(50),
+      },
+    },
+    (a) =>
+      handle(async () => {
+        // outside a git repository: the global listings and the active profile
+        const repo = (await gitToplevel(a.repo ?? process.cwd())) ?? undefined;
+        return deps.routing.catalog(
+          { role: a.role, backend: a.backend, text: a.text, scoredOnly: a.scored_only, limit: a.limit, repo },
+          deps.profiles.forRepo(repo ?? null).billing,
+        );
+      }),
+  );
+
+  server.registerTool(
+    "profile_get",
+    {
+      description:
+        "A profile (without a name: the profile this repo runs on, i.e. the one bound to `repo`, default this server's directory, else the active one) as the run engine reads it, with every default filled in: per role its access mode, rungs and default rung, and whether its backend enforces the access (enforcement); billing, jev, harness isolation, failover, budget, timeouts, preflight, lock and notify. Also `active` (the global active profile), `here` (the profile this repo runs on) and every name.",
+      inputSchema: { name: PROFILE, repo: REPO },
+    },
+    (a) => handle(async () => deps.profiles.get(a.name, await toplevel(a.repo))),
+  );
+
+  server.registerTool(
+    "profile_validate",
+    {
+      description:
+        "Check a profile (without a name: the profile this repo runs on, as in profile_get). errors block a save: the worker disabled, an enabled role with no usable rung, an unscored rung without a 'treat like', a failover stand-in unscored or on the same quota, a backend catherd cannot run. warnings do not: an access mode other than the role's default, a model the backend's listing lacks, a stand-in that never runs. Each has a path, a message and often a fix.",
+      inputSchema: { name: PROFILE, repo: REPO },
+    },
+    (a) => handle(async () => deps.profiles.validate(a.name, await toplevel(a.repo))),
+  );
+
+  server.registerTool(
+    "profile_set",
+    {
+      description:
+        "Apply a patch to a profile (without a name: the profile this repo runs on, as in profile_get; a new name starts from the default profile): objective, jev.use, billing, roles (enabled, access, network, rungs, defaultRung), harness isolation per backend, failover, budget, timeouts, preflight.confirm, lock.heavy and notify. Lists replace, maps merge, and null removes a key. An unknown key is refused. It validates first and writes nothing when invalid; otherwise it saves, rewrites the agent files and relinks them. Returns the errors and warnings, the diff, and newSessionNeededFor: the agents that apply from the next Claude Code session.",
+      inputSchema: { name: PROFILE, repo: REPO, patch: ProfilePatchSchema },
+    },
+    (a) => handle(async () => deps.profiles.set(a.name, a.patch, await toplevel(a.repo))),
+  );
+}

package/src/entry/profile-command.ts

@@ -0,0 +1,318 @@
+import { assertProfileName } from "../domain/profile.ts";
+import { defineCommand } from "citty";
+import type { Catalog } from "../domain/catalog.ts";
+import { rungInfo } from "../domain/catalog.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { type Change, patchAt, type Profile } from "../domain/profile.ts";
+import { inferredScores, type Issue } from "../domain/profile-rules.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import { gitToplevel } from "../infra/git.ts";
+import { loadCatalog } from "../services/catalog-service.ts";
+import type { Synced } from "../services/agent-links.ts";
+import {
+  activate,
+  createProfile,
+  deleteProfile,
+  diffNamed,
+  patchProfile,
+  unbind,
+} from "../services/profile-service.ts";
+import {
+  activeName,
+  getProfile,
+  keyRunnable,
+  listProfiles,
+  profileExists,
+  readProjects,
+  requireProfile,
+  roleEnforcement,
+  runnableBackends,
+  validateNamed,
+} from "../services/profile-store.ts";
+import { EXIT, JSON_ARG, mark, printJson } from "./cli-kit.ts";
+
+const json = JSON_ARG;
+
+export interface StandIn {
+  from: string;
+  to: string;
+  inferred: boolean;
+  via: string | null;
+}
+
+/** Spec §7.2: each stand-in; `via` names the rung whose scores it borrows (spec 1.1 §11). */
+export function standIns(p: Profile, c: Catalog): StandIn[] {
+  return Object.entries(p.failover).map(([from, to]) => {
+    try {
+      return { from, to, ...inferredScores(c, rungInfo(c, to)) };
+    } catch {
+      return { from, to, inferred: false, via: null };
+    }
+  });
+}
+
+const value = (v: unknown) => (v === null ? "none" : typeof v === "string" ? v : JSON.stringify(v));
+export const formatChange = (c: Change): string => `${c.path}: ${value(c.before)} → ${value(c.after)}`;
+export const formatIssue = (i: Issue, glyph: string): string[] => [
+  `${glyph} ${i.path}: ${i.message}`,
+  ...(i.fix ? [`  fix: ${i.fix}`] : []),
+];
+
+/** `profile show`: every setting, each role with its access and how strongly its backend holds it (spec D10). */
+export function formatProfile(
+  p: Profile,
+  o: {
+    active: boolean;
+    enforcement: Record<Role, "enforced" | "advisory">;
+    standIns: StandIn[];
+    /** the backends catherd can run: runnableBackends() */
+    backends: string[];
+  },
+): string[] {
+  const width = Math.max(...ROLES.map((r) => r.length));
+  const lines = [
+    `profile ${p.name}${o.active ? " (active)" : ""}`,
+    `objective ${p.objective} · jev ${p.jev.use} · heavy slots ${p.lock.heavy} · notify ${p.notify.join(", ") || "none"}`,
+    "roles",
+  ];
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    if (!rc.enabled) {
+      lines.push(`  ${role.padEnd(width)}  off`);
+      continue;
+    }
+    const ladder = rc.rungs.map((r) => (r === rc.defaultRung ? `${r} (default)` : r)).join(" → ");
+    lines.push(
+      `  ${role.padEnd(width)}  ${`${rc.access}${rc.network === false ? " (no network)" : ""}, ${o.enforcement[role]}`.padEnd(27)}  ${ladder || "no rungs"}`,
+    );
+  }
+  // only what catherd can run today: a backend without an adapter has nothing to bill or isolate
+  const runs = ([key]: [string, unknown]) => keyRunnable(key, o.backends);
+  const billing = Object.entries(p.billing).filter(runs);
+  lines.push(`billing ${billing.map(([k, m]) => `${k} ${m}`).join(" · ")}`);
+  const harness = Object.entries(p.harness).filter(runs);
+  lines.push(`harness ${harness.map(([k, h]) => `${k} ${h.isolated ? "isolated" : "native"}`).join(" · ")}`);
+  lines.push(o.standIns.length ? "failover" : "failover none");
+  for (const s of o.standIns)
+    lines.push(`  ${s.from} → ${s.to}${s.via ? ` (scores borrowed from ${s.via})` : ""}`);
+  const budget = Object.entries(p.budget).map(([k, v]) => (k === "usd" ? `$${v}` : `${v} ${k}`));
+  lines.push(`budget ${budget.join(" · ") || "no cap"}`);
+  lines.push(`timeouts idle ${p.timeouts.idleMin} min · wall ${p.timeouts.wallMin} min`);
+  lines.push(
+    `preflight ${p.preflight.confirm ? "shows its commands and asks first" : "runs the checks without asking"}`,
+  );
+  return lines;
+}
+
+function printSynced(r: Pick<Synced, "newSessionNeededFor">): void {
+  if (r.newSessionNeededFor.length)
+    console.log(`new Claude Code session needed for: ${r.newSessionNeededFor.join(", ")}`);
+}
+
+function printIssues(errors: Issue[], warnings: Issue[]): void {
+  for (const e of errors) for (const l of formatIssue(e, mark("fail"))) console.log(l);
+  for (const w of warnings) for (const l of formatIssue(w, mark("warn"))) console.log(l);
+}
+
+const refused = (errors: Issue[]) =>
+  new CatherdError(
+    "E_CONFIG_INVALID",
+    `the profile was not saved: ${errors.map((e) => `${e.path}: ${e.message}`).join("; ")}`,
+    { fix: errors.find((e) => e.fix)?.fix ?? "catherd profile validate lists what to change" },
+  );
+
+async function repoHere(): Promise<string> {
+  const top = await gitToplevel(process.cwd());
+  if (!top)
+    throw new CatherdError("E_INPUT_INVALID", `${process.cwd()} is not inside a git repository`, {
+      fix: "run it inside the repo to bind, or leave out --repo",
+    });
+  return top;
+}
+
+/** The profile this directory runs on: its repo's binding, else the active one (outside a repo too). */
+const activeHere = async (): Promise<string> => activeName(await gitToplevel(process.cwd()));
+
+const list = defineCommand({
+  meta: {
+    name: "list",
+    description: "Every profile, the one this repo runs on (*), and the repos bound to each",
+  },
+  args: json,
+  async run({ args }) {
+    const active = await activeHere();
+    const bindings = Object.entries(readProjects().bindings);
+    const rows = listProfiles().map((name) => ({
+      name,
+      active: name === active,
+      repos: bindings.filter(([, p]) => p === name).map(([r]) => r),
+    }));
+    if (args.json) return printJson(rows);
+    for (const r of rows)
+      console.log(
+        `${r.active ? "*" : " "} ${r.name}${r.repos.length ? `  bound to ${r.repos.join(", ")}` : ""}`,
+      );
+  },
+});
+
+const show = defineCommand({
+  meta: {
+    name: "show",
+    description: "A profile with every default filled in (without a name: the one this repo runs on)",
+  },
+  args: { name: { type: "positional", required: false, description: "profile name" }, ...json },
+  async run({ args }) {
+    const here = await activeHere();
+    const name = args.name === undefined ? here : requireProfile(args.name);
+    const p = getProfile(name);
+    const o = {
+      active: name === here,
+      enforcement: roleEnforcement(p),
+      standIns: standIns(p, loadCatalog({ timings: false })),
+    };
+    if (args.json) return printJson({ profile: p, ...o });
+    for (const l of formatProfile(p, { ...o, backends: runnableBackends() })) console.log(l);
+  },
+});
+
+const use = defineCommand({
+  meta: {
+    name: "use",
+    description:
+      "Make a profile active, bind it to this repo with --repo, or unbind this repo with --repo --clear",
+  },
+  args: {
+    name: { type: "positional", required: false, description: "profile name" },
+    repo: { type: "boolean", description: "bind it to the git repo you are in, instead of making it active" },
+    clear: { type: "boolean", description: "with --repo and no name: unbind the git repo you are in" },
+  },
+  async run({ args }) {
+    if (args.clear) {
+      if (!args.repo || args.name !== undefined)
+        throw new CatherdError("E_INPUT_INVALID", "--clear goes with --repo and no profile name", {
+          fix: "catherd profile use --repo --clear, inside the repo to unbind",
+        });
+      const r = unbind(await repoHere());
+      console.log(`${mark("ok")} ${r.repo} is unbound`);
+      printSynced(r);
+      return;
+    }
+    if (args.name === undefined)
+      throw new CatherdError("E_INPUT_INVALID", "which profile? name one", {
+        fix: "catherd profile use <name> [--repo], or catherd profile use --repo --clear",
+      });
+    const r = activate(args.name, args.repo ? await repoHere() : null);
+    console.log(`${mark("ok")} ${r.active} ${r.repo ? `is bound to ${r.repo}` : "is active"}`);
+    printSynced(r);
+  },
+});
+
+const create = defineCommand({
+  meta: { name: "new", description: "A new profile from the default one, or from --from <profile>" },
+  args: {
+    name: { type: "positional", required: true, description: "new profile name" },
+    from: { type: "string", description: "copy this profile instead of the default one" },
+  },
+  run({ args }) {
+    const r = createProfile(args.name, args.from);
+    if (!r.saved) throw refused(r.errors);
+    console.log(`${mark("ok")} created ${args.name}${args.from ? ` from ${args.from}` : ""}`);
+    printIssues([], r.warnings);
+  },
+});
+
+const copy = defineCommand({
+  meta: { name: "copy", description: "Copy a profile under a new name" },
+  args: {
+    from: { type: "positional", required: true, description: "profile to copy" },
+    to: { type: "positional", required: true, description: "new profile name" },
+  },
+  run({ args }) {
+    const r = createProfile(args.to, args.from);
+    if (!r.saved) throw refused(r.errors);
+    console.log(`${mark("ok")} copied ${args.from} to ${args.to}`);
+    printIssues([], r.warnings);
+  },
+});
+
+const rm = defineCommand({
+  meta: { name: "rm", description: "Delete a profile and its agent files (never the active or a bound one)" },
+  args: { name: { type: "positional", required: true, description: "profile name" } },
+  run({ args }) {
+    deleteProfile(args.name);
+    console.log(`${mark("ok")} deleted ${args.name}`);
+  },
+});
+
+const set = defineCommand({
+  meta: {
+    name: "set",
+    description:
+      "Set one field: e.g. roles.worker.access read-only, budget.usd 20, failover.<rung> <rung>, roles.worker.rungs a,b; null removes",
+  },
+  args: {
+    path: { type: "positional", required: true, description: "dotted path, e.g. roles.verifier.access" },
+    value: { type: "positional", required: true, description: "JSON, or a plain word; null removes the key" },
+    profile: { type: "string", description: "the profile to change (default: the one this repo runs on)" },
+  },
+  async run({ args }) {
+    // the CLI never creates a profile by setting a field of it: a typo would start a new one
+    if (args.profile !== undefined && !profileExists(assertProfileName(args.profile)))
+      throw new CatherdError("E_INPUT_INVALID", `no profile named "${args.profile}"`, {
+        fix: `catherd profile new ${args.profile}`,
+      });
+    const r = patchProfile(args.profile ?? (await activeHere()), patchAt(args.path, args.value));
+    if (!r.saved) throw refused(r.errors);
+    if (r.diff.length === 0) console.log("no change");
+    for (const c of r.diff) console.log(`${mark("ok")} ${formatChange(c)}`);
+    printIssues([], r.warnings);
+    printSynced(r);
+  },
+});
+
+const diff = defineCommand({
+  meta: {
+    name: "diff",
+    description: "What differs between two profiles (the second defaults to the one this repo runs on)",
+  },
+  args: {
+    a: { type: "positional", required: true, description: "profile" },
+    b: { type: "positional", required: false, description: "profile (default: the one this repo runs on)" },
+    ...json,
+  },
+  async run({ args }) {
+    const changes = diffNamed(
+      args.b === undefined ? await activeHere() : requireProfile(args.b),
+      requireProfile(args.a),
+    );
+    if (args.json) return printJson(changes);
+    if (changes.length === 0) console.log("no differences");
+    for (const c of changes) console.log(formatChange(c));
+  },
+});
+
+const validate = defineCommand({
+  meta: { name: "validate", description: "Errors that block a save, and warnings that do not" },
+  args: {
+    name: {
+      type: "positional",
+      required: false,
+      description: "profile name (default: the one this repo runs on)",
+    },
+    ...json,
+  },
+  async run({ args }) {
+    const repo = await gitToplevel(process.cwd());
+    const v = validateNamed(args.name === undefined ? activeName(repo) : requireProfile(args.name), repo);
+    if (args.json) printJson({ valid: v.errors.length === 0, ...v });
+    else if (v.errors.length === 0 && v.warnings.length === 0) console.log(`${mark("ok")} valid`);
+    else printIssues(v.errors, v.warnings);
+    if (v.errors.length) process.exitCode = EXIT.error;
+  },
+});
+
+/** Spec §8: `catherd profile list|show|use [--repo [--clear]]|new|copy|rm|set <path> <value>|diff|validate`. */
+export const profileCommand = defineCommand({
+  meta: { name: "profile", description: "Profiles: which models each role runs, and how" },
+  subCommands: { list, show, use, new: create, copy, rm, set, diff, validate },
+});

package/src/entry/prompt.ts

@@ -0,0 +1,103 @@
+import { createInterface, type Interface } from "node:readline/promises";
+import { EXIT } from "./cli-kit.ts";
+
+/** Plain questions on stdin; `secret` does not echo what is typed. */
+export interface Prompter {
+  ask(question: string): Promise<string>;
+  secret(question: string): Promise<string>;
+  /** A question this machine does not need asked: piped, its line is still consumed, so answers keep their place */
+  skip?(): void;
+  close(): void;
+}
+
+/** A terminal's hidden input, one character at a time; Ctrl-C exits 130 (spec §8). */
+function readSecret(question: string): Promise<string> {
+  process.stdout.write(question);
+  const stdin = process.stdin;
+  return new Promise((resolve) => {
+    let value = "";
+    const done = () => {
+      stdin.off("data", onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      process.stdout.write("\n");
+      resolve(value.trim());
+    };
+    const onData = (chunk: Buffer) => {
+      for (const ch of chunk.toString("utf8")) {
+        if (ch === "\r" || ch === "\n") return done();
+        if (ch === "\u0003") {
+          stdin.setRawMode(false);
+          process.exit(EXIT.interrupted);
+        }
+        if (ch === "\u007f") {
+          if (value) process.stdout.write("\b \b");
+          value = value.slice(0, -1);
+        } else {
+          value += ch;
+          process.stdout.write("*");
+        }
+      }
+    };
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
+
+/** What `terminalAsk` needs of a readline interface. */
+interface Line {
+  question(q: string): Promise<string>;
+  on(event: "SIGINT", listener: () => void): unknown;
+}
+const isAbort = (e: unknown) =>
+  e instanceof Error && (e.name === "AbortError" || (e as { code?: string }).code === "ABORT_ERR");
+
+/**
+ * A terminal question on `rl`, trimmed. Ctrl-C exits 130 (spec §8), as the secret prompt does: readline
+ * emits SIGINT, or the pending question rejects with an AbortError, depending on the runtime.
+ */
+export function terminalAsk(
+  rl: Line,
+  exit: (code: number) => never = (code) => process.exit(code),
+): (q: string) => Promise<string> {
+  rl.on("SIGINT", () => exit(EXIT.interrupted));
+  return async (q) => {
+    try {
+      return (await rl.question(q)).trim();
+    } catch (e) {
+      if (isAbort(e)) exit(EXIT.interrupted);
+      throw e;
+    }
+  };
+}
+
+/**
+ * Questions for `catherd init`. On a terminal they are asked one by one; piped, stdin is read once and each
+ * question takes its own line (an empty or missing line takes the default), whether or not this machine
+ * asks it, so a script's answers never shift onto another question.
+ */
+export async function prompter(): Promise<Prompter> {
+  if (!process.stdin.isTTY) {
+    const lines = (await Bun.stdin.text()).split("\n");
+    const next = async (q: string) => {
+      const answer = (lines.shift() ?? "").trim();
+      process.stdout.write(`${q}\n`);
+      return answer;
+    };
+    return { ask: next, secret: next, skip: () => void lines.shift(), close() {} };
+  }
+  let rl: Interface | null = null;
+  let ask: ((q: string) => Promise<string>) | null = null;
+  return {
+    ask(q) {
+      rl ??= createInterface({ input: process.stdin, output: process.stdout });
+      ask ??= terminalAsk(rl);
+      return ask(q);
+    },
+    secret: (q) => readSecret(q),
+    close() {
+      rl?.close();
+    },
+  };
+}