@chrischall/mcp-host-cli 0.0.0-stage → 2.33.1

package/src/operations.mjs

@@ -0,0 +1,650 @@
+// Every operation in the control API's contract (packages/core/openapi/
+// openapi.json), and how this CLI reaches it.
+//
+// This table IS the parity claim, and `tests/api-parity.test.ts` holds it to
+// the contract in both directions: every operation the document declares is
+// either a row here or an EXCLUDED entry with its reason, nothing is listed
+// that the document does not declare, and every row is DRIVEN — the test runs
+// the CLI with the row's example against a listener and requires the request
+// to arrive. So a new route in `core/src/openapi.ts` fails this package's
+// suite until somebody decides how the CLI reaches it, which is the step that
+// was missing while the portal grew three screens of API the CLI never
+// learned (the CLI was written in #1, beside six routes; the portal is where
+// every later route was built, and nothing asked the CLI to follow).
+//
+// Two kinds of row. A GENERIC row is data — words, positionals, query flags,
+// body flags — and `runGeneric` in index.mjs executes it with no code of its
+// own: positionals named in the path fill the path, the rest become body
+// fields, `--<kebab-name>` flags become query parameters or typed body fields,
+// and any row with a body also takes `--data <json | @file | ->` for the
+// fields no flag names. The test additionally holds a generic row's query
+// flags EQUAL to the operation's query parameters, and its body flags to
+// properties the body schema declares — so a parameter added to the API is a
+// failure here, not a silently unreachable option. A BESPOKE row names a
+// command that `main()` in index.mjs implements by hand, because it does
+// something a request cannot (seals a secret, uploads a file, prompts, renders
+// a table); its example is still driven.
+
+/** Flags every paged list endpoint takes (core/src/list-query.ts). */
+const LIST = ['sort', 'order', 'q', 'page', 'perPage'];
+/** The same, under a prefix, for an endpoint carrying two lists. */
+const prefixed = (prefix) => LIST.map((name) => `${prefix}${name[0].toUpperCase()}${name.slice(1)}`);
+
+/**
+ * Operations the CLI deliberately does not reach, each with the reason. A
+ * reason is a statement about WHO makes the call, never "not done yet": an
+ * operation nobody has decided about belongs in OPERATIONS, and the test's
+ * job is to make that decision unavoidable.
+ */
+export const EXCLUDED = {
+  'GET /admin/session': 'the portal\'s cookie session; the CLI authenticates with a bearer on every request',
+  'POST /admin/session': 'the portal\'s cookie sign-in; the CLI authenticates with a bearer on every request',
+  'DELETE /admin/session': 'the portal\'s cookie sign-out; a bearer has no session to end',
+  'GET /m/marketplace.json': 'the feed Claude Code reads with the marketplace token; `marketplace rotate` prints the command that subscribes it',
+  'GET /m/{token}/marketplace.json': 'the deprecated token-in-path form of the same feed, read by Claude Code',
+  'POST /bridge/connect/start': 'the browser extension starting a Connect with its own keys (D18); the CLI holds no extension identity, and since D18 no CLI, operator or ADMIN_TOKEN mints a bridge credential',
+  'POST /bridge/connect/approve': 'the connect page\'s Confirm, in the account owner\'s own signed-in session with CSRF; a CLI bearer (ADMIN_TOKEN) has nobody behind it and is refused by design',
+  'POST /bridge/connect/finish': 'the browser extension finishing a Connect, signed by the key that started it (D18); the credential goes to that extension alone',
+  'GET /bridge/connect/status': 'the connect page polling its own request, in the approving owner\'s session; the CLI holds no session',
+  'POST /api/v1/bridge-tokens/{id}/serve': 'choosing which of the owner\'s browsers serves the account, for the account owner\'s own session only (the portal and the app, spec 2026-10-05 §5.7); a CLI bearer (ADMIN_TOKEN) gets the cross-account 404 by design',
+  'GET /api/v1/bridge-tokens/presence': 'whether the owner\'s browser is attached right now, for the account owner\'s own session only (portal or app, spec §4.13); a CLI bearer (ADMIN_TOKEN) gets the cross-account 404 by design',
+  'PUT /api/v1/bridge-tokens/pins': 'the account owner\'s managed-pins switch, in their own signed-in session (Settings in the portal or the app); a CLI bearer (ADMIN_TOKEN) has nobody behind it and is refused by design',
+  'PUT /api/v1/bridge-tokens/account-pairing': 'the account owner\'s account-pairing switch, in their own signed-in session (Settings in the portal or the app); a CLI bearer (ADMIN_TOKEN) has nobody behind it and is refused by design',
+  'POST /api/v1/me/push-devices': 'a phone enrols its own APNs/FCM token, which only the device holds',
+  'DELETE /api/v1/me': 'a person deleting their OWN account, in their own signed-in session with CSRF and their typed address (the portal\'s Account screen, or the app); a CLI bearer (ADMIN_TOKEN) has nobody behind it and is refused by design — an operator erases someone with `users erase`',
+};
+
+/**
+ * @typedef {'string' | 'integer' | 'number' | 'boolean' | 'json'} FieldType
+ * @typedef {{
+ *   op: string,
+ *   words: string[],
+ *   args?: string[],
+ *   query?: string[],
+ *   body?: Record<string, FieldType>,
+ *   summary: string,
+ *   bespoke?: false,
+ * }} GenericRow
+ * @typedef {{ op: string, usage: string, summary: string, example: string[], bespoke: true, words?: string[], query?: string[], booleanQuery?: string[] }} BespokeRow
+ *
+ * A bespoke row DECLARES the query parameters its command sends (`query`,
+ * and `booleanQuery` for a bare flag sent as `=1`), and the test holds that
+ * list equal to the contract and drives the command with every one set — the
+ * same guarantee a generic row gets, without making the command generic.
+ *
+ * A bespoke row names `words` only where it shares a prefix with a generic
+ * row (`connections login` beside `connections`), so the matcher can tell
+ * that the longer, hand-written command is the one meant.
+ */
+
+/** @type {Array<GenericRow | BespokeRow>} */
+export const OPERATIONS = [
+  // ── registrations ────────────────────────────────────────────────────────
+  {
+    op: 'POST /api/v1/registrations',
+    bespoke: true,
+    usage: 'register --slug <slug> (--npm | --github | --pypi | --mcpb) <spec> [flags] [--data <json>]   (no flags on a terminal: the wizard)',
+    summary: 'register an MCP',
+    example: ['register', '--slug', 'x', '--npm', 'thing-mcp'],
+  },
+  { op: 'GET /api/v1/registrations', words: ['list'], query: ['account', ...LIST], summary: 'list registrations' },
+  { op: 'GET /api/v1/registrations/{id}', words: ['get'], args: ['id'], summary: 'one registration' },
+  {
+    op: 'PUT /api/v1/registrations/{id}',
+    bespoke: true,
+    usage:
+      'set <id> [--data-dir|--no-data-dir] [--state-store volume|snapshot] [--follow|--no-follow] [--bridge-approval account|prompt] [--dep …|--no-deps] ' +
+      '[--deny destructive|non-read-only|--allow-all] [--ask <tool,…>|--no-ask] [--tools <tool,…>|--all-tools] [--aggregate inline|search|exclude] [--data <json>]',
+    summary: 'edit a registration in place (partial patch)',
+    example: ['set', 'x', '--follow'],
+  },
+  { op: 'DELETE /api/v1/registrations/{id}', words: ['rm'], args: ['id'], summary: 'delete a registration' },
+  { op: 'GET /api/v1/registrations/{id}/status', words: ['status'], args: ['id'], summary: 'registration plus live instance status' },
+  {
+    op: 'GET /api/v1/registrations/{id}/logs',
+    bespoke: true,
+    usage: 'logs <id> [--lines N]',
+    query: ['lines'],
+    summary: 'tail the child\'s stderr (a bare array of lines)',
+    example: ['logs', 'reg_1', '--lines', '5'],
+  },
+  { op: 'POST /api/v1/registrations/{id}/prewarm', words: ['prewarm'], args: ['id'], summary: 'install and start the instance' },
+  { op: 'POST /api/v1/registrations/{id}/restart', words: ['restart'], args: ['id'], summary: 'stop, then re-ensure the instance' },
+  {
+    op: 'POST /api/v1/registrations/{id}/build',
+    bespoke: true,
+    usage: 'build <id> [--force] [--wait]',
+    booleanQuery: ['force', 'wait'],
+    summary: 'ask the builder for a prebuilt install tree',
+    example: ['build', 'x'],
+  },
+  { op: 'GET /api/v1/registrations/{id}/tools', words: ['tools'], args: ['id'], query: LIST, summary: 'one registration\'s tool menu' },
+  { op: 'GET /api/v1/tools', words: ['tools'], query: ['account', ...LIST], summary: 'every registration\'s tool menu (no id)' },
+  {
+    op: 'POST /api/v1/registrations/{id}/call',
+    words: ['call'],
+    args: ['id', 'tool'],
+    body: { args: 'json' },
+    summary: 'invoke one tool (--args \'{"k":"v"}\')',
+  },
+  { op: 'GET /api/v1/registrations/{id}/env', words: ['env'], args: ['id'], query: LIST, summary: 'the env a registration hands its child (names and references)' },
+  { op: 'GET /api/v1/registrations/{id}/auth-fields', words: ['auth-fields'], args: ['id'], summary: 'propose a login form from the pinned source\'s metadata' },
+  // A READ: records what the package asks for and opens or clears the alert,
+  // and applies nothing — acting on an ask is still `set` or a PUT
+  // (docs/MINT-MANIFEST.md §9).
+  { op: 'POST /api/v1/registrations/{id}/manifest-check', words: ['manifest-check'], args: ['id'], summary: 'read this registration\'s mint.yaml now' },
+  { op: 'POST /api/v1/registrations/{id}/manifest-ack', words: ['manifest-ack'], args: ['id'], summary: 'record that the package\'s asks have been read' },
+  // Accepting a `losing state` warning for the files it names — no flag
+  // flips and nothing restarts; `--names '[".cache"]'` names what is accepted,
+  // and without it the open finding's names are (core `state-loss-ack.ts`).
+  {
+    op: 'POST /api/v1/registrations/{id}/state-loss-ack',
+    words: ['state-loss-ack'],
+    args: ['id'],
+    body: { names: 'json' },
+    summary: 'accept losing the files a losing-state warning names (--names \'[".cache"]\')',
+  },
+  { op: 'DELETE /api/v1/registrations/{id}/state-loss-ack', words: ['state-loss-unack'], args: ['id'], summary: 'undo a losing-state acknowledgement' },
+  { op: 'DELETE /api/v1/registrations/{id}/state', words: ['reset', 'state'], args: ['id'], summary: 'throw away the sealed $HOME snapshot' },
+  { op: 'DELETE /api/v1/registrations/{id}/lockfile', words: ['reset', 'lockfile'], args: ['id'], summary: 'retire the canonical dependency tree for this pin' },
+  { op: 'DELETE /api/v1/registrations/{id}/bridge-identity', words: ['reset', 'bridge-identity'], args: ['id'], summary: 'throw away the fetchproxy identity (re-pairs the browser)' },
+  {
+    op: 'GET /api/v1/registrations/{id}/bridge-scope',
+    words: ['bridge-scope'],
+    args: ['id'],
+    query: ['account'],
+    summary: 'the proposed and approved browser-bridge scope, and who approved it',
+  },
+  {
+    op: 'POST /api/v1/registrations/{id}/bridge-scope/approve',
+    words: ['bridge-scope', 'approve'],
+    args: ['id'],
+    query: ['account'],
+    body: { digest: 'string', basis: 'string' },
+    summary: 'approve exactly the proposed scope carrying --digest, over the code and settings carrying --basis (409 if either moved)',
+  },
+  {
+    op: 'DELETE /api/v1/registrations/{id}/bridge-scope',
+    words: ['bridge-scope', 'retract'],
+    args: ['id'],
+    query: ['account'],
+    summary: 'retract the approved scope back to a proposal',
+  },
+  {
+    op: 'GET /api/v1/registrations/{id}/profiles',
+    words: ['profile', 'ls'],
+    args: ['id'],
+    query: ['account'],
+    summary: 'a registration\'s profiles (labeled credential sets): label and secret references',
+  },
+  // Bespoke for `--secret-env VAR=SECRET`: an overlay is references only, so
+  // the common case is "this variable reads that secret", which a nested JSON
+  // flag made a shell-quoting exercise. `--env <json>` stays for scripts.
+  {
+    op: 'POST /api/v1/registrations/{id}/profiles',
+    bespoke: true,
+    words: ['profile', 'add'],
+    usage: 'profile add <id> --label <label> (--secret-env VAR=SECRET … | --env <json>) [--account slug] [--data <json>]',
+    query: ['account'],
+    summary: 'add a profile: a label and the account secrets its variables read (references only)',
+    example: ['profile', 'add', 'reg_1', '--label', 'work', '--secret-env', 'API_TOKEN=WORK_TOKEN'],
+  },
+  {
+    op: 'PUT /api/v1/registrations/{id}/profiles/{profileId}',
+    bespoke: true,
+    words: ['profile', 'set'],
+    usage: 'profile set <id> <profileId> [--label <label>] [--secret-env VAR=SECRET … | --env <json>] [--account slug] [--data <json>]',
+    query: ['account'],
+    summary: 'rename a profile (--label) or replace its whole overlay (--secret-env / --env)',
+    example: ['profile', 'set', 'reg_1', 'rpf_1', '--label', 'office'],
+  },
+  {
+    op: 'DELETE /api/v1/registrations/{id}/profiles/{profileId}',
+    words: ['profile', 'rm'],
+    args: ['id', 'profileId'],
+    query: ['account'],
+    summary: 'delete a profile',
+  },
+  {
+    op: 'POST /api/v1/registrations/update-all',
+    words: ['update-all'],
+    body: { mode: 'string', limit: 'integer', cursor: 'integer', cursorKey: 'string' },
+    summary: 're-resolve every enabled registration (--mode follow|force)',
+  },
+  {
+    op: 'POST /api/v1/registrations/preview',
+    bespoke: true,
+    usage: 'preview (--npm | --github | --pypi | --mcpb) <spec> [--dep …]',
+    summary: 'resolve a source to exact pins, write nothing',
+    example: ['preview', '--npm', 'thing-mcp'],
+  },
+  {
+    op: 'PUT /api/v1/bundles',
+    bespoke: true,
+    usage: 'bundles upload <path.mcpb>',
+    summary: 'upload an MCPB bundle; prints its sha256',
+    example: ['bundles', 'upload', '{mcpb}'],
+  },
+  { op: 'GET /api/v1/bundles/{sha256}', words: ['bundles', 'get'], args: ['sha256'], summary: 'an uploaded bundle\'s summary' },
+  { op: 'GET /api/v1/catalog', words: ['catalog'], query: LIST, summary: 'search the discovery catalogue (--q <text>)' },
+
+  // ── the account's view ───────────────────────────────────────────────────
+  { op: 'GET /api/v1/session', words: ['whoami'], summary: 'who the caller is' },
+  { op: 'GET /api/v1/overview', words: ['overview'], query: ['account'], summary: 'health, counts and 24h request stats' },
+  { op: 'GET /api/v1/instances', words: ['instances'], query: ['account'], summary: 'every running child in scope' },
+  {
+    op: 'GET /api/v1/usage',
+    words: ['usage'],
+    query: ['since', 'until', 'registration', 'bucket', 'account', 'principal', 'days', ...prefixed('reg'), ...prefixed('prin')],
+    summary: 'metered usage',
+  },
+  { op: 'GET /api/v1/billing', words: ['billing'], query: ['period', 'account', 'invoiceCents', ...LIST], summary: 'the month\'s bill and its apportionment' },
+  { op: 'GET /api/v1/activity', words: ['activity'], query: ['limit', 'account', ...LIST], summary: 'the audit trail' },
+  { op: 'GET /api/v1/alerts', words: ['alerts'], query: ['status', 'kind', 'account', ...LIST], summary: 'open and resolved alerts' },
+  // Tool calls a policy said to ask about (spec 2026-10-19 D3). An operator
+  // may answer one from outside the account; the owner usually answers from
+  // the push on their phone.
+  // Bespoke for the summary: stdout stays the JSON, and a line per row on
+  // stderr says which MCP, which tool, with what arguments, for how long.
+  {
+    op: 'GET /api/v1/approvals',
+    bespoke: true,
+    usage: 'approvals [ls] [--status pending|approved|refused|consumed|expired|all] [--account slug] [--sort v] [--order v] [--q v] [--page v] [--per-page v]',
+    query: ['status', 'account', ...LIST],
+    summary: 'tool calls waiting for approval: MCP, tool, argument preview, time left',
+    example: ['approvals', 'ls'],
+  },
+  // Bespoke so that it SHOWS the call before letting it through (fleet-audit
+  // #1454): an id pasted from a notification was approved without this
+  // terminal ever naming the MCP, the tool or the arguments.
+  {
+    op: 'POST /api/v1/approvals/{id}/approve',
+    bespoke: true,
+    words: ['approvals', 'approve'],
+    usage: 'approvals approve <id> [--account slug] [--yes]   (shows the call first; asks, unless --yes)',
+    query: ['account'],
+    summary: 'let one waiting tool call through, once, after showing which MCP, tool and arguments',
+    example: ['approvals', 'approve', 'apr_1', '--yes'],
+  },
+  { op: 'POST /api/v1/approvals/{id}/refuse', words: ['approvals', 'refuse'], args: ['id'], query: ['account'], summary: 'refuse one waiting tool call' },
+
+  // ── connections (principals) ─────────────────────────────────────────────
+  { op: 'GET /api/v1/principals', words: ['connections'], query: ['registration', 'account', ...LIST], summary: 'every authorization, with the profile (account) each one uses' },
+  { op: 'DELETE /api/v1/principals/{id}', words: ['connections', 'revoke'], args: ['id'], summary: 'revoke one connection' },
+  { op: 'PUT /api/v1/principals/{id}/label', words: ['connections', 'rename'], args: ['id', 'label'], body: {}, summary: 'name one connection (an empty label clears it)' },
+  { op: 'PUT /api/v1/principals/{id}/default', words: ['connections', 'default'], args: ['id'], summary: 'act through this connection of yours on its registration (else the newest)' },
+  { op: 'DELETE /api/v1/principals/{id}/default', words: ['connections', 'undefault'], args: ['id'], summary: 'stop preferring this connection: the newest live one is used again' },
+  { op: 'GET /api/v1/principals/{id}/secrets', words: ['connections', 'secrets'], args: ['id'], summary: 'one connection\'s credential names' },
+  {
+    op: 'PUT /api/v1/principals/{id}/secrets/{name}',
+    bespoke: true,
+    words: ['connections', 'secret', 'set'],
+    usage: 'connections secret set <principal id> <NAME> [--value v | --from-env [VAR]]',
+    summary: 'repair one connection\'s credential',
+    example: ['connections', 'secret', 'set', 'p1', 'NAME', '--value', 'v'],
+  },
+  { op: 'DELETE /api/v1/principals/{id}/secrets/{name}', words: ['connections', 'secret', 'rm'], args: ['id', 'name'], summary: 'remove one connection\'s credential' },
+  {
+    op: 'POST /api/v1/principals/{id}/login',
+    bespoke: true,
+    words: ['connections', 'login'],
+    usage: 'connections login <principal id>   (on a terminal, answers each step\'s prompts)',
+    summary: 'run the connection\'s declared sign-in again',
+    example: ['connections', 'login', 'p1'],
+  },
+  {
+    op: 'POST /api/v1/principals/{id}/login/step',
+    words: ['connections', 'login-step'],
+    args: ['id'],
+    body: { login: 'string', step: 'integer', answers: 'json' },
+    summary: 'answer one sign-in step (the scripted form of `connections login`)',
+  },
+
+  // ── you ──────────────────────────────────────────────────────────────────
+  { op: 'GET /api/v1/me', words: ['me'], summary: 'your own preferences (whether alerts about your MCPs are pushed to you)' },
+  // Bespoke, not a boolean flag: a bare boolean can only send `true`, and the
+  // switch is mostly used to turn alerts OFF — `off` is what anyone types,
+  // which a JSON-typed flag refused as "takes JSON".
+  {
+    op: 'PUT /api/v1/me',
+    bespoke: true,
+    words: ['me', 'set'],
+    usage: 'me set --push-tenant-alerts on|off [--data <json>]',
+    summary: 'set your own preferences (whether alerts about your MCPs are pushed to your devices)',
+    example: ['me', 'set', '--push-tenant-alerts', 'off'],
+  },
+  { op: 'GET /api/v1/me/identities', words: ['me', 'identities'], summary: 'your linked sign-in methods' },
+  { op: 'DELETE /api/v1/me/identities/{provider}/{subject}', words: ['me', 'identities', 'rm'], args: ['provider', 'subject'], summary: 'unlink a sign-in method' },
+  { op: 'GET /api/v1/me/push-devices', words: ['me', 'devices'], summary: 'devices enrolled for alerts' },
+  { op: 'DELETE /api/v1/me/push-devices/{id}', words: ['me', 'devices', 'rm'], args: ['id'], summary: 'stop alerting a device' },
+  { op: 'PATCH /api/v1/me/account', words: ['me', 'rename'], args: ['slug'], body: {}, summary: 'rename your account slug' },
+
+  // ── users, accounts, invites ─────────────────────────────────────────────
+  { op: 'GET /api/v1/users', words: ['users'], query: ['account', ...LIST], summary: 'every user' },
+  { op: 'PUT /api/v1/users/{idOrEmail}/role', words: ['users', 'role'], args: ['idOrEmail', 'role'], body: {}, summary: 'promote or demote (user|super)' },
+  { op: 'DELETE /api/v1/users/{idOrEmail}', words: ['users', 'erase'], args: ['idOrEmail'], summary: 'erase a person' },
+  { op: 'GET /api/v1/users/{idOrEmail}/entitlements', words: ['users', 'entitlements'], args: ['idOrEmail'], summary: 'a person\'s granted entitlements' },
+  { op: 'PUT /api/v1/users/{idOrEmail}/entitlements/{name}', words: ['users', 'grant'], args: ['idOrEmail', 'name'], summary: 'grant an entitlement (super-admin only)' },
+  { op: 'DELETE /api/v1/users/{idOrEmail}/entitlements/{name}', words: ['users', 'revoke'], args: ['idOrEmail', 'name'], summary: 'revoke an entitlement (super-admin only)' },
+  { op: 'GET /api/v1/accounts/{idOrSlug}/limits', words: ['limits'], args: ['idOrSlug'], summary: 'an account\'s quotas' },
+  {
+    op: 'PUT /api/v1/accounts/{idOrSlug}/limits',
+    words: ['limits', 'set'],
+    args: ['idOrSlug'],
+    body: { maxRegistrations: 'integer', maxCallsPerMinute: 'integer', maxBundleBytes: 'integer', minSecurityScore: 'number' },
+    // No "reset to default": the fields are optional, not nullable, and the
+    // write COALESCEs, so an omitted field keeps its current value.
+    summary: 'raise or lower an account\'s quotas (an omitted field keeps its value)',
+  },
+  { op: 'GET /api/v1/invites', words: ['invites'], query: ['account', ...LIST], summary: 'outstanding invites' },
+  {
+    op: 'POST /api/v1/invites',
+    words: ['invites', 'new'],
+    body: { email: 'string', account: 'string', note: 'string', expiresAt: 'string' },
+    summary: 'mint an invite',
+  },
+  { op: 'DELETE /api/v1/invites/{id}', words: ['invites', 'revoke'], args: ['id'], summary: 'revoke an unredeemed invite' },
+
+  // ── secrets ──────────────────────────────────────────────────────────────
+  {
+    op: 'PUT /api/v1/secrets/{name}',
+    bespoke: true,
+    usage: 'secret set <NAME> [--value v | --from-env [VAR]] [--legacy] [--account slug]   (sealed before it leaves this process)',
+    query: ['account'],
+    summary: 'set or rotate a secret',
+    example: ['secret', 'set', 'NAME', '--value', 'v', '--legacy'],
+  },
+  {
+    op: 'GET /api/v1/secrets',
+    bespoke: true,
+    usage: 'secret ls [--account slug] [--sort v] [--order v] [--q v] [--page v] [--per-page v]   |   secret fingerprint <NAME> [--value v | --from-env [VAR]] [--account slug]',
+    query: ['account', ...LIST],
+    summary: 'list secrets, or compare a value against a stored fingerprint locally',
+    example: ['secret', 'ls'],
+  },
+  {
+    op: 'DELETE /api/v1/secrets/{name}',
+    bespoke: true,
+    usage: 'secret rm <NAME> [--force] [--account slug]   (--force deletes one a registration or profile still uses)',
+    query: ['account'],
+    booleanQuery: ['force'],
+    summary: 'delete a secret (refused while in use unless --force)',
+    example: ['secret', 'rm', 'NAME'],
+  },
+  { op: 'GET /api/v1/secrets/public-key', words: ['secret', 'public-key'], query: ['account'], summary: 'the account seal key' },
+  { op: 'POST /api/v1/secrets/reseal', words: ['secret', 'reseal'], body: { limit: 'integer', cursor: 'string' }, summary: 'seal every legacy row (one-time migration)' },
+  { op: 'POST /api/v1/secrets/rotate', words: ['secret', 'rotate'], body: { limit: 'integer', cursor: 'string' }, summary: 're-wrap sealed rows after a seal-root rotation' },
+
+  // ── browser bridge, marketplace ──────────────────────────────────────────
+  {
+    op: 'GET /api/v1/bridge-tokens',
+    bespoke: true,
+    usage: 'bridge [ls] [--account slug] [--sort v] [--order v] [--q v] [--page v] [--per-page v]',
+    query: ['account', ...LIST],
+    // connectedNow/connectedSince (D18, spec §4.13) are answered to the
+    // account OWNER's own session only; this CLI authenticates with
+    // ADMIN_TOKEN, so its listing never carries them (the portal and the app
+    // show them). Printed as-is, the column appears whenever the API sends it.
+    summary: 'list bridge credentials (browsers connect from the extension; connected-now is the owner\'s session only)',
+    example: ['bridge', 'ls', '--account', 'acme'],
+  },
+  {
+    op: 'GET /api/v1/bridge-tokens/pins',
+    words: ['bridge', 'pins'],
+    query: ['account'],
+    summary: 'show whether the account is on managed extension pins, and why',
+  },
+  {
+    op: 'GET /api/v1/bridge-tokens/account-pairing',
+    words: ['bridge', 'account-pairing'],
+    query: ['account'],
+    summary: 'show whether account pairing is on for the account, and why',
+  },
+  {
+    op: 'POST /api/v1/bridge-tokens/unpair-account',
+    words: ['bridge', 'unpair-account'],
+    query: ['account'],
+    summary: 'unpair the account: every browser sees a new account key (owner only)',
+  },
+  {
+    op: 'POST /api/v1/bridge-tokens/mac-pass',
+    words: ['bridge', 'mac-pass'],
+    body: { dryRun: 'boolean', rotate: 'boolean', limit: 'integer', cursor: 'string' },
+    summary: 'MAC bridge credentials minted before BRIDGE_ATTEST_ROOT (a dry run unless --data {"dryRun":false}; scripts/bridge-mac-pass.mjs --apply)',
+  },
+  {
+    op: 'DELETE /api/v1/bridge-tokens/{id}',
+    bespoke: true,
+    usage: 'bridge revoke <id> [--account slug]',
+    query: ['account'],
+    summary: 'revoke a bridge credential',
+    example: ['bridge', 'revoke', 'b1', '--account', 'acme'],
+  },
+  {
+    op: 'GET /api/v1/connector',
+    bespoke: true,
+    usage: 'connector [--account slug] [--json]',
+    query: ['account'],
+    summary: 'print the account\'s one connect URL for every MCP (the aggregate connector) and what it reaches',
+    example: ['connector', '--account', 'acme'],
+  },
+  { op: 'GET /api/v1/connector/connections', words: ['connector', 'connections'], query: ['account'], summary: 'your connections through the aggregate connector (one per approval), each revocable' },
+  { op: 'DELETE /api/v1/connector/connections/{id}', words: ['connector', 'revoke'], args: ['id'], query: ['account'], summary: 'revoke ONE aggregate connection: its tokens stop working at once' },
+  { op: 'DELETE /api/v1/connector/connections', words: ['connector', 'revoke-all'], query: ['account'], summary: 'revoke every one of your aggregate connections in this account' },
+  {
+    op: 'GET /api/v1/marketplace',
+    bespoke: true,
+    usage: 'marketplace [--account slug]',
+    query: ['account'],
+    summary: 'whether a marketplace feed exists',
+    example: ['marketplace', '--account', 'acme'],
+  },
+  {
+    op: 'POST /api/v1/marketplace/token',
+    bespoke: true,
+    usage: 'marketplace rotate [--account slug]',
+    query: ['account'],
+    summary: 'mint (or rotate) the marketplace URL',
+    example: ['marketplace', 'rotate', '--account', 'acme'],
+  },
+  {
+    op: 'DELETE /api/v1/marketplace/token',
+    bespoke: true,
+    usage: 'marketplace revoke [--account slug]',
+    query: ['account'],
+    summary: 'revoke the marketplace URL',
+    example: ['marketplace', 'revoke', '--account', 'acme'],
+  },
+
+  // ── infrastructure (super-admin) ─────────────────────────────────────────
+  {
+    op: 'GET /api/v1/infra',
+    bespoke: true,
+    usage: 'infra [--days N] [--account slug] [--res-sort v] [--res-order v] [--res-q v] [--res-page v] [--res-per-page v]',
+    query: ['account', 'days', ...prefixed('res')],
+    summary: 'machines, the shared pool, resource totals',
+    example: ['infra', '--days', '7'],
+  },
+  {
+    op: 'POST /api/v1/infra/shared-machines/sync',
+    bespoke: true,
+    usage: 'infra sync',
+    summary: 'bring the pool\'s machine set in step with Fly',
+    example: ['infra', 'sync'],
+  },
+  {
+    op: 'POST /api/v1/infra/shared-machines/{id}/drain',
+    bespoke: true,
+    usage: 'infra drain <machine id>',
+    summary: 'take a pool machine out of placement',
+    example: ['infra', 'drain', 'm1'],
+  },
+  {
+    op: 'POST /api/v1/infra/shared-machines/{id}/undrain',
+    bespoke: true,
+    usage: 'infra undrain <machine id>',
+    summary: 'return a drained machine to placement',
+    example: ['infra', 'undrain', 'm1'],
+  },
+];
+
+const kebabList = (prefix = '') => LIST.map((n) => flagName(prefix ? `${prefix}${n[0].toUpperCase()}${n.slice(1)}` : n));
+
+/**
+ * The flags each HAND-WRITTEN command accepts (fleet-audit#1407), keyed by the
+ * words that name it. A generic row's flags are derived from the row; a
+ * bespoke command's were whatever its code happened to read, so a typo beside
+ * a valid flag was dropped and the request still sent. index.mjs parses each
+ * of these commands against its entry and REFUSES anything outside it, with
+ * the usage line of the row named by `op`.
+ *
+ * `values` take a value, `booleans` take none, `optional` may take one
+ * (`--from-env [VAR]`). Held to an enumeration in tests/bespoke-flags.test.ts.
+ *
+ * @type {Record<string, { op: string, values?: string[], booleans?: string[], optional?: string[] }>}
+ */
+export const COMMAND_FLAGS = {
+  register: {
+    op: 'POST /api/v1/registrations',
+    values: ['slug', 'npm', 'github', 'pypi', 'mcpb', 'subdir', 'build', 'bin', 'dep', 'dep-sha256', 'account', 'name', 'env', 'secret-env', 'tools', 'auth-flow', 'data'],
+    booleans: ['follow', 'data-dir', 'no-data-dir', 'per-user-child', 'bridge'],
+  },
+  set: {
+    op: 'PUT /api/v1/registrations/{id}',
+    values: ['data', 'state-store', 'dep', 'dep-sha256', 'bridge-approval', 'deny', 'ask', 'tools', 'aggregate'],
+    booleans: ['data-dir', 'no-data-dir', 'no-deps', 'follow', 'no-follow', 'allow-all', 'no-ask', 'all-tools'],
+  },
+  logs: { op: 'GET /api/v1/registrations/{id}/logs', values: ['lines'] },
+  build: { op: 'POST /api/v1/registrations/{id}/build', booleans: ['force', 'wait'] },
+  preview: { op: 'POST /api/v1/registrations/preview', values: ['npm', 'github', 'pypi', 'mcpb', 'subdir', 'build', 'dep', 'dep-sha256'] },
+  'bundles upload': { op: 'PUT /api/v1/bundles' },
+  approvals: { op: 'GET /api/v1/approvals', values: ['status', 'account', ...kebabList()] },
+  'approvals approve': { op: 'POST /api/v1/approvals/{id}/approve', values: ['account'], booleans: ['yes'] },
+  'me set': { op: 'PUT /api/v1/me', values: ['push-tenant-alerts', 'data'] },
+  'profile add': { op: 'POST /api/v1/registrations/{id}/profiles', values: ['label', 'secret-env', 'env', 'account', 'data'] },
+  'profile set': { op: 'PUT /api/v1/registrations/{id}/profiles/{profileId}', values: ['label', 'secret-env', 'env', 'account', 'data'] },
+  'connections login': { op: 'POST /api/v1/principals/{id}/login' },
+  'connections secret set': { op: 'PUT /api/v1/principals/{id}/secrets/{name}', values: ['value'], optional: ['from-env'] },
+  'secret set': { op: 'PUT /api/v1/secrets/{name}', values: ['value', 'account'], booleans: ['legacy'], optional: ['from-env'] },
+  'secret fingerprint': { op: 'GET /api/v1/secrets', values: ['value', 'account'], optional: ['from-env'] },
+  'secret ls': { op: 'GET /api/v1/secrets', values: ['account', ...kebabList()] },
+  'secret rm': { op: 'DELETE /api/v1/secrets/{name}', values: ['account'], booleans: ['force'] },
+  bridge: { op: 'GET /api/v1/bridge-tokens', values: ['account', ...kebabList()] },
+  'bridge revoke': { op: 'DELETE /api/v1/bridge-tokens/{id}', values: ['account'] },
+  connector: { op: 'GET /api/v1/connector', values: ['account'], booleans: ['json'] },
+  marketplace: { op: 'GET /api/v1/marketplace', values: ['account'] },
+  'marketplace rotate': { op: 'POST /api/v1/marketplace/token', values: ['account'] },
+  'marketplace revoke': { op: 'DELETE /api/v1/marketplace/token', values: ['account'] },
+  infra: { op: 'GET /api/v1/infra', values: ['account', 'days', ...kebabList('res')] },
+  'infra sync': { op: 'POST /api/v1/infra/shared-machines/sync' },
+  'infra drain': { op: 'POST /api/v1/infra/shared-machines/{id}/drain' },
+  'infra undrain': { op: 'POST /api/v1/infra/shared-machines/{id}/undrain' },
+};
+
+/** `usage: mcp-host …` for a COMMAND_FLAGS key: its row's usage line, so the refusal and `--help` say one thing. */
+export function commandUsage(key) {
+  const row = OPERATIONS.find((r) => r.op === COMMAND_FLAGS[key].op);
+  return `usage: mcp-host ${usageFor(row)}`;
+}
+
+/** `perPage` → `per-page`: the flag spelling of a query or body field name. */
+export function flagName(field) {
+  return field.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+/** The path parameters of an operation, in the order they appear. */
+export function pathParams(op) {
+  return [...op.split(' ')[1].matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+}
+
+/** The usage line for a row — written out for a bespoke row, derived for a generic one. */
+export function usageFor(row) {
+  if (row.bespoke) return row.usage;
+  const parts = [...row.words, ...(row.args ?? []).map((a) => `<${a}>`)];
+  for (const q of row.query ?? []) parts.push(`[--${flagName(q)} v]`);
+  for (const [field, type] of Object.entries(row.body ?? {})) {
+    parts.push(type === 'boolean' ? `[--${flagName(field)}]` : `[--${flagName(field)} ${type === 'json' ? 'json' : 'v'}]`);
+  }
+  if (row.body) parts.push('[--data <json|@file|->]');
+  return parts.join(' ');
+}
+
+/** The argv a generic row is exercised with: its words and a placeholder per positional. */
+export function exampleFor(row) {
+  if (row.bespoke) return row.example;
+  return [...row.words, ...(row.args ?? []).map((a, i) => `${a}${i}`)];
+}
+
+/**
+ * The generic row an argv names, or undefined. The LONGEST word prefix wins
+ * (`connections secret rm` over `connections`), and among rows sharing words
+ * the one whose positional count matches (`tools` vs `tools <id>`). Called on
+ * the WORDS only — flags are parsed by the row once it is chosen, since
+ * which names are flags depends on the row.
+ *
+ * @param {string[]} argv
+ */
+export function matchGeneric(argv) {
+  const leading = [];
+  for (const arg of argv) {
+    if (arg.startsWith('--')) break;
+    leading.push(arg);
+  }
+  const candidates = OPERATIONS.filter(
+    (row) => row.words !== undefined && row.words.length <= leading.length && row.words.every((w, i) => leading[i] === w),
+  );
+  if (candidates.length === 0) return undefined;
+  const longest = Math.max(...candidates.map((row) => row.words.length));
+  const tied = candidates.filter((row) => row.words.length === longest);
+  // A longer bespoke command wins over a shorter generic one, and is main()'s.
+  if (tied.some((row) => row.bespoke)) return undefined;
+  if (tied.length === 1) return tied[0];
+  // A shared prefix: decide by how many positionals follow the words. Counted
+  // over the whole argv's positionals would need the row's flag set to skip
+  // flag values, so count only the run before the first flag — which is where
+  // every usage line puts them.
+  const given = leading.length - longest;
+  return tied.find((row) => (row.args ?? []).length === given) ?? tied[0];
+}
+
+/**
+ * Help for what was typed: the one row a command names (`list --help`), else
+ * every row under the words given (`secret --help`), else everything. Matched
+ * on the leading WORDS of each row's usage line, so bespoke rows — which have
+ * no `words` — are found by what they print.
+ *
+ * @param {string[]} argv  the command line with `--help` removed
+ */
+export function helpFor(argv) {
+  const leading = [];
+  for (const arg of argv) {
+    if (arg.startsWith('-')) break;
+    leading.push(arg);
+  }
+  if (leading.length === 0) return helpText();
+  const row = matchGeneric(leading);
+  if (row && row.words.length === leading.length) return `usage: mcp-host ${usageFor(row)}`;
+  for (let k = leading.length; k > 0; k--) {
+    const prefix = leading.slice(0, k);
+    const lines = OPERATIONS.map(usageFor).filter((usage) => {
+      const words = usage.split(' ');
+      return prefix.every((w, i) => words[i] === w || (i === 1 && words[i] === `[${w}]`));
+    });
+    if (lines.length === 1) return `usage: mcp-host ${lines[0]}`;
+    if (lines.length > 1) return lines.map((u) => `  mcp-host ${u}`).join('\n');
+  }
+  return helpText();
+}
+
+/** The help text: every reachable operation, one line each. */
+export function helpText() {
+  const lines = ['usage: mcp-host <command> [--insecure]', ''];
+  const rows = OPERATIONS.map((row) => [usageFor(row), row.summary]);
+  const width = Math.min(72, Math.max(...rows.map(([u]) => u.length)));
+  for (const [usage, summary] of rows) {
+    lines.push(usage.length > width ? `  ${usage}\n  ${' '.repeat(width)}  ${summary}` : `  ${usage.padEnd(width)}  ${summary}`);
+  }
+  lines.push('', '  wizard                              register interactively', '  builder-key                         LEGACY: print HMAC(RUNNER_KEY, \'builder\')');
+  lines.push('', 'MCP_HOST_URL and MCP_HOST_ADMIN_TOKEN must be set. Output is JSON on stdout.');
+  return lines.join('\n');
+}