@indigoai-us/hq-cli 5.50.0 → 5.50.2

package/src/commands/mcp-status.ts

@@ -0,0 +1,575 @@
+/**
+ * hq mcp status — read-only observability over installed MCP packs across BOTH
+ * runtimes (Claude + Codex). US-011.
+ *
+ * This closes the US-009 gap: the old symlink-only `linkStatus` structurally
+ * cannot see a JSON/TOML *merge* (an MCP server is MERGED into the shared agent
+ * configs, never symlinked). So status reads the PROVENANCE marker `_hqPack`
+ * directly off the server defs in `~/.claude.json` + `~/.codex/config.toml`,
+ * enumerates every HQ-owned server, and reports — PER runtime — present? parses?
+ * matches-or-drifted? It surfaces PARTIAL explicitly (registered in one runtime
+ * but not the other, naming the missing runtime) and lists the most-recent
+ * backups so a corrupted config has a discoverable restore target.
+ *
+ * SECRET SAFETY (hard rule): header/env VALUES are NEVER rendered in the clear.
+ * Status reads configs that hold RESOLVED secrets (the runtime needs real
+ * headers), and we do NOT have the raw secret-set at status time — so we redact
+ * by KEY presence: header/env KEYS are shown, every value is rendered as
+ * {@link SECRET_REDACTION}, and no value is ever compared in the clear.
+ *
+ * The pure {@link computeMcpStatus} + {@link renderMcpStatus} functions are
+ * exported so tests (and CI / US-013) can drive them WITHOUT going through
+ * commander; {@link registerMcpCommand} wires the `hq mcp status` command group.
+ */
+import * as fs from 'fs';
+import { Command } from 'commander';
+
+import {
+  HQ_PACK_PROVENANCE_KEY,
+  SECRET_REDACTION,
+  backupRoot,
+  claudeConfigFormat,
+  claudeConfigPath,
+  codexConfigFormat,
+  codexConfigPath,
+  CODEX_MCP_SERVERS_KEY,
+  ConfigParseError,
+  isCodexInstalled,
+  readConfigDoc,
+  resolveEnv,
+  type SafeWriteEnv,
+} from './mcp-registration.js';
+
+// ---------------------------------------------------------------------------
+// Report shape.
+// ---------------------------------------------------------------------------
+
+/** A server's presence on ONE runtime surface. */
+export type PresenceState =
+  /** The server def is present (and parsed) on this runtime. */
+  | 'present'
+  /** The runtime parsed fine but this server is not registered there. */
+  | 'absent'
+  /** The runtime's config is malformed (unparseable) — presence is unknowable. */
+  | 'unparseable'
+  /** The runtime is not installed (Codex only: `~/.codex` missing). */
+  | 'not-installed';
+
+/** Per-runtime, per-server status. */
+export interface RuntimeServerStatus {
+  /** present / absent / unparseable / not-installed. */
+  presence: PresenceState;
+  /** The transport read off this runtime's def (undefined when absent). */
+  transport?: string;
+  /** The target (url or command+args) read off this runtime's def (undefined when absent). */
+  target?: string;
+  /** Header KEYS present on this runtime's def (values are NEVER captured). */
+  headerKeys?: string[];
+  /** Env KEYS present on this runtime's def (values are NEVER captured). */
+  envKeys?: string[];
+}
+
+/** A single HQ-owned MCP server's cross-runtime status. */
+export interface McpServerStatus {
+  /** The bare server name (the `mcpServers` / `mcp_servers` key). */
+  server: string;
+  /** The pack that owns it (`_hqPack` provenance). */
+  pack: string;
+  /** The transport (from whichever runtime has the def; '' when neither). */
+  transport: string;
+  /** The target — url (http/sse) or command+args (stdio); '' when unknown. NEVER a secret. */
+  target: string;
+  /** Claude-runtime status. */
+  claude: RuntimeServerStatus;
+  /** Codex-runtime status. */
+  codex: RuntimeServerStatus;
+  /**
+   * True iff the server is present on EXACTLY ONE of the two runtimes (a partial
+   * registration). When Codex is not installed and the server is Claude-only, this
+   * is still PARTIAL — `partialReason` names the missing runtime.
+   */
+  partial: boolean;
+  /** Human-readable reason naming the missing runtime when `partial`. */
+  partialReason?: string;
+  /**
+   * True iff the server is present on BOTH runtimes but the transport-relevant
+   * content differs (transport, target, or header/env KEY sets). Header VALUES are
+   * never compared.
+   */
+  drifted: boolean;
+}
+
+/** A runtime's top-level status. */
+export interface RuntimeStatus {
+  /** Whether the runtime is installed (Claude is always; Codex iff `~/.codex` exists). */
+  installed: boolean;
+  /** Whether the runtime's config parsed (false => unparseable). */
+  parses: boolean;
+  /** The config file path inspected. */
+  configPath: string;
+}
+
+/** The structured `hq mcp status` report. */
+export interface McpStatusReport {
+  /** Every HQ-owned server, keyed by name, with cross-runtime status. */
+  servers: McpServerStatus[];
+  /** Per-runtime top-level status. */
+  runtimes: {
+    claude: RuntimeStatus;
+    codex: RuntimeStatus;
+  };
+  /** The backup root + the most-recent backup directory names (restore targets). */
+  backups: {
+    /** `~/.hq/backups/mcp` — where US-006 writes pre-write snapshots. */
+    root: string;
+    /** The most-recent backup dir NAMES (`<iso>-<pack>`), newest first (capped). */
+    recent: string[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pure status computation.
+// ---------------------------------------------------------------------------
+
+/** How many recent backup dirs to surface. */
+const MAX_RECENT_BACKUPS = 5;
+
+/** Read provenance (`_hqPack`) off a def; non-empty string => HQ-owned. */
+function provenanceOf(def: unknown): string | undefined {
+  if (def === null || typeof def !== 'object' || Array.isArray(def)) return undefined;
+  const stamp = (def as Record<string, unknown>)[HQ_PACK_PROVENANCE_KEY];
+  return typeof stamp === 'string' && stamp.length > 0 ? stamp : undefined;
+}
+
+/** The transport string off a def (`type`), or '' when not a string. */
+function transportOf(def: Record<string, unknown>): string {
+  return typeof def.type === 'string' ? def.type : '';
+}
+
+/**
+ * The target off a def — url (http/sse) or command(+args) (stdio). NEVER a
+ * header/secret. '' when neither a url nor a command is present.
+ */
+function targetOf(def: Record<string, unknown>): string {
+  const type = transportOf(def);
+  if ((type === 'http' || type === 'sse') && typeof def.url === 'string') return def.url;
+  if (typeof def.command === 'string') {
+    const args = Array.isArray(def.args) && def.args.length > 0 ? ` ${def.args.join(' ')}` : '';
+    return `${def.command}${args}`;
+  }
+  if (typeof def.url === 'string') return def.url;
+  return '';
+}
+
+/** Header KEYS off a def (values NEVER captured). */
+function headerKeysOf(def: Record<string, unknown>): string[] {
+  const h = def.headers;
+  if (!h || typeof h !== 'object' || Array.isArray(h)) return [];
+  return Object.keys(h as Record<string, unknown>).sort();
+}
+
+/** Env KEYS off a def (values NEVER captured). */
+function envKeysOf(def: Record<string, unknown>): string[] {
+  const e = def.env;
+  if (!e || typeof e !== 'object' || Array.isArray(e)) return [];
+  return Object.keys(e as Record<string, unknown>).sort();
+}
+
+/** A normalized, value-free view of a def for drift comparison. */
+interface DefSummary {
+  transport: string;
+  target: string;
+  headerKeys: string[];
+  envKeys: string[];
+}
+
+/** Summarize a def into its transport-relevant, value-FREE content (for drift). */
+function summarizeDef(def: Record<string, unknown>): DefSummary {
+  return {
+    transport: transportOf(def),
+    target: targetOf(def),
+    headerKeys: headerKeysOf(def),
+    envKeys: envKeysOf(def),
+  };
+}
+
+/** True iff two def summaries differ in any transport-relevant field (header VALUES never compared). */
+function summariesDiffer(a: DefSummary, b: DefSummary): boolean {
+  return JSON.stringify(a) !== JSON.stringify(b);
+}
+
+/** A runtime's HQ-owned server defs, keyed by name, plus parse/installed flags. */
+interface RuntimeScan {
+  installed: boolean;
+  parses: boolean;
+  configPath: string;
+  /** name -> { def, pack } for every HQ-owned (provenance-stamped) server. */
+  hqServers: Map<string, { def: Record<string, unknown>; pack: string }>;
+}
+
+/** Scan the Claude runtime: read `~/.claude.json`, collect HQ-owned servers. */
+function scanClaude(env: SafeWriteEnv): RuntimeScan {
+  const configPath = claudeConfigPath(env);
+  const hqServers = new Map<string, { def: Record<string, unknown>; pack: string }>();
+  let parses = true;
+  try {
+    const { doc } = readConfigDoc(configPath, claudeConfigFormat);
+    const servers = doc.mcpServers as Record<string, unknown> | undefined;
+    if (servers && typeof servers === 'object' && !Array.isArray(servers)) {
+      for (const [name, def] of Object.entries(servers)) {
+        const pack = provenanceOf(def);
+        if (pack !== undefined) {
+          hqServers.set(name, { def: def as Record<string, unknown>, pack });
+        }
+      }
+    }
+  } catch (e) {
+    if (e instanceof ConfigParseError) {
+      parses = false; // malformed — report unparseable, do NOT crash the command.
+    } else {
+      throw e; // ConfigPermissionError or anything unexpected — surface it.
+    }
+  }
+  return { installed: true, parses, configPath, hqServers };
+}
+
+/** Scan the Codex runtime: only when installed; read `~/.codex/config.toml`. */
+function scanCodex(env: SafeWriteEnv): RuntimeScan {
+  const configPath = codexConfigPath(env);
+  const hqServers = new Map<string, { def: Record<string, unknown>; pack: string }>();
+  if (!isCodexInstalled(env)) {
+    return { installed: false, parses: true, configPath, hqServers };
+  }
+  let parses = true;
+  try {
+    const { doc } = readConfigDoc(configPath, codexConfigFormat);
+    const servers = doc.value[CODEX_MCP_SERVERS_KEY] as Record<string, unknown> | undefined;
+    if (servers && typeof servers === 'object' && !Array.isArray(servers)) {
+      for (const [name, def] of Object.entries(servers)) {
+        const pack = provenanceOf(def);
+        if (pack !== undefined) {
+          hqServers.set(name, { def: def as Record<string, unknown>, pack });
+        }
+      }
+    }
+  } catch (e) {
+    if (e instanceof ConfigParseError) {
+      parses = false;
+    } else {
+      throw e;
+    }
+  }
+  return { installed: true, parses, configPath, hqServers };
+}
+
+/** Build the per-runtime, per-server status from a scan (or its absence). */
+function runtimeServerStatus(
+  scan: RuntimeScan,
+  name: string,
+): RuntimeServerStatus {
+  if (!scan.installed) return { presence: 'not-installed' };
+  if (!scan.parses) return { presence: 'unparseable' };
+  const found = scan.hqServers.get(name);
+  if (!found) return { presence: 'absent' };
+  return {
+    presence: 'present',
+    transport: transportOf(found.def),
+    target: targetOf(found.def),
+    headerKeys: headerKeysOf(found.def),
+    envKeys: envKeysOf(found.def),
+  };
+}
+
+/** List the most-recent backup dir names under `backupRoot` (newest first, capped). */
+function recentBackups(env: SafeWriteEnv): string[] {
+  const root = backupRoot(env);
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    // ENOENT (no backups yet) or unreadable — surface an empty list.
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    // Names are `<iso>-<pack>` with a sortable UTC stamp prefix — desc = newest first.
+    .sort((a, b) => (a < b ? 1 : a > b ? -1 : 0))
+    .slice(0, MAX_RECENT_BACKUPS);
+}
+
+/**
+ * Compute the cross-runtime MCP status report. PURE (modulo filesystem reads):
+ * reads `~/.claude.json` + `~/.codex/config.toml` (Codex only when installed),
+ * enumerates HQ-owned servers (those with a non-empty `_hqPack`), and annotates
+ * each with per-runtime presence, PARTIAL (present in exactly one runtime, missing
+ * runtime named), and DRIFT (present in both but transport/target/header-keys
+ * differ). A malformed config marks that runtime `parses:false`/`unparseable`
+ * rather than throwing. Header VALUES are never read into the report.
+ */
+export function computeMcpStatus(env: SafeWriteEnv): McpStatusReport {
+  const claudeScan = scanClaude(env);
+  const codexScan = scanCodex(env);
+
+  // Union of every HQ-owned server name across both runtimes.
+  const names = new Set<string>([...claudeScan.hqServers.keys(), ...codexScan.hqServers.keys()]);
+
+  const servers: McpServerStatus[] = [];
+  for (const name of [...names].sort()) {
+    const claude = runtimeServerStatus(claudeScan, name);
+    const codex = runtimeServerStatus(codexScan, name);
+
+    // Prefer whichever runtime has the def for the top-level transport/target.
+    const claudeFound = claudeScan.hqServers.get(name);
+    const codexFound = codexScan.hqServers.get(name);
+    const repDef = claudeFound?.def ?? codexFound?.def;
+    const pack = claudeFound?.pack ?? codexFound?.pack ?? '';
+    const transport = repDef ? transportOf(repDef) : '';
+    const target = repDef ? targetOf(repDef) : '';
+
+    const onClaude = claude.presence === 'present';
+    const onCodex = codex.presence === 'present';
+
+    // PARTIAL = present in exactly one runtime. Name the missing runtime.
+    let partial = false;
+    let partialReason: string | undefined;
+    if (onClaude && !onCodex) {
+      partial = true;
+      partialReason = codexScan.installed
+        ? 'registered in Claude but NOT in Codex'
+        : 'registered in Claude; Codex runtime not installed (server not registered in Codex)';
+    } else if (onCodex && !onClaude) {
+      partial = true;
+      partialReason = 'registered in Codex but NOT in Claude';
+    }
+
+    // DRIFT = present in both but transport-relevant content differs (no header VALUES).
+    let drifted = false;
+    if (onClaude && onCodex && claudeFound && codexFound) {
+      drifted = summariesDiffer(summarizeDef(claudeFound.def), summarizeDef(codexFound.def));
+    }
+
+    servers.push({
+      server: name,
+      pack,
+      transport,
+      target,
+      claude,
+      codex,
+      partial,
+      partialReason,
+      drifted,
+    });
+  }
+
+  return {
+    servers,
+    runtimes: {
+      claude: {
+        installed: claudeScan.installed,
+        parses: claudeScan.parses,
+        configPath: claudeScan.configPath,
+      },
+      codex: {
+        installed: codexScan.installed,
+        parses: codexScan.parses,
+        configPath: codexScan.configPath,
+      },
+    },
+    backups: {
+      root: backupRoot(env),
+      recent: recentBackups(env),
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Human-readable rendering.
+// ---------------------------------------------------------------------------
+
+/** Render one runtime's per-server line. Header/env VALUES are NEVER printed. */
+function renderRuntimeLine(label: string, st: RuntimeServerStatus): string {
+  switch (st.presence) {
+    case 'present': {
+      const parts: string[] = [`present`];
+      if (st.headerKeys && st.headerKeys.length > 0) {
+        parts.push(`headers: ${st.headerKeys.map((k) => `${k}=${SECRET_REDACTION}`).join(', ')}`);
+      }
+      if (st.envKeys && st.envKeys.length > 0) {
+        parts.push(`env: ${st.envKeys.map((k) => `${k}=${SECRET_REDACTION}`).join(', ')}`);
+      }
+      return `    ${label}: ${parts.join('  |  ')}`;
+    }
+    case 'absent':
+      return `    ${label}: absent`;
+    case 'unparseable':
+      return `    ${label}: UNPARSEABLE (config malformed)`;
+    case 'not-installed':
+      return `    ${label}: not installed`;
+  }
+}
+
+/**
+ * Render the report as human-readable text. Per server: name, pack, transport,
+ * target, and a per-runtime line. PARTIAL servers are marked loudly with the
+ * missing runtime NAMED; DRIFT is flagged. Header/env VALUES are rendered as
+ * {@link SECRET_REDACTION} — never the value. Ends with the backup restore hint.
+ */
+export function renderMcpStatus(report: McpStatusReport): string {
+  const lines: string[] = [];
+  lines.push('HQ MCP status — installed packs across Claude + Codex');
+  lines.push('');
+
+  // Runtime header.
+  const c = report.runtimes.claude;
+  const x = report.runtimes.codex;
+  lines.push(
+    `Runtimes:  Claude [${c.parses ? 'ok' : 'UNPARSEABLE'}]  ` +
+      `Codex [${!x.installed ? 'not installed' : x.parses ? 'ok' : 'UNPARSEABLE'}]`,
+  );
+  lines.push('');
+
+  if (report.servers.length === 0) {
+    lines.push('No HQ-owned MCP servers registered (no _hqPack provenance found in either runtime).');
+  } else {
+    for (const s of report.servers) {
+      const flags: string[] = [];
+      if (s.partial) flags.push('PARTIAL');
+      if (s.drifted) flags.push('DRIFTED');
+      const flagStr = flags.length > 0 ? `  <<< ${flags.join(' + ')}` : '';
+      lines.push(`• ${s.server}  (pack: ${s.pack})${flagStr}`);
+      lines.push(`    transport: ${s.transport || '(unknown)'}    target: ${s.target || '(none)'}`);
+      lines.push(renderRuntimeLine('Claude', s.claude));
+      lines.push(renderRuntimeLine('Codex ', s.codex));
+      if (s.partial && s.partialReason) {
+        lines.push(`    PARTIAL: ${s.partialReason}`);
+      }
+      if (s.drifted) {
+        lines.push(`    DRIFTED: Claude and Codex defs differ (transport/target/header-keys)`);
+      }
+      lines.push('');
+    }
+  }
+
+  // Backups (restore targets for a corrupted config).
+  lines.push(`Backups:   ${report.backups.root}`);
+  if (report.backups.recent.length > 0) {
+    lines.push(`  Most recent:`);
+    for (const b of report.backups.recent) {
+      lines.push(`    - ${b}`);
+    }
+    lines.push(
+      `  To restore a corrupted config, copy the snapshot from the newest dir above back into place.`,
+    );
+  } else {
+    lines.push(`  (no backups yet)`);
+  }
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Capability advertisement (US-012).
+//
+// `hq` advertises that THIS hq-cli supports the `contributes.mcp` capability —
+// dual-runtime (Claude + Codex) MCP server registration. This is the CLI-side
+// half of the 15.1.0 platform-GA cut: the host advertises support via its
+// `core.yaml` hqVersion (>=15.1.0 carries contributes.mcp), and the CLI
+// advertises support via this command. A consumer/CI can read `hq mcp
+// capabilities --json` to confirm the running CLI is MCP-aware before relying on
+// an MCP-bearing pack install (the skew guard — see the 15.1.0 changelog).
+//
+// Pure split mirrors computeMcpStatus/renderMcpStatus: computeMcpCapabilities()
+// returns a static structured object (no IO), renderMcpCapabilities() formats it.
+// ---------------------------------------------------------------------------
+
+/** The structured capability advertisement for this hq-cli. */
+export interface McpCapabilities {
+  /** This hq-cli supports MCP pack registration. */
+  supportsMcp: boolean;
+  /** The pack contribution types this CLI can register (currently just `mcp`). */
+  contributes: string[];
+  /** The agent runtimes MCP servers are registered into. */
+  runtimes: string[];
+  /** The MCP transports this CLI can emit. */
+  transports: string[];
+}
+
+/**
+ * Compute this hq-cli's MCP capability advertisement. PURE — no IO, no env: the
+ * answer is a property of the CLI build itself (it supports `contributes.mcp`
+ * dual-runtime registration), so it returns a static structured object. Kept as a
+ * helper (not inlined into the action) so tests / CI can assert the advert shape
+ * without commander, mirroring {@link computeMcpStatus}.
+ */
+export function computeMcpCapabilities(): McpCapabilities {
+  return {
+    supportsMcp: true,
+    contributes: ['mcp'],
+    runtimes: ['claude', 'codex'],
+    transports: ['http', 'stdio', 'sse'],
+  };
+}
+
+/** Render the capability advert as human-readable text. */
+export function renderMcpCapabilities(caps: McpCapabilities): string {
+  const lines: string[] = [];
+  lines.push('HQ MCP capabilities — what this hq-cli supports');
+  lines.push('');
+  lines.push(`  supports MCP: ${caps.supportsMcp ? 'yes' : 'no'}`);
+  lines.push(`  contributes:  ${caps.contributes.join(', ')}`);
+  lines.push(`  runtimes:     ${caps.runtimes.join(', ')}`);
+  lines.push(`  transports:   ${caps.transports.join(', ')}`);
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Command wiring.
+// ---------------------------------------------------------------------------
+
+/**
+ * Wire the `hq mcp` command group with a read-only `status` subcommand and a
+ * `capabilities` advertisement subcommand (US-012). `status` resolves the
+ * production env (real home), computes the report, and prints either
+ * `JSON.stringify(report, null, 2)` (`--json`, for CI / US-013) or the
+ * human-readable {@link renderMcpStatus} text. `capabilities` advertises that this
+ * hq-cli supports `contributes.mcp` ({@link computeMcpCapabilities} /
+ * {@link renderMcpCapabilities}). Follows the commander pattern used by
+ * {@link registerReindexCommand} and the subcommand-group pattern in index.ts.
+ */
+export function registerMcpCommand(program: Command): void {
+  const mcp = program
+    .command('mcp')
+    .description('MCP pack observability (read-only) across Claude + Codex');
+
+  mcp
+    .command('status')
+    .description(
+      'Show installed MCP packs/servers and their health in BOTH Claude and Codex (PARTIAL/DRIFT flagged; secrets redacted)',
+    )
+    .option('--json', 'Emit the structured report as JSON (for CI / scripting)')
+    .action((opts: { json?: boolean }) => {
+      const env = resolveEnv();
+      const report = computeMcpStatus(env);
+      if (opts.json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+      } else {
+        process.stdout.write(`${renderMcpStatus(report)}\n`);
+      }
+    });
+
+  mcp
+    .command('capabilities')
+    .description(
+      'Advertise that this hq-cli supports contributes.mcp (dual-runtime Claude+Codex registration)',
+    )
+    .option('--json', 'Emit the structured capability object as JSON (for CI / scripting)')
+    .action((opts: { json?: boolean }) => {
+      const caps = computeMcpCapabilities();
+      if (opts.json) {
+        process.stdout.write(`${JSON.stringify(caps, null, 2)}\n`);
+      } else {
+        process.stdout.write(`${renderMcpCapabilities(caps)}\n`);
+      }
+    });
+}