@indigoai-us/hq-cli 5.77.14 → 5.78.0

package/src/commands/mcp-status.ts

@@ -1,575 +0,0 @@
-/**
- * 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`);
-      }
-    });
-}