voroa-cli 0.0.0-stage → 0.3.0

package/src/config.js

@@ -0,0 +1,108 @@
+// Where the CLI keeps its session: ~/.voroa/config.json { apiUrl, token, workspaceId }.
+//
+// Golden rule 13 - the token is a live credential. It is written to a file the owner alone can
+// read, and it never travels anywhere else: not to argv (visible in `ps` to every user on the box),
+// not to a log line, not into an error message. `readSettings` is the only reader; `api.js` puts it
+// straight into an Authorization header and nothing else ever holds it.
+//
+// PERMISSIONS: 0700 on the directory and 0600 on the file. On Linux and macOS that is enforced by
+// the kernel. On Windows it is not - `fs.chmod` there only flips the read-only attribute, so the
+// file inherits the user profile's ACL (which already excludes other standard users, but is not the
+// same guarantee). That difference is documented in the README rather than papered over.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export const DEFAULT_API_URL = 'https://api.getvoroa.com';
+
+// VOROA_CONFIG_DIR ek escape hatch hai (tests + "ye machine share hoti hai" wale cases). Absent =
+// normal ~/.voroa.
+export function configDir() {
+  return process.env.VOROA_CONFIG_DIR || path.join(os.homedir(), '.voroa');
+}
+
+export function configPath() {
+  return path.join(configDir(), 'config.json');
+}
+
+// Corrupt/absent file -> {} (never a throw). A CLI that cannot start because its own cache is
+// malformed is worse than one that asks you to sign in again.
+export function readConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// Write via a temp file + rename so an interrupted write cannot leave a half-written config behind.
+// The temp file is created 0600 from birth - never 0644-then-chmod, which is a window where the
+// token is world-readable.
+export function writeConfig(next) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = configPath();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  try {
+    fs.chmodSync(tmp, 0o600); // belt-and-suspenders: mode above is ignored if the file already existed
+  } catch {
+    /* Windows - documented, not fatal */
+  }
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+// Same endpoint or not, ignoring a trailing slash and letter case.
+function sameEndpoint(a, b) {
+  return String(a).replace(/\/+$/, '').toLowerCase() === String(b).replace(/\/+$/, '').toLowerCase();
+}
+
+// Merge the three sources, most specific first: an explicit flag, then the environment (CI), then
+// the stored config, then the built-in default.
+//
+// A STORED TOKEN IS BOUND TO THE ENDPOINT THAT ISSUED IT. If the caller points the CLI somewhere
+// else with --api-url or VOROA_API_URL, the stored token is withheld rather than sent there. That
+// flag is one word in a command someone can paste from anywhere, and sending a live session token
+// to whatever host it names would be a silent credential leak - the CLI would look like it was
+// working while handing the token to a stranger (golden rule 13).
+//
+// VOROA_TOKEN still wins outright: setting it is an explicit act by whoever runs the command, which
+// is exactly the CI case, and it is not read off disk.
+export function readSettings({ apiUrl, workspace } = {}) {
+  const cfg = readConfig();
+  const requested = apiUrl || process.env.VOROA_API_URL || null;
+  const resolved = requested || cfg.apiUrl || DEFAULT_API_URL;
+
+  // A token with NO recorded endpoint is treated as belonging to the DEFAULT one, not as belonging
+  // to whatever the caller asks for. The first version compared only when `cfg.apiUrl` existed, so a
+  // hand-written or pre-upgrade config holding just a token still went anywhere `--api-url` pointed -
+  // the exact hole the check was added to close, left open for the one config shape we did not write
+  // ourselves. Assuming the default is both safe (it is where an unlabelled token most likely came
+  // from) and sufficient (pointing elsewhere still withholds it).
+  const storedEndpoint = cfg.apiUrl || DEFAULT_API_URL;
+  const storedIsForThisEndpoint = sameEndpoint(storedEndpoint, resolved);
+  const envToken = process.env.VOROA_TOKEN || null;
+  const storedToken = storedIsForThisEndpoint ? cfg.token || null : null;
+
+  return {
+    apiUrl: resolved,
+    token: envToken || storedToken,
+    // The API token `voroa tokens create --save` stored for the tool commands (mcpTools.js). Bound to
+    // the endpoint that MINTED it (recorded beside it, because a session supplied through VOROA_TOKEN can
+    // mint against an endpoint the stored config has never heard of) - the same rule as the session token
+    // above, and for the same reason.
+    apiToken: cfg.apiToken && sameEndpoint(cfg.apiTokenUrl || storedEndpoint, resolved) ? cfg.apiToken : null,
+    workspaceId: workspace || cfg.workspaceId || null,
+    // Set only when a token WAS on disk and we deliberately did not send it - lets the caller
+    // explain the refusal instead of a bare "you are not signed in", which would be misleading.
+    tokenWithheldFrom: !envToken && cfg.token && !storedIsForThisEndpoint ? storedEndpoint : null,
+  };
+}
+
+// Save only the keys given, keeping whatever else is already stored (so `workspace set` does not
+// wipe the token and `login` does not wipe the chosen workspace).
+export function saveSettings(patch) {
+  return writeConfig({ ...readConfig(), ...patch });
+}

package/src/errors.js

@@ -0,0 +1,53 @@
+// A failure the user caused or can act on: a wrong name, a missing argument, an unusable flag.
+// Carries the exit code so `index.js` never has to guess one, and its message is written to be read
+// by a person - never a stack trace, never an internal detail.
+//
+// `code` is for a PROGRAM reading the failure - a script, or a customer's AI agent - so it never has
+// to parse the English. The list is short and fixed on purpose: a caller can switch on it, and
+// `voroa agent` prints exactly this table (test/agent.test.js keeps the two from drifting).
+export const ERROR_CODES = {
+  NOT_SIGNED_IN: 'No usable credential. A person must run voroa login, or set VOROA_TOKEN to an API token.',
+  FORBIDDEN: 'The credential is valid but may not do this (role, token scope, or a protected environment).',
+  NOT_FOUND: 'The service, database or other resource named does not exist in this workspace.',
+  AMBIGUOUS: 'More than one resource matches that name. Use the id.',
+  BAD_INPUT: 'A flag or argument is missing, unknown or malformed. Fix the command; do not retry it unchanged.',
+  NEEDS_HUMAN: 'This step asks a person a question (a sign-in code, a password, a confirmation). Stop and ask them.',
+  TIMEOUT: 'Voroa did not answer in time. Safe to retry once.',
+  UNREACHABLE: 'Voroa could not be reached from this machine (network, proxy or a wrong --api-url).',
+  FAILED: 'Anything else. The message says what happened.',
+};
+
+export class CliError extends Error {
+  constructor(message, exitCode = 1, code = null) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+    this.code = code;
+  }
+}
+
+const FROM_HTTP = { 0: 'UNREACHABLE', 401: 'NOT_SIGNED_IN', 403: 'FORBIDDEN', 404: 'NOT_FOUND', 408: 'TIMEOUT', 504: 'TIMEOUT' };
+// What the server, or the tool kernel (customer-mcp/src/lib/http.js), calls the same things.
+const FROM_OTHER = {
+  step_up_required: 'NEEDS_HUMAN',
+  UPSTREAM_TIMEOUT: 'TIMEOUT',
+  UPSTREAM_UNREACHABLE: 'UNREACHABLE',
+  NOT_CONFIGURED: 'NOT_SIGNED_IN',
+  INSECURE_URL: 'BAD_INPUT',
+  UNAUTHORIZED: 'NOT_SIGNED_IN',
+};
+
+// One answer for any thrown thing. Order matters: our own code wins, then a name the server or the
+// kernel used, then the HTTP status, then FAILED - never undefined, so a reader can always switch on it.
+export function errorCode(e) {
+  if (!e) return 'FAILED';
+  for (const c of [e.code, e.cause && e.cause.code]) {
+    if (typeof c !== 'string') continue;
+    if (Object.hasOwn(ERROR_CODES, c)) return c;
+    if (Object.hasOwn(FROM_OTHER, c)) return FROM_OTHER[c];
+  }
+  for (const s of [e.httpStatus, e.cause && e.cause.httpStatus]) {
+    if (Number.isInteger(s) && Object.hasOwn(FROM_HTTP, s)) return FROM_HTTP[s];
+  }
+  return 'FAILED';
+}

package/src/flags.js

@@ -0,0 +1,32 @@
+// Numeric flag values.
+//
+// `Number('abc')` is NaN and every comparison against NaN is false, so the obvious shape -
+// `Number(flags.timeout) > 0 ? Number(flags.timeout) : DEFAULT` - quietly discards a typo and uses
+// the default. The user asked for something specific, was given something else, and was not told:
+// `--timeout abc` waited ten minutes, and so did `--timeout 0` and `--timeout -5`.
+//
+// One home because the same shape was in two commands (--timeout and --lines) and would be in the
+// next one too (rule #10).
+import { CliError } from './errors.js';
+
+// A CLAMP and a REFUSAL are different things and this module does both on purpose:
+//   * out-of-range against a documented ceiling (--lines 5000, where the server's own maximum is
+//     1000) is clamped, because the ceiling is published and clamping is what it means.
+//   * unparseable or nonsensical (--lines abc, --timeout 0) is REFUSED, because there is no
+//     defensible value to substitute and guessing one is how the flag stopped meaning anything.
+export function numberFlag(name, raw, { fallback, min = 0, max = null, clampToMax = false, integer = false } = {}) {
+  if (raw === undefined || raw === true) return fallback; // flag absent, or given with no value
+  const n = Number(String(raw).trim());
+  if (!Number.isFinite(n)) throw new CliError(`${name} takes a number. Got "${raw}".`);
+  // A count of lines has no fractional meaning, and the consumer would quietly round it: `--lines 0.5`
+  // survived the checks above and then became 1 downstream. That is the same silent substitution this
+  // module exists to stop, just one layer further down. --timeout is deliberately NOT integer-only -
+  // half a minute is a real thing to ask for.
+  if (integer && !Number.isInteger(n)) throw new CliError(`${name} takes a whole number. Got "${raw}".`);
+  if (n <= min) throw new CliError(`${name} must be greater than ${min}. Got "${raw}".`);
+  if (max !== null && n > max) {
+    if (!clampToMax) throw new CliError(`${name} cannot be more than ${max}. Got "${raw}".`);
+    return max;
+  }
+  return n;
+}

package/src/index.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// voroa - the Voroa command line interface.
+//
+// Everything a command needs arrives as one `ctx` (endpoint, token, workspace) built here from
+// flags, environment and stored config in that order of precedence. A command never reads config or
+// the environment itself, so `--workspace` genuinely applies to exactly one invocation.
+//
+// One error path: a command either returns an exit code or throws. Nothing here prints a stack
+// trace to a user - a stack is for a log, and this output goes on a screen and into tickets
+// (golden rule 13: it is also the last place a token could accidentally surface, so the catch below
+// prints a message and never an error object).
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { readSettings } from './config.js';
+import { contextFrom } from './api.js';
+import { out, reportError } from './output.js';
+import { closePrompts, setNoInput } from './prompt.js';
+import { CliError } from './errors.js';
+import { login } from './commands/login.js';
+import { services } from './commands/services.js';
+import { status } from './commands/status.js';
+import { logs } from './commands/logs.js';
+import { deploy } from './commands/deploy.js';
+import { workspace } from './commands/workspace.js';
+import { link, unlink, open } from './commands/link.js';
+import { env, ENV_HELP } from './commands/env.js';
+import { restart, stop, start, rollback } from './commands/lifecycle.js';
+import { db } from './commands/db.js';
+import { tokens } from './commands/tokens.js';
+import { domains } from './commands/domains.js';
+import { ssh } from './commands/ssh.js';
+import { runTool } from './mcpTools.js';
+import { startSession, wantsSession } from './session.js';
+import { agent } from './agent.js';
+
+// Read from the manifest rather than repeated here. A hardcoded copy goes stale at the first
+// release nobody remembers to edit in two places, and `--version` reporting the wrong number is the
+// kind of small lie that costs an hour in a bug report. package.json ships in every npm tarball, so
+// this resolves after a global install too.
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+const USAGE = `voroa - deploy and inspect your Voroa services
+
+Usage
+  voroa login [--password] [--recovery] sign in (a 6-digit code by email, or a password)
+  voroa services                        the services in the active workspace
+  voroa status <service>                one service's live state
+  voroa status --all                    every service's state
+  voroa logs <service> [--lines N]      the running container's output
+  voroa logs <service> --search TEXT    only lines containing TEXT (last 24 hours)
+  voroa logs <service> --follow         keep tailing it
+  voroa logs <service> --build [id]     a build's log (the latest build with no id)
+  voroa deploy <service> [--wait]       trigger a deploy
+  voroa deploy <service> --follow       trigger a deploy, stream its build log, wait for the outcome
+  voroa restart|stop|start <service>    restart, stop or start the running service
+  voroa rollback <service> [--to <id>]  serve the previous version (or a chosen deploy) again
+  voroa env list|set|unset              environment variables - see voroa env --help
+  voroa link <service>                  bind this folder to a service; <service> is then optional here
+  voroa unlink                          remove that binding
+  voroa open [service] [--print]        the service's dashboard page (--print: only show the URL)
+  voroa db list                         databases in the active workspace
+  voroa db connect <database>           open psql (asks you to confirm it is you); --show-url prints it
+  voroa tokens list                     API tokens for CI and AI clients
+  voroa tokens create --name <n> --scope <a,b>   create one - the value is shown once
+  voroa tokens create ... --save        keep it on this machine for the voroa tools commands instead
+  voroa tokens revoke <id>              stop a token working immediately
+  voroa domains list [service]          custom domains and their state
+  voroa domains add <domain> [service]  add one and print the DNS record to create
+  voroa domains verify <domain> [--fix] check DNS and certificate (exit 2 until live)
+  voroa ssh [service] [--print]         a shell in the running service
+  voroa workspace list                  your workspaces
+  voroa workspace set <id>              choose the workspace commands act on
+  voroa tools [word]                    every other command (projects, cron, backups, buckets, ...)
+  voroa                                 with nothing after it: an interactive session (also: voroa session)
+  voroa agent                           how an AI agent should drive this CLI (--json for data)
+  voroa <command> --help                what one of those takes
+
+Flags
+  --workspace <id>    act on this workspace, for this command only
+  --api-url <url>     talk to a different Voroa API
+  --json              machine-readable output; a failure is then {"error","code"} on stderr
+  --no-input          never ask a question - fail with NEEDS_HUMAN instead (also VOROA_NO_INPUT=1)
+  --timeout <min>     with deploy --wait, how long to wait (default 10)
+  --lines <n>         with logs, how many lines to fetch (default 100, max 1000)
+  --search <text>     with logs, only lines containing this text (case-insensitive)
+  --help  --version
+
+Exit codes
+  0  succeeded (with deploy --wait: the service is live)
+  1  failed (including a deploy that failed or did not start)
+  2  deploy --wait ran out of time while the deploy was still going; domains verify: not live yet
+
+<service> is a service name or its id, resolved inside the active workspace only.
+
+CI
+  Set VOROA_TOKEN to an API token created in the dashboard (scoped, revocable, pinned to one
+  workspace). Sign-in, workspace switching and live build streaming need a login session instead.`;
+
+// Flags that consume the next argument.
+const VALUE_FLAGS = new Set(['--workspace', '--api-url', '--timeout', '--lines', '--search', '--to', '--name', '--scope']);
+// Flags whose value is optional: `--build` alone means "the latest build".
+const OPTIONAL_VALUE_FLAGS = new Set(['--build']);
+
+export function parseArgv(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token.startsWith('-')) {
+      positionals.push(token);
+      continue;
+    }
+    const [name, inline] = token.includes('=') ? [token.slice(0, token.indexOf('=')), token.slice(token.indexOf('=') + 1)] : [token, undefined];
+    const key = name.replace(/^--?/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (VALUE_FLAGS.has(name)) {
+      const value = inline !== undefined ? inline : argv[++i];
+      if (value === undefined) throw new CliError(`${name} needs a value.`);
+      flags[key] = value;
+    } else if (OPTIONAL_VALUE_FLAGS.has(name)) {
+      // Take the next token only if it is not itself a flag. A service name must therefore come
+      // before --build, which the usage text shows.
+      const next = inline !== undefined ? inline : argv[i + 1];
+      if (inline === undefined && next !== undefined && !next.startsWith('-')) i++;
+      flags[key] = inline !== undefined ? inline : next !== undefined && !next.startsWith('-') ? next : true;
+    } else {
+      flags[key] = inline !== undefined ? inline : true;
+    }
+  }
+  return { flags, positionals };
+}
+
+// Every flag an everyday command reads. A flag outside this list is REFUSED: `--line 5` for `--lines 5`
+// used to be ignored without a word, and the command then did something other than what was asked.
+// (The tool commands check their own flags against their own schema - mcpTools.js.)
+const KNOWN_FLAGS = new Set(['all', 'apiUrl', 'build', 'buildTime', 'fix', 'follow', 'h', 'help', 'json', 'lines', 'name', 'noInput', 'overwrite', 'password', 'print', 'recovery', 'save', 'scope', 'search', 'showUrl', 'timeout', 'to', 'v', 'version', 'wait', 'workspace']);
+const asFlag = (key) => `--${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+
+// Exported for test/mcpTools.test.js, which pins exactly which tool names these shadow.
+export const COMMANDS = { login, services, status, logs, deploy, workspace, link, unlink, open, env, restart, stop, start, rollback, db, tokens, domains, ssh };
+
+export async function run(argv) {
+  const { flags, positionals } = parseArgv(argv);
+
+  if (flags.version || flags.v) {
+    out(VERSION);
+    return 0;
+  }
+  // Asking for help SUCCEEDED at what was asked, with or without a command - `voroa --help` and
+  // `voroa services --help` must not disagree about that. Running the tool with nothing to do is the
+  // only usage error here.
+  setNoInput(flags.noInput || process.env.VOROA_NO_INPUT);
+  const name = positionals[0];
+  const command = COMMANDS[name];
+  if (name === 'agent') return agent({ flags, version: VERSION });
+  // No command at all, in a real terminal: the interactive session (session.js). On a pipe or in CI
+  // nothing changes - the usage text and exit 1 below. `voroa session` asks for it by name.
+  if (name === 'session' || (!name && !flags.help && !flags.h && wantsSession())) {
+    return startSession({ run, version: VERSION, commands: Object.keys(COMMANDS) });
+  }
+  // Anything that is not a hand-written command is looked up among the customer-MCP tools
+  // (mcpTools.js). Those parse their own flags from their own schema, --help included. `tool <name>`
+  // reaches one whose short name a hand-written command already owns (restart, stop, start, rollback).
+  if (name && (name === 'tools' || name === 'tool' || !command)) {
+    const explicit = name === 'tool';
+    const toolName = explicit ? positionals[1] : name;
+    if (!toolName) throw new CliError('Which one? `voroa tools` lists them.');
+    const rest = argv.slice(argv.indexOf(toolName, explicit ? argv.indexOf('tool') + 1 : 0) + 1);
+    return runTool(readSettings({ apiUrl: flags.apiUrl, workspace: flags.workspace }), toolName, rest, { asJson: !!flags.json, explicit });
+  }
+  if (flags.help || flags.h) {
+    out(positionals[0] === 'env' ? ENV_HELP : USAGE);
+    return 0;
+  }
+  if (!name) {
+    out(USAGE);
+    return 1;
+  }
+
+
+  const stray = Object.keys(flags).find((key) => !KNOWN_FLAGS.has(key));
+  if (stray) throw new CliError(`${name} has no ${asFlag(stray)} flag. Run \`voroa --help\`.`, 1, 'BAD_INPUT');
+
+  const settings = readSettings({ apiUrl: flags.apiUrl, workspace: flags.workspace });
+  const ctx = contextFrom(settings);
+  ctx.workspaceExplicit = !!flags.workspace;
+  return (await command(ctx, { positionals: positionals.slice(1), flags })) ?? 0;
+}
+
+// Only run when invoked as the binary, so tests can import `run`/`parseArgv`. pathToFileURL rather
+// than a hand-built `file://` string - on Windows the drive letter makes those two differ.
+const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  // `process.exitCode` and a natural end, NEVER `process.exit()`. Two reasons, both real:
+  //   * stdout on a pipe is asynchronous, so a hard exit can truncate the last lines of output -
+  //     which is precisely the case where output is being captured by a script.
+  //   * on Windows, Node 24 aborts with a libuv assertion (UV_HANDLE_CLOSING in async.c) when
+  //     process.exit() runs while fetch's pooled sockets are closing. The process then reports
+  //     0xC0000409 instead of our exit code - so `deploy --wait` would hand a pipeline a garbage
+  //     status after correctly working out the right one. Verified locally on Node v24.14.0.
+  // Undici's idle sockets are unref'd, so nothing here keeps the process alive after the work ends.
+  run(process.argv.slice(2))
+    .then((code) => {
+      process.exitCode = code ?? 0;
+    })
+    .catch((e) => {
+      reportError(e, { asJson: process.argv.includes('--json') });
+      process.exitCode = e && Number.isInteger(e.exitCode) ? e.exitCode : 1;
+    })
+    // An open readline interface holds the event loop open. Closed centrally so no command has to
+    // remember, and so an error path cannot leave the process hanging with the exit code decided.
+    .finally(closePrompts);
+}

package/src/interactive.js

@@ -0,0 +1,34 @@
+// Hand the terminal to another program (psql, ssh) and return its exit code.
+//
+// One home because two commands need exactly this and a copy drifts (rule 10). While the child runs,
+// Ctrl-C belongs to IT - cancelling a query, interrupting a remote command - so this process ignores
+// SIGINT instead of dying and orphaning the child. Released on `exit` (where the result settles) or
+// on `error`.
+//
+// No shell, ever: `args` are passed straight to the program, so nothing in them is interpreted.
+import { spawn } from 'node:child_process';
+import { CliError } from './errors.js';
+import { suspendPrompts, resumePrompts } from './prompt.js';
+
+export function runInteractive(cmd, args, { env, notFound } = {}) {
+  const ignoreSigint = () => {};
+  process.on('SIGINT', ignoreSigint);
+  // Inside a session readline holds the terminal; the child gets it for as long as it runs. Outside one
+  // both calls do nothing.
+  suspendPrompts();
+  return new Promise((resolve, reject) => {
+    // The CLI's own credential never reaches the child (ssh can forward variables with SendEnv).
+    const base = env || Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^VOROA_/i.test(k)));
+    const child = spawn(cmd, args, { stdio: 'inherit', env: base });
+    child.on('error', (e) => {
+      process.off('SIGINT', ignoreSigint);
+      resumePrompts();
+      reject(new CliError(e && e.code === 'ENOENT' ? notFound || `${cmd} was not found.` : `Could not start ${cmd}.`));
+    });
+    child.on('exit', (code) => {
+      process.off('SIGINT', ignoreSigint);
+      resumePrompts();
+      resolve(code ?? 1);
+    });
+  });
+}

package/src/link.js

@@ -0,0 +1,72 @@
+// `.voroa.json` - binds a folder to a service so `voroa deploy` / `logs` / `status` need no name.
+//
+// WHAT IT HOLDS: a service id, its name (for messages only) and the workspace id it was linked in.
+// All three are NON-SECRET identifiers - the file is meant to be safe to commit, and nothing that
+// authenticates anyone is ever written here (golden rule 13; the session lives in ~/.voroa, 0600).
+//
+// WHAT IT IS NOT: an ownership claim. The id is only a needle handed to `resolveService`, which
+// still matches it against the server's own scoped listing on every command (golden rule 2,
+// bug #14), and by uuid ONLY - never by name - so a `.voroa.json` copied from someone else's repo
+// resolves to "not in this workspace" even when you own a service whose name equals its id.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { CliError } from './errors.js';
+
+export const LINK_FILE = '.voroa.json';
+
+// Walk up from `from` like git does, so the link works from a subfolder of the project. Two stops:
+//   * the FIRST `.voroa.json` found decides. A broken one is an error, never skipped - skipping it
+//     would silently hand the decision to a parent folder's link and deploy a different service.
+//   * the home folder and the filesystem root are never read, so a stray `.voroa.json` there cannot
+//     choose for every project below it. Other shared parents (e.g. /tmp) ARE read - a project can
+//     legitimately live there; what makes a planted link harmless is that it matches by uuid only and
+//     the server still checks ownership.
+// Windows paths compare case-insensitively: `c:\users\x` and `C:\Users\x` are the same folder, and a
+// case-sensitive compare let the walk go straight past home.
+export function samePath(a, b, platform = process.platform) {
+  return platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+export function findLink(from = process.cwd()) {
+  const home = path.resolve(os.homedir());
+  let dir = path.resolve(from);
+  for (;;) {
+    const parent = path.dirname(dir);
+    if (samePath(dir, home) || parent === dir) return null;
+    const file = path.join(dir, LINK_FILE);
+    if (fs.existsSync(file)) {
+      let parsed = null;
+      try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      } catch {
+        /* reported below */
+      }
+      if (!parsed || typeof parsed.serviceId !== 'string' || !parsed.serviceId) {
+        throw new CliError(`${file} is not a valid link. Run \`voroa link <service>\` again, or delete it.`);
+      }
+      return {
+        file,
+        serviceId: parsed.serviceId,
+        serviceName: typeof parsed.serviceName === 'string' ? parsed.serviceName : null,
+        workspaceId: typeof parsed.workspaceId === 'string' && parsed.workspaceId ? parsed.workspaceId : null,
+      };
+    }
+    dir = parent;
+  }
+}
+
+export function writeLink({ serviceId, serviceName, workspaceId }, dir = process.cwd()) {
+  const file = path.join(dir, LINK_FILE);
+  fs.writeFileSync(file, `${JSON.stringify({ serviceId, serviceName, workspaceId: workspaceId || null }, null, 2)}\n`);
+  return file;
+}
+
+// Removes the link in THIS folder only. Walking up to delete a parent's file from a subfolder is
+// the kind of helpfulness that deletes something the user was not looking at.
+export function removeLink(dir = process.cwd()) {
+  const file = path.join(dir, LINK_FILE);
+  if (!fs.existsSync(file)) return null;
+  fs.rmSync(file);
+  return file;
+}

package/src/mcp/build.js

@@ -0,0 +1,72 @@
+// Builds the kernel with all tools + the shared HTTP client wired in. Kept separate from server.js so
+// tests can exercise the kernel without the MCP SDK (transport) and with an injected fetch/logger - no
+// network, no credentials.
+//
+// env / fetchImpl / logger are injectable for tests: pass a mock fetch to assert the bearer is attached
+// and never logged, with no real HTTP.
+
+import { createKernel } from './kernel/index.js';
+import { createLogger } from './kernel/logger.js';
+import { loadConfig } from './lib/config.js';
+import { createHttpClient } from './lib/http.js';
+import { isReversible } from './lib/reversibility.js';
+
+import { listServices } from './tools/listServices.js';
+import { getServiceStatus } from './tools/getServiceStatus.js';
+import { getDeployHistory } from './tools/getDeployHistory.js';
+import { getBuildLog } from './tools/getBuildLog.js';
+import { getRuntimeLogs } from './tools/getRuntimeLogs.js';
+import { listDomains } from './tools/listDomains.js';
+import { listDatabases } from './tools/listDatabases.js';
+import { getUsage } from './tools/getUsage.js';
+import { redeploy, restart, stop, start, rollback, cancelDeploy, purgeEdgeCache, scanDisk } from './tools/actions.js';
+import { READ_TOOLS } from './tools/reads.js';
+import { WRITE_TOOLS } from './tools/writes.js';
+import { PROPOSE_TOOLS } from './tools/propose.js';
+
+export function buildKernel({ env = process.env, fetchImpl, logger = createLogger('voroa-customer-mcp') } = {}) {
+  const kernel = createKernel({ logger });
+
+  // Read config fresh on each call so a rotated token is picked up without a restart.
+  const getConfig = () => loadConfig(env);
+  const http = createHttpClient({ getConfig, logger, fetchImpl });
+
+  kernel.setContext({ http, getConfig, env, logger, isReversible });
+
+  // READ tier (services:read)
+  kernel.registerTool(listServices);
+  kernel.registerTool(getServiceStatus);
+  kernel.registerTool(getDeployHistory);
+  kernel.registerTool(getBuildLog);
+  kernel.registerTool(getRuntimeLogs);
+  kernel.registerTool(listDomains);
+  kernel.registerTool(listDatabases);
+  kernel.registerTool(getUsage);
+
+  // Phase B read parity - grouped in tools/reads.js (see its header for why one file, and for the
+  // conservative projection rule every one of them follows).
+  for (const t of READ_TOOLS) kernel.registerTool(t);
+
+  // Phase C configuration tools (services:write), plus set_maintenance_mode which is services:act - see
+  // tools/writes.js for why the tier is "destroys no RESOURCE" rather than "reversible".
+  for (const t of WRITE_TOOLS) kernel.registerTool(t);
+
+  // Phase D (services:admin). Both are reversible:true because PROPOSING changes nothing - the
+  // irreversible thing they ask for happens only when a person approves it, on a surface this token
+  // cannot reach.
+  for (const t of PROPOSE_TOOLS) kernel.registerTool(t);
+
+  // ACTION tier (services:act) - every one REVERSIBLE (ADR-0060 D8). Nothing that deletes a resource,
+  // writes an environment variable, or touches billing exists on this surface at all.
+  kernel.registerTool(redeploy);
+  kernel.registerTool(restart);
+  kernel.registerTool(stop);
+  kernel.registerTool(start);
+  kernel.registerTool(rollback);
+  kernel.registerTool(cancelDeploy);
+  // Wave 2 (plan 2026-10-27): the edge cache refills, the disk scan reads.
+  kernel.registerTool(purgeEdgeCache);
+  kernel.registerTool(scanDisk);
+
+  return kernel;
+}

package/src/mcp/kernel/index.js

@@ -0,0 +1,59 @@
+// Kernel: a thin tool registry. Knows nothing about specific tools or the HTTP
+// transport. Adding a tool = new file in src/tools/ + one registry line in build.js.
+//
+// DELIBERATE DUPLICATE of admin-mcp/src/kernel/index.js (rule #10 requires the reason
+// be written down, so: these are two independently-installable npm packages with
+// deliberately SEPARATE blast radii - the same separation ADR-0013 chose when it
+// refused to add write tools to the read-only mcp/ package. A shared kernel would
+// mean a customer's laptop installs a package that also carries the staff ops
+// server's code, and a cross-package import between two `bin` entrypoints with no
+// build step is a packaging problem, not a centralisation win. The file is 50 lines
+// with no branching; if it ever grows logic worth sharing, extract it then.)
+
+export function createKernel({ logger }) {
+  const tools = new Map();
+  let ctx = { logger };
+
+  return {
+    logger,
+
+    // Shared context handed to every tool handler (http client, logger,
+    // isReversible). Set once in build.js.
+    setContext(extra) {
+      ctx = { ...ctx, ...extra };
+    },
+
+    registerTool(tool) {
+      if (tools.has(tool.name)) {
+        throw new Error(`tool already registered: ${tool.name}`);
+      }
+      tools.set(tool.name, tool);
+    },
+
+    listTools() {
+      return [...tools.values()].map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      }));
+    },
+
+    getTool(name) {
+      return tools.get(name) || null;
+    },
+
+    toolNames() {
+      return [...tools.keys()];
+    },
+
+    async callTool(name, args) {
+      const tool = tools.get(name);
+      if (!tool) {
+        const err = new Error(`unknown tool: ${name}`);
+        err.code = 'NOT_FOUND';
+        throw err;
+      }
+      return tool.handler(args ?? {}, ctx);
+    },
+  };
+}