@wickedevolutions/abilities-mcp 1.3.1 → 1.5.1

package/lib/cli/commands/list-sites.js

@@ -0,0 +1,93 @@
+'use strict';
+
+const { AUTH_STATUS } = require('../../auth');
+const { readConfig } = require('../config-store');
+const { renderSiteTable, expiresLabel, shortScopes } = require('../output');
+const { CliError, EXIT_CONFIG } = require('../errors');
+
+/**
+ * `list-sites` — print a table of all sites + auth status.
+ *
+ * Columns chosen to match the F.5 example output:
+ *   SITE   URL   AUTH   USER   SCOPES   EXPIRES
+ * Phase 5 adds a STATUS column (active / expired / revoked / pending-reauth)
+ * because F.5 mandates the enum but the example didn't show it.
+ *
+ * H.2.3 mandates that `force-downgrade` actions are surfaced in `list-sites`
+ * for 30 days. We render an annotation line under the affected site row.
+ *
+ * Spec references:
+ *   - "CLI surface" main spec section (column choice)
+ *   - F.5 (auth_status enum + apppassword fallback presence)
+ *   - I.3 (status labels)
+ *   - H.2.3 (force-downgrade audit surfacing)
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const STATUS_BADGE = Object.freeze({
+  [AUTH_STATUS.ACTIVE]: 'active',
+  [AUTH_STATUS.EXPIRED]: 'expired',
+  [AUTH_STATUS.REVOKED]: 'revoked',
+  [AUTH_STATUS.PENDING_REAUTH]: 'pending-reauth',
+});
+
+async function run(args, ctx) {
+  let config;
+  try { config = readConfig(ctx.configPath); }
+  catch (err) {
+    if (err instanceof CliError && err.exitCode === EXIT_CONFIG && /not found/i.test(err.message)) {
+      return {
+        exitCode: 0,
+        lines: [
+          '(no sites configured — run: abilities-mcp add-site <url>)',
+        ],
+      };
+    }
+    throw err;
+  }
+
+  const nowMs = ctx.now ? ctx.now() : Date.now();
+  const rows = [];
+  for (const [siteId, site] of Object.entries(config.sites)) {
+    const auth = site.auth;
+    const isOAuth = auth.method === 'oauth';
+    const user = isOAuth ? (auth.user_login || '—') : (auth.username || '—');
+    const scopesShort = isOAuth ? shortScopes(auth.scopes) : '(full)';
+    const expires = isOAuth ? expiresLabel(auth.access_token_expires_at, nowMs) : '—';
+
+    let statusBadge = STATUS_BADGE[site.auth_status] || site.auth_status || '?';
+    // Decorate the badge with the apppassword-fallback signal — operators
+    // mid-upgrade will want to see it.
+    if (isOAuth && auth.apppassword_fallback) {
+      statusBadge += ' +apppassword-fallback';
+    }
+
+    let downgradeAnnotation = null;
+    if (site.force_downgrade) {
+      const expiresAt = Date.parse(site.force_downgrade.expires_at);
+      if (!Number.isNaN(expiresAt) && expiresAt > nowMs) {
+        const at = Date.parse(site.force_downgrade.at);
+        const days = Number.isNaN(at) ? '?' : Math.max(0, Math.floor((nowMs - at) / (24 * 3600 * 1000)));
+        downgradeAnnotation = `⚠ force-downgrade ${days}d ago${site.force_downgrade.reason ? ` (${site.force_downgrade.reason})` : ''}`;
+      }
+    }
+
+    rows.push({
+      siteId,
+      url: site.url || '—',
+      authMethod: auth.method,
+      user,
+      scopesShort,
+      expires,
+      statusBadge,
+      downgradeAnnotation,
+    });
+  }
+
+  const lines = renderSiteTable(rows);
+  return { exitCode: 0, lines };
+}
+
+module.exports = { run };

package/lib/cli/commands/reauth.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const {
+  OAuthClient,
+  TokenManager,
+  AUTH_STATUS,
+  DEFAULT_SCOPE,
+} = require('../../auth');
+const { CliError, EXIT_USAGE, fromAuthError } = require('../errors');
+const { subscribeProgress } = require('../output');
+const { readConfig, writeConfig } = require('../config-store');
+
+/**
+ * `reauth <site_id>` — re-run the OAuth flow for an existing site.
+ *
+ * Reuses the existing site URL and existing capability pin; mints a fresh
+ * client_id (FreshEachTimeIdentityProvider in v1.0); replaces the access /
+ * refresh tokens in keychain.
+ *
+ * Spec references:
+ *   - "CLI surface" main spec section
+ *   - F.5 (auth_status enum)
+ *   - H.2.3 (capabilityPin firstSeenAt is preserved across reauths)
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+async function run(args, ctx) {
+  const siteId = args._ && args._[0];
+  if (!siteId) {
+    throw new CliError('reauth requires a site_id argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp reauth <site_id>',
+    });
+  }
+  const config = readConfig(ctx.configPath);
+  const site = config.sites[siteId];
+  if (!site) {
+    throw new CliError(`reauth: unknown site_id "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: `Run: abilities-mcp list-sites to see configured sites`,
+    });
+  }
+  if (site.auth.method !== 'oauth') {
+    throw new CliError(`reauth: site "${siteId}" uses ${site.auth.method}, not OAuth`, {
+      exitCode: EXIT_USAGE,
+      nextAction: `Run: abilities-mcp upgrade-auth ${siteId} to migrate to OAuth`,
+    });
+  }
+
+  const out = [];
+  out.push(`Re-running OAuth flow for site "${siteId}" (${site.url})…`);
+
+  const clientName = `${ctx.userLabel}'s Operator (${ctx.hostnameLabel})`;
+  const OAuthClientCls = (ctx.deps && ctx.deps.OAuthClient) || OAuthClient;
+  const oauth = new OAuthClientCls({
+    siteUrl: site.url,
+    clientName,
+    softwareVersion: ctx.softwareVersion,
+    scope: args.scope || (Array.isArray(site.auth.scopes) ? site.auth.scopes : DEFAULT_SCOPE),
+    identityProvider: ctx.identityProvider,
+    allowInsecure: ctx.allowInsecure,
+    capabilityPin: site.oauth_capability_pinned ? {
+      firstSeenAt: site.oauth_capability_pinned.first_seen_at,
+    } : null,
+    deps: ctx.deps && ctx.deps.oauthClientDeps,
+  });
+  subscribeProgress(oauth, out);
+
+  let result;
+  try { result = await oauth.run(); }
+  catch (err) { throw fromAuthError(err, { siteId }); }
+
+  const tm = new TokenManager({ secretStore: ctx.secretStore, allowInsecure: ctx.allowInsecure });
+  const persisted = await tm.persistTokens({ siteId, tokens: result.tokens });
+
+  // Carry forward apppassword_fallback so an in-progress upgrade-auth
+  // (Step 2 done, Step 4 not yet run) is not silently undone by a reauth.
+  // Operators remove the fallback only via `upgrade-auth --confirm`.
+  const carryFallback = site.auth.apppassword_fallback || null;
+  site.auth = {
+    method: 'oauth',
+    client_id: result.clientId,
+    user_login: site.auth.user_login || ctx.userLabel || 'operator',
+    scopes: result.scopes,
+    access_token_expires_at: persisted.accessTokenExpiresAt,
+    refresh_token_expires_at: persisted.refreshTokenExpiresAt,
+    access_token_ref: persisted.accessTokenRef,
+    refresh_token_ref: persisted.refreshTokenRef,
+  };
+  if (carryFallback) site.auth.apppassword_fallback = carryFallback;
+
+  site.auth_status = AUTH_STATUS.ACTIVE;
+  site.oauth_capability_pinned = {
+    first_seen_at: result.capabilityPin.firstSeenAt,
+    last_confirmed_at: result.capabilityPin.lastConfirmedAt,
+  };
+  if (result.prMetadata && result.prMetadata.resource) {
+    site.mcp_resource = result.prMetadata.resource;
+  }
+  await writeConfig(ctx.configPath, config);
+
+  out.push(`✓ Site "${siteId}" re-authorized. Granted scopes: ${result.scopes.join(', ')}.`);
+  return { exitCode: 0, lines: out };
+}
+
+module.exports = { run };

package/lib/cli/commands/revoke.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const { TokenManager, AUTH_STATUS } = require('../../auth');
+const { resolveRef, parseRef } = require('../../auth/secret-store');
+const { discover } = require('../../auth/discovery-client');
+const { CliError, EXIT_USAGE, fromAuthError } = require('../errors');
+const { readConfig, writeConfig } = require('../config-store');
+
+/**
+ * `revoke <site_id>` — local + remote revocation.
+ *
+ * Per the sub-issue: "local keychain cleanup + remote /oauth/revoke call."
+ *
+ * Behavior:
+ *   1. Resolve the site's revocation_endpoint by re-running discovery (the
+ *      site config does not stash the AS metadata — we re-fetch).
+ *   2. POST refresh_token to /oauth/revoke (if present), then access_token.
+ *      RFC 7009: revoking refresh also revokes derived access tokens, but we
+ *      send both for adapters that don't cascade.
+ *   3. Delete the keychain entries for this site.
+ *   4. Mark auth_status = "revoked" in wp-sites.json so list-sites surfaces it.
+ *
+ * Errors are tolerated where the spirit is "best effort":
+ *   - 4xx on revoke is treated as success (server has a final say).
+ *   - 5xx / network error stops the flow before we delete keychain so the
+ *     operator can retry without losing the token.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+async function run(args, ctx) {
+  const siteId = args._ && args._[0];
+  if (!siteId) {
+    throw new CliError('revoke requires a site_id argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp revoke <site_id>',
+    });
+  }
+  const config = readConfig(ctx.configPath);
+  const site = config.sites[siteId];
+  if (!site) {
+    throw new CliError(`revoke: unknown site_id "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp list-sites to see configured sites',
+    });
+  }
+  if (site.auth.method !== 'oauth') {
+    throw new CliError(`revoke: site "${siteId}" uses ${site.auth.method}, not OAuth`, {
+      exitCode: EXIT_USAGE,
+      nextAction: `App Password sites are revoked by deleting the password in WordPress; use clear-keychain ${siteId} to remove the local copy`,
+    });
+  }
+
+  const out = [];
+  out.push(`Revoking OAuth tokens for site "${siteId}"…`);
+
+  // Re-discover to get the revocation_endpoint. Use the existing capability
+  // pin so a 404 on a previously-OAuth site still fails loud.
+  const discoverFn = (ctx.deps && ctx.deps.discover) || discover;
+  let asMetadata;
+  try {
+    const discovered = await discoverFn(site.url, {
+      pinned: !!site.oauth_capability_pinned,
+      pinnedFirstSeenAt: site.oauth_capability_pinned && site.oauth_capability_pinned.first_seen_at,
+      allowInsecure: ctx.allowInsecure,
+    });
+    asMetadata = discovered.asMetadata;
+  } catch (err) {
+    throw fromAuthError(err, { siteId });
+  }
+  const revocationEndpoint = asMetadata && asMetadata.revocation_endpoint;
+  if (!revocationEndpoint) {
+    out.push('  (Adapter does not advertise revocation_endpoint — skipping remote revocation, deleting local keychain only.)');
+  }
+
+  const tm = new TokenManager({ secretStore: ctx.secretStore, allowInsecure: ctx.allowInsecure });
+  if (revocationEndpoint) {
+    // Revoke refresh first (cascades on a compliant adapter), then access.
+    const tokenRefs = [
+      { kind: 'refresh_token', ref: site.auth.refresh_token_ref },
+      { kind: 'access_token', ref: site.auth.access_token_ref },
+    ];
+    for (const { kind, ref } of tokenRefs) {
+      if (!ref) continue;
+      let token;
+      try { token = await resolveRef(ctx.secretStore, ref); }
+      catch {
+        out.push(`  (No ${kind} present in keychain — skipping.)`);
+        continue;
+      }
+      try {
+        const res = await tm.revoke({
+          revocationEndpoint,
+          token,
+          clientId: site.auth.client_id,
+          tokenTypeHint: kind,
+        });
+        out.push(`  Remote revocation (${kind}): HTTP ${res.statusCode}`);
+      } catch (err) {
+        // 5xx → bail before we delete keychain (operator can retry).
+        throw fromAuthError(err, { siteId });
+      }
+    }
+  }
+
+  // Delete keychain entries. Per F.5, account names follow `<siteId>/<kind>`.
+  const accounts = [];
+  for (const ref of [site.auth.access_token_ref, site.auth.refresh_token_ref]) {
+    if (!ref) continue;
+    try { accounts.push(parseRef(ref).account); } catch { /* ignore malformed */ }
+  }
+  for (const account of accounts) {
+    await ctx.secretStore.delete('abilities-mcp', account).catch(() => {});
+  }
+
+  // Mark auth_status revoked rather than deleting the site — so the operator
+  // sees a record in list-sites and can choose to remove it later.
+  site.auth_status = AUTH_STATUS.REVOKED;
+  await writeConfig(ctx.configPath, config);
+
+  out.push(`✓ Site "${siteId}" revoked. Tokens deleted from keychain; auth_status = revoked.`);
+  out.push(`  Run: abilities-mcp reauth ${siteId} to start a fresh authorization.`);
+  return { exitCode: 0, lines: out };
+}
+
+module.exports = { run };

package/lib/cli/commands/self-check.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const { URL } = require('node:url');
+
+const { TokenManager, AUTH_STATUS } = require('../../auth');
+const { discover } = require('../../auth/discovery-client');
+const { request } = require('../../auth/http-json');
+const { CliError, EXIT_USAGE, fromAuthError } = require('../errors');
+const { readConfig } = require('../config-store');
+
+/**
+ * `self-check <site_id>` — Authorization-header survival probe (H.2.6).
+ *
+ * Hits `/wp-json/abilities-mcp-adapter/v1/oauth/echo-headers` with the OAuth
+ * bearer; that adapter endpoint returns presence/absence of expected headers
+ * (never the values). Reports whether the Authorization header survived the
+ * trip — many shared hosts strip it on FastCGI/PHP-FPM unless an .htaccess
+ * snippet recovers it.
+ *
+ * Per H.2.6: "the debug endpoint is OAuth-token-protected (so it's not a
+ * fingerprint surface) and returns only the **presence/absence** of expected
+ * headers, never the values."
+ *
+ * Spec is silent on whether self-check takes a site_id. The natural reading
+ * is yes (it requires an OAuth token, which lives per-site).
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const ECHO_HEADERS_PATH = '/wp-json/abilities-mcp-adapter/v1/oauth/echo-headers';
+
+async function run(args, ctx) {
+  const siteId = args._ && args._[0];
+  if (!siteId) {
+    throw new CliError('self-check requires a site_id argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp self-check <site_id>',
+    });
+  }
+  const config = readConfig(ctx.configPath);
+  const site = config.sites[siteId];
+  if (!site) {
+    throw new CliError(`self-check: unknown site_id "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp list-sites to see configured sites',
+    });
+  }
+  if (site.auth.method !== 'oauth') {
+    throw new CliError(`self-check: site "${siteId}" uses ${site.auth.method}, not OAuth`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'self-check probes the OAuth bearer path — only OAuth sites are supported',
+    });
+  }
+
+  const out = [];
+  out.push(`Probing Authorization-header survival on site "${siteId}"…`);
+
+  // Re-discover purely to find the token endpoint (for a possible refresh).
+  const discoverFn = (ctx.deps && ctx.deps.discover) || discover;
+  let asMetadata;
+  try {
+    const discovered = await discoverFn(site.url, {
+      pinned: !!site.oauth_capability_pinned,
+      pinnedFirstSeenAt: site.oauth_capability_pinned && site.oauth_capability_pinned.first_seen_at,
+      allowInsecure: ctx.allowInsecure,
+    });
+    asMetadata = discovered.asMetadata;
+  } catch (err) {
+    throw fromAuthError(err, { siteId });
+  }
+
+  const tm = new TokenManager({ secretStore: ctx.secretStore, allowInsecure: ctx.allowInsecure });
+  const siteAuthState = {
+    siteId,
+    tokenEndpoint: asMetadata.token_endpoint,
+    clientId: site.auth.client_id,
+    accessTokenRef: site.auth.access_token_ref,
+    refreshTokenRef: site.auth.refresh_token_ref,
+    accessTokenExpiresAt: site.auth.access_token_expires_at,
+    refreshTokenExpiresAt: site.auth.refresh_token_expires_at,
+    authStatus: site.auth_status || AUTH_STATUS.ACTIVE,
+  };
+  let accessToken;
+  try {
+    const tok = await tm.getAccessToken(siteAuthState);
+    accessToken = tok.accessToken;
+  } catch (err) {
+    throw fromAuthError(err, { siteId });
+  }
+
+  const url = new URL(ECHO_HEADERS_PATH, site.url).toString();
+  const requestFn = (ctx.deps && ctx.deps.request) || request;
+  let res;
+  try {
+    res = await requestFn({
+      url,
+      method: 'GET',
+      headers: { 'Authorization': `Bearer ${accessToken}`, 'Accept': 'application/json' },
+      allowInsecure: ctx.allowInsecure,
+    });
+  } catch (err) {
+    throw new CliError(`self-check: probe to ${url} failed: ${err.message}`, {
+      exitCode: 4,
+      nextAction: 'Verify the site is reachable and the adapter exposes /oauth/echo-headers',
+      cause: err,
+    });
+  }
+
+  if (res.statusCode === 404) {
+    return {
+      exitCode: 0,
+      lines: out.concat([
+        `(Adapter does not expose ${ECHO_HEADERS_PATH} on this site.)`,
+        '  This endpoint ships with abilities-mcp-adapter v1.5.0+. Older adapters cannot self-check.',
+      ]),
+    };
+  }
+  if (res.statusCode === 401 || res.statusCode === 403) {
+    throw new CliError(
+      `self-check: bearer rejected (HTTP ${res.statusCode}) reaching ${url}`,
+      {
+        exitCode: 4,
+        nextAction: `Run: abilities-mcp reauth ${siteId}`,
+      }
+    );
+  }
+  if (res.statusCode < 200 || res.statusCode >= 300 || !res.json) {
+    throw new CliError(
+      `self-check: adapter returned HTTP ${res.statusCode} (no JSON body)`,
+      {
+        exitCode: 4,
+        nextAction: 'Inspect the adapter logs for the failing request',
+      }
+    );
+  }
+
+  // The adapter's response shape (H.2.6): presence flags only.
+  const auth = !!(res.json.authorization_present || res.json.headers && res.json.headers.authorization);
+  out.push(`  Authorization header: ${auth ? '✓ Detected' : '⚠ NOT detected'}`);
+  // Common companion fields adapters may include.
+  if (typeof res.json.host_software === 'string') {
+    out.push(`  Adapter reports host: ${res.json.host_software}`);
+  }
+  if (Array.isArray(res.json.recovery_hints) && res.json.recovery_hints.length) {
+    out.push('  Recovery hints from adapter:');
+    for (const h of res.json.recovery_hints) out.push(`    - ${h}`);
+  }
+  if (!auth) {
+    out.push('');
+    out.push('Your hosting may be stripping the Authorization header on FastCGI/PHP-FPM.');
+    out.push('Apache: ship the .htaccess RewriteRule from H.2.6.');
+    out.push('LiteSpeed / Nginx: see the operator setup guide.');
+  }
+  return { exitCode: auth ? 0 : 4, lines: out };
+}
+
+module.exports = { run, ECHO_HEADERS_PATH };

package/lib/cli/commands/test.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const { TokenManager, AUTH_STATUS } = require('../../auth');
+const { resolveRef } = require('../../auth/secret-store');
+const { request } = require('../../auth/http-json');
+const { CliError, EXIT_USAGE, fromAuthError } = require('../errors');
+const { readConfig, writeConfig } = require('../config-store');
+const { shortScopes } = require('../output');
+
+/**
+ * `test <site_id>` — ping the adapter and report granted scopes.
+ *
+ * Behavior:
+ *   1. Resolve a current access token via TokenManager (refreshing if within
+ *      the 300s window per Appendix H.2.1).
+ *   2. Hit the resource (`mcp_resource` from F.5 / Phase 4 PR metadata) with
+ *      a tiny MCP `initialize` request — that is the lightest call WordPress
+ *      will accept and works on every adapter version.
+ *   3. Report status, scopes, expiry.
+ *
+ * On token refresh: the new tokens are written to keychain by TokenManager,
+ * and we persist the updated `access_token_expires_at` to wp-sites.json so
+ * subsequent calls don't refresh again.
+ *
+ * Spec references:
+ *   - "CLI surface" main spec section — "ping ability + show granted scopes"
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+async function run(args, ctx) {
+  const siteId = args._ && args._[0];
+  if (!siteId) {
+    throw new CliError('test requires a site_id argument', {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp test <site_id>',
+    });
+  }
+  const config = readConfig(ctx.configPath);
+  const site = config.sites[siteId];
+  if (!site) {
+    throw new CliError(`test: unknown site_id "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp list-sites to see configured sites',
+    });
+  }
+  if (site.auth.method !== 'oauth') {
+    throw new CliError(`test: site "${siteId}" uses ${site.auth.method}, not OAuth`, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'This subcommand currently exercises OAuth bearer authentication only',
+    });
+  }
+
+  const out = [];
+  out.push(`Testing site "${siteId}" (${site.url})…`);
+
+  // We need the token endpoint for refresh and the resource for the ping.
+  // The token endpoint is not stored in v2 config — we resolve it from the
+  // cached metadata only when needed. Phase 4 keeps the AS metadata
+  // ephemeral, so we re-discover here.
+  const { discover } = require('../../auth/discovery-client');
+  const discoverFn = (ctx.deps && ctx.deps.discover) || discover;
+  let asMetadata, prMetadata;
+  try {
+    const discovered = await discoverFn(site.url, {
+      pinned: !!site.oauth_capability_pinned,
+      pinnedFirstSeenAt: site.oauth_capability_pinned && site.oauth_capability_pinned.first_seen_at,
+      allowInsecure: ctx.allowInsecure,
+    });
+    asMetadata = discovered.asMetadata;
+    prMetadata = discovered.prMetadata;
+  } catch (err) {
+    throw fromAuthError(err, { siteId });
+  }
+
+  const tm = new TokenManager({ secretStore: ctx.secretStore, allowInsecure: ctx.allowInsecure });
+  const siteAuthState = {
+    siteId,
+    tokenEndpoint: asMetadata.token_endpoint,
+    clientId: site.auth.client_id,
+    accessTokenRef: site.auth.access_token_ref,
+    refreshTokenRef: site.auth.refresh_token_ref,
+    accessTokenExpiresAt: site.auth.access_token_expires_at,
+    refreshTokenExpiresAt: site.auth.refresh_token_expires_at,
+    authStatus: site.auth_status || AUTH_STATUS.ACTIVE,
+  };
+
+  let accessToken;
+  try {
+    const tok = await tm.getAccessToken(siteAuthState);
+    accessToken = tok.accessToken;
+    if (tok.refreshed && tok.updatedAuth) {
+      site.auth.access_token_expires_at = tok.updatedAuth.accessTokenExpiresAt;
+      site.auth.refresh_token_ref = tok.updatedAuth.refreshTokenRef;
+      site.auth_status = AUTH_STATUS.ACTIVE;
+      await writeConfig(ctx.configPath, config);
+      out.push('  (Refreshed access token before testing.)');
+    }
+  } catch (err) {
+    // RefreshError carries an updatedAuth on 4xx — persist it so future
+    // CLI calls see auth_status = expired immediately.
+    if (err && err.updatedAuth) {
+      site.auth_status = err.updatedAuth.authStatus;
+      try { await writeConfig(ctx.configPath, config); } catch { /* best effort */ }
+    }
+    throw fromAuthError(err, { siteId });
+  }
+
+  const resource = site.mcp_resource || (prMetadata && prMetadata.resource);
+  if (!resource) {
+    throw new CliError(`test: no MCP resource URL known for site "${siteId}"`, {
+      exitCode: EXIT_USAGE,
+      nextAction: `Run: abilities-mcp reauth ${siteId} to refresh the resource pointer`,
+    });
+  }
+
+  // Smallest MCP request we can send — initialize. The adapter answers with
+  // server capabilities, which is enough proof that the bearer survived.
+  const requestFn = (ctx.deps && ctx.deps.request) || request;
+  const body = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'abilities-mcp test', version: ctx.softwareVersion },
+    },
+  });
+  let res;
+  try {
+    res = await requestFn({
+      url: resource,
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+        'Accept': 'application/json, text/event-stream',
+      },
+      body,
+      allowInsecure: ctx.allowInsecure,
+    });
+  } catch (err) {
+    throw new CliError(`test: ping to ${resource} failed: ${err.message}`, {
+      exitCode: 4,
+      nextAction: 'Verify the site is reachable and the adapter is running',
+      cause: err,
+    });
+  }
+
+  if (res.statusCode === 401 || res.statusCode === 403) {
+    throw new CliError(
+      `test: bearer rejected (HTTP ${res.statusCode}) — token may be revoked or scope is missing`,
+      {
+        exitCode: 4,
+        nextAction: `Run: abilities-mcp reauth ${siteId}`,
+      }
+    );
+  }
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    throw new CliError(`test: adapter returned HTTP ${res.statusCode}`, {
+      exitCode: 4,
+      nextAction: 'Inspect the adapter logs for the failing request',
+    });
+  }
+
+  out.push(`✓ Reachable: ${resource} (HTTP ${res.statusCode})`);
+  out.push(`  Granted scopes: ${shortScopes(site.auth.scopes)}`);
+  out.push(`  Authenticated as: ${site.auth.user_login || '(unknown)'}`);
+  return { exitCode: 0, lines: out };
+}
+
+module.exports = { run };