@wickedevolutions/abilities-mcp 1.3.1 → 1.5.3

package/lib/cli/errors.js

@@ -0,0 +1,227 @@
+'use strict';
+
+/**
+ * CLI error helpers + exit-code table.
+ *
+ * The design doc does not pin a CLI exit-code table — only the constraint that
+ * `lib/auth/` itself contains no `process.exit` calls. The table below is a
+ * Phase 5 design choice, intentionally narrow:
+ *
+ *   0  success
+ *   1  generic / unexpected error                (catch-all, includes --debug stack)
+ *   2  usage error                               (bad args, unknown subcommand)
+ *   3  config error                              (wp-sites.json missing/invalid)
+ *   4  auth failure                              (consent denied, refresh expired,
+ *                                                 token endpoint 4xx, network)
+ *   5  capability-pinning violation              (H.2.3 — pinned site lost OAuth)
+ *
+ * Operator-facing error messages MUST name the next action to take. CliError
+ * carries that next-action text on the `nextAction` field so the formatter can
+ * render it consistently.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const EXIT_OK = 0;
+const EXIT_GENERIC = 1;
+const EXIT_USAGE = 2;
+const EXIT_CONFIG = 3;
+const EXIT_AUTH = 4;
+const EXIT_PIN_VIOLATION = 5;
+
+class CliError extends Error {
+  /**
+   * @param {string} message            One-line operator-facing summary.
+   * @param {object} [opts]
+   * @param {number} [opts.exitCode]    Defaults to EXIT_GENERIC.
+   * @param {string} [opts.nextAction]  Required for non-zero exits — names the
+   *                                    exact command / action the operator
+   *                                    should run next.
+   * @param {Error}  [opts.cause]
+   */
+  constructor(message, opts = {}) {
+    super(message);
+    this.name = 'CliError';
+    this.exitCode = typeof opts.exitCode === 'number' ? opts.exitCode : EXIT_GENERIC;
+    this.nextAction = opts.nextAction || null;
+    // Progress lines accumulated by the command before it threw — these are
+    // the operator's record of "how far the command got." The router prints
+    // them on stdout so the operator sees the partial trace alongside the
+    // error on stderr. (The lib/auth/ state machine has no notion of CLI
+    // output, so commands accumulate lines locally and pass them along.)
+    if (Array.isArray(opts.progressLines)) this.progressLines = opts.progressLines;
+    if (opts.cause) this.cause = opts.cause;
+  }
+}
+
+/**
+ * Map a thrown error from `lib/auth/` (or anywhere) onto a CliError.
+ * Pure — does not print. The caller decides how to render.
+ *
+ * @param {Error} err
+ * @param {object} [ctx]                Optional context to enrich next-action
+ * @param {string} [ctx.siteId]
+ * @returns {CliError}
+ */
+function fromAuthError(err, ctx = {}) {
+  if (err instanceof CliError) {
+    // Caller may layer additional progressLines onto an already-CliError.
+    if (Array.isArray(ctx.progressLines) && !err.progressLines) {
+      err.progressLines = ctx.progressLines;
+    }
+    return err;
+  }
+
+  const code = err && err.code;
+  const siteRef = ctx.siteId || (err && err.reauthHint && err.reauthHint.siteId) || null;
+  const progressLines = Array.isArray(ctx.progressLines) ? ctx.progressLines : undefined;
+
+  // H.2.3 — capability pinning failure has its own exit code so scripts can
+  // distinguish a possible network-attack signal from a routine auth failure.
+  if (err && err.name === 'CapabilityPinningError') {
+    return new CliError(err.message, {
+      exitCode: EXIT_PIN_VIOLATION,
+      nextAction: siteRef
+        ? `Run: abilities-mcp force-downgrade ${siteRef} --i-understand-the-risk (only if you intend to override OAuth pinning)`
+        : 'Run: abilities-mcp force-downgrade <site_id> --i-understand-the-risk (only if you intend to override OAuth pinning)',
+      cause: err,
+    });
+  }
+
+  // Operator denied consent on the adapter screen — no remediation needed
+  // beyond re-running add-site / reauth.
+  if (err && err.name === 'UserDeniedError') {
+    return new CliError('Authorization was denied on the consent screen.', {
+      exitCode: EXIT_AUTH,
+      nextAction: siteRef
+        ? `Run: abilities-mcp reauth ${siteRef} (and click Allow on the consent screen)`
+        : 'Re-run add-site and click Allow on the consent screen',
+      cause: err,
+    });
+  }
+
+  // Refresh token rejected by adapter → reauth.
+  if (err && err.name === 'RefreshError') {
+    if (code === 'reauth_required' || code === 'invalid_grant' || code === 'unauthorized_client') {
+      return new CliError(`Refresh token rejected (${code || 'invalid_grant'}).`, {
+        exitCode: EXIT_AUTH,
+        nextAction: siteRef
+          ? `Run: abilities-mcp reauth ${siteRef} to refresh consent`
+          : 'Run: abilities-mcp reauth <site_id> to refresh consent',
+        cause: err,
+      });
+    }
+    if (code === 'no_refresh_token' || code === 'revoked') {
+      return new CliError(err.message || 'No usable refresh token.', {
+        exitCode: EXIT_AUTH,
+        nextAction: siteRef
+          ? `Run: abilities-mcp reauth ${siteRef}`
+          : 'Run: abilities-mcp reauth <site_id>',
+        cause: err,
+      });
+    }
+    return new CliError(err.message || 'Token refresh failed.', {
+      exitCode: EXIT_AUTH,
+      nextAction: siteRef
+        ? `Run: abilities-mcp reauth ${siteRef} if the failure persists`
+        : 'Re-check site connectivity and run reauth if the failure persists',
+      cause: err,
+    });
+  }
+
+  // Discovery 404 / no metadata → adapter likely not installed.
+  if (err && err.name === 'DiscoveryError') {
+    return new CliError(err.message || 'OAuth discovery failed.', {
+      exitCode: EXIT_AUTH,
+      nextAction: 'Verify the site has abilities-mcp-adapter v1.5.0+ installed and reachable over HTTPS',
+      cause: err,
+    });
+  }
+
+  // Adapter rejected DCR — usually a configuration mismatch on the adapter.
+  if (err && err.name === 'RegistrationError') {
+    return new CliError(err.message || 'Dynamic Client Registration failed.', {
+      exitCode: EXIT_AUTH,
+      nextAction: 'Check the adapter\'s OAuth client policy and try add-site again',
+      cause: err,
+    });
+  }
+
+  // Token exchange rejected — typically PKCE / code re-use.
+  if (err && err.name === 'TokenExchangeError') {
+    return new CliError(err.message || 'Token exchange failed.', {
+      exitCode: EXIT_AUTH,
+      nextAction: siteRef
+        ? `Run: abilities-mcp reauth ${siteRef}`
+        : 'Re-run add-site to start a fresh authorization',
+      cause: err,
+    });
+  }
+
+  // SecretStore (keytar) unavailable on this host.
+  if (err && err.name === 'SecretStoreError') {
+    return new CliError(err.message || 'OS keychain unavailable.', {
+      exitCode: EXIT_CONFIG,
+      nextAction: 'Install OS keychain support (libsecret on Linux) or run on a host with native keychain',
+      cause: err,
+    });
+  }
+
+  // State machine state-token mismatch — almost always the operator
+  // re-clicking an old consent link.
+  if (err && err.name === 'StateMismatchError') {
+    return new CliError(err.message, {
+      exitCode: EXIT_AUTH,
+      nextAction: siteRef
+        ? `Run: abilities-mcp reauth ${siteRef} and complete the flow without re-using stale links`
+        : 'Re-run add-site and complete the flow without re-using stale browser tabs',
+      cause: err,
+    });
+  }
+
+  // Migration failure — surfaced from config-migration.js.
+  if (err && err.name === 'MigrationError') {
+    return new CliError(err.message || 'Config migration failed.', {
+      exitCode: EXIT_CONFIG,
+      nextAction: 'Inspect wp-sites.json (and its .v1.bak) and fix the source schema',
+      cause: err,
+    });
+  }
+
+  // Fallback — unknown error class.
+  const fallback = new CliError(err && err.message ? err.message : String(err), {
+    exitCode: EXIT_GENERIC,
+    cause: err,
+  });
+  if (progressLines) fallback.progressLines = progressLines;
+  return fallback;
+}
+
+/**
+ * After fromAuthError() returns, attach `progressLines` collected by the
+ * command. Done via a wrapper so each `new CliError(...)` branch above stays
+ * a one-liner.
+ *
+ * @param {CliError} cliErr
+ * @param {string[]} progressLines
+ * @returns {CliError}
+ */
+function withProgress(cliErr, progressLines) {
+  if (cliErr instanceof CliError && Array.isArray(progressLines) && progressLines.length) {
+    cliErr.progressLines = progressLines;
+  }
+  return cliErr;
+}
+
+module.exports = {
+  CliError,
+  fromAuthError,
+  withProgress,
+  EXIT_OK,
+  EXIT_GENERIC,
+  EXIT_USAGE,
+  EXIT_CONFIG,
+  EXIT_AUTH,
+  EXIT_PIN_VIOLATION,
+};

package/lib/cli/index.js

@@ -0,0 +1,173 @@
+'use strict';
+
+const { parse } = require('./parse-args');
+const { createContext } = require('./context');
+const { CliError, fromAuthError, EXIT_USAGE, EXIT_OK, EXIT_GENERIC } = require('./errors');
+const { renderNextAction } = require('./output');
+const { migrateFile } = require('../auth/config-migration');
+
+const COMMANDS = {
+  'add-site': () => require('./commands/add-site'),
+  'reauth': () => require('./commands/reauth'),
+  'revoke': () => require('./commands/revoke'),
+  'list-sites': () => require('./commands/list-sites'),
+  'test': () => require('./commands/test'),
+  'upgrade-auth': () => require('./commands/upgrade-auth'),
+  // Documented in Appendix J of the design doc:
+  'force-downgrade': () => require('./commands/force-downgrade'),    // J.1 — H.2.3 escape hatch
+  'self-check': () => require('./commands/self-check'),              // J.2 — H.2.6 header probe
+};
+
+/**
+ * Subcommand router for `abilities-mcp <subcommand> ...`.
+ *
+ * The router is invoked by abilities-mcp.js when the first argv token is one
+ * of the known subcommand names. When it isn't, the bridge falls through to
+ * MCP server mode (the original behavior).
+ *
+ * Tests can call `runCommand({ subcommand, argv, ctx })` directly with a
+ * test context, bypassing process.argv / process.exit / stdout entirely.
+ *
+ * Exit codes are defined in `./errors.js` (0/1/2/3/4/5).
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+function isKnownSubcommand(name) {
+  return Object.prototype.hasOwnProperty.call(COMMANDS, name);
+}
+
+/**
+ * Run a single subcommand. Pure of process / stdout — returns { exitCode,
+ * lines, errLines }. The caller writes to streams and exits.
+ *
+ * @param {object} opts
+ * @param {string} opts.subcommand
+ * @param {string[]} opts.argv             Tokens after the subcommand name.
+ * @param {object} [opts.ctx]              Pre-built context (tests). When
+ *                                          omitted, createContext(args) is used.
+ * @returns {Promise<{exitCode:number, lines:string[], errLines:string[]}>}
+ */
+async function runCommand(opts) {
+  const args = parse(opts.argv || []);
+  if (!isKnownSubcommand(opts.subcommand)) {
+    return {
+      exitCode: EXIT_USAGE,
+      lines: [],
+      errLines: [
+        `abilities-mcp: unknown subcommand "${opts.subcommand}"`,
+        `  → Run: abilities-mcp --help`,
+      ],
+    };
+  }
+  const cmd = COMMANDS[opts.subcommand]();
+  const ctx = opts.ctx || createContext(args);
+
+  // Schema v1→v2 migration runs before any subcommand reads the config, so
+  // `upgrade-auth`, `add-site`, `list-sites`, etc. work on a fresh v1.4.x
+  // upgrade without first starting the bridge as MCP server. `migrateFile`
+  // is idempotent (a v2 file is a no-op) and ENOENT-safe (returns
+  // missing:true for clean installs that haven't run add-site yet). The
+  // migration uses `ctx.secretStore` so lifted secrets land in the same
+  // store the subcommand will read from a moment later — production
+  // contexts share KeychainSecretStore (entry identity is (service,
+  // account), not instance-bound); tests share their MemorySecretStore.
+  const preLines = [];
+  try {
+    if (ctx.configPath) {
+      const result = await migrateFile({
+        filePath: ctx.configPath,
+        secretStore: ctx.secretStore,
+      });
+      if (result.migrated) {
+        preLines.push(
+          `Migrated wp-sites.json v1 → v2 (${result.liftedCount} secret(s) lifted; backup: ${result.backupPath})`
+        );
+      }
+    }
+  } catch (err) {
+    const cliErr = fromAuthError(err);
+    return {
+      exitCode: cliErr.exitCode || EXIT_GENERIC,
+      lines: [],
+      errLines: renderNextAction(cliErr),
+    };
+  }
+
+  try {
+    const r = await cmd.run(args, ctx);
+    const lines = preLines.length
+      ? preLines.concat(r.lines || [])
+      : (r.lines || []);
+    return { exitCode: r.exitCode || EXIT_OK, lines, errLines: [] };
+  } catch (err) {
+    const cliErr = err instanceof CliError ? err : fromAuthError(err);
+    const errLines = renderNextAction(cliErr);
+    if (ctx.debug && cliErr.cause && cliErr.cause.stack) {
+      errLines.push('');
+      errLines.push('--- debug stack ---');
+      errLines.push(cliErr.cause.stack);
+    }
+    // If the command accumulated progress before throwing, surface it on
+    // stdout — the operator sees how far the command got alongside the
+    // stderr error message. Migration-success preLines also need to surface
+    // when the subsequent subcommand throws.
+    const progress = Array.isArray(cliErr.progressLines) ? cliErr.progressLines : [];
+    const lines = preLines.length ? preLines.concat(progress) : progress;
+    return {
+      exitCode: cliErr.exitCode || EXIT_GENERIC,
+      lines,
+      errLines,
+    };
+  }
+}
+
+const HELP_TEXT = [
+  'abilities-mcp — MCP bridge for WordPress Abilities API',
+  '',
+  'Subcommands:',
+  '  add-site <url>                       Register a new site (OAuth by default)',
+  '       --apppassword                   Use App Password authentication instead',
+  '       --username=<user> --password=<pw>   (required with --apppassword)',
+  '       --scope="<space-sep scopes>"    Override default DCR scope',
+  '       --site-id=<id>                  Override the derived site_id',
+  '       --label=<text>                  Human-readable label',
+  '       --force                         Overwrite an existing site_id',
+  '  reauth <site_id>                     Re-run OAuth flow for an existing site',
+  '  revoke <site_id>                     Revoke OAuth tokens (local + remote)',
+  '  list-sites                           Show configured sites + auth status',
+  '  test <site_id>                       Ping the adapter and report scopes',
+  '  upgrade-auth <site_id>               Migrate App Password → OAuth (Step 1-3)',
+  '       --confirm                       Step 4: remove App Password fallback',
+  '  force-downgrade <site_id>            Override OAuth pinning (H.2.3)',
+  '       --i-understand-the-risk         (required)',
+  '       --reason="<text>"               Audit message (visible in list-sites for 30 days)',
+  '  self-check <site_id>                 Probe Authorization-header survival (H.2.6)',
+  '',
+  'Global flags:',
+  '  --config=<path>        Use this wp-sites.json (defaults: ./wp-sites.json or',
+  '                         ~/.abilities-mcp/wp-sites.json)',
+  '  --debug                Include cause stack on errors',
+  '  --allow-insecure       Allow plain HTTP (localhost dev only)',
+  '',
+  'Exit codes:',
+  '  0  success',
+  '  1  unexpected error',
+  '  2  usage error',
+  '  3  config error (wp-sites.json)',
+  '  4  auth failure (consent denied / token rejected / network)',
+  '  5  capability-pinning violation (H.2.3 — pinned site lost OAuth)',
+];
+
+function isHelpToken(tok) {
+  return tok === '-h' || tok === '--help' || tok === 'help';
+}
+
+module.exports = {
+  isKnownSubcommand,
+  runCommand,
+  COMMANDS,
+  HELP_TEXT,
+  isHelpToken,
+};

package/lib/cli/output.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Output formatter for CLI subcommands.
+ *
+ * Returns lines (strings) rather than printing directly so commands stay
+ * testable without stdout capture. The router writes `lines` to stdout, and
+ * any `errLines` to stderr, after the command resolves.
+ *
+ * Renders:
+ *   - State-machine progress lines (subscribed from lib/auth/ events).
+ *   - Site tables for `list-sites`.
+ *   - "next action" hints for failed commands.
+ *
+ * No emoji unless the spec verbatim text uses one (✓, ✗, ⚠ appear in the
+ * design doc's binding error wording — those we preserve).
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const { STATES } = require('../auth/events');
+
+const PROGRESS_LABEL = Object.freeze({
+  [STATES.DISCOVERING]:        '→ Discovering OAuth metadata',
+  [STATES.REGISTERING]:        '→ Registering bridge client (DCR)',
+  [STATES.AWAITING_CONSENT]:   '→ Waiting for consent in browser',
+  [STATES.EXCHANGING]:         '→ Exchanging authorization code for tokens',
+  [STATES.COMPLETE]:           '✓ Authorization complete',
+  [STATES.FAILED]:             '✗ Authorization failed',
+});
+
+/**
+ * Subscribe to an OAuthClient event emitter and push human-readable progress
+ * lines onto `out`. The caller decides when to flush; this only mutates `out`.
+ *
+ * @param {import('node:events').EventEmitter} client
+ * @param {string[]} out
+ * @param {object} [opts]
+ * @param {boolean} [opts.includeProgress]   default true — sub-step lines
+ * @param {boolean} [opts.includeAuthorizeUrl] default true — print URL when
+ *                                              awaiting_consent so headless
+ *                                              operators can paste it.
+ */
+function subscribeProgress(client, out, opts = {}) {
+  const includeProgress = opts.includeProgress !== false;
+  const includeAuthorizeUrl = opts.includeAuthorizeUrl !== false;
+  client.on('state', ({ to, data }) => {
+    const label = PROGRESS_LABEL[to];
+    if (label) out.push(label);
+    if (includeAuthorizeUrl && to === STATES.AWAITING_CONSENT && data && data.authorizeUrl) {
+      out.push(`  If a browser tab does not open, paste this URL:`);
+      out.push(`  ${data.authorizeUrl}`);
+    }
+  });
+  if (includeProgress) {
+    client.on('progress', ({ message, data }) => {
+      // Pull a couple of useful fields out for the operator without dumping
+      // raw JSON. Keep it terse.
+      if (message === 'discovery_succeeded' && data && data.asMetadataUrl) {
+        out.push(`  Authorization server: ${data.asMetadataUrl}`);
+      } else if (message === 'registered' && data && data.clientId) {
+        out.push(`  Registered client: ${data.clientId}`);
+      } else if (message === 'callback_received') {
+        out.push('  Consent received from browser');
+      } else if (message === 'browser_launch_failed') {
+        out.push('  (Browser launch failed — paste the URL above into your browser)');
+      } else if (message === 'reusing_persisted_client_id' && data && data.clientId) {
+        out.push(`  Reusing persisted client_id: ${data.clientId}`);
+      }
+    });
+  }
+}
+
+/**
+ * Render a list of `sites` per F.5 example:
+ *
+ *   SITE        URL                          AUTH        USER         SCOPES                EXPIRES
+ *   siteA       https://siteA.com            oauth       wp_agent     read, write, menus    in 87 days
+ *
+ * @param {Array<{
+ *   siteId: string,
+ *   url: string,
+ *   authMethod: string,
+ *   user: string,
+ *   scopesShort: string,
+ *   expires: string,
+ *   statusBadge: string,
+ *   downgradeAnnotation: string,
+ * }>} rows
+ * @param {object} [opts]
+ * @param {number} [opts.maxWidth]    Default 120 — wraps wide tables to fit.
+ * @returns {string[]} lines
+ */
+function renderSiteTable(rows, opts = {}) {
+  if (!rows.length) {
+    return ['(no sites configured — run: abilities-mcp add-site <url>)'];
+  }
+  const headers = ['SITE', 'URL', 'AUTH', 'USER', 'SCOPES', 'EXPIRES', 'STATUS'];
+  const widths = headers.map((h) => h.length);
+  for (const r of rows) {
+    widths[0] = Math.max(widths[0], r.siteId.length);
+    widths[1] = Math.max(widths[1], r.url.length);
+    widths[2] = Math.max(widths[2], r.authMethod.length);
+    widths[3] = Math.max(widths[3], r.user.length);
+    widths[4] = Math.max(widths[4], r.scopesShort.length);
+    widths[5] = Math.max(widths[5], r.expires.length);
+    widths[6] = Math.max(widths[6], r.statusBadge.length);
+  }
+  const fmt = (cells) => cells.map((c, i) => String(c).padEnd(widths[i])).join('  ').trimEnd();
+  const lines = [];
+  lines.push(fmt(headers));
+  for (const r of rows) {
+    lines.push(fmt([
+      r.siteId, r.url, r.authMethod, r.user, r.scopesShort, r.expires, r.statusBadge,
+    ]));
+    if (r.downgradeAnnotation) {
+      lines.push(`  ${r.downgradeAnnotation}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Compute a human "in N days" / "expired" string from an ISO timestamp.
+ * @param {string|null|undefined} iso
+ * @param {number} [nowMs]
+ * @returns {string}
+ */
+function expiresLabel(iso, nowMs) {
+  if (!iso) return '—';
+  const at = Date.parse(iso);
+  if (Number.isNaN(at)) return '—';
+  const now = typeof nowMs === 'number' ? nowMs : Date.now();
+  const days = Math.floor((at - now) / (24 * 3600 * 1000));
+  if (days < 0) return `expired ${-days}d ago`;
+  if (days === 0) return 'today';
+  if (days === 1) return 'in 1 day';
+  return `in ${days} days`;
+}
+
+/**
+ * Compact rendering of a scope list for the EXPIRES table.
+ * Drops the `abilities:` prefix and joins with commas. Truncates to 4 entries
+ * with a "+N" suffix to keep the table readable.
+ *
+ * @param {string[]} scopes
+ * @returns {string}
+ */
+function shortScopes(scopes) {
+  if (!Array.isArray(scopes) || scopes.length === 0) return '(full)';
+  const trimmed = scopes.map((s) => s.replace(/^abilities:/, ''));
+  if (trimmed.length <= 4) return trimmed.join(', ');
+  return trimmed.slice(0, 3).join(', ') + ` +${trimmed.length - 3}`;
+}
+
+/**
+ * Render the trailing "next action" hint for a failed CliError.
+ * @param {import('./errors').CliError} err
+ * @returns {string[]}
+ */
+function renderNextAction(err) {
+  const lines = [`✗ ${err.message}`];
+  if (err.nextAction) lines.push(`  → ${err.nextAction}`);
+  return lines;
+}
+
+module.exports = {
+  subscribeProgress,
+  renderSiteTable,
+  renderNextAction,
+  expiresLabel,
+  shortScopes,
+  PROGRESS_LABEL,
+};

package/lib/cli/parse-args.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * Minimal CLI arg parser for the abilities-mcp subcommand surface.
+ *
+ * Supported forms:
+ *   <subcommand> <positional...> [--flag] [--key=value] [--key value]
+ *
+ * Boolean flags: `--debug`, `--apppassword`, `--confirm`, `--force`,
+ * `--allow-insecure`, `--i-understand-the-risk`.
+ *
+ * Value flags accept either `--key=value` or `--key value` form.
+ *
+ * Long options only — no short forms — to keep the surface small and
+ * predictable. The argv array starts at the subcommand (i.e. caller has
+ * already sliced argv to remove `node` / script path).
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+// Keys we treat as boolean even when they appear as `--key value` — value
+// will be left as a positional. (Currently empty; we use the "next token
+// is a flag → boolean" heuristic, which works for our flags.)
+const BOOLEAN_FLAGS = new Set([
+  'debug',
+  'apppassword',
+  'confirm',
+  'force',
+  'allow-insecure',
+  'i-understand-the-risk',
+]);
+
+/**
+ * @param {string[]} argv  Tokens after the subcommand name.
+ * @returns {object}        { _: [...positionals], <flag>: <value|true>, ... }
+ */
+function parse(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === '--') {
+      // Everything after `--` is positional.
+      for (let j = i + 1; j < argv.length; j++) out._.push(argv[j]);
+      break;
+    }
+    if (tok.startsWith('--')) {
+      const eq = tok.indexOf('=');
+      if (eq > -1) {
+        const key = tok.slice(2, eq);
+        const value = tok.slice(eq + 1);
+        out[key] = _coerce(value);
+        continue;
+      }
+      const key = tok.slice(2);
+      if (BOOLEAN_FLAGS.has(key)) {
+        out[key] = true;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        out[key] = true;
+        continue;
+      }
+      out[key] = _coerce(next);
+      i++;
+    } else {
+      out._.push(tok);
+    }
+  }
+  return out;
+}
+
+function _coerce(s) {
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  return s;
+}
+
+module.exports = { parse, BOOLEAN_FLAGS };