@kirrosh/zond 0.26.1 → 0.27.0

package/src/cli/resolve.ts

@@ -1,105 +0,0 @@
-/**
- * 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/runtime.ts

@@ -1,7 +0,0 @@
-export function isCompiledBinary(): boolean {
-  return process.argv[0] === "bun" && import.meta.path.includes("~BUN");
-}
-
-export function getRuntimeInfo(): string {
-  return isCompiledBinary() ? "standalone" : "bun";
-}

package/src/cli/safe-live.ts

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

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

@@ -1,85 +0,0 @@
-/**
- * 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,8 +0,0 @@
-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

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

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