voroa-cli 0.0.0-stage → 0.2.0

package/src/mcp/lib/config.js

@@ -0,0 +1,72 @@
+// Config comes from ENV first, then this device's stored credential file. It is never hardcoded (no
+// default host lives in code) and never printed (golden rule #13).
+//   VOROA_MCP_URL   - the Voroa API base (e.g. https://api.getvoroa.com)
+//   VOROA_MCP_TOKEN - the scoped token minted in the Voroa dashboard (secret)
+//
+// PRECEDENCE: env -> stored credentials file (~/.voroa/customer-mcp/credentials.json) -> unconfigured.
+// ENV WINS, deliberately: this is a CLIENT credential, so a stale local file must never silently shadow
+// an explicitly-set env var. (Rule #11's "admin DB -> env -> default" governs SERVER settings and does
+// not transfer here.)
+//
+// The token is a SECRET: it is loaded here and handed only to the http helper's Authorization header. It
+// is never logged, never returned in a tool response, never put in an error message.
+
+import { readCredentials } from './credentials.js';
+
+export function loadConfig(env = process.env, { readStored = readCredentials } = {}) {
+  // strip trailing slashes so path-joins stay clean
+  const envUrl = String(env.VOROA_MCP_URL || '').replace(/\/+$/, '');
+  const envToken = String(env.VOROA_MCP_TOKEN || '');
+  if (envUrl && envToken) return { baseUrl: envUrl, token: envToken, source: 'env' };
+
+  const stored = readStored(env) || {};
+  return {
+    baseUrl: envUrl || stored.baseUrl || '',
+    token: envToken || stored.token || '',
+    source: envToken ? 'env' : stored.token ? 'file' : 'none',
+  };
+}
+
+// isSecureBaseUrl - https, or plain http ONLY to the loopback interface (local development against a
+// backend on this machine). Same discipline `scripts/lib/report-job.sh` applies server-side before a
+// destructive token goes on the wire, and for the identical reason: every request this client makes
+// carries a bearer in a header, so one mistyped `http://` scheme sends a live credential in cleartext
+// across whatever network is between the laptop and the API. A typo must fail loudly here rather than
+// succeed quietly on the wire.
+export function isSecureBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(String(value || ''));
+  } catch {
+    return false;
+  }
+  if (url.protocol === 'https:') return true;
+  if (url.protocol !== 'http:') return false;
+  const h = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1';
+}
+
+// Called at request time (not at boot) so `list_tools` works unconfigured for discovery, but any actual
+// API call fails with a clean, secret-free message that tells the human exactly what to do.
+export function assertConfigured(cfg) {
+  if (!cfg.baseUrl) {
+    const err = new Error('Not connected: set VOROA_MCP_URL to your Voroa API address.');
+    err.code = 'NOT_CONFIGURED';
+    throw err;
+  }
+  if (!isSecureBaseUrl(cfg.baseUrl)) {
+    const err = new Error(
+      'Refusing to connect: VOROA_MCP_URL must start with https:// (http:// is allowed only for localhost). '
+      + 'Your token travels on every request and must not be sent unencrypted.'
+    );
+    err.code = 'INSECURE_URL';
+    throw err;
+  }
+  if (!cfg.token) {
+    const err = new Error(
+      'Not connected: set VOROA_MCP_TOKEN to a token from your Voroa dashboard (Settings -> API tokens).'
+    );
+    err.code = 'NOT_CONFIGURED';
+    throw err;
+  }
+}

package/src/mcp/lib/credentials.js

@@ -0,0 +1,51 @@
+// The stored-credential file for this device: ~/.voroa/customer-mcp/credentials.json holding
+// { baseUrl, token }. Read by config.js as the fallback when env is unset.
+//
+// SECURITY (golden rule #13): this file holds the scoped bearer. Its VALUE is never logged, never echoed,
+// never returned in a tool response - it is read straight into the Authorization header by lib/http.js.
+//
+// FILE PERMISSIONS - be honest about what protects it:
+//   * POSIX (macOS/Linux): chmod 0600 is attempted best-effort and IS a real control (owner-only).
+//   * Windows: chmod is a NO-OP. NTFS has no POSIX permission bits, so 0600 means NOTHING there. What
+//     actually protects the file on Windows is that it sits under the user's own profile
+//     (%USERPROFILE%\.voroa\customer-mcp\), which the default ACL restricts to that account. Do not claim
+//     0600 as a control on Windows.
+
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { mkdir, writeFile, chmod } from 'node:fs/promises';
+
+// VOROA_CUSTOMER_MCP_HOME overrides the home dir (tests + odd profile paths). It is a PATH, never a secret.
+export function credentialsPath(env = process.env) {
+  const home = env.VOROA_CUSTOMER_MCP_HOME || homedir();
+  return join(home, '.voroa', 'customer-mcp', 'credentials.json');
+}
+
+// Sync + tolerant: any problem (absent file, bad JSON, wrong shape) reads as "no stored credential", never
+// throws - an unreadable file must degrade to "unconfigured", not break every tool call.
+export function readCredentials(env = process.env) {
+  try {
+    const parsed = JSON.parse(readFileSync(credentialsPath(env), 'utf8'));
+    const baseUrl = String(parsed.baseUrl || '').replace(/\/+$/, '');
+    const token = String(parsed.token || '');
+    if (!baseUrl || !token) return null;
+    return { baseUrl, token };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeCredentials({ baseUrl, token }, env = process.env) {
+  const path = credentialsPath(env);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify({ baseUrl, token }, null, 2) + '\n', { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try {
+      await chmod(path, 0o600);
+    } catch {
+      // non-fatal: the write succeeded, only the tighten failed
+    }
+  }
+  return path;
+}

package/src/mcp/lib/http.js

@@ -0,0 +1,136 @@
+// The ONE HTTP seam to the customer token API (`/api/ext/customer/*`, ADR-0060). This package holds NO DB
+// access and imports NO backend code - every read and every action goes over HTTP with the scoped bearer,
+// so tenant isolation, the capability allow-list and the reversibility gate all stay server-side where
+// they cannot be edited by whoever holds the laptop.
+//
+// SECURITY (golden rule #13): the Authorization header carries the secret token. It is attached here and
+// NOWHERE logged, echoed, or surfaced in an error. Log lines carry method + path only - no headers, no
+// token, no query VALUES (a service id in a query string is the customer's own, but the habit of logging
+// query values is how a token in a query string gets logged one refactor later).
+//
+// WHITE-LABEL (golden rule 6): cleanError() below surfaces the API's own error string, which is generated
+// by the backend's central error handler and is already generic by contract. It NEVER includes the URL,
+// the host, or the response body of a non-JSON error.
+
+import { assertConfigured } from './config.js';
+
+const API_PREFIX = '/api/ext/customer';
+
+// A hung backend must not hang the customer's AI client. Without a deadline a tool call waits on the
+// socket forever and the conversation simply stops with no explanation - the worst failure mode available,
+// because the human cannot tell it apart from the model thinking. 30s is comfortably above the slowest
+// call on this surface (a build-log read that assembles phases) and far below a human's patience.
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export function createHttpClient({ getConfig, logger, fetchImpl, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const doFetch = fetchImpl || globalThis.fetch;
+  if (typeof doFetch !== 'function') {
+    throw new Error('no fetch available (need Node >=20 or an injected fetchImpl)');
+  }
+
+  async function call(method, path, { query, body } = {}) {
+    const cfg = getConfig();
+    assertConfigured(cfg);
+
+    const url = new URL(cfg.baseUrl + API_PREFIX + path);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v));
+      }
+    }
+
+    logger.info({ method, path }, 'voroa_api_call'); // path only - never headers/token/query values
+
+    const headers = {
+      Authorization: `Bearer ${cfg.token}`,
+      Accept: 'application/json',
+    };
+    let payload;
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      payload = JSON.stringify(body);
+    }
+
+    // AbortController rather than Promise.race: the race leaves the socket open and the response body
+    // unread, so a slow backend would still accumulate connections behind the scenes.
+    const controller = new AbortController();
+    // Deliberately NOT unref'd: the timer lives only while a request is in flight (the finally below
+    // clears it on every settled request), and that is exactly when the process must stay alive to
+    // deliver the timeout error. An unref'd timer let the event loop drain before it fired - the abort
+    // then never happened, which surfaced on CI (Node 20) as a hung-promise cancellation and would
+    // surface in a one-shot caller as a silent exit instead of the promised clean timeout.
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let res;
+    try {
+      res = await doFetch(url, { method, headers, body: payload, signal: controller.signal });
+    } catch (err) {
+      // Timeout and network failure are DIFFERENT answers and are reported differently: "it did not
+      // respond in time" tells the caller to retry, "it is unreachable" tells them to check the address.
+      // Collapsing them is the bug #39 shape - two causes that look identical to whoever must act.
+      if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
+        const e = new Error(`Voroa did not respond within ${Math.round(timeoutMs / 1000)} seconds. Try again.`);
+        e.code = 'UPSTREAM_TIMEOUT';
+        throw e;
+      }
+      // network/DNS failure - a generic message, never the URL or the token
+      const e = new Error('Voroa is unreachable from this machine.');
+      e.code = 'UPSTREAM_UNREACHABLE';
+      throw e;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const text = await res.text();
+    let data = {};
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        // A non-JSON body is NOT surfaced. It could be a proxy error page carrying an infra hostname
+        // (golden rule 6) - so it is dropped entirely and only the status travels.
+        data = {};
+      }
+    }
+
+    if (!res.ok) {
+      const e = new Error(cleanError(res.status, data));
+      e.code = 'UPSTREAM_ERROR';
+      e.status = res.status;
+      throw e;
+    }
+    return data;
+  }
+
+  return {
+    get: (path, query) => call('GET', path, { query }),
+    post: (path, body) => call('POST', path, { body }),
+    // PUT and PATCH arrived with the Phase C configuration tools. Same `call` - the bearer, the timeout,
+    // the redaction and the error cleaning are all one path, so a new verb cannot acquire its own posture.
+    put: (path, body) => call('PUT', path, { body }),
+    patch: (path, body) => call('PATCH', path, { body }),
+  };
+}
+
+// Surface only a status + the API's own clean error string (the API returns generic JSON errors by
+// contract - golden rule #3). Never the token, never the full URL/host.
+//
+// 404 gets its own sentence deliberately: on this surface a 404 means EITHER the feature is not enabled
+// for this account OR the capability is not on the customer surface at all. The API cannot tell those
+// apart without becoming an oracle (ADR-0060 D7), so the client says both rather than guessing one.
+function cleanError(status, data) {
+  const detail =
+    (data && typeof data.error === 'string' && data.error) ||
+    (data && typeof data.message === 'string' && data.message) ||
+    '';
+  if (status === 401) {
+    return 'Voroa rejected this token. It may have been revoked, expired, or invalidated by a password change - mint a new one in your dashboard.';
+  }
+  if (status === 403) {
+    return 'This token does not have permission for that action. Mint a token with the required permission in your dashboard.';
+  }
+  if (status === 404 && !detail) {
+    return 'Not available: either this feature is not enabled for your account, or that action is not offered on the API-token surface.';
+  }
+  return detail ? `Voroa API error (status ${status}): ${detail}` : `Voroa API error (status ${status})`;
+}

package/src/mcp/lib/response.js

@@ -0,0 +1,14 @@
+// Shared MCP tool response shaping - one home (rule #10) so every tool returns the same JSON-text shape.
+
+export function jsonResponse(payload) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+// A clean input-validation error (the client sees the message; no token/host in it).
+export function badInput(message) {
+  const err = new Error(message);
+  err.code = 'BAD_INPUT';
+  return err;
+}

package/src/mcp/lib/reversibility.js

@@ -0,0 +1,33 @@
+// Reversibility gate (ADR-0060 D8, mirroring ADR-0013's LOCKED governing rule).
+//
+// The mapping is DATA, not a runtime judgement the model makes. An UNMAPPED tool defaults to IRREVERSIBLE
+// (fail-safe), so a future tool that deletes something can never quietly become auto-runnable by omission.
+//
+// SINGLE source of truth = ../reversibilityMap.json, which backend/tests/customerMcpCapabilities.test.js
+// pins against the backend's capability allow-list in BOTH directions. We DERIVE the set from that file
+// rather than re-declaring it here, so the map cannot drift between the two homes (rule #10). Read via fs
+// (not a JSON import assertion) to stay portable across Node versions.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAP = JSON.parse(readFileSync(resolve(HERE, '..', 'reversibilityMap.json'), 'utf8'));
+
+const REVERSIBLE_TOOLS = Object.freeze(
+  new Set((MAP.actions || []).filter((r) => r.reversible === true).map((r) => r.tool))
+);
+
+// True ONLY for an explicitly-mapped reversible tool. Anything else - an unknown name, a read tool, a
+// mapped-irreversible tool - returns false (fail-safe: irreversible by default).
+export function isReversible(toolName) {
+  return REVERSIBLE_TOOLS.has(toolName);
+}
+
+export function reversibleToolNames() {
+  return [...REVERSIBLE_TOOLS];
+}
+
+export function actionRows() {
+  return MAP.actions || [];
+}

package/src/mcp/reversibilityMap.json

@@ -0,0 +1,77 @@
+{
+  "note": "SINGLE source of truth for CUSTOMER MCP action reversibility (ADR-0060 D8, mirroring ADR-0013's governing rule). Each row binds a customer-mcp tool name to its backend capability and whether it may run without a confirmation step. reversible:true = the action is undoable or re-runnable: no resource is destroyed, no money moves, and a subsequent action restores the previous state. reversible:false = IRREVERSIBLE - it must never run unattended. An UNMAPPED tool defaults to IRREVERSIBLE (fail-safe) in lib/reversibility.js. READ tools carry NO row. EVERY row is still reversible, and that is still the point - including the two propose tools added in Phase D. Proposing is not the action: it writes a request that changes nothing and can be withdrawn, and the IRREVERSIBLE thing it asks for happens only when a person approves it in their dashboard, on a surface this token cannot reach. So an autopilot may call propose freely; what it cannot do is make anything happen. Parity is CI-asserted against the backend allow-list (backend/tests/customerMcpCapabilities.test.js): every services:act capability must appear here, and every row here must be a services:act capability.",
+  "actions": [
+    {
+      "tool": "redeploy",
+      "capability": "POST /apps/:uuid/redeploy",
+      "reversible": true,
+      "why": "Builds and ships the current branch again. The previous version stays available to rollback, and a failed build leaves whatever is serving in place."
+    },
+    {
+      "tool": "restart",
+      "capability": "POST /apps/:uuid/restart",
+      "reversible": true,
+      "why": "Restarts the running container. No code, configuration or data changes; the service comes back on its own."
+    },
+    {
+      "tool": "stop",
+      "capability": "POST /apps/:uuid/stop",
+      "reversible": true,
+      "why": "Stops the running container. The sharpest tool on this surface - the service is DOWN until someone starts it - but nothing is destroyed and start() restores service, so it is reversible rather than irreversible. The tool description says the service goes down."
+    },
+    {
+      "tool": "start",
+      "capability": "POST /apps/:uuid/start",
+      "reversible": true,
+      "why": "Starts a stopped container. stop() reverses it."
+    },
+    {
+      "tool": "cancel_deploy",
+      "capability": "POST /apps/:uuid/deploy/cancel",
+      "reversible": true,
+      "why": "Stops a build that has not finished: a queued job is dropped, a running build is killed. Nothing that is already serving is touched, and once the new version has gone live the cancel is refused outright rather than un-deploying it. Deploying again re-runs it. Note: a cancelled deploy still counts toward the plan's build minutes (time is rounded up to whole minutes), so a redeploy/cancel loop is not free."
+    },
+    {
+      "tool": "rollback",
+      "capability": "POST /apps/:uuid/rollback",
+      "reversible": true,
+      "why": "Serves the previous version again from the artifact already on the host. No build runs; the swap is readiness-gated, so a failed rollback leaves the current version serving. Deploying again moves forward. Note: a rollback attempt still counts toward the plan's build minutes (time is rounded up to whole minutes), even when there is no previous version to restore."
+    },
+    {
+      "tool": "set_maintenance_mode",
+      "capability": "PUT /apps/:uuid/maintenance",
+      "reversible": true,
+      "why": "Puts a maintenance page in front of the service, or takes it away again. Visitors stop reaching the service while it is on - the same honesty `stop` needs - but nothing is destroyed, no code or data changes, and turning it off restores service immediately."
+    },
+    {
+      "tool": "set_edge_protection",
+      "capability": "PATCH /apps/:uuid/edge-protection",
+      "reversible": true,
+      "why": "Changes whether the service's address is served through the edge network or directly. The service keeps running, nothing is destroyed and no code or data changes; setting it back restores the previous path within a few minutes."
+    },
+    {
+      "tool": "purge_edge_cache",
+      "capability": "POST /apps/:uuid/edge-cache/purge",
+      "reversible": true,
+      "why": "Empties the edge cache of a web service. Nothing on the service is touched; the cache refills from the service on the next request, so there is nothing to undo."
+    },
+    {
+      "tool": "scan_disk",
+      "capability": "POST /apps/:uuid/disk/scan",
+      "reversible": true,
+      "why": "Reads what is using the service's disk and reports the largest paths. A measurement: it changes nothing on the service."
+    },
+    {
+      "tool": "propose",
+      "capability": "POST /propose/:action",
+      "reversible": true,
+      "why": "Records a request and changes nothing at all. The service, database or setting it names is untouched until a person approves it in the Voroa dashboard, which this token cannot do. A proposal expires on its own, and discard_proposal withdraws it."
+    },
+    {
+      "tool": "discard_proposal",
+      "capability": "POST /propose/:nonce/discard",
+      "reversible": true,
+      "why": "Withdraws a request this same token made. The only possible outcome is that nothing happens; proposing again re-raises it."
+    }
+  ]
+}

package/src/mcp/tools/_action.js

@@ -0,0 +1,49 @@
+// The ONE factory every ACTION tool is built from (rule #10). Six near-identical tools written out by
+// hand would be six places the reversibility gate could be forgotten in exactly the way that matters.
+//
+// THE GATE. Before any request leaves this machine, the tool asserts `ctx.isReversible(name)` - which reads
+// ../reversibilityMap.json and returns false for anything not explicitly mapped reversible:true. So a tool
+// added later WITHOUT a map row cannot call the API at all; it fails locally with a message saying it needs
+// a confirmation path. That is the fail-safe direction ADR-0013 locked and ADR-0060 D8 inherits, expressed
+// as a runtime assertion rather than a comment.
+//
+// The gate is DEFENCE IN DEPTH, not the boundary. The real boundary is server-side: the backend capability
+// allow-list (lib/customerMcpCapabilities.js) simply has no irreversible entry, so even a tampered copy of
+// this package reaches nothing destructive. Both matter - this one gives an honest local refusal instead of
+// a confusing 404.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { serviceId } from './_ids.js';
+import { actionResult } from './_shape.js';
+
+export function makeServiceAction({ name, path, description, successMessage }) {
+  return {
+    name,
+    kind: 'action',
+    scope: 'services:act',
+    description,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        serviceId: { type: 'string', description: 'The service id, from list_services.' },
+      },
+      required: ['serviceId'],
+      additionalProperties: false,
+    },
+    async handler(args, ctx) {
+      // Fail-safe: unmapped -> irreversible -> refuse here, before any request.
+      if (typeof ctx.isReversible !== 'function' || !ctx.isReversible(name)) {
+        const err = new Error(
+          `${name} is not marked as a reversible action, so it will not run unattended. `
+          + 'An action that cannot be undone needs an explicit confirmation path that this client does not have.'
+        );
+        err.code = 'IRREVERSIBLE_BLOCKED';
+        throw err;
+      }
+      const id = serviceId(args.serviceId);
+      if (!id) throw badInput('serviceId is required and must be a valid service id from list_services.');
+      const data = await ctx.http.post(`/apps/${encodeURIComponent(id)}/${path}`);
+      return jsonResponse(actionResult(data, { message: successMessage }));
+    },
+  };
+}

package/src/mcp/tools/_ids.js

@@ -0,0 +1,42 @@
+// Identifier validation for tool arguments - one home (rule #10).
+//
+// These ids reach a URL PATH segment, so the charset gate here is a real control and not a nicety: it is
+// what stops an argument like `../../admin` or a value carrying `?`/`#`/`/` from being composed into a
+// different path than the tool intends. The backend's capability allow-list would 404 such a request
+// anyway (anchored, single-segment patterns), so this is defence in depth - but it turns a confusing 404
+// into a clear message the model can act on.
+//
+// Voroa ids are lower-case alphanumeric; a native deployment id is `<uuid>-<epoch>`. Hyphens are therefore
+// allowed, dots and slashes are not.
+//
+// UNDERSCORE IS ALLOWED, and it is not a loosening of the gate above - it is the gate finally admitting an
+// id the platform has always minted. A deploy that FAILED before it had a real deployment id is referred to
+// by `vfail_<26>` (`backend/src/lib/appId.js`, FAILED_REF_PREFIX), so `get_deploy_history` returned that id
+// and `get_build_log` refused the very same value as "not a deploy id from get_deploy_history". Measured
+// 2026-09-26 on a customer's own report: the one tool built to answer "why did my deploy fail" was broken
+// for exactly the deploys that failed, and only for those.
+//
+// The charset gate is unchanged in the way that matters: `/`, `.`, `?`, `#` and every other path-significant
+// character are still out, so nothing here can compose a different path than the tool intends. The first
+// character is still alphanumeric, so no id can lead with `_`.
+//
+// `backend/tests/customerMcpIdShapes.test.js` now checks the platform's minted shapes against this regex, so
+// the next prefix cannot break the same way unnoticed.
+const ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+
+export function serviceId(value) {
+  const s = String(value == null ? '' : value).trim();
+  return ID_RE.test(s) ? s : null;
+}
+
+export function deploymentId(value) {
+  const s = String(value == null ? '' : value).trim();
+  return ID_RE.test(s) ? s : null;
+}
+
+// A YYYY-MM billing period, or null. Absent is legal (the API defaults to the current period).
+export function period(value) {
+  if (value == null || value === '') return null;
+  const s = String(value).trim();
+  return /^\d{4}-\d{2}$/.test(s) ? s : null;
+}