@yansigit/opencodex 2.31.0

package/src/cli/init.ts

@@ -0,0 +1,211 @@
+import * as readline from "node:readline";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { injectCodexConfig } from "../codex/inject";
+import { classifyOpenAiTierBackup, getConfigPath, getDefaultConfig, isValidProviderName, preserveOpenAiTierRollbackSnapshot, saveConfig } from "../config";
+import { enrichProviderFromCatalog } from "../oauth/key-providers";
+import { deriveInitProviders } from "../providers/derive";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+
+function createPrompt(): { ask(question: string): Promise<string>; close(): void } {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let closed = false;
+  rl.on("close", () => { closed = true; });
+  return {
+    ask(question: string): Promise<string> {
+      return new Promise((resolve, reject) => {
+        if (closed) {
+          reject(new Error("stdin closed before the prompt could be answered"));
+          return;
+        }
+        const onClose = () => {
+          reject(new Error("stdin reached EOF while waiting for input"));
+        };
+        rl.once("close", onClose);
+        rl.question(question, answer => {
+          rl.off("close", onClose);
+          resolve(answer);
+        });
+      });
+    },
+    close() {
+      if (!closed) rl.close();
+    },
+  };
+}
+
+type InitKind = "forward" | "oauth" | "key" | "local";
+export interface InitProvider {
+  id: string;
+  label: string;
+  adapter: string;
+  baseUrl: string;
+  kind: InitKind;
+  dashboardUrl?: string;
+  defaultModel?: string;
+}
+
+/**
+ * The full CLI provider menu, derived from the canonical provider registry so `ocx init`,
+ * the GUI picker, key-login catalog, OAuth seeds, and metadata aliases cannot drift.
+ */
+export function buildInitProviders(): InitProvider[] {
+  return deriveInitProviders();
+}
+
+const KIND_HEADING: Record<InitKind, string> = {
+  forward: "ChatGPT login",
+  oauth: "Account login (OAuth — then run: ocx login <id>)",
+  key: "API key (paste a key from the provider's dashboard)",
+  local: "Local servers (usually no key)",
+};
+
+function printMenu(providers: InitProvider[]): void {
+  console.log("Choose your default provider (you can add more later):");
+  let lastKind: InitKind | null = null;
+  providers.forEach((p, i) => {
+    if (p.kind !== lastKind) { console.log(`\n  ${KIND_HEADING[p.kind]}:`); lastKind = p.kind; }
+    console.log(`   ${String(i + 1).padStart(2)}. ${p.label}`);
+  });
+  console.log(`\n   ${providers.length + 1}. custom (enter URL manually)`);
+}
+
+const envKeyFor = (id: string) => `${id.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`;
+
+/** Post-init cleanup of `.pre-openai-tiers-v2.bak` with rollback preservation (issue #257). */
+export function cleanupOpenAiTierBackupAfterInit(configPath = getConfigPath()): void {
+  const backup = `${configPath}.pre-openai-tiers-v2.bak`;
+  try {
+    if (!existsSync(backup)) return;
+    if (classifyOpenAiTierBackup(readFileSync(backup)) === "stale") {
+      unlinkSync(backup);
+      return;
+    }
+    const preserved = preserveOpenAiTierRollbackSnapshot(configPath);
+    console.warn(`⚠️  Kept your pre-migration config rollback snapshot at ${preserved}`);
+  } catch { /* cleanup is best-effort; never block init on backup housekeeping */ }
+}
+
+export async function runInit(): Promise<void> {
+  const prompt = createPrompt();
+  try {
+    console.log("\n🔧 opencodex (ocx) setup\n");
+
+    const providers = buildInitProviders();
+    printMenu(providers);
+
+    const choice = await prompt.ask("\nSelect default provider (number): ");
+    const idx = parseInt(choice, 10) - 1;
+
+    let providerName: string;
+    let providerConfig: OcxProviderConfig;
+    let oauthHint = false;
+
+    if (idx >= 0 && idx < providers.length) {
+      const p = providers[idx];
+      providerName = p.id;
+      console.log(`\n📡 ${p.label}`);
+      console.log(`   Base URL: ${p.baseUrl}`);
+
+      if (p.kind === "forward") {
+        providerConfig = { adapter: p.adapter, baseUrl: p.baseUrl, authMode: "forward" };
+        console.log("   No API key needed — forwards your existing `codex login`.");
+      } else if (p.kind === "oauth") {
+        providerConfig = { adapter: p.adapter, baseUrl: p.baseUrl, authMode: "oauth", ...(p.defaultModel ? { defaultModel: p.defaultModel } : {}) };
+        oauthHint = true;
+      } else {
+        // key + local: collect a key (local usually blank).
+        if (p.dashboardUrl) console.log(`   🔑 Get your key: ${p.dashboardUrl}`);
+        // Template URL with placeholders (e.g. Cloudflare's {account_id}) needs a resolved value.
+        let baseUrl = p.baseUrl;
+        if (/\{[^}]*\}/.test(baseUrl)) {
+          const resolved = (await prompt.ask(`   Your endpoint URL (${baseUrl}): `)).trim();
+          if (!resolved) {
+            console.error("   A resolved URL is required — replace the {placeholder} with your actual value.");
+            process.exit(1);
+          }
+          baseUrl = resolved;
+        }
+        const env = envKeyFor(p.id);
+        const hint = p.kind === "local" ? "API key (usually blank — press Enter): " : `API key (paste, or env var $${env}): `;
+        const apiKey = (await prompt.ask(`\n${hint}`)).trim();
+        const modelChoice = (await prompt.ask(`Default model${p.defaultModel ? ` [${p.defaultModel}]` : " (optional)"}: `)).trim();
+        const defaultModel = modelChoice || p.defaultModel;
+        providerConfig = {
+          adapter: p.adapter,
+          baseUrl,
+          ...(p.kind === "key" ? { apiKey: apiKey || `\${${env}}` } : apiKey ? { apiKey } : {}),
+          ...(defaultModel ? { defaultModel } : {}),
+        };
+        // Apply the catalog's models / vision classification (same enrichment as the GUI).
+        enrichProviderFromCatalog(p.id, providerConfig);
+      }
+    } else {
+      providerName = (await prompt.ask("Provider name: ")).trim();
+      if (!isValidProviderName(providerName)) {
+        console.error("Provider name must use letters, numbers, dot, underscore, or hyphen and cannot be a reserved object key.");
+        process.exit(1);
+      }
+      const baseUrl = await prompt.ask("Base URL (e.g. http://localhost:11434/v1): ");
+      const adapter = await prompt.ask("Adapter [openai-chat]: ") || "openai-chat";
+      const apiKey = await prompt.ask("API key (optional): ");
+      const defaultModel = await prompt.ask("Default model: ");
+      providerConfig = {
+        adapter: adapter.trim(),
+        baseUrl: baseUrl.trim(),
+        ...(apiKey.trim() ? { apiKey: apiKey.trim() } : {}),
+        ...(defaultModel.trim() ? { defaultModel: defaultModel.trim() } : {}),
+      };
+    }
+
+    const portStr = await prompt.ask("\nProxy port [10100]: ");
+    const port = parseInt(portStr, 10) || 10100;
+
+    const config: OcxConfig = {
+      ...getDefaultConfig(),
+      port,
+      providers: { [providerName]: providerConfig },
+      defaultProvider: providerName,
+    };
+
+    saveConfig(config);
+    // Init writes a fresh config, so a stale pre-migration backup from a previous
+    // installation would make the next `ocx start` crash on a stale-backup
+    // collision (issue #257). But only a STALE backup (unparseable, or already a
+    // post-migration v2 snapshot) may be deleted; a backup that still parses as a
+    // valid pre-migration (v1) config is a user-intentional rollback point and is
+    // preserved by renaming it out of the collision path (sol review 260722).
+    cleanupOpenAiTierBackupAfterInit();
+    console.log(`\n✅ Config saved to ~/.opencodex/config.json`);
+    if (oauthHint) console.log(`🔐 Authenticate this provider with:  ocx login ${providerName}`);
+
+    const injectAnswer = await prompt.ask("Inject into Codex config.toml? [Y/n]: ");
+    if (injectAnswer.trim().toLowerCase() !== "n") {
+      console.log("Fetching available models from provider...");
+      const result = await injectCodexConfig(port, config);
+      console.log(result.success ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+    }
+
+    const shimAnswer = await prompt.ask("Install Codex autostart shim? [Y/n]: ");
+    if (shimAnswer.trim().toLowerCase() !== "n") {
+      try {
+        const { installCodexShim } = await import("../codex/shim");
+        const result = installCodexShim();
+        console.log(result.installed ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+      } catch (err) {
+        console.log(`⚠️  Codex autostart shim skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    console.log(`\n🚀 Setup complete! Run 'ocx start' to start the proxy.`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/stdin (closed|reached EOF)/i.test(message)) {
+      console.error(`\n❌ ${message}. Re-run \`ocx init\` in an interactive terminal.`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  } finally {
+    prompt.close();
+  }
+}

package/src/cli/integrations.ts

@@ -0,0 +1,260 @@
+import {
+  CliUsageError,
+  csv,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeBooleanOption,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const CLAUDE_USAGE = `Usage:
+  ocx claude config [status] [--json]
+  ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>]
+      [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>]
+      [--compact-window <tokens|default>] [--inject-agents <on|off>]
+      [--small-fast-model <id|->] [--model-map <from=to,from=to|->]
+      [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->]
+      [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]`;
+
+const GROK_USAGE = `Usage:
+  ocx grok [status] [--json]
+  ocx grok <exclude|include|set> <model,model...> [--json]
+  ocx grok clear [--json]
+  ocx grok apply [--json]`;
+
+const CLIENT_USAGE = `Usage:
+  ocx integration client [status] [--client <id>] [--json]
+  ocx integration client <enable|disable> --client <id> [--json]
+  ocx integration client history [--client <id>] [--json]
+  ocx integration client restore --op <opId> [--confirm-drift] [--json]`;
+
+function parseMap(raw: string): Record<string, string> {
+  if (raw === "-") return {};
+  const map: Record<string, string> = {};
+  for (const pair of raw.split(",")) {
+    const index = pair.indexOf("=");
+    if (index <= 0 || index === pair.length - 1) throw new CliUsageError(`invalid model map entry "${pair}"; use from=to`, CLAUDE_USAGE);
+    map[pair.slice(0, index).trim()] = pair.slice(index + 1).trim();
+  }
+  return map;
+}
+
+export async function handleClaudeConfigCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "status").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+    if (action === "status" || action === "show") {
+      rejectArgs(args, CLAUDE_USAGE);
+      const result = await runtimeRequest("/api/claude-code", {}, deps);
+      printData(result, wantsJson, summaryLines(result));
+      return;
+    }
+    if (action !== "set") throw new CliUsageError(`unknown Claude config command ${action}`, CLAUDE_USAGE);
+    const body: Record<string, unknown> = {};
+    const enabled = takeBooleanOption(args, "--enabled");
+    const authMode = takeOption(args, "--auth-mode");
+    const systemEnv = takeBooleanOption(args, "--system-env");
+    const fastMode = takeBooleanOption(args, "--fast-mode");
+    const autoContext = takeBooleanOption(args, "--auto-context");
+    const compact = takeOption(args, "--compact-window");
+    const injectAgents = takeBooleanOption(args, "--inject-agents");
+    const smallFastModel = takeOption(args, "--small-fast-model");
+    const modelMap = takeOption(args, "--model-map");
+    const blockedSkills = takeOption(args, "--blocked-skills");
+    const webModel = takeOption(args, "--web-model");
+    const webBackend = takeOption(args, "--web-backend");
+    const visionModel = takeOption(args, "--vision-model");
+    const visionBackend = takeOption(args, "--vision-backend");
+    rejectArgs(args, CLAUDE_USAGE);
+    if (enabled !== undefined) body.enabled = enabled;
+    if (authMode !== undefined) body.authMode = authMode;
+    if (systemEnv !== undefined) body.systemEnv = systemEnv;
+    if (fastMode !== undefined) body.fastMode = fastMode;
+    if (autoContext !== undefined) body.autoContext = autoContext;
+    if (compact !== undefined) {
+      if (compact === "default" || compact === "-") body.autoCompactWindow = null;
+      else {
+        const value = Number(compact.replace(/[_,]/g, ""));
+        if (!Number.isInteger(value) || value <= 0) throw new CliUsageError("--compact-window must be a positive integer or default", CLAUDE_USAGE);
+        body.autoCompactWindow = value;
+      }
+    }
+    if (injectAgents !== undefined) body.injectAgents = injectAgents;
+    if (smallFastModel !== undefined) body.smallFastModel = smallFastModel === "-" ? "" : smallFastModel;
+    if (modelMap !== undefined) body.modelMap = parseMap(modelMap);
+    if (blockedSkills !== undefined) body.blockedSkills = blockedSkills === "-" ? null : csv(blockedSkills);
+    const sidecar = (model: string | undefined, backend: string | undefined): Record<string, unknown> | undefined => {
+      if (model === undefined && backend === undefined) return undefined;
+      const result: Record<string, unknown> = {};
+      if (model !== undefined) result.model = model === "-" ? "" : model;
+      if (backend !== undefined) result.backend = backend === "-" ? null : backend;
+      return result;
+    };
+    const web = sidecar(webModel, webBackend);
+    const vision = sidecar(visionModel, visionBackend);
+    if (web) body.webSearchSidecar = web;
+    if (vision) body.visionSidecar = vision;
+    if (Object.keys(body).length === 0) throw new CliUsageError("at least one Claude setting is required", CLAUDE_USAGE);
+    const result = await runtimeRequest("/api/claude-code", { method: "PUT", body: JSON.stringify(body) }, deps);
+    printData(result, wantsJson, ["Claude Code settings updated."]);
+  });
+}
+
+type GrokState = Record<string, unknown> & { excluded?: string[] };
+
+export async function handleGrokCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "status").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+    if (action === "status" || action === "show") {
+      rejectArgs(args, GROK_USAGE);
+      const result = await runtimeRequest("/api/grok", {}, deps);
+      printData(result, wantsJson, summaryLines(result));
+      return;
+    }
+    if (action === "apply") {
+      rejectArgs(args, GROK_USAGE);
+      const result = await runtimeRequest("/api/grok/apply", { method: "POST" }, deps);
+      printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? "Grok configuration applied.")]);
+      return;
+    }
+    let excluded: string[];
+    if (action === "clear") excluded = [];
+    else if (["exclude", "include", "set"].includes(action)) {
+      const raw = args.shift();
+      if (!raw) throw new CliUsageError("comma-separated models are required", GROK_USAGE);
+      const requested = csv(raw) ?? [];
+      if (action === "set") excluded = requested;
+      else {
+        const state = await runtimeRequest<GrokState>("/api/grok", {}, deps);
+        const current = new Set(state.excluded ?? []);
+        for (const model of requested) action === "exclude" ? current.add(model) : current.delete(model);
+        excluded = [...current].sort();
+      }
+    } else throw new CliUsageError(`unknown Grok command ${action}`, GROK_USAGE);
+    rejectArgs(args, GROK_USAGE);
+    const result = await runtimeRequest("/api/grok/selection", { method: "PUT", body: JSON.stringify({ excluded }) }, deps);
+    printData(result, wantsJson, [`Grok exclusions: ${excluded.join(", ") || "none"}`]);
+  });
+}
+
+/**
+ * The headless half of the client-integration toggle.
+ *
+ * Every safety property lives behind the management API — ownership, the
+ * pre-write snapshot, the journal, the drift refusal — so this command is a
+ * thin caller and deliberately re-implements none of it. That is also why
+ * `restore` surfaces the drift refusal as an error telling the user to pass
+ * `--confirm-drift` rather than retrying on their behalf: replacing edits a
+ * user made after the snapshot is exactly the decision they have to make.
+ */
+export async function handleClientIntegrationCommand(
+  argv: string[],
+  deps: RuntimeApiDeps = {},
+): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "status").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+
+    if (action === "status" || action === "show" || action === "list") {
+      const client = takeOption(args, "--client");
+      rejectArgs(args, CLIENT_USAGE);
+      const path = client
+        ? `/api/client-integrations/${encodeURIComponent(client)}`
+        : "/api/client-integrations";
+      const result = await runtimeRequest(path, {}, deps);
+      const rows = (result as { clients?: Array<Record<string, unknown>> }).clients;
+      printData(result, wantsJson, rows
+        ? rows.map(row => `${String(row.clientId)}: ${String(row.state)}${row.installed ? "" : " (not installed)"}`)
+        : summaryLines(result));
+      return;
+    }
+
+    if (action === "history" || action === "journal") {
+      const client = takeOption(args, "--client");
+      rejectArgs(args, CLIENT_USAGE);
+      const query = client ? `?client=${encodeURIComponent(client)}` : "";
+      const result = await runtimeRequest(`/api/client-integrations/journal${query}`, {}, deps);
+      const operations = (result as { operations?: Array<Record<string, unknown>> }).operations ?? [];
+      printData(result, wantsJson, operations.length === 0
+        ? ["No integration operations recorded yet."]
+        : operations.map(row => {
+          // `snapshot` is resolved against the disk by the route, so "expired"
+          // here means the bytes are genuinely gone, not merely old.
+          const backup = row.snapshot === "expired" ? "backup expired" : `op ${String(row.opId)}`;
+          return `${String(row.at)}  ${String(row.clientId)}  ${String(row.kind)}  (${backup})`;
+        }));
+      return;
+    }
+
+    if (action === "restore") {
+      const opId = takeOption(args, "--op") ?? takeOption(args, "--op-id");
+      const confirmDrift = takeFlag(args, "--confirm-drift");
+      rejectArgs(args, CLIENT_USAGE);
+      if (!opId) throw new CliUsageError("--op <opId> is required", CLIENT_USAGE);
+      const result = await runtimeRequest("/api/client-integrations/restore", {
+        method: "POST",
+        body: JSON.stringify({ opId, confirmDrift }),
+      }, deps);
+      printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? "Restored.")]);
+      return;
+    }
+
+    if (action !== "enable" && action !== "disable") {
+      throw new CliUsageError(`unknown client integration command ${action}`, CLIENT_USAGE);
+    }
+    const client = takeOption(args, "--client");
+    rejectArgs(args, CLIENT_USAGE);
+    if (!client) throw new CliUsageError("--client <id> is required", CLIENT_USAGE);
+    const result = await runtimeRequest(`/api/client-integrations/${encodeURIComponent(client)}`, {
+      method: "PUT",
+      body: JSON.stringify({ enabled: action === "enable" }),
+    }, deps);
+    printData(result, wantsJson, [String((result as Record<string, unknown>).message ?? `${client} ${action}d.`)]);
+  });
+}
+
+export const INTEGRATION_USAGE = { claude: CLAUDE_USAGE, grok: GROK_USAGE, client: CLIENT_USAGE };
+
+const ZCODE_USAGE = `Usage:
+  ocx zcode [status] [--json]
+  ocx zcode <enable|disable> [--json]
+  ocx zcode history [--json]
+  ocx zcode restore --op <opId> [--confirm-drift] [--json]`;
+
+/**
+ * Thin alias over the client-integration surface for ZCode (Z.ai's desktop
+ * client). ZCode is a GUI app with no launch surface to wrap, so unlike
+ * `ocx mcode` there is no exec step: connecting the managed provider block is
+ * the whole integration, and every safety property (ownership, snapshots,
+ * journal, drift refusal) stays behind the shared management API. ZCode reads
+ * its config at startup, so enable/disable print a restart reminder.
+ */
+export async function handleZcodeCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const args = [...argv];
+  // Find the first non-flag token so `ocx zcode --json enable` still enables.
+  const verbIndex = args.findIndex(arg => !arg.startsWith("-"));
+  const action = (verbIndex === -1 ? "status" : args[verbIndex]).toLowerCase();
+  const known = ["status", "show", "list", "enable", "disable", "history", "journal", "restore"];
+  if (!known.includes(action)) {
+    console.error(`unknown zcode command ${action}`);
+    console.error(ZCODE_USAGE);
+    return 2;
+  }
+  const rest = verbIndex === -1 ? args : [...args.slice(0, verbIndex), ...args.slice(verbIndex + 1)];
+  // `restore` addresses an operation id, not a client, so nothing is injected.
+  const forwarded = action === "restore" ? [action, ...rest] : [action, ...rest, "--client", "zcode"];
+  const code = await handleClientIntegrationCommand(forwarded, deps);
+  if (code === 0 && (action === "enable" || action === "disable")) {
+    console.error("Restart ZCode to pick up the provider change.");
+  }
+  return code;
+}

package/src/cli/interactive-confirm.ts

@@ -0,0 +1,133 @@
+import { createInterface } from "node:readline/promises";
+
+/**
+ * Inline yes/no selector for interactive CLI prompts.
+ *
+ * Both choices are drawn on one line: the user moves between them with the
+ * arrow keys (or Tab), confirms with Enter, or answers straight away with
+ * `y`/`n`. Escape and Ctrl-C resolve to "no", so backing out never counts as
+ * consent.
+ *
+ * The highlighted choice is caller-supplied and is what a bare Enter returns.
+ * Whatever the default, the selector always shows which side is highlighted, so
+ * Enter never does something the screen did not already say it would.
+ */
+
+export interface InteractiveConfirmOptions {
+  /** Question text rendered before the choices. May contain ANSI styling. */
+  question: string;
+  /** Which choice starts highlighted, and therefore what a bare Enter returns. */
+  defaultYes: boolean;
+  /** Key hint shown after the choices. */
+  hint?: string;
+  /** Overridable for tests; defaults to the process streams. */
+  input?: NodeJS.ReadStream;
+  output?: NodeJS.WriteStream;
+}
+
+// The highlight sets an explicit black-on-white pair rather than bare reverse
+// video (\x1b[7m). Reverse alone inherits whatever foreground colour is in
+// effect, so on some themes the selected label rendered as black text on a black
+// block and the choice became invisible.
+const REVERSE = "\x1b[30;47m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+const CLEAR_LINE = "\r\x1b[K";
+
+const KEY_ENTER = new Set(["\r", "\n"]);
+const KEY_YES_SIDE = new Set(["\x1b[D", "\x1b[A", "\x1bOD", "\x1bOA"]); // left / up
+const KEY_NO_SIDE = new Set(["\x1b[C", "\x1b[B", "\x1bOC", "\x1bOB"]); // right / down
+const KEY_ESCAPE = "\x1b";
+const KEY_INTERRUPT = "\x03";
+const KEY_TAB = "\t";
+
+function renderChoices(question: string, yes: boolean, hint: string): string {
+  const yesLabel = yes ? `${REVERSE} Yes ${RESET}` : `${DIM} Yes ${RESET}`;
+  const noLabel = yes ? `${DIM} No ${RESET}` : `${REVERSE} No ${RESET}`;
+  return `${CLEAR_LINE}${question} ${yesLabel} ${noLabel}  ${DIM}${hint}${RESET}`;
+}
+
+function renderAnswer(question: string, yes: boolean): string {
+  return `${CLEAR_LINE}${question} ${yes ? "Yes" : "No"}\n`;
+}
+
+/** Fallback for terminals without raw mode: a plain typed answer. */
+async function readlineConfirm(
+  options: InteractiveConfirmOptions,
+  input: NodeJS.ReadStream,
+  output: NodeJS.WriteStream,
+): Promise<boolean> {
+  const suffix = options.defaultYes ? "[Y/n]" : "[y/N]";
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question(`${options.question} ${suffix} `)).trim().toLowerCase();
+    if (answer === "") return options.defaultYes;
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Ask a yes/no question with an inline arrow-key selector. Resolves to the
+ * user's choice; never throws for input handling and always restores the
+ * terminal mode it changed.
+ */
+export async function interactiveConfirm(options: InteractiveConfirmOptions): Promise<boolean> {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const hint = options.hint ?? "←/→ move · y/n · enter";
+
+  // Raw mode is what makes single-keypress navigation possible. Without it
+  // (pipes, some CI shells, Windows consoles without a TTY) fall back to a
+  // typed answer rather than silently swallowing the question.
+  if (typeof input.setRawMode !== "function") {
+    return await readlineConfirm(options, input, output);
+  }
+
+  return await new Promise<boolean>(resolve => {
+    let yes = options.defaultYes;
+    const wasRaw = input.isRaw === true;
+    const hadOtherReaders = input.listenerCount("data") > 0;
+
+    const paint = () => {
+      output.write(renderChoices(options.question, yes, hint));
+    };
+
+    const finish = (answer: boolean, interrupted: boolean) => {
+      input.off("data", onData);
+      if (!wasRaw) input.setRawMode(false);
+      if (!hadOtherReaders) input.pause();
+      output.write(renderAnswer(options.question, answer));
+      resolve(answer);
+      // A Ctrl-C during the prompt is still a Ctrl-C: hand it back to the
+      // process so the normal shutdown path runs instead of being eaten here.
+      if (interrupted) process.kill(process.pid, "SIGINT");
+    };
+
+    const onData = (chunk: Buffer | string) => {
+      const key = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      if (key === KEY_INTERRUPT) return finish(false, true);
+      if (key === KEY_ESCAPE) return finish(false, false);
+      if (KEY_ENTER.has(key)) return finish(yes, false);
+      const lower = key.toLowerCase();
+      if (lower === "y") return finish(true, false);
+      if (lower === "n") return finish(false, false);
+      if (KEY_YES_SIDE.has(key)) {
+        yes = true;
+        paint();
+        return;
+      }
+      if (KEY_NO_SIDE.has(key) || key === KEY_TAB) {
+        yes = key === KEY_TAB ? !yes : false;
+        paint();
+        return;
+      }
+    };
+
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+    paint();
+  });
+}