@kirrosh/zond 0.21.0 → 0.23.0

package/src/cli/json-envelope.ts

@@ -1,19 +1,128 @@
+/**
+ * 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: 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: string[], warnings?: string[]): JsonEnvelope<null> {
-  return { ok: false, command, data: null, 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;
+}
+
+/**
+ * High-order wrapper for `--json` action handlers. Accepts an async
+ * producer and renders its return value (or thrown error) as an
+ * envelope. Errors thrown synchronously or asynchronously become
+ * `{ ok: false, errors: [{code: "unknown_error", message}] }` with
+ * `exitCode = 2`.
+ */
+export async function withEnvelope<T>(
+  command: string,
+  produce: () => Promise<{ data: T; warnings?: string[] }>,
+): Promise<number> {
+  try {
+    const { data, warnings } = await produce();
+    return writeEnvelope(command, { ok: true, data, warnings });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return writeEnvelope(command, { ok: false, errors: [message] });
+  }
+}

package/src/cli/json-schemas.ts

@@ -0,0 +1,263 @@
+/**
+ * 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()),
+});
+
+export const ChecksRunDataSchema = z.object({
+  findings: z.array(CheckFindingSchema),
+  summary: CheckRunSummarySchema,
+});
+
+/** 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(),
+  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,
+});
+
+export const NdjsonEventSchema = z.discriminatedUnion("type", [
+  NdjsonCheckStartEventSchema,
+  NdjsonCheckResultEventSchema,
+  NdjsonFindingEventSchema,
+  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/program.ts

@@ -0,0 +1,218 @@
+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 { 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);
+  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);
+  }
+
+  // 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;
+}