@kirrosh/zond 0.26.0 → 0.27.0

package/src/cli/commands/ci-init.ts

@@ -1,223 +0,0 @@
-import { resolve, dirname } from "path";
-import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { printSuccess, printError } from "../output.ts";
-import { jsonOk, printJson } from "../json-envelope.ts";
-
-export interface CiInitOptions {
-  platform?: "github" | "gitlab";
-  force: boolean;
-  dir?: string;
-  json?: boolean;
-}
-
-const GH_ACTIONS_TEMPLATE = `name: API Tests
-on:
-  push:
-    branches: [main]
-  pull_request:
-  schedule:
-    - cron: "0 */6 * * *"
-  workflow_dispatch:
-  repository_dispatch:
-    types: [api-updated]
-
-permissions:
-  contents: read
-  checks: write
-  pull-requests: write
-  # ARV-5: required for github/codeql-action/upload-sarif to surface
-  # zond-checks findings in the Code Scanning tab.
-  security-events: write
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Install zond
-        run: curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
-
-      - name: Check coverage
-        run: zond coverage --api myapi --fail-on-coverage 60
-        # Fails if coverage drops below 60% — adjust threshold as needed
-
-      - name: Run smoke tests (read-only, safe for production)
-        run: |
-          mkdir -p test-results
-          # --exclude-tag needs-id skips positive smoke that needs real IDs from .env.yaml
-          zond run apis/ --tag smoke --exclude-tag needs-id --safe --report junit --no-db > test-results/smoke.xml
-          # Use --env-var "API_KEY=\${{ secrets.API_KEY }}" to inject secrets without writing to disk
-        continue-on-error: true
-
-      - name: Run CRUD tests (staging only — ephemeral suites only)
-        run: |
-          # --exclude-tag persistent-write keeps only ephemeral CRUD (suites that DELETE what they create).
-          # Drop --exclude-tag persistent-write to opt into write suites that leave residual data.
-          zond run apis/ --tag crud --exclude-tag persistent-write --env staging --report junit --no-db > test-results/crud.xml
-          # Add --env-var "BASE_URL=\${{ secrets.STAGING_URL }}" for staging URL
-        continue-on-error: true
-
-      - name: Run depth checks (SARIF for Code Scanning)
-        run: |
-          zond checks run --api myapi --report sarif --output test-results/zond-checks.sarif || true
-          # ARV-5: \`|| true\` keeps the workflow green even when HIGH/CRITICAL
-          # findings would otherwise exit 1 — Code Scanning will still get the
-          # SARIF and gate on the alerts via branch protection if desired.
-        continue-on-error: true
-
-      - name: Upload SARIF to GitHub Code Scanning
-        if: always()
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: test-results/zond-checks.sarif
-          category: zond-checks
-
-      - name: Publish test results
-        uses: EnricoMi/publish-unit-test-result-action@v2
-        if: always()
-        with:
-          files: test-results/*.xml
-
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: test-results
-          path: test-results/
-`;
-
-const GITLAB_CI_TEMPLATE = `# Trigger via API: curl -X POST --form ref=main --form token=TRIGGER_TOKEN $CI_API_V4_URL/projects/$CI_PROJECT_ID/trigger/pipeline
-
-variables:
-  # Set API_KEY in GitLab CI/CD → Settings → Variables
-  API_KEY: ""
-
-api-coverage:
-  image: ubuntu:latest
-  before_script:
-    - apt-get update -qq && apt-get install -y -qq curl
-    - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
-  script:
-    - zond coverage --api myapi --fail-on-coverage 60
-
-api-smoke:
-  image: ubuntu:latest
-  before_script:
-    - apt-get update -qq && apt-get install -y -qq curl
-    - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
-  script:
-    - mkdir -p test-results
-    # Use --env-var to inject secrets without writing to disk.
-    # --exclude-tag needs-id skips positive smoke that needs real IDs from .env.yaml.
-    - zond run apis/ --tag smoke --exclude-tag needs-id --safe --report junit --no-db --env-var "API_KEY=$API_KEY" > test-results/smoke.xml
-  allow_failure:
-    exit_codes: 1
-  artifacts:
-    when: always
-    reports:
-      junit: test-results/smoke.xml
-
-api-crud:
-  image: ubuntu:latest
-  before_script:
-    - apt-get update -qq && apt-get install -y -qq curl
-    - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
-  script:
-    - mkdir -p test-results
-    # --exclude-tag persistent-write keeps only ephemeral CRUD (suites that DELETE what they create).
-    # Drop --exclude-tag persistent-write to opt into write suites that leave residual data.
-    - zond run apis/ --tag crud --exclude-tag persistent-write --env staging --report junit --no-db > test-results/crud.xml
-  allow_failure:
-    exit_codes: 1
-  artifacts:
-    when: always
-    reports:
-      junit: test-results/crud.xml
-`;
-
-function writeIfMissing(filePath: string, content: string, force: boolean): boolean {
-  if (!force && existsSync(filePath)) {
-    console.log(`  Skipped ${filePath} (already exists, use --force to overwrite)`);
-    return false;
-  }
-  const dir = dirname(filePath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  writeFileSync(filePath, content, "utf-8");
-  console.log(`  Created ${filePath}`);
-  return true;
-}
-
-function detectPlatform(cwd: string): "github" | "gitlab" | undefined {
-  if (existsSync(resolve(cwd, ".github"))) return "github";
-  if (existsSync(resolve(cwd, ".gitlab-ci.yml"))) return "gitlab";
-  return undefined;
-}
-
-export async function ciInitCommand(options: CiInitOptions): Promise<number> {
-  const cwd = options.dir ? resolve(options.dir) : process.cwd();
-  let platform = options.platform;
-
-  if (!platform) {
-    platform = detectPlatform(cwd);
-    if (!platform) {
-      platform = "github";
-      console.log("No CI platform detected, defaulting to GitHub Actions.\n");
-    } else {
-      console.log(`Detected ${platform === "github" ? "GitHub Actions" : "GitLab CI"}.\n`);
-    }
-  }
-
-  console.log(`Generating ${platform === "github" ? "GitHub Actions" : "GitLab CI"} workflow...\n`);
-
-  let created = false;
-
-  if (platform === "github") {
-    const targetPath = resolve(cwd, ".github/workflows/api-tests.yml");
-    created = writeIfMissing(targetPath, GH_ACTIONS_TEMPLATE, options.force);
-  } else {
-    const targetPath = resolve(cwd, ".gitlab-ci.yml");
-    created = writeIfMissing(targetPath, GITLAB_CI_TEMPLATE, options.force);
-  }
-
-  if (options.json) {
-    const targetPath = platform === "github"
-      ? resolve(cwd, ".github/workflows/api-tests.yml")
-      : resolve(cwd, ".gitlab-ci.yml");
-    printJson(jsonOk("ci init", {
-      platform,
-      filePath: targetPath,
-      created,
-    }));
-  } else if (created) {
-    printSuccess("CI workflow created. Commit and push to activate.");
-  }
-
-  return 0;
-}
-
-import type { Command } from "commander";
-import { globalJson } from "../resolve.ts";
-
-export function registerCi(program: Command): void {
-  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),
-      });
-    });
-}

package/src/cli/commands/clean.ts

@@ -1,212 +0,0 @@
-/**
- * `zond clean` — remove auto-generated files tracked in `.zond/manifest.json`.
- *
- * Default mode is dry-run; `--force` is required to actually delete. Files
- * whose sha256 no longer matches the manifest entry are treated as
- * manually-edited and skipped (TASK-156, m-9).
- */
-
-import { rmSync, rmdirSync, readdirSync, existsSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { findWorkspaceRoot } from "../../core/workspace/root.ts";
-import {
-  hasManifest,
-  inspectEntries,
-  loadManifest,
-  removeManifestEntries,
-  selectEntriesEx,
-  type CleanItem,
-  type ManifestCategory,
-} from "../../core/workspace/manifest.ts";
-import type { Command } from "commander";
-import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
-import { printError, printSuccess } from "../output.ts";
-import { globalJson } from "../resolve.ts";
-import { getApi } from "../util/api-context.ts";
-
-export interface CleanOptions {
-  api?: string;
-  probes?: boolean;
-  all?: boolean;
-  force?: boolean;
-  json?: boolean;
-}
-
-export async function cleanCommand(opts: CleanOptions): Promise<number> {
-  const ws = findWorkspaceRoot();
-  if (ws.fromFallback) {
-    const m = "No workspace detected. Run `zond init` first.";
-    if (opts.json) printJson(jsonError("clean", [m])); else printError(m);
-    return 2;
-  }
-
-  if (!hasManifest(ws.root)) {
-    const msg = `No .zond/manifest.json — nothing tracked yet. Run \`zond add api\`, \`zond generate\`, or a probe-* --emit first.`;
-    if (opts.json) {
-      printJson(jsonOk("clean", { dryRun: true, deleted: [], modified: [], missing: [], message: msg }));
-    } else {
-      console.log(msg);
-    }
-    return 0;
-  }
-
-  if (!opts.api && !opts.probes && !opts.all) {
-    const m = "Specify a scope: --api <name>, --probes, or --all.";
-    if (opts.json) printJson(jsonError("clean", [m])); else printError(m);
-    return 2;
-  }
-
-  const manifest = loadManifest(ws.root);
-  const category: ManifestCategory | undefined = opts.probes ? "probes" : undefined;
-  const { selected: entries, probesPreserved } = selectEntriesEx(manifest, {
-    api: opts.api,
-    category,
-    all: opts.all && !opts.api && !opts.probes,
-  });
-
-  if (entries.length === 0 && probesPreserved.length === 0) {
-    const m = "No matching auto-generated files in manifest.";
-    if (opts.json) {
-      printJson(jsonOk("clean", { dryRun: true, deleted: [], modified: [], missing: [], message: m }));
-    } else {
-      console.log(m);
-    }
-    return 0;
-  }
-
-  const items = inspectEntries(ws.root, entries);
-  const toDelete = items.filter((i) => i.verdict === "delete");
-  const modified = items.filter((i) => i.verdict === "modified");
-  const missing = items.filter((i) => i.verdict === "missing");
-
-  const dryRun = !opts.force;
-
-  if (!dryRun) {
-    for (const item of toDelete) {
-      try {
-        rmSync(item.absPath, { force: true });
-      } catch {
-        // best-effort
-      }
-    }
-    pruneEmptyDirs(ws.root, toDelete);
-    const removedPaths = [...toDelete, ...missing].map((i) => i.entry.path);
-    removeManifestEntries(ws.root, removedPaths);
-  }
-
-  if (opts.json) {
-    printJson(jsonOk("clean", {
-      dryRun,
-      scope: { api: opts.api, probes: !!opts.probes, all: !!opts.all },
-      deleted: toDelete.map(itemSummary),
-      modified: modified.map(itemSummary),
-      missing: missing.map(itemSummary),
-      probesPreserved: probesPreserved.map((e) => ({ path: e.path, api: e.api })),
-    }));
-    return 0;
-  }
-
-  const verb = dryRun ? "Would delete" : "Deleted";
-  printSuccess(`${verb} ${toDelete.length} file(s); ${modified.length} skipped (manually edited); ${missing.length} already missing.`);
-  if (toDelete.length > 0) {
-    console.log("");
-    console.log(`${verb}:`);
-    for (const i of toDelete) console.log(`  - ${i.entry.path}`);
-  }
-  if (modified.length > 0) {
-    console.log("");
-    console.log("Skipped (manually edited, sha256 mismatch):");
-    for (const i of modified) console.log(`  ! ${i.entry.path}`);
-  }
-  // TASK-258: probes belong to a separate pipeline. Scoping by --api alone
-  // preserves them and surfaces the regen command so users don't lose
-  // 30s+ of probe-validation/-methods work to a typo.
-  if (probesPreserved.length > 0) {
-    console.log("");
-    console.log(`Preserved ${probesPreserved.length} probe-suite file(s) under apis/${opts.api ?? "<api>"}/probes/.`);
-    console.log("Pass --probes to also remove them, or regenerate via:");
-    console.log(`  zond probe-validation --api ${opts.api} --output apis/${opts.api}/probes`);
-    console.log(`  zond probe-methods    --api ${opts.api} --output apis/${opts.api}/probes`);
-  }
-  if (dryRun) {
-    console.log("");
-    console.log("Re-run with --force to actually delete.");
-  }
-  return 0;
-}
-
-function itemSummary(i: CleanItem) {
-  return {
-    path: i.entry.path,
-    by: i.entry.by,
-    ts: i.entry.ts,
-    api: i.entry.api,
-    category: i.entry.category,
-    verdict: i.verdict,
-  };
-}
-
-/**
- * After deleting tracked files, remove any directories that are now empty
- * and live inside the workspace. Best-effort: stops at first non-empty dir.
- */
-function pruneEmptyDirs(workspaceRoot: string, items: CleanItem[]): void {
-  const dirs = new Set<string>();
-  for (const i of items) dirs.add(dirname(i.absPath));
-  // Process deepest first.
-  const sorted = [...dirs].sort((a, b) => b.length - a.length);
-  for (const d of sorted) {
-    let cur = d;
-    while (cur.startsWith(workspaceRoot) && cur !== workspaceRoot) {
-      if (!existsSync(cur)) {
-        cur = dirname(cur);
-        continue;
-      }
-      let entries: string[] = [];
-      try {
-        entries = readdirSync(cur);
-      } catch {
-        break;
-      }
-      if (entries.length > 0) break;
-      try {
-        rmdirSync(cur);
-      } catch {
-        break;
-      }
-      cur = dirname(cur);
-    }
-  }
-  // Keep `resolve` reachable for type-only imports.
-  void resolve;
-}
-
-export function registerClean(program: Command): void {
-  program
-    .command("clean")
-    .description("Remove auto-generated files tracked in .zond/manifest.json (TASK-156, m-9)")
-    .option("--api <name>", "Limit to a single API (apis/<name>/). Preserves probes/ unless --probes is also passed (TASK-258)")
-    .option(
-      "--probes",
-      "Scope deletion to probe-suite files only (apis/<api>/probes/). " +
-      "TASK-265: this is effectively `--probes-only` — `tests/`, `spec.json`, " +
-      "and `.api-catalog.yaml` are NEVER touched in this mode. Combine with " +
-      "--api <name> to limit to one API; alone, removes probes for every API.",
-    )
-    .option("--all", "Remove every tracked auto-generated file in the workspace (includes probes/)")
-    .option("--force", "Actually delete files (default is dry-run)")
-    .action(async (opts, cmd: Command) => {
-      // ARV-238 (R-03/F11/SD9): `--api` exists both at program level (TASK-290)
-      // and on this subcommand; commander absorbs the value into the program
-      // option, leaving `opts.api` undefined. Fall back via `getApi` so users
-      // who follow `zond clean --api <name>` (per skill / --help) actually
-      // scope the run instead of hitting "Specify a scope".
-      process.exitCode = await cleanCommand({
-        api: getApi(cmd, opts),
-        probes: opts.probes === true,
-        all: opts.all === true,
-        force: opts.force === true,
-        json: globalJson(cmd),
-      });
-    });
-}

package/src/cli/commands/cleanup.ts

@@ -1,236 +0,0 @@
-/**
- * `zond cleanup` — retry housekeeping that probes couldn't finish.
- *
- * v1 ships only `--orphans`: read every record from
- * `~/.zond/orphans/<api>/<run-id>.jsonl` and re-issue the DELETE for any
- * resource that survived the probe's own cleanup attempts. 404 is treated
- * as success — the goal is "resource is gone", and the API getting there
- * before us is fine. (TASK-278.)
- */
-import { loadOrphans, markRemoved } from "../../core/probe/orphan-tracker.ts";
-import type { OrphanRecord } from "../../core/probe/orphan-tracker.ts";
-import { encodePathForRepro } from "../../core/probe/shared.ts";
-import { executeRequest } from "../../core/runner/http-client.ts";
-import { loadEnvironment, loadEnvMeta } from "../../core/parser/variables.ts";
-import { resolveTimeoutMs } from "../../core/workspace/config.ts";
-import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
-import { printError, printWarning, printSuccess } from "../output.ts";
-import { readCurrentApi } from "../../core/context/current.ts";
-import type { Command } from "commander";
-import { globalJson } from "../resolve.ts";
-
-export interface CleanupOptions {
-  orphans: boolean;
-  api?: string;
-  /** ARV-139: pass true to disable the default current-api scoping and look
-   *  at orphans across every API in the tracker. */
-  allApis?: boolean;
-  runId?: string;
-  dryRun?: boolean;
-  json?: boolean;
-  /** Override base_url resolution. By default the env from cwd .env.yaml or
-   *  apis/<api>/.env.yaml is used. Tests inject a known URL via this. */
-  baseUrl?: string;
-  /** Per-request timeout, ms. */
-  timeoutMs?: number;
-}
-
-/**
- * ARV-244 (R-04/F15): orphan records store `deletePath` as it was used at
- * probe time — typically built by concatenating literal id segments captured
- * from the response. CRLF / open-redirect probes can poison those ids with
- * raw `\r`, `\n`, spaces, etc. (e.g. label name `zond-safe\rX-Zond: yes`),
- * which makes the DELETE URL malformed: the API gets a request line with an
- * embedded CR and silently splits or routes elsewhere → 404 → record stays
- * in the queue and the resource leaks. Encoding is shared with the
- * security-probe digest via `core/probe/shared.ts#encodePathForRepro`.
- */
-export const encodeOrphanPath = encodePathForRepro;
-
-export async function cleanupCommand(opts: CleanupOptions): Promise<number> {
-  if (!opts.orphans) {
-    const m = "Nothing to do — pass --orphans to retry leaked probe resources.";
-    if (opts.json) printJson(jsonError("cleanup", [m]));
-    else printError(m);
-    return 2;
-  }
-
-  // ARV-139: scope the orphan queue to the active API by default. The on-disk
-  // tracker at ~/.zond/orphans/<api>/... is shared across the workspace, so
-  // switching APIs (e.g. apis/resend → apis/sentry) would otherwise surface
-  // orphans from previous work on unrelated APIs — including DELETE attempts
-  // against endpoints that aren't even part of the active spec. Explicit
-  // `--api <name>` wins; `--all-apis` opts back into the pre-ARV-139 behaviour.
-  let scopedApi = opts.api;
-  if (!scopedApi && !opts.allApis) {
-    scopedApi = readCurrentApi() ?? undefined;
-  }
-
-  let records: OrphanRecord[];
-  try {
-    const filter: { api?: string; runId?: string } = {};
-    if (scopedApi) filter.api = scopedApi;
-    if (opts.runId) filter.runId = opts.runId;
-    records = await loadOrphans(filter);
-  } catch (err) {
-    const m = `Failed to load orphan tracker: ${(err as Error).message}`;
-    if (opts.json) printJson(jsonError("cleanup", [m]));
-    else printError(m);
-    return 2;
-  }
-
-  // ARV-102 (F7): split orphans into retriable (have a DELETE plan) and
-  // manual-only (probe knew the resource was created but couldn't derive
-  // a deletePath / id). Manual-only entries are surfaced separately —
-  // we can't auto-DELETE them, but the operator must know they exist.
-  const manualOnly = records.filter(r => r.requires_manual_cleanup === true || r.deletePath === "");
-  const retriable = records.filter(r => !(r.requires_manual_cleanup === true || r.deletePath === ""));
-
-  if (records.length === 0) {
-    if (opts.json) printJson(jsonOk("cleanup", { retried: 0, removed: 0, failed: 0, items: [], manual_cleanup_required: [] }));
-    else console.log("No orphan resources to retry.");
-    return 0;
-  }
-
-  // Group by api so we resolve env once per API instead of per record.
-  const baseUrlByApi = new Map<string, string>();
-  if (opts.baseUrl) {
-    for (const r of retriable) baseUrlByApi.set(r.api, opts.baseUrl);
-  }
-
-  if (opts.dryRun) {
-    if (opts.json) printJson(jsonOk("cleanup", { dryRun: true, items: retriable, manual_cleanup_required: manualOnly }));
-    else {
-      console.log(`Dry-run: ${retriable.length} orphan(s) would be retried:`);
-      for (const r of retriable) {
-        console.log(`  ${r.method} ${r.path} (id=${r.id}); DELETE ${r.deletePath} — last status: ${r.lastCleanupStatus ?? "n/a"}`);
-      }
-      if (manualOnly.length > 0) {
-        console.log(`\nManual cleanup required: ${manualOnly.length} resource(s) (no DELETE plan):`);
-        for (const r of manualOnly) {
-          console.log(`  ${r.method} ${r.path}${r.id ? ` (id=${r.id})` : ""} — ${r.lastCleanupError ?? "no DELETE counterpart"}`);
-        }
-      }
-    }
-    return 0;
-  }
-
-  // Per-API timeout: CLI flag → apis/<api>/.env.yaml `timeoutMs:` → workspace
-  // `defaults.timeout_ms` → 30000.
-  const timeoutByApi = new Map<string, number>();
-  async function timeoutFor(api: string): Promise<number> {
-    let t = timeoutByApi.get(api);
-    if (t !== undefined) return t;
-    let envTimeout: number | undefined;
-    try {
-      const meta = await loadEnvMeta(undefined, `apis/${api}`);
-      envTimeout = meta.timeoutMs;
-    } catch { /* meta is best-effort */ }
-    t = resolveTimeoutMs(opts.timeoutMs, envTimeout);
-    timeoutByApi.set(api, t);
-    return t;
-  }
-
-  const results: Array<{ record: OrphanRecord; status: number | null; ok: boolean; error?: string }> = [];
-  for (const r of retriable) {
-    let baseUrl = baseUrlByApi.get(r.api);
-    if (!baseUrl) {
-      try {
-        const env = await loadEnvironment(undefined, `apis/${r.api}`);
-        baseUrl = env["base_url"];
-      } catch { /* fall through */ }
-    }
-    if (!baseUrl) {
-      results.push({ record: r, status: null, ok: false, error: `base_url missing — set ZOND_BASE_URL or apis/${r.api}/.env.yaml` });
-      continue;
-    }
-    baseUrlByApi.set(r.api, baseUrl);
-
-    const url = `${baseUrl.replace(/\/+$/, "")}${encodeOrphanPath(r.deletePath)}`;
-    try {
-      const resp = await executeRequest(
-        { method: "DELETE", url, headers: {} },
-        { timeout: await timeoutFor(r.api), retries: 0 },
-      );
-      // 404 = already gone → success. 2xx = just deleted → success.
-      const ok = resp.status === 404 || (resp.status >= 200 && resp.status < 300);
-      results.push({ record: r, status: resp.status, ok });
-      if (ok) await markRemoved(r);
-    } catch (err) {
-      results.push({ record: r, status: null, ok: false, error: (err as Error).message });
-    }
-  }
-
-  const removed = results.filter(r => r.ok).length;
-  const failed = results.length - removed;
-
-  if (opts.json) {
-    printJson(jsonOk("cleanup", {
-      retried: results.length,
-      removed,
-      failed,
-      items: results.map(r => ({
-        api: r.record.api,
-        runId: r.record.runId,
-        method: r.record.method,
-        path: r.record.path,
-        id: r.record.id,
-        deletePath: r.record.deletePath,
-        status: r.status,
-        ok: r.ok,
-        error: r.error ?? null,
-      })),
-      manual_cleanup_required: manualOnly.map(r => ({
-        api: r.api,
-        runId: r.runId,
-        method: r.method,
-        path: r.path,
-        id: r.id,
-        reason: r.lastCleanupError ?? "no DELETE counterpart",
-      })),
-    }));
-  } else {
-    if (removed > 0) printSuccess(`${removed} orphan(s) cleaned up.`);
-    if (failed > 0) {
-      printWarning(`${failed} orphan(s) still alive:`);
-      for (const r of results) {
-        if (r.ok) continue;
-        const tail = r.status != null ? `→ ${r.status}` : (r.error ? `→ err: ${r.error}` : "");
-        process.stderr.write(`  ${r.record.method} ${r.record.path} (id=${r.record.id}); DELETE ${r.record.deletePath} ${tail}\n`);
-      }
-    }
-    if (manualOnly.length > 0) {
-      printWarning(`${manualOnly.length} resource(s) need manual cleanup (no DELETE plan):`);
-      for (const r of manualOnly) {
-        process.stderr.write(`  ${r.method} ${r.path}${r.id ? ` (id=${r.id})` : ""} — ${r.lastCleanupError ?? "no DELETE counterpart"}\n`);
-      }
-    }
-  }
-
-  // Manual-only orphans count as "still alive" for exit-code purposes —
-  // CI must fail loudly when probes leave un-deletable state behind.
-  return failed > 0 || manualOnly.length > 0 ? 1 : 0;
-}
-
-export function registerCleanup(program: Command): void {
-  program
-    .command("cleanup")
-    .description("Retry probe-leftover work. Currently only --orphans (TASK-278) — re-issues DELETE for resources captured in ~/.zond/orphans/.")
-    .option("--orphans", "Retry DELETE for resources in the orphan tracker")
-    .option("--api <name>", "Limit to a single API (matches the orphan-tracker subdirectory; defaults to the current API)")
-    .option("--all-apis", "Include orphans from every API in the tracker (disables the default current-api scoping)")
-    .option("--run <id>", "Limit to a single probe run id")
-    .option("--dry-run", "Print the plan without sending DELETEs")
-    .option("--timeout <ms>", "Per-request timeout in ms (overrides .env.yaml `timeoutMs` and zond.config.yml `defaults.timeout_ms`; default 30000)")
-    .action(async (opts, cmd: Command) => {
-      process.exitCode = await cleanupCommand({
-        orphans: opts.orphans === true,
-        api: typeof opts.api === "string" ? opts.api : undefined,
-        allApis: opts.allApis === true,
-        runId: typeof opts.run === "string" ? opts.run : undefined,
-        dryRun: opts.dryRun === true,
-        timeoutMs: typeof opts.timeout === "string" ? Number(opts.timeout) : undefined,
-        json: globalJson(cmd),
-      });
-    });
-}