@bhooai/nexus-cli 0.1.0

package/src/supervisor.ts

@@ -0,0 +1,384 @@
+import { spawn, execFile, ChildProcess } from 'node:child_process';
+import { createServer, IncomingMessage, ServerResponse } from 'node:http';
+import { EOL } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeFile } from 'node:fs/promises';
+
+/**
+ * The framework workspace root (the dir containing `packages/`, `apps/`, `bin/`), resolved
+ * from this file so it's correct whether run from `src/` (tsx) or `dist/` (compiled), and
+ * independent of the launcher's cwd. Used to put the framework's `node_modules/.bin` on the
+ * child PATH so `tsx`/`vite` resolve even when the supervisor is launched directly via
+ * `node bin/nexus.js dev` (where npm hasn't prepended `.bin` to PATH).
+ */
+const FRAMEWORK_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const PATH_SEP = process.platform === 'win32' ? ';' : ':';
+
+export interface ServiceSpec {
+  name: string;
+  /** Command + args to run. */
+  command: string[];
+  /** Working directory relative to project root. */
+  cwd: string;
+  /** ANSI color for log prefix. */
+  color: string;
+  /** When true, a start failure is logged but does not stop the supervisor. */
+  optional?: boolean;
+  env?: Record<string, string>;
+}
+
+export interface ServiceState {
+  name: string;
+  status: 'stopped' | 'running' | 'errored';
+  pid?: number;
+  startedAt?: number;
+  lastExitCode?: number | null;
+  logTail: string[];
+}
+
+/** Structured log entry returned by /logs/all. */
+export interface LogEntry {
+  service: string;
+  ts: number;
+  source: 'stdout' | 'stderr' | 'system';
+  level: 'info' | 'warn' | 'error';
+  line: string;
+}
+
+const MAX_TAIL = 200;
+/** Max aggregated log entries across all services. */
+const MAX_ALL_LOGS = 2000;
+
+/**
+ * Inbuilt process supervisor for the four Nexus terminals.
+ * Owns child processes, streams prefixed colored logs, handles graceful shutdown,
+ * and exposes a localhost HTTP control API for the admin app.
+ */
+export class Supervisor {
+  private procs = new Map<string, ChildProcess>();
+  private states = new Map<string, ServiceState>();
+  private controlServer?: ReturnType<typeof createServer>;
+  private shuttingDown = false;
+  /** The port the control API actually bound (may differ when auto-allotted). */
+  private boundControlPort = 0;
+  /** Aggregated structured log buffer across all services - powers /logs/all. */
+  private allLogs: LogEntry[] = [];
+
+  constructor(
+    private services: ServiceSpec[],
+    private root: string,
+    private controlPort = 7474,
+  ) {
+    for (const s of services) {
+      this.states.set(s.name, { name: s.name, status: 'stopped', logTail: [] });
+    }
+  }
+
+  /** The port the supervisor control API actually bound (0 until started). */
+  get controlEndpointPort(): number {
+    return this.boundControlPort;
+  }
+
+  private async tryListen(server: ReturnType<typeof createServer>, port: number, host = '127.0.0.1'): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const onError = (err: NodeJS.ErrnoException) => {
+        server.removeListener('listening', onListening);
+        server.close();
+        reject(err);
+      };
+      const onListening = () => {
+        server.removeListener('error', onError);
+        resolve();
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(port, host);
+    });
+  }
+
+  startService(spec: ServiceSpec): void {
+    const state = this.states.get(spec.name)!;
+    if (state.status === 'running') return;
+    const [cmd, ...args] = spec.command;
+    if (!cmd) {
+      state.status = 'errored';
+      this.pushLog(spec.name, `no command specified for ${spec.name}`, 'system');
+      return;
+    }
+    const cwdAbs = resolve(this.root, spec.cwd);
+    // Put local + framework `node_modules/.bin` first on PATH so bins like `tsx`/`vite`
+    // resolve even when the supervisor is launched directly (not via `npm run dev`).
+    // Windows keeps the original `Path` if we merely add `PATH`, so drop all case variants
+    // before setting it.
+    const origPath = process.env.PATH ?? process.env.Path ?? process.env.path ?? '';
+    const binDirs = [
+      join(cwdAbs, 'node_modules', '.bin'),
+      join(this.root, 'node_modules', '.bin'),
+      join(FRAMEWORK_ROOT, 'node_modules', '.bin'),
+    ];
+    const childEnv: NodeJS.ProcessEnv = { ...process.env, ...spec.env };
+    for (const k of ['PATH', 'Path', 'path']) delete childEnv[k];
+    childEnv.PATH = [...binDirs, origPath].filter(Boolean).join(PATH_SEP);
+
+    const proc = spawn(cmd, args, {
+      cwd: cwdAbs,
+      env: childEnv,
+      shell: process.platform === 'win32',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    this.procs.set(spec.name, proc);
+    state.status = 'running';
+    state.pid = proc.pid;
+    state.startedAt = Date.now();
+
+    const prefix = `${spec.color}[${spec.name}]${EOL}${'\x1b[0m'}`;
+    const onChunk = (stream: NodeJS.ReadableStream, isErr: boolean) => {
+      let buf = '';
+      stream.on('data', (chunk: Buffer) => {
+        buf += chunk.toString();
+        // Split on CRLF or LF. Children mix line endings on Windows: our own
+        // Logger writes os.EOL (\r\n), but Vite/uvicorn/third-party CLIs write
+        // LF only. Splitting on os.EOL alone left LF-terminated output stuck in
+        // `buf` forever (Vite's whole startup banner never appeared). Re-emit
+        // with the platform EOL so the host terminal gets clean line breaks.
+        const lines = buf.split(/\r?\n/);
+        buf = lines.pop() ?? '';
+        for (const line of lines) {
+          const target = isErr ? process.stderr : process.stdout;
+          target.write(`${spec.color}[${spec.name}]\x1b[0m ${line}${EOL}`);
+          this.pushLog(spec.name, line, isErr ? 'stderr' : 'stdout');
+        }
+      });
+    };
+    onChunk(proc.stdout!, false);
+    onChunk(proc.stderr!, true);
+
+    proc.on('exit', (code, signal) => {
+      // An intentional stop sets status to 'stopped' first, so don't flip a
+      // stopped service to 'errored' when its process tree finally exits.
+      state.status = this.shuttingDown || state.status === 'stopped' ? 'stopped' : 'errored';
+      state.lastExitCode = code;
+      state.pid = undefined;
+      this.pushLog(spec.name, `exited code=${code} signal=${signal}`, 'system');
+      if (!this.shuttingDown && !spec.optional) {
+        this.pushLog(spec.name, `required service stopped - supervisor continuing (run 'nexus dev restart ${spec.name}')`, 'system');
+      }
+    });
+    proc.on('error', (err) => {
+      state.status = 'errored';
+      this.pushLog(spec.name, `failed to start: ${err.message}`, 'system');
+    });
+  }
+
+  private pushLog(name: string, line: string, source: LogEntry['source'] = 'stdout'): void {
+    const state = this.states.get(name);
+    if (!state) return;
+    state.logTail.push(line);
+    if (state.logTail.length > MAX_TAIL) state.logTail.shift();
+
+    // Also add to the aggregated structured buffer for /logs/all.
+    const entry: LogEntry = {
+      service: name,
+      ts: Date.now(),
+      source,
+      level: detectLevel(line),
+      line,
+    };
+    this.allLogs.push(entry);
+    if (this.allLogs.length > MAX_ALL_LOGS) this.allLogs.shift();
+  }
+
+  stopService(name: string): void {
+    const proc = this.procs.get(name);
+    if (!proc) return;
+    const state = this.states.get(name)!;
+    state.status = 'stopped';
+    // Windows: services spawn with `shell: true`, so `proc` IS cmd.exe and
+    // `proc.kill()` only terminates that one wrapper - the tsx/vite/python
+    // process tree below it survives as an orphan and the port stays bound.
+    // `taskkill /T /F` kills the whole tree. POSIX: signal the process group.
+    try {
+      if (process.platform === 'win32' && proc.pid) {
+        execFile('taskkill', ['/PID', String(proc.pid), '/T', '/F'], { windowsHide: true }, () => {});
+      } else if (proc.pid) {
+        try {
+          process.kill(-proc.pid, 'SIGTERM');
+        } catch {
+          proc.kill('SIGTERM');
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+    this.procs.delete(name);
+  }
+
+  restartService(name: string): void {
+    const spec = this.services.find((s) => s.name === name);
+    if (!spec) return;
+    this.stopService(name);
+    setTimeout(() => this.startService(spec), 300);
+  }
+
+  status(): ServiceState[] {
+    return this.services.map((s) => ({ ...this.states.get(s.name)! }));
+  }
+
+  /** Start all services and the control API. Resolves when started. */
+  async start(): Promise<void> {
+    // Bind the control API first so auto-allotted ports are known before the
+    // admin service boots (VITE_SUPERVISOR_URL can point at the real port).
+    await this.startControlServer();
+    this.injectControlEnv();
+    for (const s of this.services) this.startService(s);
+    process.on('SIGINT', () => this.shutdown());
+    process.on('SIGTERM', () => this.shutdown());
+  }
+
+  /** Give the admin service (and any other) the actual control URL to call back. */
+  private injectControlEnv(): void {
+    if (!this.boundControlPort) return;
+    for (const s of this.services) {
+      if (s.name === 'admin') {
+        s.env = { ...(s.env ?? {}), VITE_SUPERVISOR_URL: `http://127.0.0.1:${this.boundControlPort}` };
+      }
+    }
+  }
+
+  /**
+   * Bind the control API on 127.0.0.1. When the requested port is already
+   * taken (EADDRINUSE - e.g. another `nexus dev` is running), automatically
+   * keep trying the next free port, then persist the actual bound port to
+   * `supervisor.json` at the project root so the backend/admin can discover it.
+   */
+  private async startControlServer(): Promise<void> {
+    const server = createServer((req, res) => this.handleControl(req, res));
+    const requested = this.controlPort;
+    const MAX_ATTEMPTS = 100;
+    let bound = false;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const port = requested + attempt;
+      try {
+        await this.tryListen(server, port);
+        this.boundControlPort = port;
+        this.controlPort = port;
+        server.on('error', () => { /* ignore post-bind errors on the control socket */ });
+        process.stdout.write(`\x1b[36m[supervisor]\x1b[0m control API on http://127.0.0.1:${port}${EOL}`);
+        if (port !== requested) {
+          process.stdout.write(`\x1b[36m[supervisor]\x1b[0m note: ${requested} was busy - control API moved to port ${port}${EOL}`);
+        }
+        this.controlServer = server;
+        await this.writeSupervisorInfo();
+        bound = true;
+        break;
+      } catch (err) {
+        // Keep scanning upward on port collisions; give up on anything else.
+        if ((err as NodeJS.ErrnoException).code !== 'EADDRINUSE') {
+          process.stdout.write(`\x1b[31m[supervisor]\x1b[0m control API failed to start: ${(err as Error).message}${EOL}`);
+          break;
+        }
+      }
+    }
+    if (!bound) {
+      process.stdout.write(`\x1b[31m[supervisor]\x1b[0m no free control port near ${requested} (tried ${MAX_ATTEMPTS} ports)${EOL}`);
+    }
+  }
+
+  /** Write `supervisor.json` with the actual control endpoint for the project. */
+  private async writeSupervisorInfo(): Promise<void> {
+    try {
+      await writeFile(
+        join(this.root, 'supervisor.json'),
+        JSON.stringify({
+          port: this.boundControlPort,
+          url: this.boundControlPort ? `http://127.0.0.1:${this.boundControlPort}` : undefined,
+          writtenAt: new Date().toISOString(),
+        }, null, 2) + '\n',
+        'utf8',
+      );
+    } catch (err) {
+      process.stdout.write(`\x1b[33m[supervisor]\x1b[0m could not write supervisor.json: ${(err as Error).message}${EOL}`);
+    }
+  }
+
+  private handleControl(req: IncomingMessage, res: ServerResponse): void {
+    const url = new URL(req.url ?? '/', `http://127.0.0.1:${this.controlPort}`);
+    // Permissive CORS so the browser-based admin (localhost:3001) can call us.
+    res.setHeader('access-control-allow-origin', '*');
+    res.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
+    res.setHeader('access-control-allow-headers', 'content-type, authorization');
+    if (req.method === 'OPTIONS') { res.statusCode = 204; res.end(); return; }
+    res.setHeader('content-type', 'application/json');
+    if (req.method === 'GET' && url.pathname === '/status') {
+      res.end(JSON.stringify({ services: this.status() }));
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/start') {
+      const name = url.searchParams.get('name');
+      const spec = this.services.find((s) => s.name === name);
+      if (spec && name) this.startService(spec);
+      res.end(JSON.stringify({ ok: !!spec }));
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/restart') {
+      const name = url.searchParams.get('name');
+      if (name) this.restartService(name);
+      res.end(JSON.stringify({ ok: !!name }));
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/stop') {
+      const name = url.searchParams.get('name');
+      if (name) this.stopService(name);
+      res.end(JSON.stringify({ ok: !!name }));
+      return;
+    }
+    if (req.method === 'GET' && url.pathname === '/logs') {
+      const name = url.searchParams.get('name');
+      const state = name ? this.states.get(name) : undefined;
+      res.end(JSON.stringify({ logs: state?.logTail ?? [] }));
+      return;
+    }
+    if (req.method === 'GET' && url.pathname === '/logs/all') {
+      const service = url.searchParams.get('service') ?? '';
+      const level = url.searchParams.get('level') ?? '';
+      const q = url.searchParams.get('q') ?? '';
+      let entries = this.allLogs;
+      if (service) entries = entries.filter((e) => e.service === service);
+      if (level) entries = entries.filter((e) => e.level === level);
+      if (q) {
+        const lower = q.toLowerCase();
+        entries = entries.filter((e) => e.line.toLowerCase().includes(lower));
+      }
+      res.end(JSON.stringify({ logs: entries }));
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/logs/clear') {
+      for (const state of this.states.values()) state.logTail = [];
+      this.allLogs = [];
+      res.end(JSON.stringify({ ok: true }));
+      return;
+    }
+    res.statusCode = 404;
+    res.end(JSON.stringify({ error: 'not found' }));
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    process.stdout.write(`\x1b[36m[supervisor]\x1b[0m shutting down...${EOL}`);
+    for (const name of this.procs.keys()) this.stopService(name);
+    this.controlServer?.close();
+    // Give processes a moment to exit.
+    await new Promise((r) => setTimeout(r, 200));
+    process.exit(0);
+  }
+}
+
+/** Classify a log line's severity from its content. */
+function detectLevel(line: string): LogEntry['level'] {
+  const lower = line.toLowerCase();
+  if (/\berror\b/.test(lower) || /\bfatal\b/.test(lower) || /\bfail(ed|ure)?\b/.test(lower) || /\bexception\b/.test(lower)) return 'error';
+  if (/\bwarn(ing)?\b/.test(lower) || /\bunauthorized\b/.test(lower) || /\bforbidden\b/.test(lower)) return 'warn';
+  return 'info';
+}

package/src/util.ts

@@ -0,0 +1,123 @@
+import { createConnection } from 'node:net';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+export interface CheckResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+/** Try a TCP connect to host:port within a timeout. */
+export function tcpReachable(host: string, port: number, timeoutMs = 1500): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host, port }, () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.setTimeout(timeoutMs);
+    socket.on('error', () => resolve(false));
+    socket.on('timeout', () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
+/** True if nothing is listening on `port` (quick TCP connect check). */
+export async function isPortFree(host: string, port: number, timeoutMs = 700): Promise<boolean> {
+  return !(await tcpReachable(host === '0.0.0.0' ? '127.0.0.1' : host, port, timeoutMs));
+}
+
+/** Parse host/port from common connection-string formats. */
+export function parseHostPort(url: string, defaultPort: number): { host: string; port: number } {
+  try {
+    const u = new URL(url);
+    return { host: u.hostname || 'localhost', port: u.port ? Number(u.port) : defaultPort };
+  } catch {
+    return { host: 'localhost', port: defaultPort };
+  }
+}
+
+export async function versionOf(cmd: string, args: string[] = ['--version']): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(cmd, args, { shell: process.platform === 'win32' });
+    return stdout.trim();
+  } catch {
+    return '';
+  }
+}
+
+/** A prerequisite check (runtime or service). */
+export interface Prereq extends CheckResult {
+  /** Critical = the wizard should refuse to proceed. Warnings ask to continue. */
+  critical?: boolean;
+}
+
+/**
+ * Detect installed runtimes: node, npm, python, git. Returns a list of checks
+ * suitable for printing. node/npm/python are critical; git is a warning.
+ * Shared by `nexus doctor` and `nexus init` step 1.
+ */
+export async function scanRuntimes(): Promise<Prereq[]> {
+  const out: Prereq[] = [];
+  out.push({ name: 'node', ok: !!process.versions.node, detail: `v${process.versions.node}`, critical: true });
+  const npmVer = await versionOf(process.platform === 'win32' ? 'npm' : 'npm');
+  out.push({ name: 'npm', ok: !!npmVer, detail: npmVer ? `v${npmVer}` : 'not found', critical: true });
+  const pyVer = await versionOf(process.platform === 'win32' ? 'python' : 'python3');
+  out.push({ name: 'python', ok: !!pyVer, detail: pyVer || 'not found (ai-server disabled)', critical: true });
+  const gitVer = await versionOf('git', ['--version']);
+  out.push({ name: 'git', ok: !!gitVer, detail: gitVer ? gitVer.replace(/^git version /, 'v') : 'not found' });
+  return out;
+}
+
+/** Lightweight config shape used by `scanServices` (avoids importing nexus-core here). */
+export interface ServiceConfig {
+  db: { uri: string };
+  redis: { url: string };
+  ai: { serverUrl: string };
+  server: { host: string; port: number };
+  frontend: { port: number };
+  admin: { port: number };
+}
+
+/**
+ * Probe Mongo, Redis, and the AI server (TCP reachability) plus check that the
+ * backend/frontend/admin ports are free. Returns a list of checks.
+ * Shared by `nexus doctor` and `nexus init` step 1 / step 18 (verify).
+ */
+export async function scanServices(cfg: ServiceConfig): Promise<Prereq[]> {
+  const out: Prereq[] = [];
+  const db = parseHostPort(cfg.db.uri, 27017);
+  const dbOk = await tcpReachable(db.host, db.port);
+  out.push({ name: 'mongodb', ok: dbOk, detail: `${db.host}:${db.port} ${dbOk ? 'reachable' : 'unreachable'}` });
+
+  const redis = parseHostPort(cfg.redis.url, 6379);
+  const redisOk = await tcpReachable(redis.host, redis.port);
+  out.push({ name: 'redis', ok: redisOk, detail: `${redis.host}:${redis.port} ${redisOk ? 'reachable' : 'unreachable'}` });
+
+  const ai = parseHostPort(cfg.ai.serverUrl, 8000);
+  const aiOk = await tcpReachable(ai.host, ai.port);
+  out.push({ name: 'ai server', ok: aiOk, detail: `${ai.host}:${ai.port} ${aiOk ? 'reachable' : 'unreachable'}` });
+
+  const backendFree = await isPortFree(cfg.server.host, cfg.server.port, 500);
+  out.push({ name: 'backend port', ok: backendFree, detail: `:${cfg.server.port} ${backendFree ? 'free' : 'IN USE'}` });
+
+  const frontendFree = await isPortFree('127.0.0.1', cfg.frontend.port, 500);
+  out.push({ name: 'frontend port', ok: frontendFree, detail: `:${cfg.frontend.port} ${frontendFree ? 'free' : 'in use'}` });
+
+  const adminFree = await isPortFree('127.0.0.1', cfg.admin.port, 500);
+  out.push({ name: 'admin port', ok: adminFree, detail: `:${cfg.admin.port} ${adminFree ? 'free' : 'in use'}` });
+
+  return out;
+}
+
+/** Returns true if `path` exists and its directory looks like a nexus project root. */
+export function looksLikeProject(root: string): boolean {
+  return existsSync(join(root, 'package.json')) &&
+    ['ts', 'js', 'mjs', 'cjs'].some((ext) => existsSync(join(root, `nexus.config.${ext}`)));
+}

package/src/wizard.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared wizard primitives for interactive CLI commands (`nexus init`, `nexus pysetup --interactive`).
+ *
+ * Everything here is dependency-free and built on `node:readline/promises` (already used
+ * by `chooseKind` in init.ts). When stdin is not a TTY (CI, piped input) or `--no-interactive`
+ * is set, `isInteractive()` returns false and the prompt functions fall back to their
+ * defaults so commands remain scriptable.
+ */
+import { createInterface, type Interface } from 'node:readline/promises';
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+/** True when the user can be prompted: a real TTY and not running under CI. */
+export function isInteractive(): boolean {
+  return !!process.stdin.isTTY && !process.env.CI;
+}
+
+let rl: Interface | null = null;
+
+function rlIf(): Interface {
+  if (!rl) {
+    rl = createInterface({ input: process.stdin, output: process.stdout, terminal: isInteractive() });
+  }
+  return rl;
+}
+
+/** Close the readline interface (call at the end of a wizard run). */
+export function closeWizard(): void {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+/** Print a section banner. */
+export function banner(title: string, lines: string[] = []): void {
+  console.log(`\n${BOLD}  *  ${title}${RESET}`);
+  for (const line of lines) console.log(`  ${DIM}${line}${RESET}`);
+  console.log();
+}
+
+/** Print a status icon for a boolean result. */
+export function statusIcon(ok: boolean): string {
+  return ok ? `${GREEN}[OK]${RESET}` : `${RED}[X]${RESET}`;
+}
+
+/** Prompt for a free-text string. Returns the default when non-interactive or empty input. */
+export async function prompt(question: string, defaultValue?: string): Promise<string> {
+  if (!isInteractive()) return defaultValue ?? '';
+  const suffix = defaultValue !== undefined ? ` ${DIM}[${defaultValue}]${RESET}` : '';
+  const answer = (await rlIf().question(`  ${question}${suffix} `)).trim();
+  return answer || defaultValue || '';
+}
+
+/**
+ * Prompt for a yes/no confirmation. Returns the default when non-interactive.
+ * Default defaults to true. Accepts y/yes/n/no (case-insensitive).
+ */
+export async function confirm(question: string, defaultValue = true): Promise<boolean> {
+  if (!isInteractive()) return defaultValue;
+  const hint = defaultValue ? 'Y/n' : 'y/N';
+  const answer = (await rlIf().question(`  ${question} ${DIM}[${hint}]${RESET} `)).trim().toLowerCase();
+  if (!answer) return defaultValue;
+  return /^[yt]/i.test(answer);
+}
+
+/** Prompt for a hidden (masked) string - used for API keys / secrets. */
+export async function promptHidden(question: string): Promise<string> {
+  if (!isInteractive()) return '';
+  // readline/promises has no built-in hidden mode; mute stdout by writing spaces.
+  // For secrets we accept that the value echoes in CI-style terminals; non-interactive
+  // paths never reach here and tests use --no-interactive so this is dev-only.
+  const answer = (await rlIf().question(`  ${question} `)).trim();
+  return answer;
+}
+
+/**
+ * Prompt for a single choice from a list. Returns the option's value.
+ * Options are 1-indexed in the prompt; press Enter to accept the default.
+ */
+export async function select<T extends string>(question: string, options: Array<{ label: string; value: T }>, defaultValue?: T): Promise<T> {
+  if (!isInteractive()) return defaultValue ?? options[0]!.value;
+  console.log(`  ${question}`);
+  options.forEach((o, i) => {
+    const marker = defaultValue === o.value ? `${CYAN}*${RESET}` : ' ';
+    console.log(`  ${marker} ${i + 1}) ${o.label}`);
+  });
+  const hint = defaultValue !== undefined ? ` (default ${options.findIndex((o) => o.value === defaultValue) + 1})` : '';
+  const answer = (await rlIf().question(`  Choose${hint}: `)).trim();
+  if (!answer) return defaultValue ?? options[0]!.value;
+  const idx = parseInt(answer, 10);
+  if (Number.isFinite(idx) && idx >= 1 && idx <= options.length) return options[idx - 1]!.value;
+  // also accept a matching label/value
+  const match = options.find((o) => o.value === answer || o.label.toLowerCase() === answer.toLowerCase());
+  return match ? match.value : defaultValue ?? options[0]!.value;
+}
+
+/**
+ * Prompt for multiple choices (toggle each). Returns the selected values.
+ * Accepts comma-separated indices or labels (e.g. "1,3" or "openai,ollama").
+ */
+export async function multiSelect<T extends string>(question: string, options: Array<{ label: string; value: T }>, defaultValues: T[] = []): Promise<T[]> {
+  if (!isInteractive()) return defaultValues;
+  console.log(`  ${question} ${DIM}(comma-separated indices, Enter for defaults)${RESET}`);
+  options.forEach((o, i) => {
+    const marker = defaultValues.includes(o.value) ? `${CYAN}*${RESET}` : ' ';
+    console.log(`  ${marker} ${i + 1}) ${o.label}`);
+  });
+  const answer = (await rlIf().question(`  Choose: `)).trim();
+  if (!answer) return defaultValues;
+  const selected: T[] = [];
+  for (const token of answer.split(/[,\s]+/).filter(Boolean)) {
+    const idx = parseInt(token, 10);
+    if (Number.isFinite(idx) && idx >= 1 && idx <= options.length) {
+      const v = options[idx - 1]!.value;
+      if (!selected.includes(v)) selected.push(v);
+      continue;
+    }
+    const match = options.find((o) => o.value === token || o.label.toLowerCase() === token.toLowerCase());
+    if (match && !selected.includes(match.value)) selected.push(match.value);
+  }
+  return selected;
+}
+
+/** A row in a summary table. */
+export interface SummaryRow {
+  label: string;
+  value: string;
+  ok?: boolean;
+}
+
+/** Render a two-column summary table (label | value). */
+export function summaryTable(rows: SummaryRow[]): void {
+  const labelWidth = Math.max(8, ...rows.map((r) => r.label.length));
+  for (const r of rows) {
+    const icon = r.ok !== undefined ? statusIcon(r.ok) : ' ';
+    const label = r.label.padEnd(labelWidth);
+    const value = r.ok === false ? `${YELLOW}${r.value}${RESET}` : r.value;
+    console.log(`  ${icon} ${label}  ${value}`);
+  }
+}
+
+export const COLORS = { GREEN, RED, YELLOW, CYAN, DIM, BOLD, RESET };