@anyslate/cli 0.1.0 → 0.3.0

package/src/commands/doctor.mjs

@@ -0,0 +1,616 @@
+// `anyslate doctor` (W4) — one command that prints every broken state.
+//
+// Designed against three simultaneously-broken states found live on one
+// machine, none of which produced a single signal anywhere:
+//   1. apiUrl ended in `/mcp` → the client appended another → permanent 404
+//   2. the token had been revoked (for an unknown length of time)
+//   3. the Claude Code hooks were never wired into ~/.claude/settings.json
+//
+// Ordering matters: the URL-shape check must run BEFORE any token verdict,
+// because a wrong URL 404s at app.notFound() before auth middleware and so
+// masks revocation, expiry and typos alike.
+//
+// Exit code: non-zero if any check FAILs. `doctor` is the one command whose
+// purpose is to fail loudly.
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  anyslateDir,
+  configPaths,
+  isCaptureDisabled,
+  loadConfig,
+  normalizeApiRoot,
+  requireToken,
+} from '../config.mjs';
+import { checkUrlShape, hasWriteScope, isValidTokenFormat, probeVerify, tokenPreview } from '../verify.mjs';
+import { hasOauthCredentials, isExpired, minutesUntilExpiry, resolveBearer } from '../auth.mjs';
+import { lastRunPath, readLastRun } from '../runlog.mjs';
+import { callTool } from '../mcp-client.mjs';
+import { VERSION, USER_AGENT } from '../version.mjs';
+import { makeIo } from '../io.mjs';
+
+const PASS = 'PASS';
+const FAIL = 'FAIL';
+const WARN = 'WARN';
+const SKIP = 'SKIP';
+
+const SETTINGS_BLOCK = `{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "anyslate hook session-start" }] }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|Bash",
+        "hooks": [{ "type": "command", "command": "anyslate hook post-tool-use" }]
+      }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "anyslate hook stop" }] }
+    ]
+  }
+}`;
+
+/**
+ * @param {string[]} argv
+ * @param {{fetchImpl?: typeof fetch, env?: NodeJS.ProcessEnv, out?: NodeJS.WritableStream,
+ *          probePath?: () => {status: string, found?: string|null, message?: string}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runDoctor(argv = [], deps = {}) {
+  const env = deps.env ?? process.env;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const { out } = makeIo({ stdout: deps.out ?? deps.stdout });
+  const probePath = deps.probePath ?? probeLoginShellPath;
+  const flags = parseFlags(argv);
+
+  const results = [];
+  const add = (status, id, message, remediation) => {
+    results.push({ status, id, message, remediation });
+  };
+
+  out.write(`anyslate doctor ${VERSION}\n\n`);
+
+  // ---- 0. Kill switch ----------------------------------------------------
+  if (isCaptureDisabled(env)) {
+    add(
+      WARN,
+      'kill-switch',
+      `ANYSLATE_DISABLE=${env.ANYSLATE_DISABLE} — capture is disabled for this shell.`,
+      'Unset ANYSLATE_DISABLE to re-enable capture. doctor still runs its checks so you can verify the setup while capture is off.',
+    );
+  }
+
+  // ---- 1. Config resolution ---------------------------------------------
+  const cfg = loadConfig(env);
+  const candidates = configPaths(env);
+  const fileFound = cfg.source !== 'env';
+
+  if (!fileFound && !env.ANYSLATE_MCP_TOKEN) {
+    add(
+      FAIL,
+      'config',
+      `No config found (looked in ${candidates.join(', ')}).`,
+      'Run `anyslate login --token <BEARER>`.',
+    );
+  } else if (fileFound && cfg.source.endsWith('session.json')) {
+    add(
+      FAIL,
+      'config',
+      `Using legacy ${cfg.source}.`,
+      'That is the desktop editor-state file and can never contain a token. Run `anyslate login`.',
+    );
+  } else {
+    // Render the per-key provenance as SHORT labels. `sources.*` carries the
+    // absolute config path, and printing an 80-char path three times on one
+    // line makes the single most important diagnostic unreadable.
+    const label = (v) => (v === 'env' ? 'env' : v === 'default' ? 'default' : 'file');
+    const layers = `apiUrl=${label(cfg.sources.apiUrl)}, token=${label(cfg.sources.mcpToken)}, handle=${label(cfg.sources.handle)}`;
+    add(PASS, 'config', `Resolved from ${fileFound ? cfg.source : 'environment'} (${layers}).`);
+    if (cfg.sources.apiUrl === 'env' && fileFound) {
+      add(
+        WARN,
+        'config-override',
+        `ANYSLATE_API_URL in your environment is overriding ${cfg.source}.`,
+        `Unset ANYSLATE_API_URL if that is not intended (env value: ${env.ANYSLATE_API_URL}).`,
+      );
+    }
+    if (cfg.sources.mcpToken === 'env' && fileFound) {
+      add(
+        WARN,
+        'token-override',
+        `ANYSLATE_MCP_TOKEN in your environment is overriding ${cfg.source}.`,
+        'Unset ANYSLATE_MCP_TOKEN if that is not intended.',
+      );
+    }
+  }
+
+  // ---- 2. Token present --------------------------------------------------
+  // "Present" now has three shapes: an env/static token, a live OAuth access
+  // token, or OAuth credentials whose access token has aged out but which carry
+  // a refresh token. The third is NOT a failure — the refresh happens further
+  // down, once the URL and reachability checks have cleared.
+  const oauthPresent = hasOauthCredentials(cfg.oauth);
+  const tokenCheck = requireToken(cfg);
+  if (!tokenCheck.ok && !oauthPresent) {
+    add(FAIL, 'token-present', 'No MCP token configured.', tokenCheck.error);
+  } else if (!tokenCheck.ok) {
+    add(
+      WARN,
+      'token-present',
+      'OAuth access token has expired; a refresh is needed before the next call.',
+      'This is normal — access tokens live one hour. The refresh is exercised by the oauth-refresh check below.',
+    );
+  } else {
+    add(
+      PASS,
+      'token-present',
+      `Token ${maskToken(cfg.mcpToken)} (from ${cfg.sources.mcpToken === 'env' ? 'ANYSLATE_MCP_TOKEN' : cfg.sources.mcpToken}).`,
+    );
+  }
+
+  // ---- 2a. Auth mode -----------------------------------------------------
+  // Pure config inspection, no network. Which credential the CLI would use is
+  // the first thing anyone debugging "capture stopped" needs to know, and it
+  // must be answerable even when the host is down.
+  if (cfg.sources.mcpToken === 'env' && cfg.mcpToken) {
+    add(PASS, 'auth-mode', 'Static token from ANYSLATE_MCP_TOKEN (env) — no refresh, never expires.');
+    if (oauthPresent) {
+      add(
+        WARN,
+        'auth-override',
+        'ANYSLATE_MCP_TOKEN is overriding a stored OAuth session.',
+        'Unset ANYSLATE_MCP_TOKEN to go back to the browser-issued credential.',
+      );
+    }
+  } else if (oauthPresent) {
+    const mins = minutesUntilExpiry(cfg.oauth);
+    const when =
+      mins == null
+        ? 'expiry unknown (no parseable expires_at)'
+        : mins >= 0
+          ? `expires in ${mins} min (${cfg.oauth.expires_at})`
+          : `expired ${Math.abs(mins)} min ago (${cfg.oauth.expires_at})`;
+    if (!cfg.oauth.refresh_token) {
+      add(
+        WARN,
+        'auth-mode',
+        `OAuth (browser sign-in), ${when}, no refresh token stored.`,
+        'Without a refresh token the session dies at expiry. Run `anyslate login` to get one.',
+      );
+    } else {
+      add(PASS, 'auth-mode', `OAuth (browser sign-in), ${when}, refresh token stored.`);
+    }
+  } else if (cfg.staticToken) {
+    add(PASS, 'auth-mode', `Static MCP token from ${cfg.sources.mcpToken} — no refresh, never expires.`);
+  } else {
+    add(SKIP, 'auth-mode', 'No credentials to classify.');
+  }
+
+  // ---- 2b. Handle FORMAT — never gated behind a server round trip ---------
+  // This is the exact live failure that produced a 100% invisible capture
+  // loss: cli/README.md told users to export `ANYSLATE_HANDLE=h_xxx`, but real
+  // handle ids are `mh_`-prefixed, so every call returned
+  // {"error":"handle_not_found"} as HTTP 200 + isError. It is pure string
+  // inspection, so it must NOT sit behind `verified.ok` (check #8) — otherwise
+  // any upstream breakage hides it, which is how it stayed invisible.
+  if (!cfg.handle) {
+    add(SKIP, 'handle-format', 'No handle configured (bearer-token scope).');
+  } else if (/^mh_/.test(cfg.handle)) {
+    add(PASS, 'handle-format', `Handle ${cfg.handle} has the expected \`mh_\` prefix.`);
+  } else {
+    add(
+      FAIL,
+      'handle-format',
+      `Handle "${cfg.handle}" (from ${cfg.sources.handle === 'env' ? 'ANYSLATE_HANDLE' : cfg.sources.handle}) is not a valid handle id — real ids are \`mh_\`-prefixed.`,
+      'Every call with an unknown handle fails as handle_not_found, which the server returns as HTTP 200 + isError. Unset ANYSLATE_HANDLE for workspace-wide capture, or copy a real `mh_…` id from Settings → MCP Tokens → Handles.',
+    );
+  }
+
+  // ---- 3. Token format ---------------------------------------------------
+  if (tokenCheck.ok) {
+    if (isValidTokenFormat(cfg.mcpToken)) {
+      add(PASS, 'token-format', 'Token matches as_mcp_<48 hex> or as_oauth_<64 hex>.');
+    } else {
+      add(
+        FAIL,
+        'token-format',
+        `That doesn't look like an AnySlate token (expected as_mcp_… or as_oauth_…, got "${tokenPreview(cfg.mcpToken)}").`,
+        'Mint one in the desktop app at Avatar (top-right) → API Tokens → Create Token.',
+      );
+    }
+  } else if (oauthPresent) {
+    add(SKIP, 'token-format', 'OAuth access token is past its expiry; the format is checked after it is refreshed.');
+  } else {
+    add(SKIP, 'token-format', 'No token to check.');
+  }
+
+  // ---- 4. URL shape (MUST run before #6) ---------------------------------
+  const shape = checkUrlShape(cfg.apiUrlRaw);
+  let root = cfg.apiUrl;
+  if (!shape.ok) {
+    add(FAIL, 'url-shape', shape.message, 'Run `anyslate login --api-url <service root>`.');
+  } else {
+    root = shape.root;
+    if (cfg.apiUrlNormalized) {
+      add(
+        WARN,
+        'url-shape',
+        `apiUrl "${cfg.apiUrlRaw}" ends in /mcp — the CLI wants the service ROOT and appends /mcp itself. Using "${root}".`,
+        `The read path self-heals this, but the stored value is still wrong. Run \`anyslate login --api-url ${root}\` to persist.`,
+      );
+    } else {
+      add(PASS, 'url-shape', `Service root resolves to ${root} (requests go to ${root}/mcp).`);
+    }
+  }
+
+  // ---- 5. Reachability, no token ----------------------------------------
+  let reachable = false;
+  if (shape.ok) {
+    const health = await probeHealth(root, fetchImpl);
+    if (health.ok) {
+      reachable = true;
+      if (health.degraded) {
+        add(
+          WARN,
+          'reachability',
+          `Service degraded: ${health.degraded}.`,
+          'Capture may fail — this is a service problem, not a config problem.',
+        );
+      } else {
+        add(PASS, 'reachability', `${root}/health responded 200.`);
+      }
+    } else if (health.status === 404) {
+      add(
+        FAIL,
+        'reachability',
+        `${root}/health returned 404 — not an AnySlate MCP service, or --api-url has a path prefix.`,
+        'Check the host in `anyslate login --api-url <root>`.',
+      );
+    } else {
+      add(FAIL, 'reachability', `Cannot reach ${shape.host} — ${health.detail}.`, 'Check --api-url and your network.');
+    }
+  } else {
+    add(SKIP, 'reachability', 'URL shape failed; not probing.');
+  }
+
+  // ---- 5b. OAuth refresh -------------------------------------------------
+  // Deliberately AFTER url-shape and reachability. A refresh against an
+  // unreachable host fails for a reason that has nothing to do with the
+  // credential, and reporting that as "refresh is broken" sends the user
+  // hunting for the wrong bug.
+  let bearer = cfg.mcpToken;
+  if (shape.ok && reachable && oauthPresent && cfg.sources.mcpToken !== 'env') {
+    const wasStale = isExpired(cfg.oauth) || flags.refresh;
+    const resolved = await resolveBearer({ cfg, env, fetchImpl, force: flags.refresh });
+    if (resolved.ok) {
+      bearer = resolved.token;
+      if (resolved.refreshed) {
+        add(PASS, 'oauth-refresh', 'Refreshed the access token successfully; the rotated refresh token was persisted.');
+      } else if (wasStale) {
+        add(PASS, 'oauth-refresh', 'Access token was already renewed by another process; nothing to do.');
+      } else {
+        add(
+          PASS,
+          'oauth-refresh',
+          'Refresh token is stored and the access token is still valid — refresh not exercised.',
+          'Run `anyslate doctor --refresh` to force a real refresh round trip (it rotates the refresh token).',
+        );
+      }
+    } else {
+      add(
+        FAIL,
+        'oauth-refresh',
+        `OAuth refresh failed: ${String(resolved.message).replace(/^anyslate: /, '')}`,
+        'Run `anyslate login` to sign in again. Refresh tokens live 30 days and are single-use (rotated on every refresh).',
+      );
+    }
+  } else if (oauthPresent && cfg.sources.mcpToken === 'env') {
+    add(SKIP, 'oauth-refresh', 'ANYSLATE_MCP_TOKEN is in use; the stored OAuth session is not consulted.');
+  } else if (oauthPresent) {
+    add(SKIP, 'oauth-refresh', 'Skipped — the URL and reachability checks must pass before a refresh is meaningful.');
+  } else {
+    add(SKIP, 'oauth-refresh', 'Not an OAuth session.');
+  }
+
+  // ---- 6. Token valid ----------------------------------------------------
+  let verified = null;
+  if (shape.ok && reachable && bearer) {
+    verified = await probeVerify({ root, token: bearer, fetchImpl });
+    if (verified.ok) {
+      add(PASS, 'token-valid', `${verified.message.replace(/^anyslate: /, '')}`);
+    } else {
+      add(FAIL, 'token-valid', verified.message.replace(/^anyslate: /, ''), remediationFor(verified.code));
+    }
+  } else {
+    add(SKIP, 'token-valid', 'Skipped — an earlier check must pass first (a wrong URL masks every token verdict).');
+  }
+
+  // ---- 7. Scope sufficient ----------------------------------------------
+  if (verified?.ok) {
+    if (hasWriteScope(verified.scopes)) {
+      add(PASS, 'scope', `Token scopes [${verified.scopes.join(',')}] include memory:write.`);
+    } else {
+      add(
+        FAIL,
+        'scope',
+        `Token scopes are [${(verified.scopes || []).join(',')}]; \`anyslate hook\` needs memory:write.`,
+        'Mint a token with the Memory profile.',
+      );
+    }
+  } else {
+    add(SKIP, 'scope', 'Token not verified.');
+  }
+
+  // ---- 8. Effective handle scope ----------------------------------------
+  if (verified?.ok) {
+    const bound = verified.defaultHandleId;
+    if (bound === undefined || (bound === null && !('default_handle_id' in (verified.raw ?? {})))) {
+      add(
+        WARN,
+        'handle-scope',
+        'Server did not report default_handle_id, so the effective memory scope cannot be shown.',
+        'Requires the /mcp/auth/verify companion change. Until then, check the token in Settings → MCP Tokens.',
+      );
+    } else if (bound) {
+      add(
+        WARN,
+        'handle-scope',
+        `Token is bound to handle ${bound} — capture is narrower than workspace-wide.`,
+        'ANYSLATE_HANDLE/--handle is ignored for scoped tokens (the dispatcher logs and discards it). Mint an unscoped token for workspace-wide capture.',
+      );
+    } else if (cfg.handle) {
+      add(
+        WARN,
+        'handle-scope',
+        `Token is unscoped, and ANYSLATE_HANDLE/--handle is set to ${cfg.handle}.`,
+        'Handle ids are `mh_`-prefixed. An unknown handle makes every call fail with handle_not_found (HTTP 200 + isError, which older CLI builds reported as success).',
+      );
+    } else {
+      add(PASS, 'handle-scope', 'Token is unscoped — workspace-wide capture.');
+    }
+  } else {
+    add(SKIP, 'handle-scope', 'Token not verified.');
+  }
+
+  // ---- 9. Binary on the hook subprocess's PATH --------------------------
+  const pathCheck = probePath();
+  if (pathCheck.status === SKIP) {
+    add(SKIP, 'path', pathCheck.message);
+  } else if (pathCheck.found) {
+    add(PASS, 'path', `Login-shell PATH resolves anyslate to ${pathCheck.found}.`);
+  } else {
+    add(
+      FAIL,
+      'path',
+      'anyslate is not on the login-shell PATH.',
+      `Claude Code spawns hooks with a minimal PATH — use the absolute path ${process.argv[1] ?? '/usr/local/bin/anyslate'} in ~/.claude/settings.json.`,
+    );
+  }
+
+  // ---- 10. Hooks wired ---------------------------------------------------
+  const hooks = inspectClaudeSettings(env);
+  if (hooks.error) {
+    add(FAIL, 'hooks', hooks.error, `Add this to ${hooks.path}:\n${indent(SETTINGS_BLOCK)}`);
+  } else {
+    for (const missing of hooks.missing) {
+      add(FAIL, 'hooks', `${missing} hook not wired.`, `Add this to ${hooks.path}:\n${indent(SETTINGS_BLOCK)}`);
+    }
+    if (!hooks.missing.length) {
+      add(PASS, 'hooks', `SessionStart, PostToolUse and Stop all invoke \`anyslate hook\` (${hooks.path}).`);
+    }
+    if (hooks.matcherGaps.length) {
+      add(
+        WARN,
+        'hooks-matcher',
+        `PostToolUse matcher does not cover ${hooks.matcherGaps.join(', ')}.`,
+        'Use "matcher": "Edit|Write|MultiEdit|Bash" so file edits and shell commands are both captured.',
+      );
+    }
+  }
+
+  // ---- 11. Last run outcome ---------------------------------------------
+  const last = readLastRun(env);
+  if (!last) {
+    add(
+      WARN,
+      'last-run',
+      `No run record at ${lastRunPath(env)} — this CLI has never run, or never got far enough to write one.`,
+      'If hooks are wired but there is no run record, the hook command is not being executed at all (check check #9 and #10).',
+    );
+  } else if (last.ok) {
+    add(PASS, 'last-run', `Last run ${last.ts} (${last.command}) succeeded.`);
+  } else {
+    add(
+      FAIL,
+      'last-run',
+      `Last run ${last.ts} (${last.command}) failed: ${last.error ?? 'unknown'} [http ${last.http_status ?? 'n/a'}]. ${last.consecutive_failures ?? 1} consecutive failure(s)${last.last_success_at ? `; last success ${last.last_success_at}` : '; no success on record'}.`,
+      'Fix whichever check above is FAILing, then re-run the command.',
+    );
+  }
+
+  // ---- 12. Live round trip (opt-in) -------------------------------------
+  if (flags.deep) {
+    if (verified?.ok) {
+      const res = await callTool({
+        apiUrl: root,
+        token: bearer,
+        toolName: 'activity_submit',
+        args: {
+          source: 'api',
+          kind: 'topic_shift',
+          payload: { notes: 'anyslate doctor probe', host_hint: 'cli-doctor', confidence: 0.1 },
+        },
+        fetchImpl,
+      });
+      if (res.ok) {
+        add(PASS, 'deep', `activity_submit round trip OK: ${JSON.stringify(res.data)}`);
+      } else {
+        const msg = typeof res.data === 'string' ? res.data : JSON.stringify(res.data);
+        add(FAIL, 'deep', `activity_submit failed: ${res.networkError ? msg : `server ${res.status} — ${msg}`}.`);
+      }
+    } else {
+      add(SKIP, 'deep', 'Token not verified; not writing a probe row.');
+    }
+  }
+
+  // ---- Render ------------------------------------------------------------
+  let failures = 0;
+  for (const r of results) {
+    if (r.status === FAIL) failures += 1;
+    out.write(`${r.status.padEnd(4)}  ${r.id.padEnd(16)}  ${r.message}\n`);
+    if (r.remediation) out.write(`${''.padEnd(4)}  ${''.padEnd(16)}  → ${r.remediation}\n`);
+  }
+
+  out.write('\n');
+  out.write(`user-agent: ${USER_AGENT}\n`);
+  if (failures) {
+    out.write(`\n${failures} check(s) FAILED.\n`);
+    return 1;
+  }
+  out.write('\nAll checks passed.\n');
+  return 0;
+}
+
+function remediationFor(code) {
+  switch (code) {
+    case 'revoked':
+      return 'Mint a new token at Avatar (top-right) → API Tokens, then re-run `anyslate login`.';
+    case 'expired':
+      return 'Mint a new token at Avatar (top-right) → API Tokens.';
+    case 'invalid_token':
+      return 'Check for a typo, or that you minted the token in the same environment (dev vs prod).';
+    case 'not_found':
+      return 'The host is not an AnySlate MCP service, or --api-url includes a path prefix.';
+    case 'authorization_required':
+      return 'This is a CLI bug — please report it.';
+    case 'unreachable':
+      return 'Check --api-url and your network.';
+    default:
+      return 'Re-run `anyslate login` against the correct environment.';
+  }
+}
+
+async function probeHealth(root, fetchImpl) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), 10_000);
+  try {
+    const res = await fetchImpl(`${root}/health`, {
+      method: 'GET',
+      headers: { accept: 'application/json', 'user-agent': USER_AGENT },
+      signal: ac.signal,
+    });
+    if (res.status === 404) return { ok: false, status: 404 };
+    if (!res.ok) return { ok: false, status: res.status, detail: `HTTP ${res.status}` };
+    let body = null;
+    try {
+      body = await res.json();
+    } catch {
+      body = null;
+    }
+    const checks = body?.checks && typeof body.checks === 'object' ? body.checks : null;
+    let degraded = null;
+    if (checks) {
+      const bad = Object.entries(checks).filter(([, v]) => v !== true && v !== 'ok' && v !== 'healthy');
+      if (bad.length) degraded = bad.map(([k, v]) => `${k}=${v}`).join(' ');
+    }
+    return { ok: true, status: res.status, degraded };
+  } catch (e) {
+    return { ok: false, status: 0, detail: String(e?.cause?.code ?? e?.message ?? e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Claude Code spawns hooks with a minimal, non-interactive PATH. Resolving
+ * `anyslate` from *this* process proves nothing — probe a login shell.
+ */
+function probeLoginShellPath() {
+  if (process.platform === 'win32') {
+    return { status: SKIP, message: 'Login-shell PATH probe is POSIX-only; skipped on Windows.' };
+  }
+  try {
+    const r = spawnSync('sh', ['-lc', 'command -v anyslate'], {
+      encoding: 'utf8',
+      timeout: 5_000,
+    });
+    const found = (r.stdout || '').trim();
+    return { status: 'ran', found: found || null };
+  } catch {
+    return { status: SKIP, message: 'Could not spawn a login shell to probe PATH.' };
+  }
+}
+
+function inspectClaudeSettings(env) {
+  const home = env.CLAUDE_HOME || homedir();
+  const path = join(home, '.claude', 'settings.json');
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      return { path, error: `${path} does not exist — Claude Code hooks are not wired.`, missing: [], matcherGaps: [] };
+    }
+    return { path, error: `${path} could not be parsed (${e?.message ?? e}).`, missing: [], matcherGaps: [] };
+  }
+
+  const hooks = parsed?.hooks;
+  if (!hooks || typeof hooks !== 'object') {
+    return { path, error: `${path} has no "hooks" key — Claude Code hooks are not wired.`, missing: [], matcherGaps: [] };
+  }
+
+  const missing = [];
+  const matcherGaps = [];
+  for (const eventName of ['SessionStart', 'PostToolUse', 'Stop']) {
+    const entries = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
+    const commands = [];
+    for (const entry of entries) {
+      const inner = Array.isArray(entry?.hooks) ? entry.hooks : [];
+      for (const h of inner) if (typeof h?.command === 'string') commands.push({ command: h.command, matcher: entry.matcher });
+    }
+    const hit = commands.find((c) => /anyslate\s+hook/.test(c.command));
+    if (!hit) {
+      missing.push(eventName);
+      continue;
+    }
+    if (eventName === 'PostToolUse') {
+      const matcher = String(hit.matcher ?? '');
+      if (matcher && matcher !== '*') {
+        for (const tool of ['Edit', 'Write', 'MultiEdit', 'Bash']) {
+          if (!matcher.includes(tool)) matcherGaps.push(tool);
+        }
+      }
+    }
+  }
+  return { path, missing, matcherGaps };
+}
+
+function maskToken(token) {
+  const s = String(token ?? '');
+  const prefixMatch = s.match(/^(as_mcp_|as_oauth_)/);
+  const prefix = prefixMatch ? prefixMatch[1] : s.slice(0, 4);
+  return `${prefix}…${s.slice(-4)}`;
+}
+
+function indent(block) {
+  return block
+    .split('\n')
+    .map((l) => `        ${l}`)
+    .join('\n');
+}
+
+/** @param {string[]} argv */
+function parseFlags(argv) {
+  const out = { deep: false, refresh: false };
+  for (const a of argv) {
+    if (a === '--deep') out.deep = true;
+    else if (a === '--refresh') out.refresh = true;
+  }
+  return out;
+}
+
+export const __testing = { inspectClaudeSettings, maskToken, SETTINGS_BLOCK, anyslateDir, normalizeApiRoot };