@kirrosh/zond 0.22.0 → 0.23.0

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

@@ -25,6 +25,9 @@ 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:
@@ -55,6 +58,21 @@ jobs:
           # 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()
@@ -178,3 +196,28 @@ export async function ciInitCommand(options: CiInitOptions): Promise<number> {
 
   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

@@ -0,0 +1,212 @@
+/**
+ * `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

@@ -0,0 +1,262 @@
+/**
+ * `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 { 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.
+ *
+ * Encode unsafe characters per path-segment while preserving anything that
+ * is already percent-encoded. Slashes (segment separators), the unreserved
+ * set, and a conservative slice of sub-delims are kept verbatim.
+ */
+export function encodeOrphanPath(deletePath: string): string {
+  const SAFE = /[A-Za-z0-9._~!$&'()*+,;=:@-]/;
+  return deletePath
+    .split("/")
+    .map((segment) => {
+      if (segment.length === 0) return segment;
+      let out = "";
+      for (let i = 0; i < segment.length; i++) {
+        const ch = segment.charAt(i);
+        // Preserve existing percent escapes (`%XX`) — probe pre-encoded.
+        if (ch === "%" && /^[0-9A-Fa-f]{2}$/.test(segment.slice(i + 1, i + 3))) {
+          out += segment.slice(i, i + 3);
+          i += 2;
+          continue;
+        }
+        if (SAFE.test(ch)) {
+          out += ch;
+        } else {
+          out += encodeURIComponent(ch);
+        }
+      }
+      return out;
+    })
+    .join("/");
+}
+
+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),
+      });
+    });
+}

package/src/cli/commands/completions.ts

@@ -174,3 +174,19 @@ export function completionsCommand(options: CompletionsOptions): number {
   process.stdout.write(script);
   return 0;
 }
+
+import { printError } from "../output.ts";
+
+export function registerCompletions(program: Command): void {
+  program
+    .command("completions <shell>")
+    .description(`Generate shell completion script (${COMPLETION_SHELLS.join(", ")})`)
+    .action((shell: string) => {
+      if (!(COMPLETION_SHELLS as readonly string[]).includes(shell)) {
+        printError(`Unsupported shell: ${shell}. Supported: ${COMPLETION_SHELLS.join(", ")}`);
+        process.exitCode = 2;
+        return;
+      }
+      process.exitCode = completionsCommand({ shell: shell as CompletionShell, program });
+    });
+}