@kirrosh/zond 0.22.0 → 0.23.0

package/src/cli/program.ts

@@ -1,157 +1,41 @@
-import { Command, InvalidArgumentError, Option } from "commander";
-
-import { runCommand } from "./commands/run.ts";
-import { validateCommand } from "./commands/validate.ts";
-import { serveCommand } from "./commands/serve.ts";
-import { coverageCommand } from "./commands/coverage.ts";
-import { ciInitCommand } from "./commands/ci-init.ts";
-import { initCommand } from "./commands/init.ts";
-import { describeCommand } from "./commands/describe.ts";
-import { dbCommand } from "./commands/db.ts";
-import { requestCommand } from "./commands/request.ts";
-import { guideCommand } from "./commands/guide.ts";
-import { generateCommand } from "./commands/generate.ts";
-import { probeValidationCommand } from "./commands/probe-validation.ts";
-import { probeMethodsCommand } from "./commands/probe-methods.ts";
-import { exportCommand } from "./commands/export.ts";
-import { syncCommand } from "./commands/sync.ts";
-import { updateCommand } from "./commands/update.ts";
-import { catalogCommand } from "./commands/catalog.ts";
-import { completionsCommand, COMPLETION_SHELLS, type CompletionShell } from "./commands/completions.ts";
-import { useCommand } from "./commands/use.ts";
-
-import { readCurrentApi } from "../core/context/current.ts";
-import { printError } from "./output.ts";
+import { Command } from "commander";
+
+import { registerRun } from "./commands/run.ts";
+import { registerCheck, registerLint } from "./commands/check.ts";
+import { registerChecks } from "./commands/checks.ts";
+import { registerCoverage } from "./commands/coverage.ts";
+import { registerCi } from "./commands/ci-init.ts";
+import { registerClean } from "./commands/clean.ts";
+import { registerCleanup } from "./commands/cleanup.ts";
+import { registerInit } from "./commands/init/index.ts";
+import { registerDescribe } from "./commands/describe.ts";
+import { registerDb } from "./commands/db.ts";
+import { registerRequest } from "./commands/request.ts";
+import { registerGenerate } from "./commands/generate.ts";
+import { registerPrepareFixtures } from "./commands/prepare-fixtures.ts";
+import { registerFixtures } from "./commands/fixtures.ts";
+import { registerProbes } from "./commands/probe.ts";
+import { bootstrapProbes } from "../core/probe/bootstrap.ts";
+import { bootstrapAntiFp } from "../core/anti-fp/bootstrap.ts";
+import { registerReport } from "./commands/report.ts";
+import { registerCatalog } from "./commands/catalog.ts";
+import { registerCompletions } from "./commands/completions.ts";
+import { registerUse } from "./commands/use.ts";
+import { registerSession } from "./commands/session.ts";
+import { registerDoctor } from "./commands/doctor.ts";
+import { registerRefreshApi } from "./commands/refresh-api.ts";
+import { registerAdd } from "./commands/add-api.ts";
+import { registerRemove } from "./commands/remove-api.ts";
+import { registerAudit } from "./commands/audit.ts";
+import { registerReference } from "./commands/reference.ts";
+import { registerApiAnnotate } from "./commands/api/annotate/index.ts";
+
+import { getSecretRegistry } from "../core/secrets/registry.ts";
 import { getRuntimeInfo } from "./runtime.ts";
 import { VERSION } from "./version.ts";
-import { getDb } from "../db/schema.ts";
-import { findCollectionByNameOrId } from "../db/queries.ts";
-import type { ReporterName } from "../core/reporter/types.ts";
-
-// ── MSYS path preprocessing ──
-//
-// Git Bash on Windows converts API paths like "/users" → "C:/Program Files/Git/users".
-// We reverse that for flags whose values are API paths, not filesystem paths.
-
-const MSYS_PREFIX_RE = /^[A-Z]:[\\/](?:Program Files[\\/]Git|msys64|usr)[\\/]/i;
-
-const API_PATH_FLAGS = new Set(["--path", "--json-path"]);
-
-function stripMsysPath(value: string): string {
-  if (!MSYS_PREFIX_RE.test(value)) return value;
-  return value.replace(MSYS_PREFIX_RE, "/");
-}
-
-/**
- * Pre-process argv before commander sees it: undo Git Bash's MSYS path conversion
- * for `--path` and `--json-path` values (both `--path X` and `--path=X` forms).
- */
-export function preprocessArgv(argv: string[]): string[] {
-  const out = [...argv];
-  for (let i = 0; i < out.length; i++) {
-    const arg = out[i]!;
-
-    // --flag=value form
-    const eqIdx = arg.indexOf("=");
-    if (arg.startsWith("--") && eqIdx !== -1) {
-      const flag = arg.slice(0, eqIdx);
-      if (API_PATH_FLAGS.has(flag)) {
-        out[i] = `${flag}=${stripMsysPath(arg.slice(eqIdx + 1))}`;
-      }
-      continue;
-    }
-
-    // --flag value form
-    if (API_PATH_FLAGS.has(arg)) {
-      const next = out[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
-        out[i + 1] = stripMsysPath(next);
-      }
-    }
-  }
-  return out;
-}
-
-// ── Argument parsers ──
-
-function parsePositiveInt(name: string): (raw: string) => number {
-  return (raw: string) => {
-    const n = Number.parseInt(raw, 10);
-    if (Number.isNaN(n) || n <= 0) {
-      throw new InvalidArgumentError(`Invalid ${name} value: ${raw}`);
-    }
-    return n;
-  };
-}
-
-/** `--rate-limit` accepts a positive integer (req/sec cap) or the literal
- *  string `auto` (no static cap; throttle adaptively from ratelimit-* headers). */
-function parseRateLimit(raw: string): number | "auto" {
-  if (raw.toLowerCase() === "auto") return "auto";
-  const n = Number.parseInt(raw, 10);
-  if (Number.isNaN(n) || n <= 0) {
-    throw new InvalidArgumentError(`Invalid --rate-limit value: ${raw} (expected a positive integer or "auto")`);
-  }
-  return n;
-}
-
-function parseInteger(name: string): (raw: string) => number {
-  return (raw: string) => {
-    const n = Number.parseInt(raw, 10);
-    if (Number.isNaN(n)) {
-      throw new InvalidArgumentError(`Invalid ${name} value: ${raw}`);
-    }
-    return n;
-  };
-}
-
-function parsePercentage(raw: string): number {
-  const n = Number.parseInt(raw, 10);
-  if (Number.isNaN(n) || n < 0 || n > 100) {
-    throw new InvalidArgumentError(`Invalid --fail-on-coverage value: ${raw} (must be 0–100)`);
-  }
-  return n;
-}
-
-const collect = (val: string, prev: string[]): string[] => [...prev, val];
-
-const VALID_REPORTERS = new Set<string>(["console", "json", "junit"]);
-
-function parseReporter(raw: string): ReporterName {
-  if (!VALID_REPORTERS.has(raw)) {
-    throw new InvalidArgumentError(`Unknown reporter: ${raw}. Available: console, json, junit`);
-  }
-  return raw as ReporterName;
-}
-
-// Helper: split repeatable values like ["a,b", "c"] → ["a", "b", "c"]
-function flatSplit(values: string[] | undefined): string[] | undefined {
-  if (!values || values.length === 0) return undefined;
-  const out = values.flatMap((v) => v.split(",")).filter(Boolean);
-  return out.length > 0 ? out : undefined;
-}
-
-// Helper: read a global option from any command in the tree
-function globalJson(cmd: Command): boolean {
-  return cmd.optsWithGlobals().json === true;
-}
+import { preprocessArgv } from "./argv.ts";
 
-// Resolve API collection → returns { spec?, testPath? } or null when not found
-function resolveApiCollection(apiName: string, dbPath: string | undefined):
-  | { spec: string | null; testPath: string | null }
-  | { error: string } {
-  if (typeof apiName !== "string" || apiName.length === 0) {
-    return { error: "Internal: --api received non-string value" };
-  }
-  try {
-    getDb(dbPath);
-    const col = findCollectionByNameOrId(apiName);
-    if (!col) return { error: `API '${apiName}' not found` };
-    return { spec: col.openapi_spec ?? null, testPath: col.test_path ?? null };
-  } catch (err) {
-    return { error: `Failed to resolve --api: ${(err as Error).message}` };
-  }
-}
+export { preprocessArgv };
 
 // ── Program builder ──
 
@@ -160,496 +44,175 @@ export function buildProgram(): Command {
     .description("API Testing Platform")
     .version(`${VERSION} (${getRuntimeInfo()})`, "-v, --version", "Show version")
     .helpOption("-h, --help", "Show this help")
-    .option("--json", "Output in JSON envelope format")
     .showHelpAfterError("(run 'zond --help' for usage)")
-    .exitOverride();
-
-  // ── run ──
-  program
-    .command("run [path]")
-    .description("Run API tests")
-    .option("--env <name>", "Use environment file (.env.<name>.yaml)")
-    .option("--api <name>", "Use API collection (resolves test path automatically)")
-    .addOption(
-      new Option("--report <format>", "Output format")
-        .choices(["console", "json", "junit"])
-        .default("console")
-        .argParser(parseReporter),
+    .exitOverride()
+    // TASK-166 (m-10): global escape hatch for local debugging — disables
+    // the secret registry's redaction pass everywhere (DB writes,
+    // exporters, stdout). Default is redact-on. Hook is read from the
+    // env var so it survives across nested subcommand parsers.
+    .option("--no-redact", "Disable auto-redaction of registered secret values (debug only)")
+    .option(
+      "--api <name>",
+      "TASK-290: Select the active API for this invocation. Resolution order: per-command --api > global --api (this flag) > ZOND_API env > .zond/current-api file (set via `zond use <name>`).",
     )
-    .option("--timeout <ms>", "Override request timeout", parsePositiveInt("--timeout"))
-    .option("--rate-limit <N|auto>", "Throttle requests to at most N per second, or `auto` to adapt from ratelimit-* response headers", parseRateLimit)
-    .option("--bail", "Stop on first suite failure")
-    .option("--sequential", "Run regular suites one after another instead of in parallel (opt-out of Promise.all)")
-    .option("--no-db", "Do not save results to zond.db")
-    .option("--db <path>", "Path to SQLite database file (default: zond.db)")
-    .option("--auth-token <token>", "Auth token injected as {{auth_token}} variable")
-    .option("--safe", "Run only GET tests (read-only, safe mode)")
-    .option("--tag <tag>", "Filter suites by tag (repeatable, comma-separated)", collect, [])
-    .option("--exclude-tag <tag>", "Exclude suites by tag (repeatable, comma-separated)", collect, [])
-    .option("--method <method>", "Filter tests by HTTP method (e.g. GET, POST)")
-    .option("--env-var <KEY=VALUE>", "Inject env variable (repeatable, overrides env file)", collect, [])
-    .option("--dry-run", "Show requests without sending them (exit code always 0)")
-    .option("--report-out <file>", "Write the report to a file via fs (bypass stdout). Useful when the bun wrapper or other shells contaminate stdout.")
-    .action(async (pathArg: string | undefined, opts, cmd: Command) => {
-      let path = pathArg;
-      const apiFlag = (opts.api as string | undefined) ?? (path ? undefined : readCurrentApi() ?? undefined);
-      const dbPath = typeof opts.db === "string" ? opts.db : undefined;
-
-      if (!path && apiFlag) {
-        const resolved = resolveApiCollection(apiFlag, dbPath);
-        if ("error" in resolved) {
-          printError(resolved.error);
-          process.exitCode = resolved.error.startsWith("Failed") ? 2 : 1;
-          return;
-        }
-        if (!resolved.testPath) {
-          printError(`API '${apiFlag}' has no test_path`);
-          process.exitCode = 1;
-          return;
-        }
-        path = resolved.testPath;
-      }
-      if (!path) {
-        printError("No path given and .zond-current not set; run `zond use <api>` or pass path explicitly (or use --api <name>)");
-        process.exitCode = 2;
-        return;
+    .hook("preAction", (thisCommand) => {
+      const enabled = thisCommand.opts().redact !== false;
+      // Mirror the flag into env so deeply-nested code that doesn't have
+      // access to `cmd` (e.g. setup-api, exporters) can still consult it.
+      process.env.ZOND_REDACT = enabled ? "1" : "0";
+      getSecretRegistry().setEnabled(enabled);
+      // TASK-290: mirror the global --api flag into env so the resolution
+      // chain in core/context/current.ts (which has no `cmd` ref) sees it.
+      // Per-command --api still wins because it is passed positionally to
+      // resolveSpecArg / resolveApiCollection.
+      const apiGlobal = thisCommand.opts().api;
+      if (typeof apiGlobal === "string" && apiGlobal.length > 0) {
+        process.env.ZOND_API_GLOBAL = apiGlobal;
+      } else {
+        delete process.env.ZOND_API_GLOBAL;
       }
-
-      const tags = flatSplit(opts.tag);
-      const excludeTags = flatSplit(opts.excludeTag);
-      const envVars = (opts.envVar as string[] | undefined)?.length ? (opts.envVar as string[]) : undefined;
-
-      process.exitCode = await runCommand({
-        path,
-        env: opts.env,
-        report: opts.report as ReporterName,
-        timeout: opts.timeout,
-        rateLimit: opts.rateLimit,
-        bail: opts.bail === true,
-        sequential: opts.sequential === true,
-        // Commander's `--no-db` produces { db: false }; keep semantics: when --no-db given → noDb=true
-        noDb: opts.db === false,
-        dbPath: typeof opts.db === "string" ? opts.db : undefined,
-        authToken: opts.authToken,
-        safe: opts.safe === true,
-        tag: tags,
-        excludeTag: excludeTags,
-        method: opts.method,
-        envVars,
-        dryRun: opts.dryRun === true,
-        reportOut: typeof opts.reportOut === "string" ? opts.reportOut : undefined,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── validate ──
-  program
-    .command("validate <path>")
-    .description("Validate test files without running")
-    .action(async (path: string, _opts, cmd: Command) => {
-      process.exitCode = await validateCommand({ path, json: globalJson(cmd) });
-    });
-
-  // ── serve ──
-  program
-    .command("serve")
-    .description("Start web dashboard")
-    .option("--port <port>", "Server port (default: 8080)", parsePositiveInt("--port"))
-    .option("--host <host>", "Server host (default: 0.0.0.0)")
-    .option("--db <path>", "Path to SQLite database file (default: zond.db)")
-    .option("--open", "Open dashboard in browser after starting")
-    .option("--watch", "Enable dev mode with hot reload (auto-refresh on file changes)")
-    .option("--kill-existing", "Kill any process holding the requested port (DANGEROUS — can terminate your dev server)")
-    .action(async (opts) => {
-      process.exitCode = await serveCommand({
-        port: opts.port,
-        host: opts.host,
-        dbPath: opts.db,
-        watch: opts.watch === true,
-        open: opts.open === true,
-        killExisting: opts.killExisting === true,
-      });
     });
 
-  // ── ci ──
-  const ci = program.command("ci").description("CI/CD scaffolding");
-  ci
-    .command("init")
-    .description("Generate CI/CD workflow (GitHub Actions, GitLab CI)")
-    .option("--github", "Generate GitHub Actions workflow")
-    .option("--gitlab", "Generate GitLab CI config")
-    .option("--dir <path>", "Project root directory (default: current directory)")
-    .option("--force", "Overwrite existing CI config")
-    .action(async (opts, cmd: Command) => {
-      let platform: "github" | "gitlab" | undefined;
-      if (opts.github === true) platform = "github";
-      else if (opts.gitlab === true) platform = "gitlab";
-      process.exitCode = await ciInitCommand({
-        platform,
-        force: opts.force === true,
-        dir: opts.dir,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── use ──
-  program
-    .command("use [api]")
-    .description("Set or show the current API for this workspace (.zond-current)")
-    .option("--clear", "Remove .zond-current from the current directory")
-    .action(async (api: string | undefined, opts, cmd: Command) => {
-      process.exitCode = await useCommand({
-        api,
-        clear: opts.clear === true,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── coverage ──
-  program
-    .command("coverage")
-    .description("Analyze API test coverage")
-    .option("--api <name>", "Use API collection (auto-resolves spec and tests dir)")
-    .option("--spec <path>", "Path to OpenAPI spec (required unless --api used)")
-    .option("--tests <dir>", "Path to test files directory (required unless --api used)")
-    .option("--fail-on-coverage <N>", "Exit 1 when coverage percentage is below N (0–100)", parsePercentage)
-    .option("--run-id <number>", "Cross-reference with a test run for pass/fail/5xx breakdown", parseInteger("--run-id"))
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (opts, cmd: Command) => {
-      let spec: string | undefined = opts.spec;
-      let tests: string | undefined = opts.tests;
-      const apiFlag = (opts.api as string | undefined) ?? (spec || tests ? undefined : readCurrentApi() ?? undefined);
-
-      if (apiFlag) {
-        const resolved = resolveApiCollection(apiFlag, opts.db);
-        if ("error" in resolved) {
-          printError(resolved.error);
-          process.exitCode = resolved.error.startsWith("Failed") ? 2 : 1;
-          return;
-        }
-        if (!spec && resolved.spec) spec = resolved.spec;
-        if (!tests && resolved.testPath) tests = resolved.testPath;
-      }
-      if (!spec) {
-        printError("Missing --spec <path>. Usage: zond coverage --spec <path> --tests <dir>");
-        process.exitCode = 2;
-        return;
-      }
-      if (!tests) {
-        printError("Missing --tests <dir>. Usage: zond coverage --spec <path> --tests <dir>");
-        process.exitCode = 2;
-        return;
-      }
-      process.exitCode = await coverageCommand({
-        spec,
-        tests,
-        failOnCoverage: opts.failOnCoverage,
-        runId: opts.runId,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── init ──
-  program
-    .command("init [spec]")
-    .description("Bootstrap a workspace, or register an API when --spec is given")
-    .option("--name <name>", "API name (auto-detected from spec title if omitted)")
-    .option("--spec <path>", "Path to OpenAPI spec file (registers a single API)")
-    .option("--base-url <url>", "Override base URL")
-    .option("--dir <path>", "Target directory")
-    .option("--force", "Overwrite existing API collection")
-    .option("--insecure", "Skip TLS verification when fetching the spec")
-    .option("--db <path>", "Path to SQLite database file")
-    .option("--workspace", "Bootstrap a zond workspace (zond.config.yml, apis/, AGENTS.md)")
-    .option("--with-spec <path>", "Bootstrap workspace AND register first API from spec")
-    .option("--no-agents-md", "Skip writing AGENTS.md when bootstrapping")
-    .option("--no-skills", "Skip writing Claude Code skills under .claude/skills/")
-    .action(async (specPos: string | undefined, opts, cmd: Command) => {
-      process.exitCode = await initCommand({
-        name: opts.name,
-        spec: opts.spec ?? specPos,
-        baseUrl: opts.baseUrl,
-        dir: opts.dir,
-        force: opts.force === true,
-        insecure: opts.insecure === true,
-        dbPath: opts.db,
-        workspace: opts.workspace === true,
-        withSpec: opts.withSpec,
-        noAgents: opts.agentsMd === false,
-        noSkills: opts.skills === false,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── describe ──
-  program
-    .command("describe <spec>")
-    .description("Describe endpoints from OpenAPI spec")
-    .option("--compact", "List all endpoints briefly")
-    .option("--list-params", "List all unique parameters across all endpoints")
-    .option("--method <method>", "HTTP method for single endpoint detail")
-    .option("--path <path>", "Endpoint path for single endpoint detail")
-    .action(async (specPath: string, opts, cmd: Command) => {
-      process.exitCode = await describeCommand({
-        specPath,
-        compact: opts.compact === true,
-        listParams: opts.listParams === true,
-        method: opts.method,
-        path: opts.path,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── db (nested) ──
-  const db = program.command("db").description("Query the test database");
-
-  db
-    .command("collections")
-    .description("List all API collections")
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (opts, cmd: Command) => {
-      process.exitCode = await dbCommand({
-        subcommand: "collections",
-        positional: [],
-        dbPath: opts.db,
-        json: globalJson(cmd),
-      });
-    });
-
-  db
-    .command("runs")
-    .description("List recent test runs")
-    .option("--limit <N>", "Maximum number of runs to display", parsePositiveInt("--limit"))
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (opts, cmd: Command) => {
-      process.exitCode = await dbCommand({
-        subcommand: "runs",
-        positional: [],
-        limit: opts.limit,
-        dbPath: opts.db,
-        json: globalJson(cmd),
-      });
-    });
-
-  db
-    .command("run <id>")
-    .description("Show run details")
-    .option("--verbose", "Show all results")
-    .option("--method <method>", "Filter by HTTP method")
-    .option("--status <code>", "Filter by HTTP status code", parseInteger("--status"))
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (id: string, opts, cmd: Command) => {
-      process.exitCode = await dbCommand({
-        subcommand: "run",
-        positional: [id],
-        verbose: opts.verbose === true,
-        method: opts.method,
-        status: opts.status,
-        dbPath: opts.db,
-        json: globalJson(cmd),
-      });
-    });
-
-  db
-    .command("diagnose <id>")
-    .description("Diagnose run failures")
-    .option("--limit <N>", "Examples per failure group", parsePositiveInt("--limit"))
-    .option("--verbose", "Show all examples (not grouped)")
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (id: string, opts, cmd: Command) => {
-      process.exitCode = await dbCommand({
-        subcommand: "diagnose",
-        positional: [id],
-        limit: opts.limit,
-        verbose: opts.verbose === true,
-        dbPath: opts.db,
-        json: globalJson(cmd),
-      });
-    });
-
-  db
-    .command("compare <idA> <idB>")
-    .description("Compare two runs")
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (idA: string, idB: string, opts, cmd: Command) => {
-      process.exitCode = await dbCommand({
-        subcommand: "compare",
-        positional: [idA, idB],
-        dbPath: opts.db,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── request ──
-  program
-    .command("request <method> <url>")
-    .description("Send an ad-hoc HTTP request")
-    .option("--header <H>", `Request header "Name: Value" (repeatable)`, collect, [])
-    .option("--body <json>", "Request body (JSON string)")
-    .option("--timeout <ms>", "Request timeout", parsePositiveInt("--timeout"))
-    .option("--env <name>", "Environment for variable interpolation")
-    .option("--api <name>", "Collection name (loads env from its directory)")
-    .option("--json-path <path>", "Extract value from response (dot notation)")
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (method: string, url: string, opts, cmd: Command) => {
-      const headers = (opts.header as string[] | undefined)?.length ? (opts.header as string[]) : undefined;
-      const api = (opts.api as string | undefined) ?? readCurrentApi() ?? undefined;
-      process.exitCode = await requestCommand({
-        method,
-        url,
-        headers,
-        body: opts.body,
-        timeout: opts.timeout,
-        env: opts.env,
-        api,
-        jsonPath: opts.jsonPath,
-        dbPath: opts.db,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── generate ──
-  program
-    .command("generate <spec>")
-    .description("Generate test suites from OpenAPI spec")
-    .requiredOption("--output <dir>", "Output directory for generated test files")
-    .option("--tag <tag>", "Generate only for endpoints with this tag")
-    .option("--uncovered-only", "Skip endpoints already covered by existing tests")
-    .action(async (specPath: string, opts, cmd: Command) => {
-      process.exitCode = await generateCommand({
-        specPath,
-        output: opts.output,
-        tag: opts.tag,
-        uncoveredOnly: opts.uncoveredOnly === true,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── probe-validation ──
-  program
-    .command("probe-validation <spec>")
-    .description("Generate negative-input probe suites (catches 5xx-on-bad-input bugs)")
-    .requiredOption("--output <dir>", "Output directory for generated probe files")
-    .option("--tag <tag>", "Probe only endpoints with this tag")
-    .option("--list-tags", "List available tags from spec and exit")
-    .option("--max-per-endpoint <N>", "Cap probes per endpoint (default 50)", parsePositiveInt("--max-per-endpoint"))
-    .option("--no-cleanup", "Skip emission of follow-up DELETE cleanup steps for mutating probes (use in namespace-isolated test envs)")
-    .action(async (specPath: string, opts, cmd: Command) => {
-      process.exitCode = await probeValidationCommand({
-        specPath,
-        output: opts.output,
-        tag: opts.tag,
-        maxPerEndpoint: opts.maxPerEndpoint,
-        // Commander: --no-cleanup → opts.cleanup === false; default is true.
-        noCleanup: opts.cleanup === false,
-        json: globalJson(cmd),
-        listTags: opts.listTags,
-      });
-    });
-
-  // ── probe-methods ──
-  program
-    .command("probe-methods <spec>")
-    .description("Generate negative-method probe suites (catches 5xx/2xx on undeclared HTTP methods)")
-    .requiredOption("--output <dir>", "Output directory for generated probe files")
-    .option("--tag <tag>", "Probe only endpoints with this tag")
-    .action(async (specPath: string, opts, cmd: Command) => {
-      process.exitCode = await probeMethodsCommand({
-        specPath,
-        output: opts.output,
-        tag: opts.tag,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── catalog ──
-  program
-    .command("catalog <spec>")
-    .description("Generate API catalog (compact endpoint reference)")
-    .option("--output <dir>", "Output directory (default: current directory)")
-    .action(async (specPath: string, opts, cmd: Command) => {
-      process.exitCode = await catalogCommand({
-        specPath,
-        output: opts.output,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── guide ──
-  program
-    .command("guide <spec>")
-    .description("Generate test generation guide from OpenAPI spec")
-    .option("--tests-dir <dir>", "Filter to uncovered endpoints only")
-    .option("--tag <tag>", "Generate only for endpoints with this tag")
-    .action(async (specPath: string, opts, cmd: Command) => {
-      process.exitCode = await guideCommand({
-        specPath,
-        testsDir: opts.testsDir,
-        tag: opts.tag,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── export (with subcommand: postman) ──
-  const exportCmd = program.command("export").description("Export tests to other formats");
-  exportCmd
-    .command("postman <path>")
-    .description("Export YAML tests as Postman Collection v2.1")
-    .option("--output <file>", "Output file path", "collection.postman.json")
-    .option("--env <file>", "Also export .env.yaml as Postman environment")
-    .option("--collection-name <name>", "Collection name (default: derived from path)")
-    .action(async (testsPath: string, opts, cmd: Command) => {
-      process.exitCode = await exportCommand({
-        testsPath,
-        output: opts.output,
-        env: opts.env,
-        collectionName: opts.collectionName,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── update / self-update ──
-  program
-    .command("update")
-    .alias("self-update")
-    .description("Check for updates and self-update the binary")
-    .option("--check", "Only check for updates, do not download")
-    .action(async (opts, cmd: Command) => {
-      process.exitCode = await updateCommand({
-        check: opts.check === true,
-        json: globalJson(cmd),
-      });
-    });
-
-  // ── sync ──
-  program
-    .command("sync <spec>")
-    .description("Detect new/removed endpoints and generate tests for new ones")
-    .requiredOption("--tests <dir>", "Path to test files directory")
-    .option("--dry-run", "Show what would be generated without writing files")
-    .option("--tag <tag>", "Limit sync to endpoints with this tag")
-    .action(async (specPath: string, opts, cmd: Command) => {
-      process.exitCode = await syncCommand({
-        specPath,
-        testsDir: opts.tests,
-        dryRun: opts.dryRun === true,
-        tag: opts.tag,
-        json: globalJson(cmd),
-      });
-    });
+  registerRun(program);
+
+  registerCheck(program);
+  registerChecks(program);
+  registerLint(program);
+
+  registerCi(program);
+
+  registerUse(program);
+  registerRefreshApi(program);
+  registerDoctor(program);
+
+  registerSession(program);
+  registerCoverage(program);
+
+  registerInit(program);
+  registerAdd(program);
+  registerRemove(program);
+
+  registerDescribe(program);
+  registerDb(program);
+  registerRequest(program);
+
+  registerClean(program);
+  registerCleanup(program);
+
+  registerGenerate(program);
+  registerPrepareFixtures(program);
+  registerFixtures(program);
+  registerAudit(program);
+
+  // m-17 / ARV-49: validate registered probes implement the Probe
+  // contract before commander gets to wire them up. Boot-throws on a
+  // missing slot, so a regression can't slip past CI.
+  bootstrapProbes();
+  // ARV-123/124: populate the anti-FP rule registry before checks run
+  // — checks call applyAntiFp() and need every shipped rule present.
+  bootstrapAntiFp();
+  registerProbes(program);
+
+  registerCatalog(program);
+  registerReport(program);
+
+  registerCompletions(program);
+  registerReference(program);
+  registerApiAnnotate(program);
+
+  // TASK-267: group top-level commands by phase in `zond --help`. Without
+  // grouping, the flat 20+ command list buries the workflow shape; with it,
+  // a new tester can see "setup → generate → run → analyze → report" at a
+  // glance. Commands not listed below stay in the default group.
+  const HELP_GROUPS: Record<string, string> = {
+    // setup: register an API, prepare workspace
+    "init":         "Setup:",
+    "add":          "Setup:",
+    "remove":       "Setup:",
+    "use":          "Setup:",
+    "refresh-api":  "Setup:",
+    "doctor":       "Setup:",
+    "clean":        "Setup:",
+    "cleanup":      "Setup:",
+    // generate: produce suites/probes from the spec
+    "generate":         "Generate:",
+    "prepare-fixtures": "Generate:",
+    "probe":            "Generate:",
+    // run: execute suites against a live API
+    "run":     "Run:",
+    "session": "Run:",
+    "request": "Run:",
+    // analyze: post-run inspection and triage
+    "coverage": "Analyze:",
+    "db":       "Analyze:",
+    "audit":    "Analyze:",
+    "check":    "Analyze:",
+    "checks":   "Analyze:",
+    "describe": "Analyze:",
+    // report: outbound artefacts (HTML, bundles, catalog)
+    "report":  "Report:",
+    "catalog": "Report:",
+    // other: scaffolding / shell integration
+    "ci":          "Other:",
+    "completions": "Other:",
+    "reference":   "Other:",
+  };
+  for (const sub of program.commands) {
+    const group = HELP_GROUPS[sub.name()];
+    if (group) sub.helpGroup(group);
+  }
 
-  // ── completions ──
-  program
-    .command("completions <shell>")
-    .description(`Generate shell completion script (${COMPLETION_SHELLS.join(", ")})`)
-    .action((shell: string) => {
-      if (!(COMPLETION_SHELLS as readonly string[]).includes(shell)) {
-        printError(`Unsupported shell: ${shell}. Supported: ${COMPLETION_SHELLS.join(", ")}`);
-        process.exitCode = 2;
-        return;
-      }
-      process.exitCode = completionsCommand({ shell: shell as CompletionShell, program });
-    });
+  // TASK-73: previously `--json` was a top-level/global option that propagated
+  // to every subcommand, which collided with `run --report json` (and broke
+  // `run --json` outright). Now it is per-command. Attach `--json` to every
+  // subcommand that previously read it via globalJson(), EXCEPT `run` —
+  // run's only JSON output path is `--report json`.
+  // Skip by fully-qualified path so `db run` (inner) keeps --json while
+  // top-level `run` does not.
+  const skipJson = new Set(["run", "completions"]);
+  const attachJson = (cmd: Command, parentPath: string): void => {
+    const path = parentPath ? `${parentPath} ${cmd.name()}` : cmd.name();
+    // Only leaf commands (those with action handlers) get --json — parent
+    // namespace commands like `db` and `ci` would otherwise shadow the option
+    // on their children and `cmd.opts()` on the leaf would not see --json.
+    const hasAction = (cmd as unknown as { _actionHandler?: unknown })._actionHandler != null;
+    if (hasAction && !skipJson.has(path)) {
+      cmd.option(
+        "--json",
+        "Emit a `{ok, command, data, warnings, errors}` envelope on stdout. " +
+        "Distinct from `zond run --report json` (which is a per-test test-run report).",
+      );
+    }
+    for (const sub of cmd.commands) attachJson(sub, path);
+  };
+  for (const sub of program.commands) attachJson(sub, "");
+
+  // TASK-297: stamp every leaf with a "related skill" footer so `zond <cmd>
+  // --help` is a single-stop entry point for an agent: discover the flag
+  // surface AND know which skill file to open for the workflow context.
+  // Mapped by fully-qualified path; `*` matches any unnamed leaf and is
+  // tried last.
+  const skillFor: Record<string, string> = {
+    // Depth-check & probe commands → checks skill (annotate flow + m-20).
+    "checks run": "skills/zond-checks.md",
+    "checks list": "skills/zond-checks.md",
+    "api annotate": "skills/zond-checks.md",
+    "probe security": "skills/zond-checks.md",
+    "probe mass-assignment": "skills/zond-checks.md",
+    // Triage-class commands.
+    "db diagnose": "skills/zond-triage.md",
+    "db compare": "skills/zond-triage.md",
+  };
+  const attachHelp = (cmd: Command, parentPath: string): void => {
+    const path = parentPath ? `${parentPath} ${cmd.name()}` : cmd.name();
+    const hasAction = (cmd as unknown as { _actionHandler?: unknown })._actionHandler != null;
+    if (hasAction) {
+      const skill = skillFor[path] ?? "skills/zond.md";
+      cmd.addHelpText("after", `\nRelated skill: ${skill}`);
+    }
+    for (const sub of cmd.commands) attachHelp(sub, path);
+  };
+  for (const sub of program.commands) attachHelp(sub, "");
 
   return program;
 }