codebase-onboarder 0.1.0

package/cli/commands.js

@@ -0,0 +1,436 @@
+// The verbs of the `onboarder` command. `main.js` parses argv into flags and a
+// command name; each function here is one command, taking `{ flags, out, err,
+// io }` so the tests can drive them with strings instead of a terminal.
+//
+// Every command returns an exit code instead of calling process.exit — the
+// bin wrapper is the only place that touches the process.
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+
+import {
+  DEFAULT_SETTINGS, configPath, configExists, readSettings, writeSettings,
+  publicSettings, serverUrls, maskAccessKey,
+} from '../server/config.js';
+import { startServer } from '../server/index.js';
+import { tunnelStatus, cloudflareCommand, tailscaleCommand, installHint, findOnPath } from '../server/tunnel.js';
+import { bold, cyan, dim, ok, warn, bad, kv, tick, cross, dash, welcomeBanner } from './ui.js';
+import { buildSteps, pendingSteps, defaultOf, applyFlags, answersToSettings, summaryLines } from './wizard.js';
+import { runSteps, WizardCancelled } from './prompt.js';
+
+// ---------------------------------------------------------------- setup ---
+
+export async function runSetup({ flags = {}, out = console.log, err = console.error, version = '' } = {}) {
+  const file = flags.config || configPath();
+  const existed = await configExists(file);
+  const current = existed ? await readSettings(file) : { ...DEFAULT_SETTINGS };
+
+  // Non-interactive (or a piped stdout): flags are the answers, defaults fill
+  // the rest, and the summary is printed instead of asked about.
+  if (flags.nonInteractive || !process.stdout.isTTY) {
+    const { settings } = applyFlags(current, flags);
+    await writeSettings(settings, file);
+    if (flags.json) {
+      out(JSON.stringify({ configFile: file, created: !existed, settings: publicSettings(settings) }, null, 2));
+    } else {
+      out(tick + `Wrote ${file}`);
+      printSummary(out, settings, { revealKey: Boolean(patchHasNewKey(flags)) });
+    }
+    await printTunnelFollowup(out, settings);
+    if (flags.start) return runStart({ flags, out, err });
+    return 0;
+  }
+
+  out(welcomeBanner(version, file));
+  if (existed) out(dim('  A config already exists — answers start from what it says.\n'));
+
+  // Flag answers go in first; the wizard only asks what is left.
+  const seed = {};
+  for (const id of ['name', 'email', 'mode', 'host', 'port', 'domain', 'autoOpen']) {
+    if (flags[id] !== undefined) seed[id] = flags[id];
+  }
+  if (flags.provider !== undefined) seed.provider = flags.provider;
+  if (flags.baseUrl !== undefined) seed.baseUrl = flags.baseUrl;
+  if (flags.model !== undefined) seed.model = flags.model;
+
+  let answers;
+  try {
+    answers = await runSteps(pendingSteps(buildSteps(current), seed), seed);
+  } catch (e) {
+    if (e instanceof WizardCancelled) {
+      err('\n  Setup cancelled — nothing was written.');
+      return 130;
+    }
+    throw e;
+  }
+
+  let settings;
+  try {
+    settings = answersToSettings(current, answers);
+  } catch (e) {
+    err(bad('  Those answers do not make a valid config: ' + e.message));
+    return 1;
+  }
+
+  out('');
+  printSummary(out, settings, { revealKey: false });
+  out('');
+  const confirmed = await confirm(out, 'Write this config?');
+  if (!confirmed) {
+    err('  Not written.');
+    return 1;
+  }
+  await writeSettings(settings, file);
+  out(tick + 'Wrote ' + file);
+
+  // The generated key exists exactly once in a readable form: right now.
+  if (answers.keyChoice === 'generate' && settings.accessKey) {
+    out('');
+    out(warn('  Your access key — shown this once, store it somewhere safe:'));
+    out('    ' + bold(settings.accessKey));
+  }
+  await printTunnelFollowup(out, settings);
+
+  if (flags.start || await confirm(out, 'Start Onboarder now?', true)) {
+    out('');
+    return runStart({ flags, out, err });
+  }
+  out(dim('  Later: `onboarder start`'));
+  return 0;
+}
+
+function patchHasNewKey(flags) {
+  return flags.accessKey === 'generate' || (flags.accessKey === undefined && flags.mode === 'self-hosted');
+}
+
+function printSummary(out, settings, { revealKey = false } = {}) {
+  out(bold('  About to write:'));
+  for (const [label, value] of summaryLines(settings, { revealKey })) out(kv(label, String(value)));
+}
+
+async function confirm(out, question, fallback = false) {
+  const { default: readline } = await import('node:readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const typed = await rl.question(`  ${bold(question)} ${dim(fallback ? '(Y/n)' : '(y/N)')} `);
+    const v = typed.trim().toLowerCase();
+    return v ? v === 'y' || v === 'yes' : fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+async function printTunnelFollowup(out, settings) {
+  const status = tunnelStatus(settings);
+  for (const name of ['cloudflare', 'tailscale']) {
+    const t = status[name];
+    if (!t.enabled) continue;
+    out('');
+    if (t.installed) {
+      out(`  ${name} — start the tunnel with:`);
+      out('    ' + cyan(t.command));
+      out(dim(`    or just: onboarder tunnel ${name}`));
+    } else {
+      out(warn(`  ${name} is enabled but its CLI is not installed.`));
+      out(dim('    Install: ' + t.install));
+    }
+  }
+}
+
+// ---------------------------------------------------------------- start ---
+
+export async function runStart({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  if (!await configExists(file)) {
+    // No config yet: on a terminal the kind thing is to run setup first; in a
+    // script the predictable thing is to boot the defaults (which are the
+    // pre-settings behavior) and say so.
+    if (process.stdout.isTTY && !flags.nonInteractive) {
+      out(dim('  No settings yet — running setup first.'));
+      return runSetup({ flags: { ...flags, start: true }, out, err });
+    }
+    out(dim(`  No config at ${file} — starting with defaults (local mode).`));
+  }
+  const { server, host, port } = await startServer({ configFile: file, log: out });
+  if (flags.json) out(JSON.stringify({ host, port, url: `http://127.0.0.1:${port}/` }));
+  // The listening server holds the event loop; resolve so callers/tests know
+  // we are up, but leave the process running.
+  return { server, host, port, code: 0 };
+}
+
+// --------------------------------------------------------------- config ---
+
+// Keys `config set` may touch — the same allow-list the HTTP API enforces, so
+// neither surface can smuggle in a key the schema does not know.
+const SETTABLE = {
+  mode: (v) => { if (!['local', 'self-hosted'].includes(v)) throw new Error('mode must be "local" or "self-hosted".'); return v; },
+  host: (v) => v,
+  port: (v) => { const n = Number(v); if (!Number.isInteger(n) || n < 1 || n > 65535) throw new Error('port must be 1-65535.'); return n; },
+  domain: (v) => v,
+  autoOpen: (v) => ['true', 'yes', '1', 'on'].includes(String(v).toLowerCase()),
+  'account.name': (v) => v,
+  'account.email': (v) => v,
+  'account.provider': (v) => v,
+  'account.baseUrl': (v) => v,
+  'account.model': (v) => v,
+  'tunnel.cloudflare': (v) => ['true', 'yes', '1', 'on'].includes(String(v).toLowerCase()),
+  'tunnel.tailscale': (v) => ['true', 'yes', '1', 'on'].includes(String(v).toLowerCase()),
+};
+
+function dig(obj, dotted) {
+  return dotted.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+function bury(obj, dotted, value) {
+  const keys = dotted.split('.');
+  let o = obj;
+  for (const k of keys.slice(0, -1)) o = o[k] = o[k] && typeof o[k] === 'object' ? o[k] : {};
+  o[keys.at(-1)] = value;
+}
+
+
+export async function runConfig(sub, args, { flags = {}, out = console.log } = {}) {
+  const file = flags.config || configPath();
+  switch (sub) {
+    case 'path':
+      out(file);
+      return 0;
+    case 'show': {
+      const settings = await readSettings(file);
+      if (flags.json) {
+        const pub = publicSettings(settings);
+        if (flags.reveal) pub.accessKey = settings.accessKey || null;
+        out(JSON.stringify({ configFile: file, ...pub }, null, 2));
+        return 0;
+      }
+      const urls = serverUrls(settings);
+      out(bold('  ' + file));
+      out(kv('Mode', settings.mode));
+      out(kv('Bind', `${settings.host}:${settings.port}`));
+      if (settings.domain) out(kv('Domain', settings.domain));
+      out(kv('Local', urls.local));
+      if (urls.network) out(kv('Network', urls.network));
+      if (urls.domain) out(kv('Public', urls.domain));
+      if (settings.mode === 'self-hosted') {
+        out(kv('Access key', flags.reveal ? (settings.accessKey || '(none)') : maskAccessKey(settings.accessKey)));
+        if (!flags.reveal) out(dim('    `onboarder config show --reveal` prints it — you are on this machine, after all.'));
+      }
+      const who = [settings.account.name, settings.account.email].filter(Boolean).join(' · ');
+      if (who) out(kv('Profile', who));
+      if (settings.account.baseUrl) {
+        out(kv('AI', `${settings.account.provider} — ${settings.account.baseUrl}${settings.account.model ? ' — ' + settings.account.model : ''}`));
+      }
+      const status = tunnelStatus(settings);
+      for (const name of ['cloudflare', 'tailscale']) {
+        if (status[name].enabled) {
+          out(kv(name, status[name].installed ? status[name].command : 'enabled, CLI missing — ' + status[name].install));
+        }
+      }
+      out(kv('Auto-open', settings.autoOpen ? 'yes' : 'no'));
+      return 0;
+    }
+    case 'get': {
+      const [key] = args;
+      if (!key || (!(key in SETTABLE) && key !== 'accessKey')) throw new Error('Unknown key. Known: ' + [...Object.keys(SETTABLE), 'accessKey'].join(', '));
+      const settings = await readSettings(file);
+      const value = key === 'accessKey' ? maskAccessKey(settings.accessKey) : dig(settings, key);
+      out(String(value ?? ''));
+      return 0;
+    }
+    case 'set': {
+      const [key, ...rest] = args;
+      const raw = rest.join(' ');
+      if (!key || !(key in SETTABLE)) throw new Error('Unknown or unsettable key "' + key + '". Known: ' + Object.keys(SETTABLE).join(', ') + '\nThe access key is managed by `onboarder config key …`.');
+      if (!raw) throw new Error('Missing value: onboarder config set ' + key + ' <value>');
+      const value = SETTABLE[key](raw);
+      const current = await readSettings(file);
+      const next = { ...current, account: { ...current.account }, tunnel: { ...current.tunnel } };
+      bury(next, key, value);
+      await writeSettings(next, file); // normalizeSettings validates the result
+      out(tick + key + ' = ' + (typeof value === 'boolean' ? String(value) : value));
+      if (['host', 'port'].includes(key)) out(dim('    Restart the server for this to take effect.'));
+      return 0;
+    }
+    default:
+      throw new Error('Usage: onboarder config <show|get|set|path|reset|key>');
+  }
+}
+
+
+// Config surgery that did not fit in `set`: full reset, and the access key,
+// which gets its own verb because it is the one value that is shown once and
+// never round-trips through an API.
+export async function runConfigKey(action, args, { flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  const current = await readSettings(file);
+  if (action === 'rotate') {
+    const { generateAccessKey } = await import('../server/config.js');
+    const key = generateAccessKey();
+    await writeSettings({ ...current, accessKey: key }, file);
+    out(tick + 'Rotated. The old key is dead this second — settings are re-read per request.');
+    out('    ' + bold(key));
+    out(dim('    Shown once. Distribute it to your devices.'));
+    return 0;
+  }
+  if (action === 'show') {
+    out(current.accessKey || '(no key set)');
+    return 0;
+  }
+  if (action === 'set') {
+    const value = args.join(' ').trim();
+    if (value.length < 16) throw new Error('Access keys are at least 16 characters.');
+    await writeSettings({ ...current, accessKey: value }, file);
+    out(tick + 'Access key updated.');
+    return 0;
+  }
+  throw new Error('Usage: onboarder config key <rotate|show|set <value>>');
+}
+
+export async function runConfigReset({ flags = {}, out = console.log, err = console.error } = {}) {
+  const file = flags.config || configPath();
+  if (!flags.yes) {
+    err('  This rewrites ' + file + ' with factory defaults (local mode, port 4310, no key).');
+    err('  Re-run with --yes to confirm.');
+    return 1;
+  }
+  await writeSettings({ ...DEFAULT_SETTINGS }, file);
+  out(tick + 'Reset to defaults: ' + file);
+  return 0;
+}
+
+
+// --------------------------------------------------------------- doctor ---
+
+// Diagnose without mutating. Every check reports { id, ok, required, detail }
+// and the command exits non-zero if any *required* check failed — the same
+// shape `doctor --json` hands to scripts.
+export async function runDoctor({ flags = {}, out = console.log } = {}) {
+  const file = flags.config || configPath();
+  const checks = [];
+
+  checks.push({
+    id: 'node', ok: Number(process.versions.node.split('.')[0]) >= 20, required: true,
+    detail: `v${process.versions.node} (needs ≥ 20)`,
+  });
+
+  let settings = null;
+  try {
+    settings = await readSettings(file);
+    checks.push({ id: 'config', ok: true, required: true, detail: file });
+  } catch (e) {
+    checks.push({ id: 'config', ok: false, required: true, detail: `${file} — ${e.message}` });
+  }
+
+  const dir = file.slice(0, file.lastIndexOf('/'));
+  let dirOk = true;
+  try { await fsp.access(dir, fs.constants.W_OK); } catch { dirOk = false; }
+  checks.push({ id: 'config-dir', ok: dirOk, required: true, detail: dirOk ? dir + ' is writable' : dir + ' is NOT writable' });
+
+  if (settings) {
+    const free = await portIsFree(settings.host, settings.port);
+    checks.push({
+      id: 'port', ok: free, required: false,
+      detail: free ? `${settings.host}:${settings.port} is free` : `${settings.host}:${settings.port} is already in use (running already?)`,
+    });
+    if (settings.mode === 'self-hosted') {
+      checks.push({
+        id: 'access-key', ok: Boolean(settings.accessKey), required: true,
+        detail: settings.accessKey ? 'set — ' + maskAccessKey(settings.accessKey) : 'MISSING — the API refuses every call until one is set',
+      });
+      const loopback = ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(settings.host);
+      checks.push({
+        id: 'domain', ok: loopback || Boolean(settings.domain), required: !loopback,
+        detail: settings.domain || (loopback ? '(none — a tunnel provides the name)' : 'MISSING — a LAN bind needs a domain'),
+      });
+    }
+  }
+
+  for (const name of ['git', 'cloudflared', 'tailscale']) {
+    const wanted = name === 'git' || (settings && settings.tunnel?.[name === 'cloudflared' ? 'cloudflare' : 'tailscale']);
+    const found = Boolean(findOnPath(name));
+    checks.push({
+      id: name, ok: found || !wanted, required: name === 'git',
+      detail: found ? 'installed' : wanted ? 'not installed — ' + installHint(name) : 'not installed (not needed for your settings)',
+    });
+  }
+
+  if (flags.json) {
+    out(JSON.stringify({ ok: checks.every((c) => c.ok || !c.required), checks }, null, 2));
+  } else {
+    out('');
+    out(bold('  Onboarder doctor'));
+    for (const c of checks) {
+      const mark = c.ok ? tick : c.required ? cross : dash;
+      out(`${mark}${c.id} — ${c.detail}`);
+    }
+    out('');
+  }
+  return checks.every((c) => c.ok || !c.required) ? 0 : 1;
+}
+
+function portIsFree(host, port) {
+  return new Promise((resolve) => {
+    const probe = net.createServer();
+    probe.once('error', () => resolve(false));
+    probe.listen(port, host, () => probe.close(() => resolve(true)));
+  });
+}
+
+// --------------------------------------------------------------- tunnel ---
+
+export async function runTunnel(kind, { flags = {}, out = console.log, err = console.error } = {}) {
+  const settings = await readSettings(flags.config || configPath());
+  const target = `http://127.0.0.1:${settings.port}`;
+  if (kind === 'tailscale') {
+    if (!findOnPath('tailscale')) {
+      err('  tailscale is not installed — ' + installHint('tailscale'));
+      return 1;
+    }
+    const cmd = tailscaleCommand(settings);
+    out('  ' + cmd);
+    const { spawnSync } = await import('node:child_process');
+    const r = spawnSync(cmd, { shell: true, stdio: 'inherit' });
+    if (r.status === 0) {
+      out(tick + 'Tailscale is serving ' + target + ' over your tailnet (https://<machine>.<tailnet>.ts.net).');
+      out(dim('    `tailscale serve status` to verify, `onboarder doctor` to re-check.'));
+    }
+    return r.status ?? 1;
+  }
+  if (kind === 'cloudflare') {
+    if (!findOnPath('cloudflared')) {
+      err('  cloudflared is not installed — ' + installHint('cloudflared'));
+      return 1;
+    }
+    const cmd = cloudflareCommand(settings);
+    out(dim('  $ ' + cmd));
+    out(dim('  Ctrl-C stops the tunnel; the server keeps running.\n'));
+    // Quick tunnels print their random name on stderr; surface just that line
+    // plus everything when --verbose, so the default output is one useful URL.
+    const child = spawn('cloudflared', ['tunnel', '--url', target], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let announced = false;
+    child.stderr.on('data', (chunk) => {
+      const text = String(chunk);
+      const m = text.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
+      if (m && !announced) {
+        announced = true;
+        out(tick + 'Public URL: ' + bold(m[0]));
+        out(dim('    Anyone with the URL still needs the access key: ' + m[0] + '?key=<your-key>'));
+      }
+      if (flags.verbose) process.stderr.write(text);
+    });
+    child.stdout.on('data', (d) => { if (flags.verbose) process.stdout.write(d); });
+    const stop = () => child.kill('SIGINT');
+    process.once('SIGINT', stop);
+    return new Promise((resolve) => {
+      child.on('close', (code) => {
+        process.removeListener('SIGINT', stop);
+        if (!announced && code !== 0) err('  cloudflared exited without printing a URL — re-run with --verbose to see why.');
+        resolve(code ?? 0);
+      });
+    });
+  }
+  throw new Error('Usage: onboarder tunnel <cloudflare|tailscale>');
+}
+

package/cli/main.js

@@ -0,0 +1,129 @@
+// argv → command. `bin/onboarder.js` is a one-line trampoline into `main`; all
+// parsing and dispatch lives here so the tests can call it directly.
+//
+// Flags use node's util.parseArgs — still zero dependencies, still strict about
+// unknown flags, which is what a tool that writes a config file should be.
+
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+
+import { runSetup, runStart, runConfig, runConfigKey, runConfigReset, runDoctor, runTunnel } from './commands.js';
+
+const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const HELP = `
+  🧭 Onboarder — drop a path, get a map.
+
+  Usage
+    onboarder                     Start the server (runs setup first if needed)
+    onboarder setup | onboard     Configure interactively (the wizard)
+    onboarder start               Start the server
+    onboarder config <…>          show | get <key> | set <key> <value> | path | reset | key <rotate|show|set>
+    onboarder tunnel <name>       cloudflare | tailscale
+    onboarder doctor              Check the machine and the config
+
+  Setup flags (interactive wizard skips what they answer)
+    --mode local|self-hosted   --host <addr>   --port <n>   --domain <name>
+    --access-key generate|<k>  --name <n>   --email <e>
+    --provider none|openai-compatible|ollama|openrouter|custom
+    --base-url <url>   --model <m>   --cloudflare   --tailscale
+
+  General flags
+    --config <file>     Use this config file (or ONBOARDER_CONFIG)
+    --non-interactive   Never prompt; flags + defaults are the answers
+    -y, --yes           Answer yes to confirmations
+    --json              Machine-readable output
+    --reveal            config show prints the full access key
+    --no-color          Plain output (NO_COLOR works too)
+    -h, --help          This text      -v, --version      Print the version
+
+  Examples
+    onboarder setup
+    onboarder setup --non-interactive --mode local --port 4310
+    onboarder setup --non-interactive --mode self-hosted --domain map.example.com --access-key generate
+    onboarder config set tunnel.cloudflare true && onboarder tunnel cloudflare
+`;
+
+const OPTIONS = {
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean', short: 'v' },
+  json: { type: 'boolean' },
+  yes: { type: 'boolean', short: 'y' },
+  'non-interactive': { type: 'boolean' },
+  reveal: { type: 'boolean' },
+  verbose: { type: 'boolean' },
+  start: { type: 'boolean' },
+  color: { type: 'boolean' }, // --no-color falls out of parseArgs for free
+  config: { type: 'string' },
+  mode: { type: 'string' },
+  host: { type: 'string' },
+  port: { type: 'string' },
+  domain: { type: 'string' },
+  'access-key': { type: 'string' },
+  name: { type: 'string' },
+  email: { type: 'string' },
+  provider: { type: 'string' },
+  'base-url': { type: 'string' },
+  model: { type: 'string' },
+  cloudflare: { type: 'boolean' },
+  tailscale: { type: 'boolean' },
+  'auto-open': { type: 'boolean' },
+};
+
+// parseArgs speaks kebab-case; the wizard's flags speak camelCase.
+function normalizeFlags(values) {
+  const out = {};
+  for (const [k, v] of Object.entries(values)) {
+    const key = k.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    out[key] = v;
+  }
+  return out;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true });
+  } catch (e) {
+    console.error('  ' + e.message + '\n' + HELP);
+    return 2;
+  }
+  const { values, positionals } = parsed;
+  const flags = normalizeFlags(values);
+
+  if (flags.help) { console.log(HELP); return 0; }
+  if (flags.version) { console.log(PACKAGE.version); return 0; }
+
+  const [cmd, sub, ...rest] = positionals;
+  try {
+    switch (cmd) {
+      case undefined:
+      case 'start':
+        return codeOf(await runStart({ flags }));
+      case 'setup':
+      case 'onboard':
+      case 'init':
+        return codeOf(await runSetup({ flags, version: PACKAGE.version }));
+      case 'config':
+        if (sub === 'key') return codeOf(await runConfigKey(rest[0], rest.slice(1), { flags }));
+        if (sub === 'reset') return codeOf(await runConfigReset({ flags }));
+        return codeOf(await runConfig(sub, rest, { flags }));
+      case 'tunnel':
+        return codeOf(await runTunnel(sub, { flags }));
+      case 'doctor':
+        return codeOf(await runDoctor({ flags }));
+      default:
+        console.error('  Unknown command: ' + cmd + '\n' + HELP);
+        return 2;
+    }
+  } catch (e) {
+    console.error('  ' + (e.message || e));
+    return 1;
+  }
+}
+
+// Commands return an exit code or, for `start`, an object carrying the live
+// server. Both collapse to "what code should the process eventually use".
+function codeOf(result) {
+  return typeof result === 'number' ? result : result?.code ?? 0;
+}

package/cli/prompt.js

@@ -0,0 +1,101 @@
+// The wizard's face: one readline interface that renders the pure steps from
+// `wizard.js`. Everything display-shaped lives here — numbered choices, hints
+// in gray, validation loops that re-ask with the reason — and nothing
+// decision-shaped does. A step asks, validates, returns; the engine decides
+// what the answer means.
+//
+// Ctrl-C is a first-class answer ("cancelled"), not a stack trace: the wizard
+// has written nothing yet at any point it can be pressed, and it says so.
+
+import readline from 'node:readline/promises';
+
+import { bold, cyan, dim, bad, section } from './ui.js';
+import { defaultOf } from './wizard.js';
+
+export class WizardCancelled extends Error {
+  constructor() {
+    super('cancelled');
+    this.code = 'CANCELLED';
+  }
+}
+
+// Run every pending step in order, collecting answers. `answers` is seeded
+// with flag answers by the caller, which is how --flags skip questions.
+export async function runSteps(steps, answers = {}, io = {}) {
+  const input = io.input || process.stdin;
+  const output = io.output || process.stdout;
+  const rl = readline.createInterface({ input, output });
+  // readline eats SIGINT when the terminal is in its raw-ish mode; route it to
+  // the same cancellation path as anything else that would kill us mid-ask.
+  const onSigint = () => rl.close();
+  process.once('SIGINT', onSigint);
+  try {
+    let lastSection = null;
+    for (const step of steps) {
+      if (step.section && step.section !== lastSection) {
+        output.write(section(step.section) + '\n');
+        lastSection = step.section;
+      }
+      answers[step.id] = await askOne(rl, output, step, answers);
+    }
+    return answers;
+  } catch (err) {
+    throw new WizardCancelled();
+  } finally {
+    process.removeListener('SIGINT', onSigint);
+    rl.close();
+  }
+}
+
+async function askOne(rl, output, step, answers) {
+  // Re-ask until the validator is happy; each failure prints the reason so the
+  // next attempt is informed rather than punished.
+  for (;;) {
+    const value = step.type === 'choice'
+      ? await askChoice(rl, output, step, answers)
+      : step.type === 'confirm'
+        ? await askConfirm(rl, step, answers)
+        : await askText(rl, step, answers);
+    const complaint = step.validate ? step.validate(value) : null;
+    if (!complaint) return value;
+    output.write(bad('    ' + complaint) + '\n');
+  }
+}
+
+async function askText(rl, step, answers) {
+  const fallback = defaultOf(step, answers);
+  if (step.hint) rl.output.write(dim('    ' + step.hint) + '\n');
+  const suffix = fallback ? dim(` (${fallback})`) : '';
+  const typed = await rl.question(`  ${bold(step.question)}${suffix}: `);
+  const value = typed.trim() || String(fallback ?? '');
+  return step.type === 'text' && /port/i.test(step.id) ? value : value;
+}
+
+async function askConfirm(rl, step, answers) {
+  const fallback = Boolean(defaultOf(step, answers));
+  const typed = await rl.question(`  ${bold(step.question)} ${dim(fallback ? '(Y/n)' : '(y/N)')} `);
+  const v = typed.trim().toLowerCase();
+  if (!v) return fallback;
+  return v === 'y' || v === 'yes';
+}
+
+async function askChoice(rl, output, step, answers) {
+  const fallback = defaultOf(step, answers);
+  const choices = step.choices.filter((c) => !c.when || c.when(answers));
+  output.write(`  ${bold(step.question)}\n`);
+  choices.forEach((c, i) => {
+    const marker = c.value === fallback ? cyan('›') : ' ';
+    const hint = c.hint ? dim('  ' + c.hint) : '';
+    output.write(`   ${marker} ${i + 1}. ${c.label}${hint}\n`);
+  });
+  if (step.hint) output.write(dim('    ' + step.hint) + '\n');
+  const typed = await rl.question(dim('  Choose [1-' + choices.length + '] ') + '');
+  const v = typed.trim();
+  if (!v) return fallback;
+  const byNumber = choices[Number(v) - 1];
+  if (byNumber) return byNumber.value;
+  const byValue = choices.find((c) => c.value === v.toLowerCase());
+  if (byValue) return byValue.value;
+  output.write(bad('    Pick a number from the list.') + '\n');
+  return askChoice(rl, output, step, answers);
+}