voroa-cli 0.0.0-stage → 0.2.0

package/src/mcpTools.js

@@ -0,0 +1,265 @@
+// 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';
+
+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 === '--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();
+      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);
+};
+
+export function toolsList(kernel) {
+  return renderTable(['COMMAND', 'WHAT IT DOES'], kernel.listTools().map((t) => [commandName(t.name), firstSentence(t.description)]));
+}
+
+export function toolHelp(tool, { explicit = false } = {}) {
+  const props = (tool.inputSchema && tool.inputSchema.properties) || {};
+  const required = new Set((tool.inputSchema && tool.inputSchema.required) || []);
+  const lines = [`voroa ${explicit ? 'tool ' : ''}${commandName(tool.name)}`, '', String(tool.description || '').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(', ')}` : String(props[p].description || '').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') {
+    if (asJson || argv.includes('--json')) json(kernel.listTools().map((t) => ({ command: commandName(t.name), description: t.description, inputSchema: t.inputSchema })));
+    else out(toolsList(kernel));
+    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.`);
+
+  const parsed = parseToolArgv(tool, argv);
+  if (parsed.help) {
+    out(toolHelp(tool, { explicit }));
+    return 0;
+  }
+  if (!token) throw new CliError(NO_API_TOKEN);
+
+  // 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,56 @@
+// Terminal output helpers. Plain text, no colour: 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.
+
+// 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) => (r[i] || '').length), 0));
+  const line = (cells) => cells.map((c, i) => (i === cells.length - 1 ? c : c.padEnd(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`);
+}
+
+export function json(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}

package/src/prompt.js

@@ -0,0 +1,127 @@
+// 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';
+
+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
+
+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,
+    });
+    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(line);
+      else buffered.push(line);
+    });
+    rl.on('close', () => {
+      closed = true;
+      while (waiting.length) waiting.shift()(''); // EOF - unblock anything still asking
+    });
+  }
+  return rl;
+}
+
+// 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);
+      }
+    );
+  });
+}
+
+function question(text, { hide = false } = {}) {
+  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)';

package/src/resolve.js

@@ -0,0 +1,64 @@
+// "myapp" -> a service uuid.
+//
+// TENANCY (golden rule 2, bug #14): the candidate set is EXCLUSIVELY `GET /api/apps` called with
+// the active workspace header. That response is already scoped by the server to this caller AND
+// this workspace, so a name can only ever resolve to something they own here. The CLI keeps no
+// local name->uuid map: a cached id from another workspace would be a client-side claim about
+// ownership, and the server is the only thing entitled to make that claim.
+//
+// A uuid is accepted as-is only when it matches a row in that same response - so passing a uuid is
+// a shortcut past the name lookup, not past the ownership check.
+import { listApps } from './api.js';
+import { CliError } from './errors.js';
+import { findLink } from './link.js';
+import { err } from './output.js';
+
+// The ONE name-or-id matcher (services and databases both use it). Order: uuid, then exact name, then
+// case-insensitive name. Returns { match } | { ambiguous: rows } | {}.
+//
+// `idOnly` is for a needle that did NOT come from the person typing - a `.voroa.json` link. That file is
+// meant to be committed, so a cloned repo's link saying `"serviceId": "api"` must not fall through to
+// NAME matching and pick the reader's own service called "api".
+export function pickByNameOrId(rows, needle, { idOnly = false } = {}) {
+  const byUuid = rows.find((r) => r.uuid === needle);
+  if (byUuid) return { match: byUuid };
+  if (idOnly) return {};
+  const exact = rows.filter((r) => r.name === needle);
+  const matches = exact.length ? exact : rows.filter((r) => String(r.name).toLowerCase() === String(needle).toLowerCase());
+  if (matches.length === 1) return { match: matches[0] };
+  if (matches.length > 1) return { ambiguous: matches };
+  return {};
+}
+
+export function ambiguityList(rows) {
+  return rows.map((r) => `  ${r.name}  ${r.uuid}`).join('\n');
+}
+
+export async function resolveService(ctx, needle, { useLink = true } = {}) {
+  // No name given -> the folder's link, if any. The linked id is only a NEEDLE: it goes through the
+  // same scoped listing below as a typed one, so a link is a shortcut past typing, never past ownership.
+  let linked = null;
+  if (!needle && useLink) {
+    linked = findLink();
+    if (linked) {
+      needle = linked.serviceId;
+      // The link remembers its workspace; an explicit --workspace still wins.
+      if (linked.workspaceId && !ctx.workspaceExplicit) ctx.workspaceId = linked.workspaceId;
+      // Said on stderr, so a deploy never acts on a service the user did not see named.
+      err(`Using linked service ${linked.serviceName || linked.serviceId} (${linked.file})`);
+    }
+  }
+  if (!needle) throw new CliError('Which service? Pass a service name or id, or run `voroa link <service>` in this folder.');
+  const apps = await listApps(ctx);
+  if (apps.length === 0) {
+    throw new CliError('There are no services in this workspace. Check `voroa workspace list`.');
+  }
+
+  const found = pickByNameOrId(apps, needle, { idOnly: !!linked });
+  if (found.match) return found.match;
+  if (found.ambiguous) throw new CliError(`Multiple services match "${needle}", use the id:\n${ambiguityList(found.ambiguous)}`);
+  if (linked) {
+    throw new CliError(`This folder is linked to ${linked.serviceName || linked.serviceId}, which is not in this workspace. Run \`voroa link <service>\` again.`);
+  }
+  throw new CliError(`No service called "${needle}" in this workspace. Run \`voroa services\` to see them.`);
+}