@kryptosai/mcp-observatory 0.14.0 → 0.14.1

package/dist/src/cli.js

@@ -1,135 +1,21 @@
 #!/usr/bin/env node
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
+import { writeFile } from "node:fs/promises";
 import { Command } from "commander";
-import { scanForTargets } from "./discovery.js";
-import { detectEnvironment } from "./environment.js";
-import os from "node:os";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { defaultCassettesDirectory, loadCassette, saveCassette } from "./cassette.js";
-import { runPromptsCheck } from "./checks/prompts.js";
-import { runResourcesCheck } from "./checks/resources.js";
-import { runToolsCheck } from "./checks/tools.js";
-import { runToolsInvokeCheck } from "./checks/tools-invoke.js";
-import { generateBadgeSvg } from "./badge.js";
-import { diffArtifacts, readArtifact, renderHtml, renderMarkdown, renderTerminal, runTarget, writeRunArtifact } from "./index.js";
-import { renderJUnit } from "./reporters/junit.js";
-import { renderSarif } from "./reporters/sarif.js";
-import { runTargetRecording } from "./runner.js";
-import { defaultRunsDirectory } from "./storage.js";
-import { ReplayTransport } from "./transport/replay-transport.js";
-import { SCHEMA_VERSION } from "./types.js";
-import { buildRunId } from "./utils/ids.js";
-import { validateTargetConfig } from "./validate.js";
-import { compareResponses } from "./verify.js";
 import { isCI } from "./ci.js";
-import { loadTelemetryConfig, saveTelemetryConfig, showFirstRunNotice, recordEvent, buildEvent, isTelemetryEnabled } from "./telemetry.js";
+import { ANSI, LOGO, c, getBinName, useColor } from "./commands/helpers.js";
+import { registerDiffCommands } from "./commands/diff.js";
+import { registerLegacyCommands } from "./commands/legacy.js";
+import { registerRecordReplayCommands } from "./commands/record-replay.js";
+import { registerScanCommands } from "./commands/scan.js";
+import { registerScoreCommands } from "./commands/score.js";
+import { registerServeCommands } from "./commands/serve.js";
+import { registerSuggestCommands } from "./commands/suggest.js";
+import { registerTelemetryCommands } from "./commands/telemetry.js";
+import { registerTestCommands } from "./commands/test.js";
+import { registerWatchCommands } from "./commands/watch.js";
+import { runTarget } from "./index.js";
+import { loadTelemetryConfig, showFirstRunNotice, recordEvent, buildEvent, isTelemetryEnabled } from "./telemetry.js";
 import { TOOL_VERSION } from "./version.js";
-// ── ASCII Logo ──────────────────────────────────────────────────────────────
-const LOGO = `
-  ███╗   ███╗ ██████╗██████╗
-  ████╗ ████║██╔════╝██╔══██╗
-  ██╔████╔██║██║     ██████╔╝
-  ██║╚██╔╝██║██║     ██╔═══╝
-  ██║ ╚═╝ ██║╚██████╗██║
-  ╚═╝     ╚═╝ ╚═════╝╚═╝
-     O B S E R V A T O R Y
-`;
-// ── Helpers ─────────────────────────────────────────────────────────────────
-async function readTargetConfig(filePath) {
-    const content = await readFile(filePath, "utf8");
-    return validateTargetConfig(JSON.parse(content));
-}
-function targetFromCommand(args) {
-    if (args.length === 0) {
-        throw new Error("No command provided. Usage: mcp-observatory test <command> [args...]");
-    }
-    const command = args[0];
-    const restArgs = args.slice(1);
-    // Build a meaningful targetId: for wrapper commands, use the package/script name
-    let targetId = command;
-    const wrappers = new Set(["npx", "node", "docker", "uvx", "bunx", "pnpx"]);
-    if (wrappers.has(command)) {
-        const pkg = restArgs.find(a => !a.startsWith("-") && a !== "run");
-        if (pkg)
-            targetId = pkg;
-    }
-    return {
-        targetId,
-        adapter: "local-process",
-        command,
-        args: restArgs,
-        timeoutMs: 15_000,
-    };
-}
-// Extract args after -- before Commander sees them
-const _rawArgv = [...process.argv];
-const _dashDashIdx = _rawArgv.indexOf("--");
-const _passthroughArgs = _dashDashIdx !== -1 ? _rawArgv.splice(_dashDashIdx).slice(1) : [];
-if (_dashDashIdx !== -1) {
-    process.argv = _rawArgv;
-}
-function getPassthroughArgs() {
-    return _passthroughArgs;
-}
-async function resolveTarget(options) {
-    if (options.target) {
-        return readTargetConfig(options.target);
-    }
-    const passthrough = getPassthroughArgs();
-    if (passthrough.length > 0) {
-        return targetFromCommand(passthrough);
-    }
-    throw new Error("Provide --target <config.json> or use: mcp-observatory test <command>");
-}
-function useColor() {
-    return !process.env["NO_COLOR"] && !process.argv.includes("--no-color");
-}
-const ANSI = {
-    red: "\x1b[31m",
-    green: "\x1b[32m",
-    yellow: "\x1b[33m",
-    blue: "\x1b[34m",
-    cyan: "\x1b[36m",
-    dim: "\x1b[2m",
-    bold: "\x1b[1m",
-    reset: "\x1b[0m",
-};
-function c(code, text) {
-    return useColor() ? `${code}${text}${ANSI.reset}` : text;
-}
-function formatOutput(artifact, format) {
-    if (format === "json")
-        return JSON.stringify(artifact, null, 2);
-    if (format === "markdown")
-        return renderMarkdown(artifact);
-    if (format === "html")
-        return renderHtml(artifact);
-    if (format === "junit" && artifact.artifactType === "run")
-        return renderJUnit(artifact);
-    if (format === "sarif" && artifact.artifactType === "run")
-        return renderSarif(artifact);
-    return renderTerminal(artifact);
-}
-async function writeOutput(content, format, outputPath) {
-    if (outputPath !== undefined) {
-        await mkdir(path.dirname(outputPath), { recursive: true });
-        await writeFile(outputPath, content + "\n", "utf8");
-        process.stdout.write(`Wrote ${format} report to ${outputPath}\n`);
-    }
-    else {
-        process.stdout.write(`${content}\n`);
-    }
-}
-// ── Invocation detection ─────────────────────────────────────────────────────
-/** Returns the command the user actually typed, so tips are copy-pasteable. */
-function getBinName() {
-    const script = process.argv[1] ?? "";
-    if (script.includes(".npm/_npx") || script.includes("npx")) {
-        return "npx @kryptosai/mcp-observatory";
-    }
-    return "mcp-observatory";
-}
 const MENU_GROUPS = [
     {
         heading: "",
@@ -301,600 +187,17 @@ async function main() {
         const lines = examples.map(([cmd, desc]) => `  ${c(ANSI.dim, "$")} ${bin}${cmd}${pad(cmd)}${desc}`);
         return ["", "Examples:", "", ...lines, ""].join("\n");
     })());
-    // ── scan ──────────────────────────────────────────────────────────────
-    const scanCmd = program
-        .command("scan")
-        .description("Check all MCP servers in your Claude configs.")
-        .option("--config <path>", "Path to a specific MCP config file.")
-        .option("--security", "Run security analysis on tool schemas.")
-        .option("--no-color", "Disable colored output.");
-    // `scan` with no subcommand — basic scan
-    scanCmd.action(async (options) => {
-        await runScan(bin, options.config, false, options.security);
-    });
-    // `scan deep` — scan + invoke tools
-    scanCmd
-        .command("deep")
-        .description("Scan and also invoke safe tools to verify they execute.")
-        .option("--config <path>", "Path to a specific MCP config file.")
-        .option("--security", "Run security analysis on tool schemas.")
-        .action(async (options) => {
-        // Inherit parent config option if set
-        const parentConfig = scanCmd.opts().config;
-        const parentSecurity = scanCmd.opts().security;
-        await runScan(bin, options.config ?? parentConfig, true, options.security ?? parentSecurity ?? true);
-    });
-    // ── test ──────────────────────────────────────────────────────────────
-    program
-        .command("test")
-        .passThroughOptions()
-        .description("Test a specific server by command.")
-        .argument("<command...>", "Server command and arguments to run.")
-        .option("--security", "Run security analysis on tool schemas.")
-        .option("--no-color", "Disable colored output.")
-        .action(async (commandArgs, options) => {
-        const target = targetFromCommand(commandArgs);
-        process.stdout.write(`  ${c(ANSI.dim, "⟳")} Checking ${c(ANSI.bold, target.targetId)}...`);
-        const artifact = await runTarget(target, { securityCheck: options.security });
-        const outPath = await writeRunArtifact(artifact, defaultRunsDirectory(process.cwd()));
-        const toolsEvidence = artifact.checks.find(ch => ch.id === "tools");
-        const promptsEvidence = artifact.checks.find(ch => ch.id === "prompts");
-        const resourcesEvidence = artifact.checks.find(ch => ch.id === "resources");
-        const toolCount = toolsEvidence?.evidence[0]?.itemCount ?? 0;
-        const promptCount = promptsEvidence?.evidence[0]?.itemCount ?? 0;
-        const resourceCount = resourcesEvidence?.evidence[0]?.itemCount ?? 0;
-        const gateIcon = artifact.gate === "pass" ? c(ANSI.green, "✓") : c(ANSI.red, "✗");
-        process.stdout.write(`\r  ${gateIcon} ${c(ANSI.bold, target.targetId)}${" ".repeat(Math.max(1, 40 - target.targetId.length))}`);
-        process.stdout.write(`${c(ANSI.dim, `${toolCount} tools, ${promptCount} prompts, ${resourceCount} resources`)}\n`);
-        for (const check of artifact.checks) {
-            if (check.status === "fail" || check.status === "partial") {
-                process.stdout.write(`    ${c(ANSI.dim, "→")} ${check.id}: ${check.message}\n`);
-            }
-        }
-        process.stdout.write(`\n  ${c(ANSI.dim, `Artifact: ${outPath}`)}\n\n`);
-        if (artifact.gate === "fail") {
-            process.exitCode = 1;
-        }
-    });
-    // ── diff ──────────────────────────────────────────────────────────────
-    program
-        .command("diff")
-        .description("Compare two runs and show regressions and schema drift.")
-        .argument("<base>", "Base run artifact JSON file.")
-        .argument("<head>", "Head run artifact JSON file.")
-        .option("--format <format>", "terminal, json, markdown, html, junit, or sarif", "terminal")
-        .option("--output <file>", "Write to file instead of stdout.")
-        .option("--no-color", "Disable colored output.")
-        .option("--fail-on-regression", "Exit with code 1 when regressions are present.", false)
-        .action(async (base, head, options) => {
-        const baseArtifact = await readArtifact(base);
-        const headArtifact = await readArtifact(head);
-        if (baseArtifact.artifactType !== "run" || headArtifact.artifactType !== "run") {
-            throw new Error("The diff command only accepts run artifacts.");
-        }
-        const artifact = diffArtifacts(baseArtifact, headArtifact);
-        const output = formatOutput(artifact, options.format);
-        await writeOutput(output, options.format, options.output);
-        if (options.failOnRegression && artifact.gate === "fail") {
-            process.exitCode = 1;
-        }
-    });
-    // ── watch ─────────────────────────────────────────────────────────────
-    program
-        .command("watch")
-        .description("Watch a server for changes, alert on regressions.")
-        .argument("<config>", "Path to a target config JSON file.")
-        .option("--interval <seconds>", "Check interval in seconds.", "30")
-        .option("--no-color", "Disable colored output.")
-        .action(async (configPath, options) => {
-        const target = await readTargetConfig(configPath);
-        const outDir = defaultRunsDirectory(process.cwd());
-        await runWatchMode(target, outDir, parseInt(options.interval, 10) || 30);
-    });
-    // ── serve ─────────────────────────────────────────────────────────────
-    program
-        .command("serve")
-        .description("Start as an MCP server for AI agents.")
-        .action(async () => {
-        const { startServer } = await import("./server.js");
-        await startServer();
-    });
-    // ── suggest ────────────────────────────────────────────────────────────
-    program
-        .command("suggest")
-        .description("Detect your stack and recommend MCP servers.")
-        .option("--cwd <path>", "Directory to scan for project signals.", process.cwd())
-        .option("--no-color", "Disable colored output.")
-        .action(async (options) => {
-        process.stdout.write(`${c(ANSI.dim, "⟳")} Scanning environment...\n\n`);
-        // 1. Current MCP servers
-        const targets = await scanForTargets();
-        if (targets.length > 0) {
-            process.stdout.write(c(ANSI.bold, "  Configured MCP Servers\n"));
-            for (const t of targets) {
-                const detail = t.config.adapter === "http"
-                    ? t.config.url
-                    : `${t.config.command} ${t.config.args.join(" ")}`;
-                process.stdout.write(`  ${c(ANSI.cyan, "●")} ${c(ANSI.bold, t.config.targetId)} ${c(ANSI.dim, detail)} ${c(ANSI.dim, `← ${t.source}`)}\n`);
-            }
-        }
-        else {
-            process.stdout.write(`  ${c(ANSI.yellow, "No MCP servers configured.")}\n`);
-        }
-        process.stdout.write("\n");
-        // 2. Environment detection
-        const env = await detectEnvironment(options.cwd);
-        const hasSignals = env.languages.length > 0 || env.frameworks.length > 0 || env.databases.length > 0;
-        if (hasSignals) {
-            process.stdout.write(c(ANSI.bold, "  Detected Stack\n"));
-            if (env.languages.length > 0)
-                process.stdout.write(`  ${c(ANSI.dim, "Languages:")}  ${env.languages.join(", ")}\n`);
-            if (env.frameworks.length > 0)
-                process.stdout.write(`  ${c(ANSI.dim, "Frameworks:")} ${env.frameworks.join(", ")}\n`);
-            if (env.databases.length > 0)
-                process.stdout.write(`  ${c(ANSI.dim, "Databases:")}  ${env.databases.join(", ")}\n`);
-            if (env.cloud.length > 0)
-                process.stdout.write(`  ${c(ANSI.dim, "Cloud:")}      ${env.cloud.join(", ")}\n`);
-            if (env.cicd.length > 0)
-                process.stdout.write(`  ${c(ANSI.dim, "CI/CD:")}      ${env.cicd.join(", ")}\n`);
-            if (env.services.length > 0)
-                process.stdout.write(`  ${c(ANSI.dim, "Services:")}   ${env.services.join(", ")}\n`);
-        }
-        else {
-            process.stdout.write(`  ${c(ANSI.dim, "No recognizable project signals in")} ${options.cwd}\n`);
-        }
-        process.stdout.write("\n");
-        // 3. MCP Registry — filtered by detected stack
-        try {
-            const response = await fetch("https://registry.modelcontextprotocol.io/v0/servers", {
-                signal: AbortSignal.timeout(10_000),
-                headers: { "Accept": "application/json" },
-            });
-            if (response.ok) {
-                const data = await response.json();
-                const raw = Array.isArray(data) ? data : (typeof data === "object" && data !== null
-                    ? (data["servers"] ?? data["results"] ?? data["items"])
-                    : null);
-                if (Array.isArray(raw)) {
-                    const allEntries = raw;
-                    // Build keyword set from detected environment
-                    const keywords = new Set([
-                        ...env.languages, ...env.frameworks, ...env.databases,
-                        ...env.services, ...env.cloud, ...env.cicd,
-                    ].map(s => s.toLowerCase()));
-                    // Also add common aliases
-                    const aliases = {
-                        typescript: ["ts"], javascript: ["js", "node"], python: ["py"],
-                        postgresql: ["postgres"], mongodb: ["mongo"], github: ["gh"],
-                    };
-                    for (const kw of [...keywords]) {
-                        for (const [full, abbrs] of Object.entries(aliases)) {
-                            if (kw === full)
-                                for (const a of abbrs)
-                                    keywords.add(a);
-                            if (abbrs.includes(kw))
-                                keywords.add(full);
-                        }
-                    }
-                    // Score each entry against detected stack
-                    const scored = allEntries.map(entry => {
-                        const srv = (typeof entry["server"] === "object" && entry["server"] !== null ? entry["server"] : entry);
-                        const name = typeof srv["name"] === "string" ? srv["name"] : (typeof entry["name"] === "string" ? entry["name"] : "unknown");
-                        const desc = typeof srv["description"] === "string" ? srv["description"] : (typeof entry["description"] === "string" ? entry["description"] : "");
-                        const text = `${name} ${desc}`.toLowerCase();
-                        const matches = [...keywords].filter(k => text.includes(k)).length;
-                        return { name, desc, matches };
-                    });
-                    const recommended = scored.filter(s => s.matches > 0).sort((a, b) => b.matches - a.matches);
-                    const others = scored.filter(s => s.matches === 0);
-                    if (recommended.length > 0) {
-                        process.stdout.write(c(ANSI.bold, "  Recommended for Your Stack\n"));
-                        for (const r of recommended.slice(0, 10)) {
-                            process.stdout.write(`  ${c(ANSI.green, "★")} ${c(ANSI.bold, r.name)}${r.desc ? ` ${c(ANSI.dim, "—")} ${r.desc}` : ""}\n`);
-                        }
-                        if (recommended.length > 10) {
-                            process.stdout.write(`  ${c(ANSI.dim, `... and ${recommended.length - 10} more matches`)}\n`);
-                        }
-                    }
-                    else {
-                        process.stdout.write(c(ANSI.bold, "  MCP Registry\n"));
-                        for (const s of scored.slice(0, 10)) {
-                            process.stdout.write(`  ${c(ANSI.dim, "●")} ${c(ANSI.bold, s.name)}${s.desc ? ` ${c(ANSI.dim, "—")} ${s.desc}` : ""}\n`);
-                        }
-                    }
-                    if (others.length > 0) {
-                        process.stdout.write(`\n  ${c(ANSI.dim, `${others.length} more servers at registry.modelcontextprotocol.io`)}\n`);
-                    }
-                }
-                else {
-                    process.stdout.write(`  ${c(ANSI.dim, "Registry returned unexpected format.")}\n`);
-                }
-            }
-            else {
-                process.stdout.write(`  ${c(ANSI.dim, `Registry returned HTTP ${response.status}`)}\n`);
-            }
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            process.stdout.write(`  ${c(ANSI.yellow, "Could not reach registry:")} ${msg}\n`);
-        }
-        process.stdout.write("\n");
-    });
-    // ── record ─────────────────────────────────────────────────────────────
-    program
-        .command("record")
-        .passThroughOptions()
-        .description("Record a server session to a cassette file for replay.")
-        .argument("[command...]", "Server command and arguments to run.")
-        .option("--target <config>", "Path to a target config JSON file.")
-        .option("--no-color", "Disable colored output.")
-        .action(async (commandArgs, options) => {
-        const target = options.target
-            ? await readTargetConfig(options.target)
-            : targetFromCommand(commandArgs.length > 0 ? commandArgs : getPassthroughArgs());
-        process.stdout.write(`${c(ANSI.dim, "⟳")} Recording session with ${c(ANSI.bold, target.targetId)}...\n`);
-        const { artifact, cassetteEntries } = await runTargetRecording(target, { invokeTools: true });
-        if (!cassetteEntries || cassetteEntries.length === 0) {
-            process.stdout.write(`${c(ANSI.yellow, "⚠")} No traffic recorded.\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const cassette = {
-            version: 1,
-            targetId: target.targetId,
-            recordedAt: new Date().toISOString(),
-            transport: target.adapter === "http" ? "http" : "stdio",
-            entries: cassetteEntries,
-        };
-        const cassettePath = await saveCassette(cassette, defaultCassettesDirectory(process.cwd()));
-        const summary = renderTerminal(artifact);
-        process.stdout.write(`\n${summary}\n`);
-        process.stdout.write(`\n${c(ANSI.green, "✓")} Cassette saved: ${cassettePath}\n`);
-        process.stdout.write(`  ${c(ANSI.dim, `${cassetteEntries.length} entries recorded`)}\n`);
-        process.stdout.write(`\n  Replay offline:  ${c(ANSI.cyan, `${bin} replay ${cassettePath}`)}\n`);
-        process.stdout.write(`  Verify live:     ${c(ANSI.cyan, `${bin} verify ${cassettePath} ${target.adapter === "http" ? `--target <config>` : commandArgs.join(" ")}`)}\n\n`);
-        if (artifact.gate === "fail") {
-            process.exitCode = 1;
-        }
-    });
-    // ── replay ─────────────────────────────────────────────────────────────
-    program
-        .command("replay")
-        .description("Replay a cassette file offline — no live server needed.")
-        .argument("<cassette>", "Path to a cassette JSON file.")
-        .option("--no-color", "Disable colored output.")
-        .action(async (cassettePath) => {
-        const cassette = await loadCassette(cassettePath);
-        process.stdout.write(`${c(ANSI.dim, "⟳")} Replaying cassette for ${c(ANSI.bold, cassette.targetId)} (${cassette.entries.length} entries)...\n`);
-        // Create a target config for the replay
-        const replayTarget = {
-            targetId: cassette.targetId,
-            adapter: "local-process",
-            command: "replay",
-            args: [],
-        };
-        // Build a ReplayTransport and run checks against it
-        const transport = new ReplayTransport(cassette.entries);
-        const client = new Client({ name: "mcp-observatory", version: TOOL_VERSION }, { capabilities: {} });
-        await client.connect(transport);
-        const serverCapabilities = client.getServerCapabilities();
-        const checkContext = {
-            client,
-            serverCapabilities,
-            target: replayTarget,
-            timeoutMs: 10_000,
-            stderrLines: [],
-        };
-        const toolsCheck = await runToolsCheck(checkContext);
-        const promptsCheck = await runPromptsCheck(checkContext);
-        const resourcesCheck = await runResourcesCheck(checkContext);
-        const invokeCheck = await runToolsInvokeCheck(checkContext);
-        await client.close();
-        const checks = [
-            toolsCheck.result,
-            promptsCheck.result,
-            resourcesCheck.result,
-            invokeCheck.result,
-        ];
-        const failCount = checks.filter((ch) => ch.status === "fail").length;
-        const gate = failCount > 0 ? "fail" : "pass";
-        const artifact = {
-            artifactType: "run",
-            schemaVersion: SCHEMA_VERSION,
-            gate,
-            runId: buildRunId(),
-            createdAt: new Date().toISOString(),
-            toolVersion: TOOL_VERSION,
-            target: {
-                targetId: cassette.targetId,
-                adapter: "local-process",
-                command: "replay",
-                args: [],
-                metadata: { source: "cassette", cassettePath },
-            },
-            environment: {
-                platform: `${os.platform()} ${os.release()}`,
-                nodeVersion: process.version,
-            },
-            summary: {
-                total: checks.length,
-                pass: checks.filter((ch) => ch.status === "pass").length,
-                fail: failCount,
-                partial: checks.filter((ch) => ch.status === "partial").length,
-                unsupported: checks.filter((ch) => ch.status === "unsupported").length,
-                flaky: checks.filter((ch) => ch.status === "flaky").length,
-                skipped: checks.filter((ch) => ch.status === "skipped").length,
-                gate,
-            },
-            checks,
-        };
-        process.stdout.write(`\n${renderTerminal(artifact)}\n`);
-        process.stdout.write(`\n${c(ANSI.dim, `Replayed from: ${cassettePath}`)}\n\n`);
-        if (artifact.gate === "fail") {
-            process.exitCode = 1;
-        }
-    });
-    // ── verify ─────────────────────────────────────────────────────────────
-    program
-        .command("verify")
-        .passThroughOptions()
-        .description("Verify a live server still matches a recorded cassette.")
-        .argument("<cassette>", "Path to a cassette JSON file.")
-        .argument("[command...]", "Server command and arguments to run.")
-        .option("--target <config>", "Path to a target config JSON file.")
-        .option("--no-color", "Disable colored output.")
-        .action(async (cassettePath, commandArgs, options) => {
-        const cassette = await loadCassette(cassettePath);
-        const target = options.target
-            ? await readTargetConfig(options.target)
-            : targetFromCommand(commandArgs.length > 0 ? commandArgs : getPassthroughArgs());
-        process.stdout.write(`${c(ANSI.dim, "⟳")} Verifying ${c(ANSI.bold, target.targetId)} against cassette...\n`);
-        const { cassetteEntries } = await runTargetRecording(target, { invokeTools: true });
-        if (!cassetteEntries) {
-            process.stdout.write(`${c(ANSI.red, "✗")} Failed to record live session for comparison.\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const verifyResult = compareResponses(cassette, cassetteEntries);
-        process.stdout.write("\n");
-        for (const entry of verifyResult.entries) {
-            if (entry.status === "pass") {
-                process.stdout.write(`  ${c(ANSI.green, "✓")} ${entry.method}\n`);
-            }
-            else if (entry.status === "fail") {
-                process.stdout.write(`  ${c(ANSI.red, "✗")} ${entry.method}\n`);
-                if (entry.diff) {
-                    for (const line of entry.diff.split("\n")) {
-                        process.stdout.write(`    ${c(ANSI.dim, line)}\n`);
-                    }
-                }
-            }
-            else {
-                process.stdout.write(`  ${c(ANSI.yellow, "?")} ${entry.method} ${c(ANSI.dim, "(missing — server did not respond)")}\n`);
-            }
-        }
-        process.stdout.write("\n");
-        if (verifyResult.failed === 0 && verifyResult.missing === 0) {
-            process.stdout.write(c(ANSI.green, `  ✓ All ${verifyResult.passed} responses match cassette\n`));
-        }
-        else {
-            process.stdout.write(c(ANSI.red, `  ✗ ${verifyResult.failed} changed, ${verifyResult.missing} missing out of ${verifyResult.totalEntries} responses\n`));
-            process.exitCode = 1;
-        }
-        process.stdout.write("\n");
-    });
-    // ── Hidden legacy commands ────────────────────────────────────────────
-    program
-        .command("run", { hidden: true })
-        .description("Check one server and save a run artifact.")
-        .option("--target <config>", "Path to a target config JSON file.")
-        .option("--out-dir <directory>", "Directory for persisted run artifacts.", defaultRunsDirectory(process.cwd()))
-        .option("--watch", "Re-run checks on an interval.", false)
-        .option("--interval <seconds>", "Interval in seconds for watch mode.", "30")
-        .option("--invoke-tools", "Actually call safe tools to verify they execute.", false)
-        .option("--no-color", "Disable colored output.")
-        .action(async (options) => {
-        const target = await resolveTarget(options);
-        if (options.watch) {
-            await runWatchMode(target, options.outDir, parseInt(options.interval, 10) || 30);
-            return;
-        }
-        const artifact = await runTarget(target, { invokeTools: options.invokeTools });
-        const outPath = await writeRunArtifact(artifact, options.outDir);
-        const summary = renderTerminal(artifact);
-        process.stdout.write(`${summary}\nArtifact: ${outPath}\n`);
-        if (artifact.gate === "fail") {
-            process.exitCode = 1;
-        }
-    });
-    program
-        .command("check", { hidden: true })
-        .description("Run a single capability check.")
-        .argument("<capability>", "tools, prompts, resources, or tools-invoke.")
-        .option("--target <config>", "Path to a target config JSON file.")
-        .option("--no-color", "Disable colored output.")
-        .action(async (capability, options) => {
-        const validCapabilities = ["tools", "prompts", "resources", "tools-invoke"];
-        if (!validCapabilities.includes(capability)) {
-            throw new Error(`Invalid capability '${capability}'. Must be one of: ${validCapabilities.join(", ")}`);
-        }
-        const target = await resolveTarget(options);
-        const invokeTools = capability === "tools-invoke";
-        const artifact = await runTarget(target, { invokeTools });
-        const check = artifact.checks.find((ch) => ch.id === capability);
-        if (!check) {
-            throw new Error(`Check '${capability}' was not found in the run results.`);
-        }
-        const statusStr = colorStatus(check.status);
-        process.stdout.write(`${c(ANSI.bold, capability)}: ${statusStr}\n`);
-        process.stdout.write(`${check.message}\n`);
-        if (check.evidence.length > 0) {
-            for (const ev of check.evidence) {
-                if (ev.identifiers && ev.identifiers.length > 0) {
-                    process.stdout.write(`Items: ${ev.identifiers.join(", ")}\n`);
-                }
-                if (ev.diagnostics && ev.diagnostics.length > 0) {
-                    process.stdout.write(`Diagnostics: ${ev.diagnostics.join("; ")}\n`);
-                }
-            }
-        }
-    });
-    program
-        .command("report", { hidden: true })
-        .description("Render a run artifact.")
-        .requiredOption("--run <artifact>", "Run artifact JSON.")
-        .option("--format <format>", "terminal, markdown, json, or html", "terminal")
-        .option("--output <file>", "Write to file instead of stdout.")
-        .option("--no-color", "Disable colored output.")
-        .action(async (options) => {
-        const artifact = await readArtifact(options.run);
-        if (artifact.artifactType !== "run") {
-            throw new Error("The report command only accepts run artifacts.");
-        }
-        const output = formatOutput(artifact, options.format);
-        await writeOutput(output, options.format, options.output);
-    });
-    // ── score ────────────────────────────────────────────────────────────
-    program
-        .command("score")
-        .passThroughOptions()
-        .description("Score an MCP server's health (0-100).")
-        .argument("<command...>", "Server command and arguments to run.")
-        .option("--format <format>", "terminal, json, junit, markdown, html, or sarif", "terminal")
-        .option("--output <file>", "Write to file instead of stdout.")
-        .option("--no-color", "Disable colored output.")
-        .action(async (commandArgs, options) => {
-        const target = targetFromCommand(commandArgs);
-        process.stdout.write(`${c(ANSI.dim, "⟳")} Scoring ${c(ANSI.bold, target.targetId)}...\n\n`);
-        const artifact = await runTarget(target, { invokeTools: true, securityCheck: true });
-        await writeRunArtifact(artifact, defaultRunsDirectory(process.cwd()));
-        if (options.format !== "terminal") {
-            const output = formatOutput(artifact, options.format);
-            await writeOutput(output, options.format, options.output);
-            return;
-        }
-        const score = artifact.healthScore;
-        if (!score) {
-            process.stdout.write("  Could not compute health score.\n\n");
-            return;
-        }
-        const gradeColor = score.grade === "A" || score.grade === "B" ? ANSI.green
-            : score.grade === "C" ? ANSI.yellow
-                : ANSI.red;
-        process.stdout.write(c(ANSI.bold, `  MCP Health Score: ${c(gradeColor, `${score.overall}/100`)} (${c(gradeColor, score.grade)})\n\n`));
-        for (const dim of score.dimensions) {
-            const filled = Math.round(dim.score / 5);
-            const empty = 20 - filled;
-            const bar = "█".repeat(filled) + "░".repeat(empty);
-            const dimColor = dim.score >= 80 ? ANSI.green : dim.score >= 60 ? ANSI.yellow : ANSI.red;
-            const weightPct = Math.round(dim.weight * 100);
-            process.stdout.write(`  ${dim.name.padEnd(22)} ${c(dimColor, bar)} ${String(dim.score).padStart(3)}  ${c(ANSI.dim, `(weight: ${weightPct}%)`)}\n`);
-        }
-        process.stdout.write("\n");
-        // Show details for dimensions that aren't perfect
-        for (const dim of score.dimensions) {
-            if (dim.score < 100 && dim.details.length > 0) {
-                process.stdout.write(`  ${c(ANSI.dim, dim.name + ":")}\n`);
-                for (const detail of dim.details) {
-                    process.stdout.write(`    ${c(ANSI.dim, "→")} ${detail}\n`);
-                }
-            }
-        }
-        process.stdout.write("\n");
-        if (artifact.gate === "fail") {
-            process.exitCode = 1;
-        }
-    });
-    // ── badge ───────────────────────────────────────────────────────────
-    program
-        .command("badge")
-        .passThroughOptions()
-        .description("Generate an SVG health score badge for your README.")
-        .argument("<command...>", "Server command and arguments to run.")
-        .option("--output <file>", "Write SVG to file (default: stdout).")
-        .option("--label <text>", "Badge label text.", "MCP Health")
-        .action(async (commandArgs, options) => {
-        const target = targetFromCommand(commandArgs);
-        process.stderr.write(`${c(ANSI.dim, "⟳")} Scoring ${c(ANSI.bold, target.targetId)}...\n`);
-        const artifact = await runTarget(target, { invokeTools: true, securityCheck: true });
-        const score = artifact.healthScore;
-        if (!score) {
-            process.stderr.write("  Could not compute health score.\n");
-            process.exitCode = 1;
-            return;
-        }
-        const svg = generateBadgeSvg({ score: score.overall, grade: score.grade, label: options.label });
-        if (options.output) {
-            await mkdir(path.dirname(options.output), { recursive: true });
-            await writeFile(options.output, svg, "utf8");
-            process.stderr.write(`  Badge written to ${options.output}\n`);
-        }
-        else {
-            process.stdout.write(svg);
-        }
-    });
-    // ── telemetry ──────────────────────────────────────────────────────────
-    program
-        .command("telemetry")
-        .description("Manage anonymous usage telemetry.")
-        .argument("[action]", "enable, disable, stats, or status (default: status)")
-        .action(async (action) => {
-        const config = await loadTelemetryConfig();
-        const envDisabled = process.env["DO_NOT_TRACK"] === "1" ||
-            process.env["MCP_OBSERVATORY_TELEMETRY_DISABLED"] === "1";
-        if (action === "enable") {
-            config.telemetryEnabled = true;
-            await saveTelemetryConfig(config);
-            process.stdout.write("  Telemetry enabled.\n\n");
-        }
-        else if (action === "disable") {
-            config.telemetryEnabled = false;
-            await saveTelemetryConfig(config);
-            process.stdout.write("  Telemetry disabled.\n\n");
-        }
-        else if (action === "stats") {
-            const endpoint = process.env["MCP_OBSERVATORY_TELEMETRY_URL"] ?? "https://mcp-observatory-telemetry.kryptosai.workers.dev";
-            const token = process.env["MCP_OBSERVATORY_STATS_TOKEN"] ?? config.statsToken;
-            if (!token) {
-                process.stderr.write("  No stats token configured.\n");
-                process.stderr.write("  Set MCP_OBSERVATORY_STATS_TOKEN or add \"statsToken\" to ~/.mcp-observatory/config.json\n\n");
-                return;
-            }
-            const authHeaders = { Authorization: `Bearer ${token}` };
-            try {
-                const [all, others] = await Promise.all([
-                    fetch(`${endpoint}/v1/stats`, { headers: authHeaders }).then(r => r.json()),
-                    fetch(`${endpoint}/v1/stats?exclude=${config.sessionId}`, { headers: authHeaders }).then(r => r.json()),
-                ]);
-                if (all.error) {
-                    process.stderr.write(`  Error: ${all.error}\n\n`);
-                    return;
-                }
-                const totalAll = all.total ?? 0;
-                const totalOthers = others.total ?? 0;
-                const you = totalAll - totalOthers;
-                const sessionsAll = all.uniqueSessions ?? 0;
-                const sessionsOthers = others.uniqueSessions ?? 0;
-                process.stdout.write(`  Total events:     ${totalAll}\n`);
-                process.stdout.write(`  Your events:      ${you}\n`);
-                process.stdout.write(`  Other events:     ${totalOthers}\n`);
-                process.stdout.write(`  Unique sessions:  ${sessionsAll}  (${sessionsOthers} excluding you)\n`);
-                process.stdout.write(`  Last 24h:         ${all.last24h ?? 0}  (${others.last24h ?? 0} excluding you)\n\n`);
-            }
-            catch {
-                process.stderr.write("  Failed to fetch telemetry stats.\n\n");
-            }
-        }
-        else {
-            const effective = isTelemetryEnabled();
-            process.stdout.write(`  Telemetry: ${effective ? "enabled" : "disabled"}\n`);
-            process.stdout.write(`  Config:    telemetryEnabled=${String(config.telemetryEnabled)}\n`);
-            if (envDisabled) {
-                process.stdout.write(`  Override:  disabled via environment variable\n`);
-            }
-            process.stdout.write(`  Session:   ${config.sessionId}\n\n`);
-        }
-    });
+    // Register all command modules
+    registerScanCommands(program, bin);
+    registerTestCommands(program);
+    registerDiffCommands(program);
+    registerRecordReplayCommands(program, bin);
+    registerWatchCommands(program);
+    registerServeCommands(program);
+    registerSuggestCommands(program);
+    registerScoreCommands(program);
+    registerLegacyCommands(program);
+    registerTelemetryCommands(program);
     // ── smithery ─────────────────────────────────────────────────────────
     const smitheryCmd = program
         .command("smithery")
@@ -907,14 +210,14 @@ async function main() {
         .option("--api-key <key>", "Smithery API key.")
         .option("--base-url <url>", "Override Smithery API base URL.")
         .action(async (qualifiedName, options) => {
-        const { resolveSmitheryTarget, generateSubmission: genSub, renderSubmissionMarkdown: renderMd } = await import("./integrations/smithery.js");
+        const smithery = await import("./integrations/smithery.js");
         const smitheryConfig = { apiKey: options.apiKey, baseUrl: options.baseUrl };
         process.stdout.write(`  Resolving ${qualifiedName} from Smithery...\n`);
-        const target = await resolveSmitheryTarget(qualifiedName, smitheryConfig);
+        const target = await smithery.resolveSmitheryTarget(qualifiedName, smitheryConfig);
         process.stdout.write(`  Running checks against ${target.targetId}...\n`);
         const artifact = await runTarget(target, { securityCheck: options.security });
-        const submission = genSub(qualifiedName, artifact);
-        const md = renderMd(submission);
+        const submission = smithery.generateSubmission(qualifiedName, artifact);
+        const md = smithery.renderSubmissionMarkdown(submission);
         process.stdout.write(`\n${md}\n`);
     });
     smitheryCmd
@@ -926,14 +229,14 @@ async function main() {
         .option("--api-key <key>", "Smithery API key.")
         .option("--base-url <url>", "Override Smithery API base URL.")
         .action(async (qualifiedName, options) => {
-        const { resolveSmitheryTarget, generateSubmission: genSub, renderSubmissionMarkdown: renderMd } = await import("./integrations/smithery.js");
+        const smithery = await import("./integrations/smithery.js");
         const smitheryConfig = { apiKey: options.apiKey, baseUrl: options.baseUrl };
         process.stdout.write(`  Resolving ${qualifiedName} from Smithery...\n`);
-        const target = await resolveSmitheryTarget(qualifiedName, smitheryConfig);
+        const target = await smithery.resolveSmitheryTarget(qualifiedName, smitheryConfig);
         process.stdout.write(`  Running checks against ${target.targetId}...\n`);
         const artifact = await runTarget(target, { securityCheck: options.security });
-        const submission = genSub(qualifiedName, artifact);
-        const md = renderMd(submission);
+        const submission = smithery.generateSubmission(qualifiedName, artifact);
+        const md = smithery.renderSubmissionMarkdown(submission);
         if (options.output) {
             await writeFile(options.output, md, "utf8");
             process.stdout.write(`  Report written to ${options.output}\n`);
@@ -950,12 +253,12 @@ async function main() {
         .option("--api-key <key>", "Smithery API key.")
         .option("--base-url <url>", "Override Smithery API base URL.")
         .action(async (options) => {
-        const { batchScanServers, renderBatchReportMarkdown } = await import("./integrations/smithery.js");
+        const smithery = await import("./integrations/smithery.js");
         const smitheryConfig = { apiKey: options.apiKey, baseUrl: options.baseUrl };
         const top = parseInt(options.top, 10) || 10;
         process.stdout.write(`  Scanning top ${top} servers from Smithery registry...\n`);
-        const results = await batchScanServers((target) => runTarget(target, {}), smitheryConfig, { top });
-        const md = renderBatchReportMarkdown(results);
+        const results = await smithery.batchScanServers((target) => runTarget(target, {}), smitheryConfig, { top });
+        const md = smithery.renderBatchReportMarkdown(results);
         if (options.output) {
             await writeFile(options.output, md, "utf8");
             process.stdout.write(`  Batch report written to ${options.output}\n`);
@@ -976,174 +279,6 @@ async function main() {
     recordEvent(buildEvent("command_run", commandName, "cli"));
     await program.parseAsync(process.argv);
 }
-// ── Scan implementation ─────────────────────────────────────────────────────
-async function runScan(bin, configPath, invokeTools, securityCheck) {
-    process.stdout.write(useColor() ? c(ANSI.cyan, LOGO) + `  ${c(ANSI.dim, `v${TOOL_VERSION}`)}\n\n` : LOGO + `  v${TOOL_VERSION}\n\n`);
-    if (configPath) {
-        try {
-            await access(configPath);
-        }
-        catch {
-            process.stdout.write(c(ANSI.red, `  ✗ Config file not found: ${configPath}\n\n`));
-            process.exitCode = 1;
-            return;
-        }
-    }
-    const targets = await scanForTargets(configPath);
-    if (targets.length === 0) {
-        process.stdout.write(c(ANSI.yellow, "  No MCP servers found.\n\n"));
-        process.stdout.write(c(ANSI.dim, "  Looked in ~/.claude.json, Claude Desktop config, .mcp.json\n\n"));
-        process.stdout.write("  Test a specific server:\n");
-        process.stdout.write(`    ${c(ANSI.dim, "$")} ${c(ANSI.cyan, `${bin} test npx -y @modelcontextprotocol/server-filesystem .`)}\n\n`);
-        return;
-    }
-    process.stdout.write(c(ANSI.bold, `  Found ${targets.length} MCP server${targets.length === 1 ? "" : "s"}:\n`));
-    for (const t of targets) {
-        process.stdout.write(`  ${c(ANSI.cyan, "●")} ${c(ANSI.bold, t.config.targetId)} ${c(ANSI.dim, `← ${t.source}`)}\n`);
-    }
-    process.stdout.write("\n");
-    const results = [];
-    let passCount = 0;
-    let failCount = 0;
-    let totalTools = 0;
-    let totalPrompts = 0;
-    let totalResources = 0;
-    for (const t of targets) {
-        process.stdout.write(`  ${c(ANSI.dim, "⟳")} Checking ${c(ANSI.bold, t.config.targetId)}...`);
-        try {
-            const artifact = await runTarget(t.config, { invokeTools, securityCheck });
-            const toolsCheck = artifact.checks.find((ch) => ch.id === "tools");
-            const promptsCheck = artifact.checks.find((ch) => ch.id === "prompts");
-            const resourcesCheck = artifact.checks.find((ch) => ch.id === "resources");
-            const toolCount = toolsCheck?.evidence[0]?.itemCount ?? 0;
-            const promptCount = promptsCheck?.evidence[0]?.itemCount ?? 0;
-            const resourceCount = resourcesCheck?.evidence[0]?.itemCount ?? 0;
-            totalTools += toolCount;
-            totalPrompts += promptCount;
-            totalResources += resourceCount;
-            const diagnostics = [];
-            for (const check of artifact.checks) {
-                if (check.status === "fail" || check.status === "partial") {
-                    diagnostics.push(`${check.id}: ${check.message}`);
-                }
-            }
-            const gateIcon = artifact.gate === "pass" ? c(ANSI.green, " ✓") : c(ANSI.red, " ✗");
-            process.stdout.write(`\r  ${gateIcon} ${c(ANSI.bold, t.config.targetId)}${" ".repeat(Math.max(1, 40 - t.config.targetId.length))}`);
-            process.stdout.write(`${c(ANSI.dim, `${toolCount} tools, ${promptCount} prompts, ${resourceCount} resources`)}\n`);
-            if (artifact.fatalError) {
-                process.stdout.write(`    ${c(ANSI.red, "→")} ${artifact.fatalError.split("\n")[0]}\n`);
-            }
-            else if (artifact.gate === "fail" && diagnostics.length > 0) {
-                process.stdout.write(`    ${c(ANSI.dim, "→")} ${diagnostics[0]}\n`);
-            }
-            results.push({ targetId: t.config.targetId, gate: artifact.gate, toolCount, promptCount, resourceCount, diagnostics });
-            if (artifact.gate === "pass")
-                passCount++;
-            else
-                failCount++;
-        }
-        catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            let friendlyMsg = msg;
-            if (msg.includes("ENOENT") || msg.includes("not found")) {
-                const cmd = t.config.adapter === "http" ? t.config.url : t.config.command;
-                friendlyMsg = `Could not start server — "${cmd}" not found. Is it installed?`;
-            }
-            else if (msg.includes("ECONNREFUSED")) {
-                friendlyMsg = `Server is not running or refused the connection.`;
-            }
-            else if (msg.includes("timed out") || msg.includes("timeout")) {
-                friendlyMsg = `Server took too long to respond.`;
-            }
-            process.stdout.write(`\r  ${c(ANSI.red, "✗")} ${c(ANSI.bold, t.config.targetId)}\n`);
-            process.stdout.write(`    ${c(ANSI.red, friendlyMsg)}\n`);
-            results.push({ targetId: t.config.targetId, gate: "fail", toolCount: 0, promptCount: 0, resourceCount: 0, error: friendlyMsg, diagnostics: [] });
-            failCount++;
-        }
-    }
-    // ── Summary ──────────────────────────────────────────────────────────
-    process.stdout.write("\n");
-    if (failCount === 0) {
-        process.stdout.write(c(ANSI.green, `  ✓ All ${passCount} server${passCount === 1 ? "" : "s"} healthy`));
-        process.stdout.write(c(ANSI.dim, ` — ${totalTools} tools, ${totalPrompts} prompts, ${totalResources} resources\n`));
-    }
-    else {
-        process.stdout.write(c(ANSI.red, `  ✗ ${failCount} of ${passCount + failCount} server${passCount + failCount === 1 ? "" : "s"} failing`));
-        if (totalTools > 0 || totalPrompts > 0 || totalResources > 0) {
-            process.stdout.write(c(ANSI.dim, ` — ${totalTools} tools, ${totalPrompts} prompts, ${totalResources} resources found\n`));
-        }
-        else {
-            process.stdout.write("\n");
-        }
-    }
-    // Show diagnostics for failures or notable partials
-    const issues = results.filter((r) => r.diagnostics.length > 0 && !r.error);
-    if (issues.length > 0) {
-        process.stdout.write("\n");
-        for (const r of issues) {
-            process.stdout.write(`  ${c(ANSI.yellow, r.targetId)}:\n`);
-            for (const d of r.diagnostics.slice(0, 3)) {
-                process.stdout.write(`    ${c(ANSI.dim, "→")} ${d}\n`);
-            }
-        }
-    }
-    // ── Next step ────────────────────────────────────────────────────────
-    process.stdout.write("\n");
-    if (!invokeTools && totalTools > 0) {
-        process.stdout.write(c(ANSI.dim, `  Next: ${c(ANSI.cyan, `${bin} scan deep`)} to also test that tools run\n`));
-    }
-    else {
-        process.stdout.write(c(ANSI.dim, `  Run ${c(ANSI.cyan, `${bin} --help`)} for more commands\n`));
-    }
-    process.stdout.write("\n");
-    if (failCount > 0) {
-        process.exitCode = 1;
-    }
-}
-// ── Utilities ───────────────────────────────────────────────────────────────
-function colorStatus(status) {
-    switch (status) {
-        case "pass":
-            return c(ANSI.green, status);
-        case "fail":
-            return c(ANSI.red, status);
-        case "partial":
-        case "flaky":
-            return c(ANSI.yellow, status);
-        case "unsupported":
-        case "skipped":
-            return c(ANSI.dim, status);
-        default:
-            return status;
-    }
-}
-async function runWatchMode(target, outDir, intervalSeconds) {
-    const { diffArtifacts: diff } = await import("./diff.js");
-    process.stdout.write(`Watch mode: checking every ${intervalSeconds}s. Press Ctrl+C to stop.\n\n`);
-    let previousArtifact = await runTarget(target);
-    await writeRunArtifact(previousArtifact, outDir);
-    process.stdout.write(`${renderTerminal(previousArtifact)}\n\n`);
-    const loop = async () => {
-        await new Promise((resolve) => setTimeout(resolve, intervalSeconds * 1000));
-        const currentArtifact = await runTarget(target);
-        const diffResult = diff(previousArtifact, currentArtifact);
-        if (diffResult.summary.regressions > 0 || diffResult.summary.recoveries > 0 || diffResult.summary.added > 0 || diffResult.summary.removed > 0) {
-            const outPath = await writeRunArtifact(currentArtifact, outDir);
-            process.stdout.write(`\n--- Change detected at ${currentArtifact.createdAt} ---\n`);
-            process.stdout.write(`${renderTerminal(diffResult)}\n`);
-            process.stdout.write(`Artifact: ${outPath}\n\n`);
-        }
-        previousArtifact = currentArtifact;
-        void loop();
-    };
-    void loop();
-    await new Promise((resolve) => {
-        process.on("SIGINT", () => {
-            process.stdout.write("\nWatch mode stopped.\n");
-            resolve();
-        });
-    });
-}
 void main().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     let friendly = message;