voroa-cli 0.0.0-stage → 0.3.0

package/src/mcpTools.js

@@ -0,0 +1,292 @@
+// Every customer-MCP tool as a CLI command (plan docs/plans/2026-11-11-cli-mcp-parity.md).
+//
+// The CLI does NOT re-implement the tools. It runs the MCP's own tool kernel (customer-mcp/src/build.js),
+// so the argument checks, the response projection and the white-label shaping have ONE home (rule #10,
+// golden rule 6), and a tool added to the MCP is a CLI command on the next release with no code here.
+// That kernel imports only `node:` builtins - the MCP SDK lives in its server.js, which is never loaded -
+// so the zero-dependency decision in the README header still holds.
+//
+// TWO PLACES THE KERNEL CAN SIT. The published tarball carries a copy at src/mcp/ (scripts/pack-mcp.mjs,
+// run by `prepack`); a repo checkout has the original next door. The packaged copy is tried FIRST on
+// purpose: after `npm install -g`, the repo-relative path would resolve to a sibling package called
+// `customer-mcp` in the same node_modules, and loading code from a name we do not own is not a fallback.
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { CliError } from './errors.js';
+import { contextFrom, isApiToken } from './api.js';
+import { resolveService } from './resolve.js';
+import { out, json, renderTable } from './output.js';
+import { ownsStdin } from './prompt.js';
+
+const KERNEL_HOMES = [new URL('./mcp/', import.meta.url), new URL('../../customer-mcp/src/', import.meta.url)];
+
+// The kernel logs one line per HTTP call to stderr - right for a long-lived MCP server, noise on a
+// terminal. Errors are not lost: they are thrown, and index.js prints the message.
+const SILENT = { info() {}, warn() {}, error() {} };
+
+export const NO_API_TOKEN =
+  'This command needs an API token. Run `voroa tokens create --name cli --scope services:read,services:act,services:write,services:admin --save`, or set VOROA_TOKEN to one from the dashboard.';
+
+// A CliError that keeps what caused it (golden rule 14). The MESSAGE is what a person reads and is written
+// here, never taken from the cause: a JSON parse error quotes its input back, and that input can be a
+// secret value on its way to being set.
+const because = (message, cause) => Object.assign(new CliError(message), { cause });
+
+export async function loadKernel({ apiUrl = '', token = '', fetchImpl } = {}) {
+  for (const home of KERNEL_HOMES) {
+    const file = new URL('build.js', home);
+    if (!existsSync(fileURLToPath(file))) continue;
+    const { buildKernel } = await import(file.href);
+    // Both values are always passed, so the kernel's own config never falls back to a credentials file
+    // on disk - a stored token is bound to the endpoint that issued it (config.js) and must not follow
+    // `--api-url` somewhere else.
+    return buildKernel({ env: { VOROA_MCP_URL: apiUrl, VOROA_MCP_TOKEN: token }, fetchImpl, logger: SILENT });
+  }
+  throw new CliError('This install of voroa-cli is incomplete. Reinstall it with `npm install -g voroa-cli`.');
+}
+
+export const commandName = (toolName) => toolName.replace(/_/g, '-');
+const flagName = (prop) => `--${prop.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+const squash = (s) => String(s).replace(/^--?/, '').replace(/[-_]/g, '').toLowerCase();
+
+export function findTool(kernel, name) {
+  const wanted = String(name || '').replace(/-/g, '_');
+  return kernel.listTools().find((t) => t.name === wanted) || null;
+}
+
+function typeOf(schema) {
+  if (Array.isArray(schema.type)) return schema.type.find((t) => t !== 'null') || 'string';
+  return schema.type || 'string';
+}
+
+function coerce(flag, raw, schema) {
+  const type = typeOf(schema);
+  if (type === 'boolean') {
+    if (raw === true || raw === 'true') return true;
+    if (raw === 'false') return false;
+    throw new CliError(`${flag} is true or false. Got "${raw}".`);
+  }
+  if (raw === true) throw new CliError(`${flag} needs a value.`);
+  if (type === 'integer' || type === 'number') {
+    const n = Number(String(raw).trim());
+    if (!Number.isFinite(n) || (type === 'integer' && !Number.isInteger(n))) {
+      throw new CliError(`${flag} takes a ${type === 'integer' ? 'whole number' : 'number'}. Got "${raw}".`);
+    }
+    return n;
+  }
+  if (type === 'object' || type === 'array') {
+    try {
+      return JSON.parse(raw);
+    } catch (e) {
+      throw because(`${flag} takes JSON (${type === 'array' ? 'a list' : 'an object'}).`, e);
+    }
+  }
+  return String(raw);
+}
+
+function readJsonObject(text, what) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (e) {
+    throw because(`${what} is not valid JSON.`, e);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new CliError(`${what} must be a JSON object.`);
+  return parsed;
+}
+
+// argv AFTER the tool name -> { args, help, asJson }. Flags are matched against the tool's own
+// schema, so `--service-id`, `--serviceId` and `--service_id` are the same flag and an unknown one is
+// refused by name rather than silently dropped. Bare words fill the REQUIRED arguments in schema order:
+// `voroa get-database <id>`.
+export function parseToolArgv(tool, argv) {
+  const props = (tool.inputSchema && tool.inputSchema.properties) || {};
+  const bySquashed = new Map(Object.keys(props).map((p) => [squash(p), p]));
+  const result = { args: {}, help: false, asJson: false };
+  const bare = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      bare.push(token);
+      continue;
+    }
+    const eq = token.indexOf('=');
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    const inline = eq === -1 ? undefined : token.slice(eq + 1);
+    const takeValue = () => {
+      if (inline !== undefined) return inline;
+      if (i + 1 >= argv.length) throw new CliError(`${flag} needs a value.`);
+      return argv[++i];
+    };
+
+    // A tool's own argument wins over a CLI-wide flag of the same name (`propose` has an `args`).
+    const prop = bySquashed.get(squash(flag));
+    if (prop) {
+      const isBool = typeOf(props[prop]) === 'boolean';
+      const next = argv[i + 1];
+      // `--enabled` alone is true; `--enabled false` and `--enabled=false` are both false.
+      const raw = !isBool ? takeValue() : inline !== undefined ? inline : next === 'true' || next === 'false' ? argv[++i] : true;
+      result.args[prop] = coerce(flag, raw, props[prop]);
+    } else if (flag === '--help') result.help = true;
+    else if (flag === '--json') result.asJson = true;
+    // Already applied by index.js when it built the settings; consumed here so they are not "unknown".
+    else if (flag === '--api-url' || flag === '--workspace') takeValue();
+    else if (flag === '--no-input') result.noInput = true;
+    else if (flag === '--args') result.args = { ...readJsonObject(takeValue(), '--args'), ...result.args };
+    else if (flag === '--args-file') {
+      // `-` is stdin. A value on the command line lands in shell history and in `ps`; a secret (an
+      // environment variable's value, a secret file's contents) should arrive by pipe or by file.
+      const file = takeValue();
+      if (file === '-' && ownsStdin()) throw new CliError('Inside a session, standard input belongs to the session. Give --args-file a real file.');
+      let text;
+      try {
+        text = readFileSync(file === '-' ? 0 : file, 'utf8');
+      } catch (e) {
+        throw because(file === '-' ? 'Nothing arrived on standard input.' : `Cannot read ${file}.`, e);
+      }
+      result.args = { ...readJsonObject(text, file), ...result.args };
+    } else {
+      throw new CliError(`${commandName(tool.name)} has no ${flag} argument. Run \`voroa ${commandName(tool.name)} --help\`.`);
+    }
+  }
+
+  const open = ((tool.inputSchema && tool.inputSchema.required) || []).filter((p) => !(p in result.args));
+  if (bare.length > open.length) throw new CliError(`Unexpected "${bare[open.length]}". Run \`voroa ${commandName(tool.name)} --help\`.`);
+  bare.forEach((value, n) => {
+    result.args[open[n]] = coerce(flagName(open[n]), value, props[open[n]]);
+  });
+  return result;
+}
+
+const firstSentence = (text) => {
+  const s = String(text || '').replace(/\s+/g, ' ').trim();
+  const end = s.search(/\.(\s|$)/);
+  return end === -1 ? s : s.slice(0, end + 1);
+};
+
+// Tool descriptions were written for the connector, where a tool is `list_buckets`. Here it is
+// `list-buckets`, and a description that names a command the reader cannot type is a small lie.
+function forCli(text, names) {
+  let said = String(text || '');
+  // Longest first, so `list_bucket_files` is not half-replaced by `list_bucket`.
+  for (const name of [...names].sort((a, b) => b.length - a.length)) {
+    if (name.includes('_')) said = said.split(name).join(commandName(name));
+  }
+  return said;
+}
+
+// What `voroa tools` lists: optionally only those whose name or description contains every word given.
+// `changes` is the tool's own declared kind - a read never changes anything.
+export function listForCli(kernel, words = []) {
+  const wanted = words.map((w) => w.toLowerCase());
+  return kernel
+    .listTools()
+    .map((t) => ({ command: commandName(t.name), changes: kernel.getTool(t.name).kind !== 'read', description: forCli(t.description, kernel.toolNames()), inputSchema: t.inputSchema }))
+    .filter((t) => wanted.every((w) => t.command.includes(w) || t.description.toLowerCase().includes(w)));
+}
+
+export function toolsList(kernel, words = []) {
+  const rows = listForCli(kernel, words);
+  if (!rows.length) return `No command matches "${words.join(' ')}". Run \`voroa tools\` for the full list.`;
+  return renderTable(['COMMAND', 'CHANGES', 'WHAT IT DOES'], rows.map((t) => [t.command, t.changes ? 'yes' : 'no', firstSentence(t.description)]));
+}
+
+export function toolHelp(tool, { explicit = false, toolNames = [] } = {}) {
+  const props = (tool.inputSchema && tool.inputSchema.properties) || {};
+  const required = new Set((tool.inputSchema && tool.inputSchema.required) || []);
+  const lines = [`voroa ${explicit ? 'tool ' : ''}${commandName(tool.name)}`, '', forCli(tool.description, toolNames).replace(/\s+/g, ' ').trim()];
+  const names = Object.keys(props);
+  if (names.length) {
+    lines.push('', 'Arguments');
+    lines.push(
+      renderTable(
+        ['FLAG', 'TYPE', 'REQUIRED', 'MEANING'],
+        names.map((p) => [
+          flagName(p),
+          props[p].enum ? 'one of' : typeOf(props[p]),
+          required.has(p) ? 'yes' : 'no',
+          props[p].enum ? `${props[p].enum.join(', ')}` : forCli(props[p].description, toolNames).replace(/\s+/g, ' ').trim(),
+        ])
+      )
+    );
+  }
+  lines.push('', 'Also: --args \'<json>\' or --args-file <path> (- for standard input) to pass every argument as one JSON object; --json for raw output.');
+  return lines.join('\n');
+}
+
+// A list of flat records reads better as a table; anything else is printed as the JSON it is. The
+// payload is whatever the tool projected - nothing is added or widened here.
+function printResult(payload, asJson) {
+  if (asJson) return json(payload);
+  const lists = Array.isArray(payload)
+    ? [payload]
+    : payload && typeof payload === 'object'
+      ? Object.values(payload).filter((v) => Array.isArray(v))
+      : [];
+  const rows = lists.length === 1 ? lists[0] : null;
+  const flat = (v) => v === null || ['string', 'number', 'boolean'].includes(typeof v);
+  if (rows && rows.length && rows.every((r) => r && typeof r === 'object' && !Array.isArray(r))) {
+    const cols = Object.keys(rows[0]).filter((k) => rows.every((r) => flat(r[k] ?? null)));
+    const scalars = Array.isArray(payload) ? [] : Object.entries(payload).filter(([, v]) => flat(v));
+    const nested = Array.isArray(payload) ? 0 : Object.keys(payload).length - scalars.length - 1;
+    if (cols.length && cols.length === Object.keys(rows[0]).length && nested === 0) {
+      out(renderTable(cols.map((c) => c.toUpperCase()), rows.map((r) => cols.map((c) => r[c]))));
+      for (const [k, v] of scalars) out(`${k}: ${v}`);
+      return undefined;
+    }
+  }
+  return json(payload);
+}
+
+// `voroa tools`, `voroa tool <name> ...` and the shorthand `voroa <tool-name> ...`.
+export async function runTool(settings, name, argv, { fetchImpl, asJson = false, explicit = false } = {}) {
+  const token = isApiToken(settings.token) ? settings.token : settings.apiToken || '';
+  // Listing and help need no credential: both come from the tool definitions. Only a call does.
+  const kernel = await loadKernel({ apiUrl: settings.apiUrl, token, fetchImpl });
+  if (name === 'tools') {
+    const words = argv.filter((a) => !a.startsWith('--'));
+    if (asJson || argv.includes('--json')) json(listForCli(kernel, words));
+    else out(toolsList(kernel, words));
+    return 0;
+  }
+  const tool = findTool(kernel, name);
+  if (!tool) throw new CliError(`Unknown command "${name}". Run \`voroa --help\`, or \`voroa tools\` for the full list.`, 1, 'BAD_INPUT');
+
+  const parsed = parseToolArgv(tool, argv);
+  if (parsed.help) {
+    out(toolHelp(tool, { explicit, toolNames: kernel.toolNames() }));
+    return 0;
+  }
+  if (!token) throw new CliError(NO_API_TOKEN, 1, 'NOT_SIGNED_IN');
+
+  // A service can be named, or left out in a linked folder - the same resolver the hand-written commands
+  // use, so the answer still comes from the server's own workspace-scoped list (resolve.js).
+  const props = tool.inputSchema.properties || {};
+  if ('serviceId' in props && tool.name !== 'list_services') {
+    const required = (tool.inputSchema.required || []).includes('serviceId');
+    if (parsed.args.serviceId || required) {
+      const ctx = contextFrom({ ...settings, token });
+      parsed.args.serviceId = (await resolveService(ctx, parsed.args.serviceId)).uuid;
+    }
+  }
+
+  let result;
+  try {
+    result = await kernel.callTool(tool.name, parsed.args);
+  } catch (e) {
+    // The kernel's messages are generic and secret-free by contract (customer-mcp/src/lib/http.js).
+    throw because(e && e.message ? e.message : 'That did not work. Try again.', e);
+  }
+  const text = result && result.content && result.content[0] && result.content[0].text;
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch (e) {
+    // Every tool answers in JSON (customer-mcp/src/lib/response.js). Anything else is a kernel this
+    // build does not understand - say so rather than print something half-read.
+    throw because('Voroa answered in a form this version cannot read. Update with `npm install -g voroa-cli`.', e);
+  }
+  printResult(payload, parsed.asJson || asJson);
+  return result && result.isError ? 1 : 0;
+}

package/src/output.js

@@ -0,0 +1,145 @@
+// Terminal output helpers. Plain text: a CLI's output gets piped, redirected and pasted into tickets,
+// and ANSI codes survive all three as garbage. The state is carried by the WORD ("Crash looping"),
+// never by a colour a pipe would strip anyway.
+//
+// The ONE exception is everything gated by `fancy()` below: colour, a status mark, a spinner. All of
+// it is decoration ON TOP of the words and switches itself off unless the stream is a real terminal,
+// NO_COLOR is unset and TERM is not "dumb" - so everything above still holds for every pipe, file and
+// CI log, and an AI agent reading the output never sees an escape code.
+import { errorCode } from './errors.js';
+
+export function fancy(stream = process.stdout) {
+  return !!(stream && stream.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+}
+
+const OFF_COLOUR = '\x1b[39m';
+const STYLES = {
+  bold: ['\x1b[1m', '\x1b[22m'],
+  dim: ['\x1b[2m', '\x1b[22m'],
+  green: ['\x1b[32m', OFF_COLOUR],
+  amber: ['\x1b[33m', OFF_COLOUR],
+  red: ['\x1b[31m', OFF_COLOUR],
+  gray: ['\x1b[90m', OFF_COLOUR],
+  cyan: ['\x1b[36m', OFF_COLOUR],
+  violet: ['\x1b[38;5;141m', OFF_COLOUR], // the brand accent, from the 256-colour table every VT terminal has
+};
+
+export function style(kind, text, stream = process.stdout) {
+  const codes = STYLES[kind];
+  if (!codes || !fancy(stream)) return text;
+  return `${codes[0]}${text}${codes[1]}`;
+}
+
+// Marks. The old Windows console host draws several of these as boxes, so it gets ASCII; Windows
+// Terminal and editor terminals announce themselves and get the real ones.
+const UNICODE = { run: '\u25cf', idle: '\u25cb', busy: '\u25d0', fail: '\u25cf', ok: '\u2714', bad: '\u2716', prompt: '\u203a', bar: '\u258c', arrow: '\u2192', logo: '\u25b2', dot: '\u00b7', spin: ['\u280b', '\u2819', '\u2839', '\u2838', '\u283c', '\u2834', '\u2826', '\u2827', '\u2807', '\u280f'] };
+const ASCII = { run: '*', idle: 'o', busy: '~', fail: 'x', ok: 'ok', bad: 'x', prompt: '>', bar: '|', arrow: '->', logo: '^', dot: '-', spin: ['-', '\\', '|', '/'] };
+
+export function glyphs(env = process.env, platform = process.platform) {
+  return platform !== 'win32' || env.WT_SESSION || env.TERM_PROGRAM ? UNICODE : ASCII;
+}
+
+const TONE = { green: ['green', 'run'], gray: ['gray', 'idle'], amber: ['amber', 'busy'], red: ['red', 'fail'] };
+
+// A status for a table cell. The WORD is always there; on a terminal it gains a mark and a colour.
+// Takes what `classify` returned - this file never looks at a raw status itself.
+export function statusCell(state, stream = process.stdout) {
+  if (!fancy(stream) || !TONE[state.tone]) return state.label;
+  const [colour, mark] = TONE[state.tone];
+  return style(colour, `${glyphs()[mark]} ${state.label}`, stream);
+}
+
+export function elapsed(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+
+// "Still working" for a wait with nothing to print. Off a terminal it is ONE plain line, exactly what
+// the command printed before spinners existed, so a log file gets a sentence and not 400 frames.
+export function spinner(text, { stream = process.stdout, intervalMs = 90 } = {}) {
+  if (!fancy(stream)) {
+    stream.write(`${text}\n`);
+    return { stop() {} };
+  }
+  const frames = glyphs().spin;
+  const started = Date.now();
+  let i = 0;
+  const draw = () => stream.write(`\r\x1b[2K  ${style('cyan', frames[i++ % frames.length], stream)} ${text} ${style('dim', elapsed(Date.now() - started), stream)}`);
+  draw();
+  const timer = setInterval(draw, intervalMs);
+  return {
+    stop() {
+      clearInterval(timer);
+      stream.write('\r\x1b[2K');
+    },
+  };
+}
+
+// Escape codes take no room on screen, so a column is measured by what is SEEN.
+const ANSI = /\x1b\[[0-9;]*m/g;
+export function visibleLength(text) {
+  return String(text).replace(ANSI, '').length;
+}
+const padTo = (text, width) => text + ' '.repeat(Math.max(0, width - visibleLength(text)));
+
+// Column-aligned table. Values are stringified defensively - a null cell renders as the em dash, so
+// an empty column never reads as an empty VALUE.
+export const EMPTY_CELL = '-';
+
+function cell(value) {
+  if (value === null || value === undefined || value === '') return EMPTY_CELL;
+  return String(value);
+}
+
+export function renderTable(headers, rows) {
+  const body = rows.map((r) => r.map(cell));
+  const widths = headers.map((h, i) => Math.max(String(h).length, ...body.map((r) => visibleLength(r[i] || '')), 0));
+  const line = (cells) => cells.map((c, i) => (i === cells.length - 1 ? c : padTo(c, widths[i]))).join('  ').trimEnd();
+  return [line(headers.map(String)), ...body.map(line)].join('\n');
+}
+
+// Key/value block for a single record.
+export function renderFields(pairs) {
+  const width = Math.max(...pairs.map(([k]) => k.length), 0);
+  return pairs.map(([k, v]) => `${k.padEnd(width)}  ${cell(v)}`).join('\n');
+}
+
+// Relative time from epoch SECONDS (what the API sends). Absolute dates are avoided because the
+// server speaks UTC and the reader thinks in their own zone; "3 hours ago" is unambiguous in both.
+export function timeAgo(epochSeconds) {
+  const secs = Number(epochSeconds);
+  if (!Number.isFinite(secs) || secs <= 0) return null;
+  const diff = Math.floor(Date.now() / 1000) - secs;
+  if (diff < 0) return 'just now'; // clock skew - never render a negative age
+  if (diff < 60) return 'just now';
+  const mins = Math.floor(diff / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days}d ago`;
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months}mo ago`;
+  return `${Math.floor(months / 12)}y ago`;
+}
+
+export function out(text = '') {
+  process.stdout.write(`${text}\n`);
+}
+
+export function err(text = '') {
+  process.stderr.write(`${text}\n`);
+}
+
+// A failure, for whoever is reading. With --json it is one JSON object on stderr - the same message a
+// person gets, plus a code from the fixed list in errors.js. Never the error object itself: that is the
+// last place a token could surface (golden rule 13).
+export function reportError(e, { asJson = false } = {}) {
+  const message = e && e.message ? e.message : 'Something went wrong.';
+  if (asJson) process.stderr.write(`${JSON.stringify({ error: message, code: errorCode(e) })}\n`);
+  else err(message);
+}
+
+export function json(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}

package/src/prompt.js

@@ -0,0 +1,229 @@
+// Interactive prompts on node:readline (no dependency - see the README header).
+//
+// ONE readline interface for the whole process, deliberately. A fresh interface per question looks
+// tidier and is wrong: readline reads stdin in CHUNKS and buffers what it has not handed out yet,
+// so closing it after the first answer throws away everything else that had already arrived. Piped
+// input ("email\ncode\n") arrives as a single chunk, which means the second prompt would wait
+// forever for a line that was read and discarded a moment earlier.
+//
+// Two things here are security-relevant, not cosmetic:
+//   * `askHidden` never echoes. A password typed into a shared terminal, a screen share or a
+//     recorded session is a leaked password (golden rule 13's spirit: a credential must not become
+//     visible anywhere).
+//   * every prompt can carry a timeout. A CLI blocked forever on stdin inside CI is a hung job with
+//     no explanation; timing out with a sentence beats hanging with none.
+import readline from 'node:readline';
+import { CliError } from './errors.js';
+
+class PromptTimeout extends Error {
+  constructor() {
+    super('prompt timed out');
+    this.name = 'PromptTimeout';
+    this.timedOut = true;
+  }
+}
+
+let rl = null;
+let closed = false;
+const waiting = []; // resolvers for prompts that have been asked but not yet answered
+const buffered = []; // lines that arrived before anything asked for them
+
+// THE INTERACTIVE SESSION (session.js) rides on this same interface - it must, for the reason above -
+// and needs three things a one-shot command does not. They are set here, once, so that an interface
+// RE-created later (a prompt timeout closes it) still has them:
+//   completer  Tab completion.
+//   onSigint   In terminal mode readline SWALLOWS Ctrl+C: the process never receives SIGINT, so the
+//              stop handlers `logs --follow` and `deploy --follow` register on `process` would never
+//              fire and a tail could not be stopped. The session decides where the keypress goes.
+//   history    Kept in this module, so it survives a re-created interface.
+let session = null;
+let history = [];
+
+export function configureSession(options) {
+  session = options || null;
+  if (!session) history = [];
+}
+
+// True while a session owns standard input - `--args-file -` cannot read it then (mcpTools.js).
+export function ownsStdin() {
+  return !!session;
+}
+
+// Readline records EVERY line it reads, and Up arrow replays them. The answer to a prompt is not a
+// command: it can be a password, a one-time code, or an environment variable's value (golden rule 13).
+// Only a line the session asked for as a command stays.
+function forget(line) {
+  if (rl && Array.isArray(rl.history) && rl.history[0] === line) rl.history.shift();
+}
+
+function iface() {
+  if (!rl) {
+    rl = readline.createInterface({
+      input: process.stdin,
+      // stderr, not stdout: a prompt is for the person, and stdout is for what a script captures
+      // (`--json`, `db connect --show-url`). A prompt mixed into it corrupts exactly that output.
+      output: process.stderr,
+      terminal: !!process.stdin.isTTY,
+      ...(session ? { completer: (line) => session.completer(line), history, historySize: 200 } : {}),
+    });
+    closed = false;
+    // We consume 'line' rather than rl.question(), and we QUEUE what nobody has asked for yet. On a
+    // pipe, readline emits a 'line' for every line the moment the chunk arrives - so a line that
+    // shows up while the CLI is mid-request (between "email" and "code" there is a network call)
+    // would otherwise be emitted to nobody and lost, and the next prompt would wait forever for
+    // input that had already been read.
+    rl.on('line', (line) => {
+      const next = waiting.shift();
+      if (!next || !next.isCommand) forget(line);
+      if (next) next(line);
+      else buffered.push(line);
+    });
+    rl.on('close', () => {
+      closed = true;
+      if (rl && Array.isArray(rl.history)) history = rl.history;
+      while (waiting.length) waiting.shift()(''); // EOF - unblock anything still asking
+    });
+    // Registered ONLY for a session: with no listener readline keeps its default for one-shot commands.
+    if (session) rl.on('SIGINT', () => session.onSigint());
+  }
+  return rl;
+}
+
+// Standard input has ended (Ctrl+D, or the end of a pipe) and every line that arrived has been used.
+export function promptsEnded() {
+  return closed && buffered.length === 0;
+}
+
+// What was typed while a command was running is thrown away, not run: a stray `y` typed during a log
+// tail must not become the next command. Terminal only - on a pipe every line "arrives early", and
+// dropping there would discard the script.
+export function dropTypeAhead() {
+  if (process.stdin.isTTY) buffered.length = 0;
+}
+
+// Hand the terminal to another program (psql, ssh) and take it back. Readline holds the terminal in raw
+// mode and reads every key; a child that inherits it would fight for each keystroke.
+export function suspendPrompts() {
+  if (!rl) return;
+  rl.pause();
+  if (process.stdin.isTTY && typeof process.stdin.setRawMode === 'function') process.stdin.setRawMode(false);
+}
+
+export function resumePrompts() {
+  if (!rl) return;
+  if (process.stdin.isTTY && typeof process.stdin.setRawMode === 'function') process.stdin.setRawMode(true);
+  rl.resume();
+}
+
+// The session's own prompt. Unlike `ask`, the text is given to readline AS its prompt, so recalling a
+// line with Up arrow redraws it instead of erasing it - and the line it returns is kept in history.
+export function askCommand(text) {
+  const r = iface();
+  if (buffered.length) return Promise.resolve(String(buffered.shift()));
+  if (closed) return Promise.resolve('');
+  r.setPrompt(text);
+  r.prompt();
+  return new Promise((resolve) => {
+    const take = (line) => {
+      r.setPrompt('');
+      resolve(String(line || ''));
+    };
+    take.isCommand = true;
+    waiting.push(take);
+  });
+}
+
+// Draw the session prompt again after something was printed over it.
+export function reprompt() {
+  if (rl) rl.prompt();
+}
+
+// Clear whatever is typed on the current line (Ctrl+C at a prompt, the way a shell does it).
+export function clearTypedLine() {
+  if (!rl || !rl.line) return false;
+  rl.write(null, { ctrl: true, name: 'u' });
+  return true;
+}
+
+// An open readline interface holds the event loop open, so the process would never exit. Every
+// command path closes prompts when it finishes (index.js does it centrally).
+export function closePrompts() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+function withTimeout(promise, timeoutMs) {
+  if (!timeoutMs) return promise;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      closePrompts();
+      reject(new PromptTimeout());
+    }, timeoutMs);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+
+// NO PERSON IS HERE (--no-input, VOROA_NO_INPUT). An agent or a pipeline that reaches a question would
+// otherwise sit on it until something upstream gives up, with nothing to tell it why. It gets a code
+// it can act on instead. The session's own prompt is not a question and is not affected.
+let noInput = false;
+export function setNoInput(value) {
+  noInput = !!value;
+}
+
+function question(text, { hide = false } = {}) {
+  if (noInput) {
+    const asked = String(text).replace(/[:\s]+$/, '');
+    throw new CliError(`This step needs a person - it asks for "${asked}". Run it yourself in a terminal, or set VOROA_TOKEN to an API token.`, 1, 'NEEDS_HUMAN');
+  }
+  const r = iface();
+  process.stderr.write(text);
+
+  // Already have the line (it arrived while we were busy) - answer immediately.
+  if (buffered.length) return Promise.resolve(String(buffered.shift()));
+  if (closed) return Promise.resolve(''); // stdin ended - the caller validates the empty answer
+
+  const hiding = hide && !!process.stdin.isTTY;
+  const original = r._writeToOutput;
+  if (hiding) {
+    // Suppress the echo readline would write for each keystroke. There is nothing to suppress on a
+    // pipe, which is why this is TTY-only.
+    r._writeToOutput = function writeToOutput() {};
+  }
+  return new Promise((resolve) => {
+    waiting.push((line) => {
+      if (hiding) {
+        r._writeToOutput = original;
+        r.output.write('\n'); // the newline Enter would have echoed
+      }
+      resolve(String(line || ''));
+    });
+  });
+}
+
+export function ask(text, { timeoutMs } = {}) {
+  return withTimeout(
+    question(text).then((v) => v.trim()),
+    timeoutMs
+  );
+}
+
+// Hidden input. `terminal: true` is what gives readline control of the echo; overriding
+// `_writeToOutput` suppresses it. On a non-TTY stdin (a pipe, a CI step) there is no echo to
+// suppress, so the line is simply read.
+export function askHidden(text, { timeoutMs } = {}) {
+  return withTimeout(question(text, { hide: true }), timeoutMs);
+}
+
+export { PromptTimeout };

package/src/region.js

@@ -0,0 +1,5 @@
+// White-label region label - CLI ka ek ghar (rule #10, golden rule 6). Customer ko HAMESHA
+// "Mumbai (IN)" dikhta hai, kabhi raw infra region (ap-south-1). Peers: frontend/src/lib/region.js
+// aur backend/src/lib/region.js. Teeno ko backend/tests/centralizationGuard.test.js pin karta hai -
+// yahan se import karo, kahin aur ye string mat likho.
+export const REGION_LABEL = 'Mumbai (IN)';