@kirrosh/zond 0.26.0 → 0.27.0

package/src/cli/json-envelope.ts

@@ -1,108 +0,0 @@
-/**
- * Single source of truth for `--json` output across all CLI commands.
- *
- * Every `--json` response carries the same envelope:
- *
- *   { ok, command, data, warnings, errors, exit_code? }
- *
- * Commands construct the payload (`data`) and ask one of the helpers
- * below to render it. Don't `console.log(JSON.stringify(...))` ad-hoc
- * for `--json` paths — go through `printJson` / `writeEnvelope` so the
- * shape stays uniform (TASK-73, TASK-74, closed by TASK-184).
- *
- * TASK-296: errors[] is a list of `{code, message, details?}` so an
- * agent can route on `code` without parsing the human message. Helpers
- * accept either a bare `string` (auto-wrapped with code `unknown_error`)
- * or a structured `ZondError` to keep call sites short.
- */
-
-// TASK-295: types are derived from the zod schemas in `./json-schemas.ts`
-// so the published JSON Schema (docs/json-schema/) and the runtime types
-// can never drift. Edit the enum/object there, run `bun run schemas`,
-// commit the regenerated docs.
-import type { z } from "zod";
-import {
-  ZondErrorCodeSchema,
-  ZondErrorSchema,
-} from "./json-schemas.ts";
-
-export type ZondErrorCode = z.infer<typeof ZondErrorCodeSchema>;
-export type ZondError = z.infer<typeof ZondErrorSchema>;
-
-export interface JsonEnvelope<T = unknown> {
-  ok: boolean;
-  command: string;
-  data: T;
-  warnings: string[];
-  errors: ZondError[];
-  /** Exit code the process will return. Present on error envelopes so a
-   *  caller can read the taxonomy class without re-parsing $? from a shell
-   *  (see ZOND.md → "Exit codes"). */
-  exit_code?: number;
-}
-
-/** Accept either a bare string (auto-coded `unknown_error`) or a fully-
- *  structured `ZondError`. Lets us migrate ~100 call sites incrementally
- *  without breaking the schema. */
-export type ErrorInput = string | ZondError;
-
-function normalizeErrors(errs: readonly ErrorInput[]): ZondError[] {
-  return errs.map(e =>
-    typeof e === "string" ? { code: "unknown_error" as const, message: e } : e,
-  );
-}
-
-export function jsonOk<T>(command: string, data: T, warnings?: string[]): JsonEnvelope<T> {
-  return { ok: true, command, data, warnings: warnings ?? [], errors: [] };
-}
-
-export function jsonError(
-  command: string,
-  errors: readonly ErrorInput[],
-  warnings?: string[],
-  exitCode = 2,
-): JsonEnvelope<null> {
-  return {
-    ok: false,
-    command,
-    data: null,
-    warnings: warnings ?? [],
-    errors: normalizeErrors(errors),
-    exit_code: exitCode,
-  };
-}
-
-export function printJson(envelope: JsonEnvelope): void {
-  process.stdout.write(JSON.stringify(envelope, null, 2) + "\n");
-}
-
-/** Convenience constructor: `zerr("env_missing", "base_url not set", { var: "base_url" })`. */
-export function zerr(code: ZondErrorCode, message: string, details?: Record<string, unknown>): ZondError {
-  return details ? { code, message, details } : { code, message };
-}
-
-/** Discriminated-union result an action can hand back to {@link writeEnvelope}. */
-export type EnvelopeResult<T> =
-  | { ok: true; data: T; warnings?: string[] }
-  | { ok: false; errors: readonly ErrorInput[]; warnings?: string[]; exitCode?: number };
-
-/**
- * Render a typed `EnvelopeResult` to stdout as a JSON envelope and return
- * the process exit code (0 on ok, `result.exitCode ?? 2` on error). This
- * is the recommended wrapper for new commands — it lets the handler
- * focus on producing a payload and surfaces the right exit code in one
- * call:
- *
- *     const result = await doWork();
- *     if (options.json) return writeEnvelope("my-cmd", result);
- *     // …human path…
- */
-export function writeEnvelope<T>(command: string, result: EnvelopeResult<T>): number {
-  if (result.ok) {
-    printJson(jsonOk(command, result.data, result.warnings));
-    return 0;
-  }
-  const exit = result.exitCode ?? 2;
-  printJson(jsonError(command, result.errors, result.warnings, exit));
-  return exit;
-}

package/src/cli/json-schemas.ts

@@ -1,314 +0,0 @@
-/**
- * TASK-295: zod sources of truth for the `--json` envelope shape and its
- * sub-types. Run `bun run scripts/emit-json-schemas.ts` after changing
- * any of these to regenerate `docs/json-schema/*.schema.json`.
- *
- * Why zod first, JSON Schema second: zod is the type AND the validator
- * we already ship; emitting JSON Schema from it keeps the published
- * schema and the runtime checks in lock-step. New fields land here and
- * propagate, instead of drifting between two hand-maintained shapes.
- */
-
-import { z } from "zod";
-
-/** TASK-296 closed enum — must stay in sync with `ZondErrorCode` in
- *  `src/cli/json-envelope.ts`. */
-export const ZondErrorCodeSchema = z.enum([
-  "unknown_error",
-  "env_missing",
-  "fixture_missing",
-  "network_timeout",
-  "network_error",
-  "sandbox_blocked",
-  "spec_load_failure",
-  "yaml_parse_error",
-  "workspace_not_found",
-  "file_not_found",
-  "permission_denied",
-  "argument_invalid",
-  "api_not_registered",
-  "db_error",
-  "auth_config_error",
-]);
-
-export const ZondErrorSchema = z.object({
-  code: ZondErrorCodeSchema,
-  message: z.string(),
-  details: z.record(z.string(), z.unknown()).optional(),
-});
-
-/** TASK-294 closed enum — must stay in sync with `RecommendedAction` in
- *  `src/core/diagnostics/failure-hints.ts` and the per-check mapping in
- *  `src/core/checks/recommended-action.ts` (ARV-11).
- *  ARV-11 added three values for the depth-checks framework:
- *    - `tighten_validation` — server accepted invalid input.
- *    - `add_required_header` — server didn't enforce a required header.
- *    - `wontfix_known_limitation` — known/accepted gap; agent should
- *       not retry or report. */
-export const RecommendedActionSchema = z.enum([
-  "report_backend_bug",
-  "fix_auth_config",
-  "fix_test_logic",
-  "fix_network_config",
-  "fix_env",
-  "fix_spec",
-  "fix_fixture",
-  // ARV-42 — re-run `zond generate` for failures rooted in generator-emitted
-  // bodies; editing the YAML directly is overwritten by the next regenerate.
-  "regenerate_suite",
-  "tighten_validation",
-  "add_required_header",
-  "wontfix_known_limitation",
-]);
-
-/** Envelope body. `data` is open (`unknown`) so this schema covers every
- *  command without enumerating each payload — command-specific schemas
- *  can refine `data` per-command in a follow-up. */
-export const JsonEnvelopeSchema = z.object({
-  ok: z.boolean(),
-  command: z.string(),
-  data: z.unknown(),
-  warnings: z.array(z.string()),
-  errors: z.array(ZondErrorSchema),
-  exit_code: z.number().int().optional(),
-});
-
-/** ARV-1 (m-15): shape of `data` for `zond checks run --json`. The
- *  envelope itself stays the generic JsonEnvelopeSchema; this schema
- *  pins the per-command payload so agents can validate findings without
- *  parsing them by-hand. ARV-11 adds `recommended_action` as a closed
- *  enum on each finding. */
-export const SeveritySchema = z.enum(["critical", "high", "medium", "low", "info"]);
-export const CategorySchema = z.enum(["security", "reliability", "contract", "hygiene"]);
-
-export const CheckFindingSchema = z.object({
-  check: z.string(),
-  severity: SeveritySchema,
-  // ARV-251: category drives per-section roll-up. Optional on the wire
-  // for backwards compat with older NDJSON streams — derived by reader
-  // from check id if absent.
-  category: CategorySchema.optional(),
-  operation: z.object({
-    path: z.string(),
-    method: z.string(),
-    operationId: z.string().optional(),
-  }),
-  request_signature: z.string(),
-  response_summary: z.object({
-    status: z.number().int(),
-    content_type: z.string().optional(),
-  }),
-  message: z.string(),
-  evidence: z.record(z.string(), z.unknown()).optional(),
-  // ARV-11: recommended_action is now a closed enum so agents can
-  // route on it without parsing free-form strings. Same enum used by
-  // `db diagnose` (TASK-294) plus three depth-check additions.
-  recommended_action: RecommendedActionSchema.optional(),
-});
-
-export const CheckRunSummarySchema = z.object({
-  operations: z.number().int().nonnegative(),
-  cases: z.number().int().nonnegative(),
-  checks_run: z.number().int().nonnegative(),
-  findings: z.number().int().nonnegative(),
-  by_severity: z.object({
-    critical: z.number().int().nonnegative(),
-    high: z.number().int().nonnegative(),
-    medium: z.number().int().nonnegative(),
-    low: z.number().int().nonnegative(),
-    info: z.number().int().nonnegative(),
-  }),
-  by_category: z.object({
-    security: z.number().int().nonnegative(),
-    reliability: z.number().int().nonnegative(),
-    contract: z.number().int().nonnegative(),
-    hygiene: z.number().int().nonnegative(),
-  }),
-  // ARV-26: per-(check, reason) skip tally — surfaces probe outcomes that
-  // never produced a checkable response (e.g. probe got 4xx, schema only on
-  // 200) so "0 findings" doesn't read as "all green".
-  skipped_outcomes: z.record(z.string(), z.number().int().nonnegative()),
-  // ARV-83: structured counterpart to skipped_outcomes — split into
-  // {check, reason, count} so consumers don't have to colon-tokenise a
-  // reason that may itself contain colons. Sorted by count desc.
-  skipped_outcomes_grouped: z.array(z.object({
-    check: z.string(),
-    reason: z.string(),
-    count: z.number().int().nonnegative(),
-  })),
-  // ARV-283 / ARV-68: count of findings the severity matrix demoted to
-  // `info-suppressed`. Excluded from `findings` / `by_severity` so CI
-  // gates ignore them, but exposed here so consumers (ajv validators
-  // included) accept the field — the runner emits it unconditionally.
-  suppressed: z.number().int().nonnegative().optional(),
-});
-
-/** ARV-60: spec-level rollup row. Emitted when ≥80% of a check's
- *  applicable operations share the same root cause (status drift,
- *  missing-declaration skip cluster, or no-detector zero-case). Lives in
- *  `data.spec_findings` and as its own `spec_finding` NDJSON event. */
-export const SpecFindingSchema = z.object({
-  check: z.string(),
-  kind: z.enum(["status_drift", "missing_declaration", "no_detector", "broken_baseline", "other"]),
-  severity: SeveritySchema,
-  category: CategorySchema.optional(),
-  reason: z.string(),
-  fix_hint: z.string(),
-  affected_operations: z.array(z.object({
-    path: z.string(),
-    method: z.string(),
-    operationId: z.string().optional(),
-  })),
-  count: z.number().int().nonnegative(),
-  applicable: z.number().int().nonnegative(),
-});
-
-export const ChecksRunDataSchema = z.object({
-  findings: z.array(CheckFindingSchema),
-  summary: CheckRunSummarySchema,
-  // ARV-60: always present (empty array when no clusters cross 80%).
-  spec_findings: z.array(SpecFindingSchema),
-});
-
-/** ARV-10 (m-15): NDJSON streaming events emitted by `zond checks run
- *  --ndjson`. Each event is a snapshot JSON line on stdout — agents pipe
- *  the stream into `jq` / a validator and consume findings as they happen
- *  rather than waiting for the run to finish. The discriminated union
- *  below is the schema we publish — every emitted line MUST match one
- *  branch exactly (verified by ajv in tests). */
-const OperationRefSchema = z.object({
-  path: z.string(),
-  method: z.string(),
-  operationId: z.string().optional(),
-});
-
-export const NdjsonCheckStartEventSchema = z.object({
-  type: z.literal("check_start"),
-  ts: z.string(),
-  operation: OperationRefSchema,
-});
-
-export const NdjsonCheckResultEventSchema = z.object({
-  type: z.literal("check_result"),
-  ts: z.string(),
-  check: z.string(),
-  // ARV-215: severity from the registry (mirrors `zond checks list`
-  // [high|medium|low]). Lets consumers group NDJSON by severity without
-  // re-joining against the registry.
-  severity: z.enum(["info", "low", "medium", "high", "critical"]),
-  verdict: z.enum(["pass", "fail"]),
-  operation: OperationRefSchema,
-  request_signature: z.string(),
-  response: z.object({
-    status: z.number().int(),
-    content_type: z.string().optional(),
-  }),
-});
-
-export const NdjsonFindingEventSchema = z.object({
-  type: z.literal("finding"),
-  ts: z.string(),
-  // ARV-156: mirror the top-level `check` field carried by check_start /
-  // check_result so consumer pipelines can `jq -c '.check'` uniformly
-  // across event types without branching on `.type`. The same value lives
-  // inside `.finding.check` — existing consumers reading the nested form
-  // keep working (back-compat addition, not a rename).
-  check: z.string(),
-  finding: CheckFindingSchema,
-});
-
-export const NdjsonSummaryEventSchema = z.object({
-  type: z.literal("summary"),
-  ts: z.string(),
-  summary: CheckRunSummarySchema,
-});
-
-/** ARV-60: rolled-up spec-level finding event. Emitted before the
- *  terminal `summary` event so streaming consumers see clusters in the
- *  same order the CLI renders them. Per-op `finding` events are NOT
- *  removed — both layers coexist. */
-export const NdjsonSpecFindingEventSchema = z.object({
-  type: z.literal("spec_finding"),
-  ts: z.string(),
-  check: z.string(),
-  spec_finding: SpecFindingSchema,
-});
-
-export const NdjsonEventSchema = z.discriminatedUnion("type", [
-  NdjsonCheckStartEventSchema,
-  NdjsonCheckResultEventSchema,
-  NdjsonFindingEventSchema,
-  NdjsonSpecFindingEventSchema,
-  NdjsonSummaryEventSchema,
-]);
-
-/** m-17 / ARV-50: shape of `data` for `zond probe <class> --dry-run --json`.
- *  Severity is intentionally absent — nothing is classified yet, so
- *  reusing the run-time bucket would mislead CI gates (F1-15). The
- *  `skip_reason` enum is open across probe families (e.g. security has
- *  `isolated-protected`, mass-assignment has its own subset); we keep
- *  it as a string with documented values rather than a closed enum
- *  that needs to be rev'd every time a new class lands. */
-export const ProbeEndpointPlanSchema = z.object({
-  path: z.string(),
-  method: z.string(),
-  planned: z.boolean(),
-  classes_planned: z.array(z.string()),
-  fields_planned: z.array(z.string()),
-  skip_reason: z.string().nullable(),
-});
-
-export const ProbeDryRunDataSchema = z.object({
-  endpoints: z.array(ProbeEndpointPlanSchema),
-  summary: z.object({
-    totalEndpoints: z.number().int().nonnegative(),
-    planned: z.number().int().nonnegative(),
-    skipped: z.number().int().nonnegative(),
-  }),
-});
-
-/** m-17 / ARV-51: shape of `data` for live probe runs (`zond probe <class>
- *  --report json` or the default `--json`). One entry per endpoint with
- *  structured findings — no markdown blob. The legacy `data.digest.stdout`
- *  field is gone (F3-15 / F4-15). */
-export const ProbeFindingSchema = z.object({
-  class: z.string(),
-  severity: z.enum(["high", "low", "inconclusive", "ok"]),
-  evidence: z.record(z.string(), z.unknown()),
-});
-
-export const ProbeEndpointResultSchema = z.object({
-  path: z.string(),
-  method: z.string(),
-  classes_run: z.array(z.string()),
-  findings: z.array(ProbeFindingSchema),
-  status: z.enum(["ok", "high", "low", "inconclusive", "skipped"]),
-  skip_reason: z.string().optional(),
-});
-
-export const ProbeRunDataSchema = z.object({
-  endpoints: z.array(ProbeEndpointResultSchema),
-  summary: z.object({
-    totalEndpoints: z.number().int().nonnegative(),
-    probed: z.number().int().nonnegative(),
-    by_status: z.object({
-      ok: z.number().int().nonnegative(),
-      high: z.number().int().nonnegative(),
-      low: z.number().int().nonnegative(),
-      inconclusive: z.number().int().nonnegative(),
-      skipped: z.number().int().nonnegative(),
-    }),
-  }),
-});
-
-export const SCHEMAS = {
-  envelope: JsonEnvelopeSchema,
-  error: ZondErrorSchema,
-  errorCode: ZondErrorCodeSchema,
-  recommendedAction: RecommendedActionSchema,
-  checksRunData: ChecksRunDataSchema,
-  checkFinding: CheckFindingSchema,
-  "ndjson-events": NdjsonEventSchema,
-  probeDryRun: ProbeDryRunDataSchema,
-  probeRun: ProbeRunDataSchema,
-} as const;

package/src/cli/output.ts

@@ -1,40 +0,0 @@
-const RESET = "\x1b[0m";
-const RED = "\x1b[31m";
-const GREEN = "\x1b[32m";
-const YELLOW = "\x1b[33m";
-
-function useColor(): boolean {
-  return process.stderr.isTTY ?? false;
-}
-
-let debugHintShown = false;
-
-// ARV-203: when a command catches an unexpected throw and calls
-// `printError(msg, err)`, gate the stack trace behind ZOND_DEBUG=1.
-// Without the env var, append a one-time hint so the user knows the
-// switch exists — the previous behaviour silently dropped TypeError
-// stacks and forced reverse-engineering from the bare message.
-export function printError(message: string, err?: unknown): void {
-  const msg = useColor() ? `${RED}Error: ${message}${RESET}` : `Error: ${message}`;
-  process.stderr.write(msg + "\n");
-  if (err === undefined) return;
-  if (process.env.ZOND_DEBUG === "1" && err instanceof Error && err.stack) {
-    process.stderr.write(err.stack + "\n");
-    return;
-  }
-  if (!debugHintShown) {
-    debugHintShown = true;
-    process.stderr.write("  hint: set ZOND_DEBUG=1 to print the full stack trace.\n");
-  }
-}
-
-export function printSuccess(message: string): void {
-  const color = process.stdout.isTTY ?? false;
-  const msg = color ? `${GREEN}${message}${RESET}` : message;
-  process.stdout.write(msg + "\n");
-}
-
-export function printWarning(message: string): void {
-  const msg = useColor() ? `${YELLOW}Warning: ${message}${RESET}` : `Warning: ${message}`;
-  process.stderr.write(msg + "\n");
-}

package/src/cli/program.ts

@@ -1,219 +0,0 @@
-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 { registerSecrets } from "./commands/secrets.ts";
-import { registerProbes } from "./commands/probe.ts";
-import { bootstrapProbes } from "../core/probe/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 { registerSchemaFromRuns } from "./commands/schema-from-runs.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 { preprocessArgv } from "./argv.ts";
-
-export { preprocessArgv };
-
-// ── Program builder ──
-
-export function buildProgram(): Command {
-  const program = new Command("zond")
-    .description("API Testing Platform")
-    .version(`${VERSION} (${getRuntimeInfo()})`, "-v, --version", "Show version")
-    .helpOption("-h, --help", "Show this help")
-    .showHelpAfterError("(run 'zond --help' for usage)")
-    .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>`).",
-    )
-    .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;
-      }
-    });
-
-  registerRun(program);
-
-  registerCheck(program);
-  registerChecks(program);
-  registerLint(program);
-
-  registerCi(program);
-
-  registerUse(program);
-  registerRefreshApi(program);
-  registerSchemaFromRuns(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);
-  registerSecrets(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();
-  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:",
-    "secrets":      "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);
-  }
-
-  // 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;
-}