@kirrosh/zond 0.22.0 → 0.26.0

package/src/cli/resolve.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared helpers for command-action callbacks: resolving the active API
+ * collection, the spec argument that spec-consuming commands accept, and
+ * tiny utilities (`globalJson`, deprecation warning). Extracted from
+ * program.ts (TASK-190 round 2a) so per-command modules can register
+ * themselves without re-importing program.ts.
+ */
+
+import type { Command } from "commander";
+import { getDb } from "../db/schema.ts";
+import { findCollectionByNameOrId } from "../db/queries.ts";
+import { resolveCollectionSpec } from "../core/setup-api.ts";
+import { readCurrentApi } from "../core/context/current.ts";
+
+/**
+ * TASK-73: `--json` is a per-command option (not a top-level global) so
+ * that `run --json` does not collide with `run --report json`.
+ * Subcommands that support an envelope output add `.option("--json", ...)`
+ * themselves and we read it from local opts.
+ */
+export function globalJson(cmd: Command): boolean {
+  return cmd.opts().json === true;
+}
+
+/** Resolve API collection → returns { spec?, testPath?, baseDir? } or { error } when not found. */
+export function resolveApiCollection(apiName: string, dbPath: string | undefined):
+  | { spec: string | null; testPath: string | null; baseDir: string | null }
+  | { error: string } {
+  if (typeof apiName !== "string" || apiName.length === 0) {
+    return { error: "Internal: --api received non-string value" };
+  }
+  try {
+    getDb(dbPath);
+    const col = findCollectionByNameOrId(apiName);
+    if (!col) return { error: `API '${apiName}' not found` };
+    const spec = col.openapi_spec ? resolveCollectionSpec(col.openapi_spec) : null;
+    return { spec, testPath: col.test_path ?? null, baseDir: col.base_dir ?? null };
+  } catch (err) {
+    return { error: `Failed to resolve --api: ${(err as Error).message}` };
+  }
+}
+
+/**
+ * Resolve `apis/<name>/.env.yaml` for a registered API. TASK-233: probe
+ * subcommands required `--env <file>` even when `--api <name>` was given,
+ * forcing users to repeat the path. When --api is set we derive the env
+ * file from the collection's base_dir; only error if the file is missing.
+ *
+ * Returns the absolute path to the env file when it exists, otherwise an
+ * error object. Callers may also fall back to other strategies on miss.
+ */
+export function resolveApiEnv(apiName: string, dbPath: string | undefined):
+  | { env: string }
+  | { error: string } {
+  const col = resolveApiCollection(apiName, dbPath);
+  if ("error" in col) return col;
+  if (!col.baseDir) {
+    return { error: `API '${apiName}' has no base_dir registered — pass --env <file> explicitly.` };
+  }
+  const envPath = `${col.baseDir.replace(/\/+$/, "")}/.env.yaml`;
+  return { env: envPath };
+}
+
+/**
+ * Resolve a `<spec>` argument used by spec-consuming commands —
+ * catalog, sync, generate, probe-validation, probe-methods,
+ * probe-mass-assignment, lint-spec, describe, guide.
+ *
+ * Resolution order:
+ *   1. Explicit positional/flag value — used as-is (URL or filesystem path).
+ *   2. --api <name> — look up the workspace-local snapshot via
+ *      `resolveCollectionSpec`.
+ *   3. ZOND_API env / .zond/current-api — same lookup using the currently-selected API
+ *      (TASK-290; resolution chain implemented in core/context/current.ts).
+ *
+ * Returns `{ spec }` on success, `{ error }` on failure. Centralised here
+ * so commands stay thin and skill/CI prompts can rely on either form.
+ */
+export function resolveSpecArg(
+  positional: string | undefined,
+  apiFlag: string | undefined,
+  dbPath: string | undefined,
+): { spec: string } | { error: string } {
+  if (typeof positional === "string" && positional.length > 0) {
+    return { spec: positional };
+  }
+  const apiName = apiFlag ?? readCurrentApi() ?? undefined;
+  if (!apiName) {
+    return {
+      error: "Need a spec — pass it positionally, via --api <name>, or set the current API with `zond use <name>`.",
+    };
+  }
+  const resolved = resolveApiCollection(apiName, dbPath);
+  if ("error" in resolved) return { error: resolved.error };
+  if (!resolved.spec) {
+    return {
+      error:
+        `API '${apiName}' is registered without an OpenAPI spec — this command needs one. ` +
+        `Run \`zond refresh-api ${apiName} --spec <path|url>\` to attach a spec, ` +
+        `or use \`zond run --api ${apiName} <test.yaml>\` for YAML-based testing.`,
+    };
+  }
+  return { spec: resolved.spec };
+}
+

package/src/cli/safe-live.ts

@@ -0,0 +1,24 @@
+/**
+ * ARV-299: one safe/live vocabulary across `audit`, `checks run`, and the
+ * mutating `probe` subcommands so a developer has a single button —
+ * `--safe` (default) means "no destructive traffic", `--live` opts in.
+ *
+ * The help strings live here so all three commands read identically
+ * (ARV-299 AC#3). `audit` predates this module and keeps its own richer
+ * --live text (it gates several stages); the shorter pair here is for
+ * checks/probe.
+ */
+
+export const SAFE_HELP =
+  "Safe mode (DEFAULT): no destructive/mutating traffic — no create/update/delete " +
+  "chains, no live attack payloads. Explicit inverse of --live; safe if neither is given.";
+
+export const LIVE_HELP =
+  "Opt into destructive/mutating operations (create/update/delete chains, live " +
+  "attack payloads) against a real API. Use only against a throwaway/sandbox account.";
+
+/** Resolve the safe/live pair to a single boolean. Default is safe;
+ *  `--live` wins if both are somehow passed. */
+export function resolveLive(opts: { safe?: boolean; live?: boolean }): boolean {
+  return opts.live === true;
+}

package/src/cli/status-filter.ts

@@ -0,0 +1,114 @@
+/**
+ * TASK-140: parse `--status` filter expressions for `zond db run/runs`.
+ *
+ * Accepted forms (combinable via comma):
+ *   502                — exact code
+ *   5xx / 4xx / 3xx / 2xx / 1xx — class wildcard (`5xx` ≡ 500..599)
+ *   500-599            — inclusive range
+ *   >=500 / >500 / <=400 / <400 — open-ended comparison
+ *   500,502,504        — list of exacts
+ *   5xx,429            — mix of class + exact
+ *
+ * The parser yields a `StatusMatcher` which the DB layer converts into a
+ * single SQL `WHERE` fragment (set + ranges combined with `OR`).
+ */
+
+export interface StatusMatcher {
+  /** Specific codes that should match. */
+  exacts: number[];
+  /** Inclusive ranges `[min, max]` — including class wildcards (5xx → 500..599). */
+  ranges: Array<[number, number]>;
+}
+
+const CLASS_RE = /^([1-5])xx$/i;
+const RANGE_RE = /^(\d{3})-(\d{3})$/;
+const CMP_RE = /^(>=|<=|>|<)\s*(\d{3})$/;
+const CODE_RE = /^\d{3}$/;
+
+function pushExact(out: StatusMatcher, code: number): void {
+  if (code < 100 || code > 599) {
+    throw new Error(`status code out of range: ${code}`);
+  }
+  if (!out.exacts.includes(code)) out.exacts.push(code);
+}
+
+function pushRange(out: StatusMatcher, min: number, max: number): void {
+  if (min > max) throw new Error(`status range start > end: ${min}-${max}`);
+  out.ranges.push([min, max]);
+}
+
+/**
+ * Parse a `--status` argument. Throws on invalid syntax — caller wraps the
+ * thrown message in a CLI error.
+ */
+export function parseStatusFilter(raw: string): StatusMatcher {
+  const trimmed = raw.trim();
+  if (trimmed === "") throw new Error("empty --status value");
+  const parts = trimmed.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+  if (parts.length === 0) throw new Error("empty --status value");
+
+  const out: StatusMatcher = { exacts: [], ranges: [] };
+  for (const part of parts) {
+    let m: RegExpMatchArray | null;
+    if ((m = part.match(CODE_RE))) {
+      pushExact(out, Number(part));
+      continue;
+    }
+    if ((m = part.match(CLASS_RE))) {
+      const klass = Number(m[1]);
+      pushRange(out, klass * 100, klass * 100 + 99);
+      continue;
+    }
+    if ((m = part.match(RANGE_RE))) {
+      const lo = Number(m[1]);
+      const hi = Number(m[2]);
+      if (lo < 100 || lo > 599 || hi < 100 || hi > 599) {
+        throw new Error(`status range out of bounds: ${part} (expected 100..599)`);
+      }
+      pushRange(out, lo, hi);
+      continue;
+    }
+    if ((m = part.match(CMP_RE))) {
+      const op = m[1]!;
+      const code = Number(m[2]);
+      if (code < 100 || code > 599) {
+        throw new Error(`status comparison out of bounds: ${part} (expected 100..599)`);
+      }
+      switch (op) {
+        case ">=": pushRange(out, code, 599); break;
+        case ">":  pushRange(out, code + 1, 599); break;
+        case "<=": pushRange(out, 100, code); break;
+        case "<":  pushRange(out, 100, code - 1); break;
+      }
+      continue;
+    }
+    throw new Error(
+      `invalid --status part: '${part}' (expected one of: 502, 5xx, 500-599, >=500, <400)`,
+    );
+  }
+  return out;
+}
+
+/**
+ * Compile a `StatusMatcher` to a SQL `WHERE` fragment + bound parameters.
+ * The fragment is wrapped in parentheses; combine with other conditions via
+ * `AND`. Returns `null` if the matcher is empty (no constraints).
+ */
+export function compileStatusFilterToSql(
+  matcher: StatusMatcher,
+  column: string,
+): { sql: string; params: number[] } | null {
+  const clauses: string[] = [];
+  const params: number[] = [];
+  if (matcher.exacts.length > 0) {
+    const placeholders = matcher.exacts.map(() => "?").join(",");
+    clauses.push(`${column} IN (${placeholders})`);
+    params.push(...matcher.exacts);
+  }
+  for (const [lo, hi] of matcher.ranges) {
+    clauses.push(`${column} BETWEEN ? AND ?`);
+    params.push(lo, hi);
+  }
+  if (clauses.length === 0) return null;
+  return { sql: `(${clauses.join(" OR ")})`, params };
+}

package/src/cli/util/api-context.ts

@@ -0,0 +1,85 @@
+/**
+ * ARV-53: single resolver for the active `--api` collection name.
+ *
+ * Before this module the chain `localOpts.api → cmd.parent?.opts().api →
+ * readCurrentApi()` was inlined in nine call-sites (probe / prepare-fixtures
+ * / audit / checks / coverage / run / request, plus two intermediate helpers
+ * in probe.ts and resolve.ts). Each repeat was a separate commit
+ * (TASK-17, TASK-20, ARV-21, ARV-29, ARV-33). Centralising the chain here
+ * means new commands consume one import and the fallback rules live in
+ * exactly one place.
+ *
+ * Resolution order (matches the chain users see documented for `zond use`):
+ *   1. Per-command `--api <name>` (the local Commander scope).
+ *   2. Any ancestor command's `--api`, walking up to the program root
+ *      (covers the global `zond --api X <subcmd>` form whose value is
+ *      otherwise stranded on the parent Command).
+ *   3. `readCurrentApi()` — which itself folds in
+ *      `ZOND_API_GLOBAL` (mirrored by program.ts preAction) →
+ *      `ZOND_API` (user env) → `.zond/current-api` (persisted by `zond use`).
+ */
+
+import { readCurrentApi } from "../../core/context/current.ts";
+
+/**
+ * Minimal shape we need from a Commander `Command`. Spelled out as an
+ * interface (not `import("commander").Command`) so test doubles can pass a
+ * plain `{ opts, parent }` literal and TS still type-checks.
+ */
+export interface CommandLike {
+  opts(): Record<string, unknown>;
+  parent?: CommandLike | null;
+}
+
+export type ApiResolution =
+  | { ok: true; api: string; source: "local" | "ancestor" | "current" }
+  | { ok: false };
+
+/** Pull the explicit --api value out of a command's parsed opts, if any. */
+function readApiOpt(cmd: CommandLike): string | undefined {
+  const v = cmd.opts().api;
+  return typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+}
+
+/**
+ * Resolve the active API collection name for `cmd`. Pass `localOpts` when
+ * the action handler already has the parsed local opts in hand (avoids a
+ * second `cmd.opts()` parse and lets callers tunnel through pre-coerced
+ * shapes from tests).
+ */
+export function resolveApi(
+  cmd: CommandLike | undefined,
+  localOpts?: Record<string, unknown>,
+): ApiResolution {
+  const localRaw = localOpts?.api;
+  const local = typeof localRaw === "string" && localRaw.trim().length > 0
+    ? localRaw.trim()
+    : (cmd ? readApiOpt(cmd) : undefined);
+  if (local) return { ok: true, api: local, source: "local" };
+
+  let parent: CommandLike | null | undefined = cmd?.parent ?? null;
+  while (parent) {
+    const fromAncestor = readApiOpt(parent);
+    if (fromAncestor) return { ok: true, api: fromAncestor, source: "ancestor" };
+    parent = parent.parent ?? null;
+  }
+
+  const fromCurrent = readCurrentApi();
+  if (fromCurrent) return { ok: true, api: fromCurrent, source: "current" };
+
+  return { ok: false };
+}
+
+/**
+ * Convenience: returns the API name as `string | undefined`. Use this when
+ * the caller decides for itself how to react to "missing" (e.g. `coverage`
+ * falls back to `--spec`, `run` falls back to a positional path).
+ */
+export function getApi(cmd: CommandLike | undefined, localOpts?: Record<string, unknown>): string | undefined {
+  const r = resolveApi(cmd, localOpts);
+  return r.ok ? r.api : undefined;
+}
+
+/** Default error message for commands that strictly require an API. */
+export const MISSING_API_MESSAGE =
+  "--api is required (or set ZOND_API / `zond use <name>`).";

package/src/cli/version.ts

@@ -1,3 +1,8 @@
 import { version } from "../../package.json";
 
 export const VERSION = version;
+
+/** Canonical GitHub repo (owner/name). Single source of truth for any code
+ *  that links to releases, install scripts, or generated artefacts. */
+export const REPO = "kirrosh/zond";
+export const REPO_URL = `https://github.com/${REPO}`;

package/src/core/audit/persist.ts

@@ -0,0 +1,183 @@
+/**
+ * ARV-265: shared helpers for "any HTTP touch by zond should be visible
+ * to `audit-coverage`". `zond run` was the only producer that wrote into
+ * `runs` / `results`; `checks run`, `probe`, `request`, and
+ * `prepare-fixtures --cascade` all emitted ndjson/stdout and left no
+ * persistent trace. This module gives those producers a uniform path:
+ *
+ *   1. `beginAuditRun(opts)` — INSERT into `runs` with the right
+ *      `run_kind` and return the row id.
+ *   2. accumulate `AuditCaseRecord` entries as the work runs.
+ *   3. `finalizeAuditRun(runId, suiteName, cases)` — group cases into a
+ *      single synthetic `TestRunResult`, call `saveResults`, then
+ *      `finalizeRun` so the row carries totals.
+ *
+ * Suite/test naming is *pseudo* (`checks/response`, `probe/security`,
+ * `request/ad-hoc`) — these rows aren't meant to drive failure triage,
+ * just to keep the audit-coverage matrix honest. The coverage engine
+ * matches results to endpoints via (request_method, request_url) regex,
+ * so the suite name is purely cosmetic.
+ *
+ * Error handling: every write is wrapped in try/catch by the CLI caller
+ * and degrades to a warning — failing to persist must not break the
+ * primary command (a `checks run` that exits 0 with no DB row is still
+ * a successful checks run for the user; audit-coverage just won't pick
+ * it up).
+ */
+import type { HttpRequest, HttpResponse, TestRunResult, StepResult, StepStatus } from "../runner/types.ts";
+import type { RunKind } from "../runner/run-kind.ts";
+import { createRun, saveResults, finalizeRun } from "../../db/queries.ts";
+import { setHttpAuditRecorder, type AuditRecord } from "../runner/http-client.ts";
+
+export interface BeginAuditRunOpts {
+  runKind: RunKind;
+  collectionId?: number;
+  sessionId?: string | null;
+  environment?: string;
+  trigger?: string;
+  tags?: string[];
+  commitSha?: string;
+  branch?: string;
+  startedAt?: string;
+}
+
+export interface AuditCaseRecord {
+  suiteName: string;
+  testName: string;
+  status: StepStatus;
+  request: HttpRequest;
+  response?: HttpResponse;
+  durationMs: number;
+  error?: string;
+  /** Optional `suite_file` value — surfaces in the diagnose output and
+   *  helps the legacy detectRunKind heuristic understand the row's
+   *  origin even if `run_kind` ever drifts. */
+  suiteFile?: string;
+}
+
+export function beginAuditRun(opts: BeginAuditRunOpts): number {
+  return createRun({
+    started_at: opts.startedAt ?? new Date().toISOString(),
+    environment: opts.environment,
+    trigger: opts.trigger ?? "manual",
+    commit_sha: opts.commitSha,
+    branch: opts.branch,
+    collection_id: opts.collectionId,
+    session_id: opts.sessionId ?? undefined,
+    tags: opts.tags && opts.tags.length > 0 ? opts.tags : undefined,
+    run_kind: opts.runKind,
+  });
+}
+
+/**
+ * Group flat case records into one `TestRunResult` per `suite_file` (or
+ * per `suiteName` when no file is set) and write them. Returns the number
+ * of `results` rows persisted so the caller can sanity-check the totals.
+ */
+export function finalizeAuditRun(
+  runId: number,
+  cases: AuditCaseRecord[],
+): { rows: number } {
+  if (cases.length === 0) {
+    // Nothing executed — still close the run so coverage queries can
+    // see an empty audit row instead of an open-ended row dangling
+    // without finished_at.
+    finalizeRun(runId, []);
+    return { rows: 0 };
+  }
+  const bySuite = new Map<string, AuditCaseRecord[]>();
+  for (const c of cases) {
+    const key = c.suiteFile ?? c.suiteName;
+    const list = bySuite.get(key) ?? [];
+    list.push(c);
+    bySuite.set(key, list);
+  }
+  const now = new Date().toISOString();
+  const results: TestRunResult[] = [];
+  for (const [, group] of bySuite) {
+    const first = group[0]!;
+    const steps: StepResult[] = group.map((c) => ({
+      name: c.testName,
+      status: c.status,
+      duration_ms: c.durationMs,
+      request: c.request,
+      response: c.response,
+      assertions: [],
+      captures: {},
+      ...(c.error ? { error: c.error } : {}),
+    }));
+    let passed = 0, failed = 0, skipped = 0;
+    for (const s of steps) {
+      if (s.status === "pass") passed += 1;
+      else if (s.status === "skip") skipped += 1;
+      else failed += 1; // fail | error both bucket as failed for the row totals
+    }
+    results.push({
+      suite_name: first.suiteName,
+      ...(first.suiteFile ? { suite_file: first.suiteFile } : {}),
+      started_at: now,
+      finished_at: now,
+      total: steps.length,
+      passed,
+      failed,
+      skipped,
+      steps,
+    });
+  }
+  saveResults(runId, results);
+  finalizeRun(runId, results);
+  return { rows: cases.length };
+}
+
+/** ARV-265: ZOND_CHECKS_PERSIST opt-out. Default ON — the task's whole
+ *  point is that `checks run` contributes to audit-coverage out of the
+ *  box. Setting the env var to "0" / "false" disables it (for tests, or
+ *  for users who want the pre-ARV-265 behaviour back). */
+export function checksPersistEnabled(): boolean {
+  const v = (process.env.ZOND_CHECKS_PERSIST ?? "").trim().toLowerCase();
+  if (v === "0" || v === "false" || v === "off" || v === "no") return false;
+  return true;
+}
+
+/**
+ * ARV-265: run `fn` with the HTTP audit recorder set; return both the
+ * function's value and the collected records. Convenience for the live
+ * probe commands (probe security / probe mass-assignment) which can't
+ * easily hook into their own internals but route every request through
+ * `executeRequest`.
+ *
+ * The recorder is always cleared in `finally`, even if `fn` throws.
+ */
+export async function withHttpAudit<T>(
+  fn: () => Promise<T>,
+): Promise<{ value: T; records: AuditRecord[] }> {
+  const records: AuditRecord[] = [];
+  setHttpAuditRecorder((rec) => records.push(rec));
+  try {
+    const value = await fn();
+    return { value, records };
+  } finally {
+    setHttpAuditRecorder(null);
+  }
+}
+
+export function auditRecordToCase(
+  rec: AuditRecord,
+  meta: { suiteName: string; suiteFile: string; testName: string },
+): AuditCaseRecord {
+  const status: StepStatus = rec.error
+    ? "error"
+    : rec.response && rec.response.status >= 200 && rec.response.status < 400 ? "pass" : "fail";
+  return {
+    suiteName: meta.suiteName,
+    suiteFile: meta.suiteFile,
+    testName: meta.testName,
+    status,
+    request: rec.request,
+    ...(rec.response ? { response: rec.response } : {}),
+    durationMs: rec.durationMs,
+    ...(rec.error ? { error: rec.error } : {}),
+  };
+}
+
+export type { AuditRecord } from "../runner/http-client.ts";

package/src/core/checks/budget.ts

@@ -0,0 +1,59 @@
+/**
+ * `--budget quick|standard|full` (ARV-292): adaptive cap for `zond audit` and
+ * `zond checks run`, designed so small-team CI gets a "60-sec gate" by default
+ * without having to remember `--max-requests` for huge specs.
+ *
+ * Tiers:
+ *   quick     — 50 req cap, skip stateful (CRUD) checks. ~60-sec wall-clock.
+ *   standard  — 500 req cap, all checks (sampling kept as a Phase-B knob).
+ *   full      — uncapped, all checks.
+ *
+ * Omitted `--budget` keeps the legacy uncapped behaviour so existing CI
+ * pipelines don't suddenly trip `max-requests-cap-reached`. `--max-requests`
+ * always wins over the tier-seeded cap.
+ */
+
+export type Budget = "quick" | "standard" | "full";
+
+export const BUDGETS: readonly Budget[] = ["quick", "standard", "full"];
+
+export interface ResolvedBudget {
+  maxRequests?: number;
+  skipStateful: boolean;
+}
+
+interface TierDefaults {
+  maxRequests?: number;
+  skipStateful: boolean;
+}
+
+const TIERS: Record<Budget, TierDefaults> = {
+  quick: { maxRequests: 50, skipStateful: true },
+  standard: { maxRequests: 500, skipStateful: false },
+  full: { skipStateful: false },
+};
+
+export function isBudget(value: unknown): value is Budget {
+  return typeof value === "string" && (BUDGETS as readonly string[]).includes(value);
+}
+
+/** Resolve final budget given an explicit budget tier and an optional
+ *  `--max-requests` override. When `--max-requests` is set it always wins,
+ *  even if it relaxes a tighter tier cap (e.g. `--budget quick --max-requests
+ *  200` → cap=200). Stateful-skip is tier-driven only; pass an explicit
+ *  include list via `forceStatefulIfIncluded` to opt back in (e.g. when the
+ *  user typed `--check stateful`). */
+export function resolveBudget(
+  budget: Budget | undefined,
+  maxRequestsOverride: number | undefined,
+  opts?: { forceStatefulIfIncluded?: boolean },
+): ResolvedBudget {
+  const tier = budget ? TIERS[budget] : undefined;
+  const skipStateful = tier?.skipStateful === true && opts?.forceStatefulIfIncluded !== true;
+  const cap = typeof maxRequestsOverride === "number" && maxRequestsOverride > 0
+    ? maxRequestsOverride
+    : tier?.maxRequests;
+  const result: ResolvedBudget = { skipStateful };
+  if (cap !== undefined) result.maxRequests = cap;
+  return result;
+}