@kirrosh/zond 0.26.1 → 0.27.0

package/src/cli/commands/doctor.ts

@@ -1,661 +0,0 @@
-/**
- * `zond doctor` — operator-friendly health check for a registered API.
- *
- * Surfaces three things the skill (and the user) need before running tests:
- *   1. Which `.env.yaml` variables are missing relative to `.api-fixtures.yaml`.
- *      Required gaps are blockers; optional gaps are warnings.
- *   2. Whether the artifact snapshots (`.api-catalog.yaml`,
- *      `.api-resources.yaml`, `.api-fixtures.yaml`) are in sync with the
- *      local `spec.json` (specHash match).
- *   3. The local `spec.json` itself — present? readable? matches what's
- *      registered in the DB?
- *
- * Output:
- *   - human form: structured, three sections.
- *   - --json envelope: { fixtures: { required, optional }, stale: [...], spec: { ... } }
- *
- * Exit codes:
- *   0 — all required fixtures present + artifacts fresh.
- *   1 — required fixture missing (the user must edit `.env.yaml`).
- *   2 — workspace problem (no API, missing artifact, stale).
- */
-
-import { readFileSync, existsSync } from "node:fs";
-import { join, resolve, isAbsolute } from "node:path";
-import YAML from "yaml";
-import { getDb } from "../../db/schema.ts";
-import { findCollectionByNameOrId, listCollections } from "../../db/queries.ts";
-import { findWorkspaceRoot } from "../../core/workspace/root.ts";
-import { resolveCollectionSpec } from "../../core/setup-api.ts";
-import { loadEnvironment } from "../../core/parser/variables.ts";
-import { loadSecretsFromAncestor } from "../../core/secrets/secrets-file.ts";
-import { loadIdentityFromAncestor } from "../../core/identity/identity-file.ts";
-import { hashSpec } from "../../core/meta/meta-store.ts";
-import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
-import { printError } from "../output.ts";
-import { getApi } from "../util/api-context.ts";
-import { detectSkillDrift } from "./init/skills.ts";
-
-export interface DoctorOptions {
-  api?: string;
-  json?: boolean;
-  dbPath?: string;
-  /** TASK-145: hide rows that are already healthy. Required fixtures with
-   *  values, optional fixtures, fresh artifacts disappear from output;
-   *  only the items doctor wants the user to fix remain. Applies to both
-   *  text and `--json` shapes. */
-  missingOnly?: boolean;
-  /** TASK-145: dot-path into the report payload (e.g. `fixtures.required`).
-   *  When set, doctor emits the resolved subtree as JSON to stdout (no
-   *  envelope) — pipe-friendly without `jq`. */
-  query?: string;
-}
-
-interface FixtureRow {
-  name: string;
-  source: string;
-  required: boolean;
-  description: string;
-  defaultValue?: string;
-  affectedEndpoints: string[];
-}
-
-interface FixtureManifestShape {
-  generatedAt?: string;
-  specHash?: string;
-  fixtures: FixtureRow[];
-}
-
-interface ArtifactStaleness {
-  file: string;
-  expected: string | null;
-  actual: string | null;
-  fresh: boolean;
-}
-
-/** TASK-172 (m-10): per-fixture metadata returned by doctor. Secrets
- *  carry no value (only set/length/secret:true); identity values are
- *  visible because that's the whole point of `.identity.yaml` (locally
- *  triagable, opt-in redaction with --redact-identity). */
-export interface FixtureMetaRow {
-  name: string;
-  set: boolean;
-  /** UTF-16 length (string.length). Useful for "is the right token
-   *  pasted, is it the 64-char one or the 32-char one?" */
-  length: number;
-  source: string;
-  description: string;
-  affectedEndpoints: string[];
-  /** True when the value came from `.secrets.yaml` or is otherwise
-   *  registered in the SecretRegistry. `value` is omitted for secrets. */
-  secret?: true;
-  /** True when the value came from `.identity.yaml`. */
-  identity?: true;
-  /** Resolved value — present for env / identity entries, omitted for
-   *  secrets so doctor never echoes a token. */
-  value?: string;
-  /** True when the value looks like a synthetic placeholder ("example",
-   *  "string", "1") rather than a real fixture. Doctor still treats the
-   *  fixture as `set` (it has a value) but flags it as suspicious so the
-   *  user knows positive/CRUD suites will hit fake IDs (TASK-216). */
-  placeholder?: true;
-}
-
-/** Synthetic stub values that cannot identify a real resource. Path-source
- *  fixtures sitting on these strings would route to non-existent IDs and
- *  return 404/422, so doctor treats them as "needs filling" rather than OK. */
-const PLACEHOLDER_VALUES = new Set(["example", "string", "1", "0"]);
-
-function looksLikePlaceholder(source: string, value: string | undefined): boolean {
-  if (source !== "path") return false;
-  if (typeof value !== "string") return false;
-  return PLACEHOLDER_VALUES.has(value.trim().toLowerCase());
-}
-
-interface DoctorReport {
-  api: string;
-  mode: "spec" | "run-only";
-  baseDir: string;
-  spec: {
-    path: string;
-    exists: boolean;
-    sha: string | null;
-  };
-  endpoints: {
-    total: number;
-    by_method: Record<string, number>;
-  } | null;
-  fixtures: {
-    required: FixtureMetaRow[];
-    optional: FixtureMetaRow[];
-    extraInEnv: string[];   // keys in .env.yaml that aren't in the manifest (informational)
-  };
-  staleArtifacts: ArtifactStaleness[];
-  blockedRequired: number;
-  warnings: string[];
-}
-
-interface DoctorRunOnlyReport {
-  api: string;
-  mode: "run-only";
-  baseDir: string;
-  envVars: Record<string, string>;
-  recommendation: string;
-}
-
-/** Read & parse a YAML artifact, returning null if missing. */
-function readYamlIfExists<T>(path: string): T | null {
-  if (!existsSync(path)) return null;
-  try {
-    return YAML.parse(readFileSync(path, "utf-8")) as T;
-  } catch {
-    return null;
-  }
-}
-
-function readArtifactSpecHash(path: string): string | null {
-  if (!existsSync(path)) return null;
-  try {
-    // Scan only the first 25 lines for the specHash field — it always appears
-    // near the top of artifact files. Avoids YAML-parsing the entire file,
-    // which can fail or be very slow for large catalogs (150KB+).
-    const raw = readFileSync(path, "utf-8");
-    const lines = raw.split("\n", 25);
-    for (const line of lines) {
-      const m = line.match(/^specHash:\s*["']?([0-9a-f]{64})["']?/);
-      if (m) return m[1]!;
-    }
-    // Fallback for non-standard layouts.
-    const doc = readYamlIfExists<{ specHash?: unknown }>(path);
-    return typeof doc?.specHash === "string" ? doc.specHash : null;
-  } catch {
-    return null;
-  }
-}
-
-function maskSecret(value: string): string {
-  if (value.length <= 6) return "***";
-  return `${"*".repeat(Math.max(value.length - 4, 4))}set`;
-}
-
-function isLikelySecret(name: string): boolean {
-  return /token|secret|key|password|pwd|api_key/i.test(name);
-}
-
-export async function doctorCommand(opts: DoctorOptions): Promise<number> {
-  try {
-    getDb(opts.dbPath);
-  } catch (err) {
-    const message = `DB unavailable: ${(err as Error).message}`;
-    if (opts.json) printJson(jsonError("doctor", [message]));
-    else printError(message);
-    return 2;
-  }
-
-  // Resolve target API
-  let apiName = opts.api;
-  if (!apiName) {
-    const cols = listCollections();
-    if (cols.length === 0) {
-      const message = "No API registered. Run `zond add api <name> --spec <path>` first.";
-      if (opts.json) printJson(jsonError("doctor", [message]));
-      else printError(message);
-      return 2;
-    }
-    if (cols.length > 1) {
-      const message = `Multiple APIs registered (${cols.map(c => c.name).join(", ")}). Pass --api <name>.`;
-      if (opts.json) printJson(jsonError("doctor", [message]));
-      else printError(message);
-      return 2;
-    }
-    apiName = cols[0]!.name;
-  }
-
-  const collection = findCollectionByNameOrId(apiName);
-  if (!collection) {
-    const message = `API '${apiName}' not found.`;
-    if (opts.json) printJson(jsonError("doctor", [message]));
-    else printError(message);
-    return 2;
-  }
-
-  const baseDir = collection.base_dir
-    ?? join(findWorkspaceRoot().root, "apis", apiName);
-
-  // Spec-less API: short-circuit. Such APIs are registered with --base-url
-  // only and have no .api-catalog/.api-resources/.api-fixtures to check. We
-  // surface what we have (env vars, base_dir) and tell the user how to upgrade.
-  if (!collection.openapi_spec) {
-    const envVars = await loadEnvironment(undefined, baseDir);
-    const recommendation =
-      `This API has no OpenAPI spec — generate/probe/validate-schema are disabled. ` +
-      `Run \`zond refresh-api ${apiName} --spec <path|url>\` to attach one.`;
-    const report: DoctorRunOnlyReport = {
-      api: apiName,
-      mode: "run-only",
-      baseDir,
-      envVars,
-      recommendation,
-    };
-    if (opts.json) {
-      printJson(jsonOk("doctor", report));
-    } else {
-      printRunOnlyHuman(report);
-    }
-    return 0;
-  }
-
-  // 1. Spec snapshot
-  let specAbsPath: string | null = null;
-  let specSha: string | null = null;
-  let specExists = false;
-  if (collection.openapi_spec) {
-    try {
-      specAbsPath = resolveCollectionSpec(collection.openapi_spec);
-      if (!isAbsolute(specAbsPath)) {
-        specAbsPath = resolve(findWorkspaceRoot().root, specAbsPath);
-      }
-      specExists = existsSync(specAbsPath);
-      if (specExists) {
-        try {
-          // Hash the file bytes directly — matches what setup-api / refresh-api
-          // record in the artifact specHash fields (TASK-215). Re-parsing and
-          // re-stringifying drops shared $ref identity and yields a different
-          // hash than the producer recorded.
-          specSha = hashSpec(readFileSync(specAbsPath, "utf-8"));
-        } catch {
-          // unreadable — leave sha null
-        }
-      }
-    } catch (err) {
-      // resolveCollectionSpec throws on legacy/stale workspace — that's
-      // exactly what doctor should report, just without crashing.
-      const m = (err as Error).message;
-      if (opts.json) printJson(jsonError("doctor", [m]));
-      else printError(m);
-      return 2;
-    }
-  }
-
-  // 2. Artifact staleness — compare each artifact's specHash to spec.json sha
-  const staleArtifacts: ArtifactStaleness[] = [];
-  for (const [file, label] of [
-    [".api-catalog.yaml", "catalog"],
-    [".api-resources.yaml", "resources"],
-    [".api-fixtures.yaml", "fixtures"],
-  ] as const) {
-    const path = join(baseDir, file);
-    if (!existsSync(path)) {
-      staleArtifacts.push({ file: label, expected: specSha, actual: null, fresh: false });
-      continue;
-    }
-    const actual = readArtifactSpecHash(path);
-    const fresh = !!specSha && actual === specSha;
-    staleArtifacts.push({ file: label, expected: specSha, actual, fresh });
-  }
-
-  // 3. Fixtures manifest vs .env.yaml
-  const manifestPath = join(baseDir, ".api-fixtures.yaml");
-  const manifest = readYamlIfExists<FixtureManifestShape>(manifestPath);
-  const envVars = await loadEnvironment(undefined, baseDir);
-
-  // TASK-172 (m-10): classify each fixture as secret / identity / plain
-  // env so doctor never echoes a raw secret. The secret registry was
-  // populated by loadEnvironment above (which loads .secrets.yaml as a
-  // side-effect); identity comes from `.secrets`'s sibling file.
-  const secretRaw = loadSecretsFromAncestor(baseDir);
-  const identityRaw = loadIdentityFromAncestor(baseDir);
-  const secretKeys = new Set(secretRaw ? Object.keys(secretRaw.values) : []);
-  const identityKeys = new Set(identityRaw ? Object.keys(identityRaw.values) : []);
-
-  const requiredOut: DoctorReport["fixtures"]["required"] = [];
-  const optionalOut: DoctorReport["fixtures"]["optional"] = [];
-  const declaredVars = new Set<string>();
-
-  if (manifest?.fixtures) {
-    for (const f of manifest.fixtures) {
-      declaredVars.add(f.name);
-      const value = envVars[f.name];
-      const set = typeof value === "string" && value.length > 0;
-      const isSecret = secretKeys.has(f.name);
-      const isIdentity = identityKeys.has(f.name);
-      const placeholder = !isSecret && looksLikePlaceholder(f.source, value);
-      const row: FixtureMetaRow = {
-        name: f.name,
-        set,
-        length: typeof value === "string" ? value.length : 0,
-        source: f.source,
-        description: f.description,
-        affectedEndpoints: f.affectedEndpoints ?? [],
-        ...(isSecret ? { secret: true as const } : {}),
-        ...(isIdentity ? { identity: true as const } : {}),
-        // Identity values stay visible (mental model: identity is for
-        // locally-triagable but personally-identifying data; `--redact-
-        // identity` swaps it for placeholders only at outbound time).
-        ...(!isSecret && set ? { value } : {}),
-        ...(placeholder ? { placeholder: true as const } : {}),
-      };
-      if (f.required) requiredOut.push(row);
-      else optionalOut.push(row);
-    }
-  }
-
-  const extraInEnv = Object.keys(envVars).filter(k => !declaredVars.has(k)).sort();
-  const blockedRequired = requiredOut.filter(r => !r.set).length;
-
-  const warnings: string[] = [];
-  if (!specExists) warnings.push(`spec.json not found at ${specAbsPath}`);
-  if (!manifest) warnings.push(`.api-fixtures.yaml missing — run \`zond refresh-api ${apiName}\``);
-
-  // ARV-237: warn when workspace .claude/skills/ copy drifts from the
-  // in-binary template (binary upgraded but `zond init` not re-run).
-  // `missing` is silent — user may have opted out via `--no-skills`.
-  try {
-    const wsRoot = findWorkspaceRoot().root;
-    const outdated = detectSkillDrift(wsRoot).filter(d => d.status === "outdated");
-    if (outdated.length > 0) {
-      warnings.push(
-        `workspace skills outdated (${outdated.map(d => d.name).join(", ")}) — run \`zond init\` to refresh .claude/skills/`,
-      );
-    }
-  } catch {
-    // not in a workspace — skip
-  }
-  const placeholderRows = [...requiredOut, ...optionalOut].filter(r => r.placeholder);
-  if (placeholderRows.length > 0) {
-    warnings.push(
-      `${placeholderRows.length} path fixture${placeholderRows.length === 1 ? "" : "s"} hold placeholder values (${placeholderRows.map(r => r.name).join(", ")}); positive/CRUD suites will hit fake ids — replace with real values in .env.yaml`,
-    );
-  }
-
-  // Endpoint counts from .api-catalog.yaml — read what `zond add api` already
-  // computed, so `--json` consumers (e.g. /zond-scan PF2 budget estimate)
-  // don't have to walk raw spec.json themselves (which would violate the
-  // "never read raw OpenAPI" iron rule in the zond skill).
-  let endpoints: DoctorReport["endpoints"] = null;
-  const catalogPath = join(baseDir, ".api-catalog.yaml");
-  if (existsSync(catalogPath)) {
-    const catalog = readYamlIfExists<{
-      endpointCount?: number;
-      endpoints?: Array<{ method?: string }>;
-    }>(catalogPath);
-    if (catalog) {
-      const list = Array.isArray(catalog.endpoints) ? catalog.endpoints : [];
-      const byMethod: Record<string, number> = {};
-      for (const ep of list) {
-        const m = (ep.method ?? "").toUpperCase();
-        if (!m) continue;
-        byMethod[m] = (byMethod[m] ?? 0) + 1;
-      }
-      endpoints = {
-        total: typeof catalog.endpointCount === "number" ? catalog.endpointCount : list.length,
-        by_method: byMethod,
-      };
-    }
-  }
-
-  const report: DoctorReport = {
-    api: apiName,
-    mode: "spec",
-    baseDir,
-    spec: {
-      path: specAbsPath ?? "",
-      exists: specExists,
-      sha: specSha,
-    },
-    endpoints,
-    fixtures: {
-      required: requiredOut,
-      optional: optionalOut,
-      extraInEnv,
-    },
-    staleArtifacts,
-    blockedRequired,
-    warnings,
-  };
-
-  // TASK-145: --missing-only filters out healthy rows so the report only
-  // contains things the user has to fix. Applies symmetrically to text and
-  // JSON so `--json | jq '.data.fixtures.required'` and the stdout view
-  // agree on what's "noise".
-  const presented = opts.missingOnly ? applyMissingOnly(report) : report;
-
-  // TASK-145: --query <dotpath> short-circuits the envelope and emits the
-  // resolved subtree as raw JSON, no `jq` required.
-  if (opts.query) {
-    const resolved = resolveDotPath(presented, opts.query);
-    if (resolved === undefined) {
-      const message = `--query path '${opts.query}' did not resolve in the doctor report (canonical paths: api, spec, endpoints, fixtures.required, fixtures.optional, fixtures.extraInEnv, staleArtifacts, warnings)`;
-      if (opts.json) printJson(jsonError("doctor", [message]));
-      else printError(message);
-      return 2;
-    }
-    process.stdout.write(JSON.stringify(resolved, null, 2) + "\n");
-    // ARV-274: --json (incl. --query) returns 0 on successful emit.
-    // Fixture/staleness state is *data*, not command failure — non-zero is
-    // reserved for command failure (missing api, parse error). Text mode
-    // still surfaces state via exit code so `if zond doctor; then ...`
-    // remains a useful gate.
-    if (opts.json) return 0;
-    if (blockedRequired > 0) return 1;
-    if (staleArtifacts.some(s => !s.fresh) || !specExists || !manifest) return 2;
-    return 0;
-  }
-
-  // ── Output ──
-  if (opts.json) {
-    printJson(jsonOk("doctor", presented));
-    return 0; // ARV-274: JSON envelope emit success → exit 0
-  }
-
-  printHuman(presented, envVars, { missingOnly: opts.missingOnly === true });
-
-  if (blockedRequired > 0) return 1;
-  if (staleArtifacts.some(s => !s.fresh) || !specExists || !manifest) return 2;
-  return 0;
-}
-
-/** TASK-145: produce a copy of the doctor report containing only items the
- *  user still has to address. Filters: required fixtures with `set: false`,
- *  artifacts where `fresh: false`, missing spec, missing manifest. Optional
- *  fixtures and `extraInEnv` are dropped wholesale — they're never "missing"
- *  by definition. `warnings` is kept intact. */
-function applyMissingOnly(r: DoctorReport): DoctorReport {
-  return {
-    ...r,
-    fixtures: {
-      required: r.fixtures.required.filter((f) => !f.set),
-      optional: [],
-      extraInEnv: [],
-    },
-    staleArtifacts: r.staleArtifacts.filter((s) => !s.fresh),
-  };
-}
-
-/** TASK-145: resolve a dot-path like `fixtures.required` against the report.
- *  Numeric segments index into arrays. Returns `undefined` when any segment
- *  is missing — the caller surfaces that as a CLI error. */
-function resolveDotPath(value: unknown, path: string): unknown {
-  const parts = path.split(".").filter((p) => p.length > 0);
-  let cur: unknown = value;
-  for (const p of parts) {
-    if (cur === null || cur === undefined) return undefined;
-    if (Array.isArray(cur)) {
-      const idx = Number.parseInt(p, 10);
-      if (Number.isNaN(idx)) return undefined;
-      cur = cur[idx];
-      continue;
-    }
-    if (typeof cur !== "object") return undefined;
-    cur = (cur as Record<string, unknown>)[p];
-  }
-  return cur;
-}
-
-function printHuman(
-  r: DoctorReport,
-  envVars: Record<string, string>,
-  opts: { missingOnly: boolean } = { missingOnly: false },
-): void {
-  const out = process.stdout;
-  out.write(`API: ${r.api}\n`);
-  out.write(`Workspace dir: ${r.baseDir}\n\n`);
-
-  // Spec snapshot
-  out.write(`Spec snapshot (${r.spec.path}):\n`);
-  if (!r.spec.exists) {
-    out.write(`  ✗ MISSING — run \`zond refresh-api ${r.api}\`\n\n`);
-  } else {
-    out.write(`  ✓ present, sha ${r.spec.sha?.slice(0, 12) ?? "?"}…\n\n`);
-  }
-
-  // Artifacts
-  if (opts.missingOnly && r.staleArtifacts.length === 0) {
-    // nothing to report — skip the section
-  } else {
-  out.write(`Artifact freshness:\n`);
-  for (const s of r.staleArtifacts) {
-    if (!s.actual) {
-      out.write(`  ✗ ${s.file}: missing\n`);
-    } else if (s.fresh) {
-      out.write(`  ✓ ${s.file}: fresh\n`);
-    } else {
-      out.write(`  ⚠ ${s.file}: STALE (artifact specHash ${s.actual.slice(0, 12)}… ≠ spec.json ${s.expected?.slice(0, 12)}…)\n`);
-    }
-  }
-  out.write("\n");
-  }
-
-  // Required fixtures
-  if (opts.missingOnly && r.fixtures.required.length === 0) {
-    // skip — nothing missing
-  } else {
-  out.write(`Required fixtures (${r.fixtures.required.length}):\n`);
-  if (r.fixtures.required.length === 0) {
-    out.write(`  (none)\n`);
-  } else {
-    for (const f of r.fixtures.required) {
-      const icon = !f.set ? "✗" : f.placeholder ? "⚠" : "✓";
-      // TASK-172 (m-10): secrets show metadata only (set + length); identity
-      // is visible because the user owns those values; plain env shows raw.
-      const value = !f.set
-        ? "UNSET"
-        : f.secret
-          ? `set (${f.length} chars, secret)`
-          : f.identity
-            ? `${envVars[f.name]} (identity)`
-            : f.placeholder
-              ? `${envVars[f.name]} (placeholder — fill with a real id)`
-              : envVars[f.name];
-      const detail = f.set ? "" : ` (${f.affectedEndpoints.length === 1 && f.affectedEndpoints[0] === "*" ? "all endpoints" : `blocks ${f.affectedEndpoints.length} endpoint${f.affectedEndpoints.length === 1 ? "" : "s"}`})`;
-      out.write(`  ${icon} ${f.name.padEnd(20)} ${String(value).padEnd(40)} [${f.source}]${detail}\n`);
-    }
-  }
-  out.write("\n");
-  }
-
-  // Optional fixtures (suppressed entirely under --missing-only — they are
-  // by definition never "missing" in the actionable sense).
-  if (!opts.missingOnly) {
-  out.write(`Optional fixtures (${r.fixtures.optional.length}):\n`);
-  if (r.fixtures.optional.length === 0) {
-    out.write(`  (none)\n`);
-  } else {
-    for (const f of r.fixtures.optional) {
-      const icon = f.set ? "✓" : "⚠";
-      out.write(`  ${icon} ${f.name.padEnd(20)} ${(f.set ? "set" : "unset").padEnd(40)} [${f.source}]\n`);
-    }
-  }
-  out.write("\n");
-  }
-
-  if (!opts.missingOnly && r.fixtures.extraInEnv.length > 0) {
-    out.write(`Other variables in .env.yaml (not in manifest, informational):\n`);
-    for (const k of r.fixtures.extraInEnv) out.write(`  • ${k}\n`);
-    out.write("\n");
-  }
-
-  // Suggested next
-  if (opts.missingOnly && r.blockedRequired === 0 && r.staleArtifacts.length === 0) {
-    out.write(`No missing items. Workspace is ready.\n`);
-  } else if (r.blockedRequired > 0) {
-    // ARV-16: align with `zond coverage`, which points users at the same
-    // remedy. `prepare-fixtures` auto-seeds from list endpoints; manual edit
-    // is the fallback for fields prepare-fixtures can't infer.
-    out.write(`Next: run \`zond prepare-fixtures --api ${r.api}\` to auto-seed from list endpoints, or edit ${r.baseDir}/.env.yaml and fill the ${r.blockedRequired} required value${r.blockedRequired === 1 ? "" : "s"} manually. Then re-run \`zond doctor --api ${r.api}\`.\n`);
-  } else if (r.staleArtifacts.some(s => !s.fresh)) {
-    out.write(`Next: artifacts are out of sync — run \`zond refresh-api ${r.api}\`.\n`);
-  } else {
-    out.write(`All checks passed. Workspace is ready.\n`);
-  }
-
-  for (const w of r.warnings) out.write(`Warning: ${w}\n`);
-}
-
-function printRunOnlyHuman(r: DoctorRunOnlyReport): void {
-  const out = process.stdout;
-  out.write(`API: ${r.api}\n`);
-  out.write(`Mode: run-only (no OpenAPI spec)\n`);
-  out.write(`Workspace dir: ${r.baseDir}\n\n`);
-  const keys = Object.keys(r.envVars);
-  out.write(`Environment variables (${keys.length}):\n`);
-  if (keys.length === 0) {
-    out.write(`  (none) — write \`base_url: ...\` into ${r.baseDir}/.env.yaml\n`);
-  } else {
-    for (const k of keys) {
-      const v = isLikelySecret(k) ? maskSecret(r.envVars[k]!) : r.envVars[k];
-      out.write(`  • ${k.padEnd(20)} ${v}\n`);
-    }
-  }
-  out.write(`\n${r.recommendation}\n`);
-}
-
-import type { Command } from "commander";
-import { globalJson as globalJsonResolver } from "../resolve.ts";
-
-export function registerDoctor(program: Command): void {
-  program
-    .command("doctor")
-    .description("Diagnose registered API: fixture gaps in .env.yaml + artifact freshness vs spec.json")
-    .addHelpText(
-      "after",
-      [
-        "",
-        "JSON shape (canonical, TASK-145):",
-        "  --json envelope is { ok, command, data, warnings, errors }. The",
-        "  doctor payload sits under .data:",
-        "    .data.api                       string",
-        "    .data.spec.{path,exists,sha}    OpenAPI snapshot",
-        "    .data.fixtures.required[]       FixtureMetaRow — each has .set",
-        "    .data.fixtures.optional[]       same shape",
-        "    .data.fixtures.extraInEnv[]     keys present in .env.yaml only",
-        "    .data.staleArtifacts[]          { file, expected, actual, fresh }",
-        "    .data.blockedRequired           number of unset required fixtures",
-        "    .data.warnings[]                advisory strings",
-        "",
-        "Tips:",
-        "  --missing-only             hide healthy rows (text + json)",
-        "  --query fixtures.required  emit one subtree as raw JSON, no jq",
-      ].join("\n"),
-    )
-    .option("--api <name>", "API collection name (defaults to the only registered one)")
-    .option("--db <path>", "Path to SQLite database file")
-    .option("--missing-only", "Show only missing/stale items (hide rows that are already healthy). Applies to both text and --json output.")
-    .option("--query <dotpath>", "Resolve a dot-path inside the doctor report and emit just that subtree as JSON (e.g. fixtures.required, staleArtifacts, spec.sha).")
-    .action(async (opts, cmd: Command) => {
-      // ARV-96: resolve --api via the shared chain (local opt > ancestor opt
-      // > ZOND_API_GLOBAL > ZOND_API > .zond/current-api). Without this,
-      // `zond --api X doctor` and `zond doctor --api X` on a multi-API
-      // workspace both fell through to the "Multiple APIs registered" branch
-      // because the global --api option (program.ts) absorbs the flag and
-      // leaves opts.api undefined for the subcommand.
-      const resolvedApi = getApi(cmd, opts);
-      process.exitCode = await doctorCommand({
-        api: resolvedApi,
-        dbPath: typeof opts.db === "string" ? opts.db : undefined,
-        json: globalJsonResolver(cmd),
-        missingOnly: opts.missingOnly === true,
-        query: typeof opts.query === "string" ? opts.query : undefined,
-      });
-    });
-}