voroa-cli 0.0.0-stage → 0.3.0

package/src/mcp/tools/listDomains.js

@@ -0,0 +1,33 @@
+// list_domains - READ (scope services:read). A service's addresses and their certificate state.
+// Maps to GET /apps/:uuid/domains.
+//
+// Registrar DNS instructions and the platform A-record address are deliberately NOT surfaced (see
+// _shape.js `domains`). Adding a domain is not on this surface either - it is a dashboard action.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+import { serviceId } from './_ids.js';
+import { domains } from './_shape.js';
+
+export const listDomains = {
+  name: 'list_domains',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'List a service\'s addresses: its default Voroa address plus any custom domains, with each domain\'s '
+    + 'routing state and certificate state. Read-only - adding or removing a domain is done in your Voroa '
+    + 'dashboard, not from here.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      serviceId: { type: 'string', description: 'The service id, from list_services.' },
+    },
+    required: ['serviceId'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    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.get(`/apps/${encodeURIComponent(id)}/domains`);
+    return jsonResponse(domains(data));
+  },
+};

package/src/mcp/tools/listServices.js

@@ -0,0 +1,20 @@
+// list_services - READ (scope services:read). Every service in the workspace this token is pinned to.
+// Maps to GET /apps.
+
+import { jsonResponse } from '../lib/response.js';
+import { service } from './_shape.js';
+
+export const listServices = {
+  name: 'list_services',
+  kind: 'read',
+  scope: 'services:read',
+  description:
+    'List the services in your Voroa workspace, with each service id, name, repository, branch, type and '
+    + 'default address. Start here - every other tool takes a service id from this list. Read-only.',
+  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+  async handler(_args, ctx) {
+    const data = await ctx.http.get('/apps');
+    const apps = Array.isArray(data && data.apps) ? data.apps : [];
+    return jsonResponse({ services: apps.map(service), count: apps.length });
+  },
+};

package/src/mcp/tools/propose.js

@@ -0,0 +1,124 @@
+// Phase D - the two tools of the propose tier (services:admin).
+//
+// There is ONE propose tool with an action name, not twenty. The actions are a closed set the server owns
+// (backend/src/lib/customerMcpProposals.js), and twenty near-identical tools would be twenty places for the
+// list to drift out of step with it. The enum below is what the model chooses from, and the server refuses
+// anything it does not recognise - so the worst a stale enum can do is offer something that 404s, never
+// something that acts.
+//
+// NEITHER TOOL CAN CHANGE ANYTHING, and that is the point of the tier rather than a limitation of it. A
+// propose call records a request and returns a summary; the service, database or setting it names is
+// untouched until a person approves it in the Voroa dashboard, on a surface this token cannot reach. Both
+// are therefore reversible:true in the reversibility map - an autopilot may call them freely, because
+// calling them makes nothing happen.
+
+import { jsonResponse, badInput } from '../lib/response.js';
+// Projected through _shape.js like every other tool - tests/staticScan refuses a tool module that shapes
+// its output inline, because an inline projection is invisible to the value-level scan.
+import { pick } from './_shape.js';
+
+// Kept in step with the server registry by the capability freeze and route-parity guards: an action here
+// that the server does not know 404s, and a server action nobody can name is unreachable. Grouped in the
+// description so the model can pick the right one without reading twenty schemas.
+const ACTIONS = [
+  'create_service', 'create_static_site', 'create_worker', 'create_cron_job', 'create_database',
+  'delete_service', 'delete_database', 'delete_domain', 'delete_env_var', 'delete_secret_file',
+  'delete_scheduled_task', 'delete_env_group', 'delete_environment', 'delete_database_user',
+  'rotate_database_credentials', 'import_database',
+  'enable_database_external_access', 'set_database_allowlist', 'add_inbound_rule', 'remove_inbound_rule',
+  'unprotect_environment',
+  // Wave 2 (plan 2026-10-27) - billable, destructive, credential-granting or irreversible settings that
+  // shipped after Phase D. A credential (deploy hook URL, bucket key) is shown ONCE in the dashboard when the
+  // person approves; this tool never sees it.
+  'delete_project',
+  'create_bucket', 'delete_bucket', 'delete_bucket_files', 'regenerate_bucket_key',
+  'set_pitr', 'pitr_restore', 'start_pitr_restore', 'restore_database_backup', 'link_database_to_service',
+  'cancel_database_import', 'disable_database_backups', 'set_database_config', 'enable_database_extension',
+  'set_hsts', 'set_edge_cache_static', 'enable_edge_cache_all', 'set_edge_cache_off',
+  'set_autoscale', 'remove_autoscale', 'create_deploy_hook', 'delete_deploy_hook',
+  'delete_preview', 'delete_preview_variable', 'delete_domain_claim',
+  'delete_env_group_variable', 'unlink_env_group',
+  // Access REMOVAL only (CTO decision 2026-10-27). Inviting someone, raising a role and adding an SSH key
+  // are not on this surface at all.
+  'remove_member', 'change_member_role', 'delete_ssh_key',
+];
+
+export const propose = {
+  name: 'propose',
+  kind: 'action',
+  scope: 'services:admin',
+  reversible: true,
+  description:
+    'ASK for a change that cannot be undone - creating a service or database, deleting something, rotating '
+    + 'a database password, importing over live data, or opening a database to the internet. This tool '
+    + 'CANNOT carry any of them out. It records the request and returns a summary; the change happens only '
+    + 'if a person approves it in their Voroa dashboard, which you cannot do. Tell the customer plainly '
+    + 'that you have asked and that it is waiting for them. Arguments go in `args`: the ids the action '
+    + 'needs (serviceId, databaseId, projectId, groupId, bucketId, backupId, jobId, previewId, claimId, '
+    + 'key, name...) plus its own fields, such as sourceUrl for import_database, targetAt for pitr_restore, '
+    + 'enabled for set_pitr / set_hsts, extension, evictionPolicy, keys for delete_bucket_files, '
+    + 'name and plan for create_bucket, minInstances / maxInstances / cpuTargetPct / memTargetPct for '
+    + 'set_autoscale, appUuid and envKey for link_database_to_service, customerId (+ a LOWER role) for remove_member / change_member_role, keyId for delete_ssh_key. Anything whose result is a one-time '
+    + 'credential (a deploy hook URL, a bucket key) is shown to the person in the dashboard, never to you. '
+    + 'Use discard_proposal to take back a request you made in error.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ACTIONS, description: 'What to ask for.' },
+      args: {
+        type: 'object',
+        description:
+          'The ids and fields this action needs. Ids come from the list tools - list_services, '
+          + 'list_databases, list_projects, list_env_groups, list_domains, list_scheduled_tasks.',
+      },
+    },
+    required: ['action', 'args'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const action = String(args.action || '').trim();
+    if (!ACTIONS.includes(action)) {
+      throw badInput(`action must be one of: ${ACTIONS.join(', ')}`);
+    }
+    if (!args.args || typeof args.args !== 'object' || Array.isArray(args.args)) {
+      throw badInput('args must be an object of the ids and fields this action needs.');
+    }
+    const data = await ctx.http.post(`/propose/${encodeURIComponent(action)}`, args.args);
+    const shaped = pick(data || {}, ['summary', 'expiresAt', 'nonce', 'whatHappensNext']);
+    return jsonResponse({
+      asked: true,
+      performed: false,
+      summary: shaped.summary,
+      expiresAt: shaped.expiresAt,
+      proposalId: shaped.nonce,
+      whatHappensNext: shaped.whatHappensNext,
+    });
+  },
+};
+
+export const discardProposal = {
+  name: 'discard_proposal',
+  kind: 'action',
+  scope: 'services:admin',
+  reversible: true,
+  description:
+    'Withdraw a request you raised with propose, so it stops waiting in the customer\'s dashboard. Only '
+    + 'works on a request this same token made. The only possible outcome is that nothing happens; propose '
+    + 'again if it was withdrawn by mistake.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      proposalId: { type: 'string', description: 'The proposalId returned by propose.' },
+    },
+    required: ['proposalId'],
+    additionalProperties: false,
+  },
+  async handler(args, ctx) {
+    const id = String(args.proposalId || '').trim();
+    if (!id) throw badInput('proposalId is required - it is returned by propose.');
+    await ctx.http.post(`/propose/${encodeURIComponent(id)}/discard`, {});
+    return jsonResponse({ withdrawn: true });
+  },
+};
+
+export const PROPOSE_TOOLS = [propose, discardProposal];