@kirrosh/zond 0.23.0 → 0.26.0

package/src/cli/json-envelope.ts

@@ -106,23 +106,3 @@ export function writeEnvelope<T>(command: string, result: EnvelopeResult<T>): nu
   printJson(jsonError(command, result.errors, result.warnings, exit));
   return exit;
 }
-
-/**
- * High-order wrapper for `--json` action handlers. Accepts an async
- * producer and renders its return value (or thrown error) as an
- * envelope. Errors thrown synchronously or asynchronously become
- * `{ ok: false, errors: [{code: "unknown_error", message}] }` with
- * `exitCode = 2`.
- */
-export async function withEnvelope<T>(
-  command: string,
-  produce: () => Promise<{ data: T; warnings?: string[] }>,
-): Promise<number> {
-  try {
-    const { data, warnings } = await produce();
-    return writeEnvelope(command, { ok: true, data, warnings });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return writeEnvelope(command, { ok: false, errors: [message] });
-  }
-}

package/src/cli/json-schemas.ts

@@ -128,11 +128,46 @@ export const CheckRunSummarySchema = z.object({
   // never produced a checkable response (e.g. probe got 4xx, schema only on
   // 200) so "0 findings" doesn't read as "all green".
   skipped_outcomes: z.record(z.string(), z.number().int().nonnegative()),
+  // ARV-83: structured counterpart to skipped_outcomes — split into
+  // {check, reason, count} so consumers don't have to colon-tokenise a
+  // reason that may itself contain colons. Sorted by count desc.
+  skipped_outcomes_grouped: z.array(z.object({
+    check: z.string(),
+    reason: z.string(),
+    count: z.number().int().nonnegative(),
+  })),
+  // ARV-283 / ARV-68: count of findings the severity matrix demoted to
+  // `info-suppressed`. Excluded from `findings` / `by_severity` so CI
+  // gates ignore them, but exposed here so consumers (ajv validators
+  // included) accept the field — the runner emits it unconditionally.
+  suppressed: z.number().int().nonnegative().optional(),
+});
+
+/** ARV-60: spec-level rollup row. Emitted when ≥80% of a check's
+ *  applicable operations share the same root cause (status drift,
+ *  missing-declaration skip cluster, or no-detector zero-case). Lives in
+ *  `data.spec_findings` and as its own `spec_finding` NDJSON event. */
+export const SpecFindingSchema = z.object({
+  check: z.string(),
+  kind: z.enum(["status_drift", "missing_declaration", "no_detector", "broken_baseline", "other"]),
+  severity: SeveritySchema,
+  category: CategorySchema.optional(),
+  reason: z.string(),
+  fix_hint: z.string(),
+  affected_operations: z.array(z.object({
+    path: z.string(),
+    method: z.string(),
+    operationId: z.string().optional(),
+  })),
+  count: z.number().int().nonnegative(),
+  applicable: z.number().int().nonnegative(),
 });
 
 export const ChecksRunDataSchema = z.object({
   findings: z.array(CheckFindingSchema),
   summary: CheckRunSummarySchema,
+  // ARV-60: always present (empty array when no clusters cross 80%).
+  spec_findings: z.array(SpecFindingSchema),
 });
 
 /** ARV-10 (m-15): NDJSON streaming events emitted by `zond checks run
@@ -157,6 +192,10 @@ export const NdjsonCheckResultEventSchema = z.object({
   type: z.literal("check_result"),
   ts: z.string(),
   check: z.string(),
+  // ARV-215: severity from the registry (mirrors `zond checks list`
+  // [high|medium|low]). Lets consumers group NDJSON by severity without
+  // re-joining against the registry.
+  severity: z.enum(["info", "low", "medium", "high", "critical"]),
   verdict: z.enum(["pass", "fail"]),
   operation: OperationRefSchema,
   request_signature: z.string(),
@@ -184,10 +223,22 @@ export const NdjsonSummaryEventSchema = z.object({
   summary: CheckRunSummarySchema,
 });
 
+/** ARV-60: rolled-up spec-level finding event. Emitted before the
+ *  terminal `summary` event so streaming consumers see clusters in the
+ *  same order the CLI renders them. Per-op `finding` events are NOT
+ *  removed — both layers coexist. */
+export const NdjsonSpecFindingEventSchema = z.object({
+  type: z.literal("spec_finding"),
+  ts: z.string(),
+  check: z.string(),
+  spec_finding: SpecFindingSchema,
+});
+
 export const NdjsonEventSchema = z.discriminatedUnion("type", [
   NdjsonCheckStartEventSchema,
   NdjsonCheckResultEventSchema,
   NdjsonFindingEventSchema,
+  NdjsonSpecFindingEventSchema,
   NdjsonSummaryEventSchema,
 ]);
 

package/src/cli/output.ts

@@ -7,9 +7,25 @@ function useColor(): boolean {
   return process.stderr.isTTY ?? false;
 }
 
-export function printError(message: string): void {
+let debugHintShown = false;
+
+// ARV-203: when a command catches an unexpected throw and calls
+// `printError(msg, err)`, gate the stack trace behind ZOND_DEBUG=1.
+// Without the env var, append a one-time hint so the user knows the
+// switch exists — the previous behaviour silently dropped TypeError
+// stacks and forced reverse-engineering from the bare message.
+export function printError(message: string, err?: unknown): void {
   const msg = useColor() ? `${RED}Error: ${message}${RESET}` : `Error: ${message}`;
   process.stderr.write(msg + "\n");
+  if (err === undefined) return;
+  if (process.env.ZOND_DEBUG === "1" && err instanceof Error && err.stack) {
+    process.stderr.write(err.stack + "\n");
+    return;
+  }
+  if (!debugHintShown) {
+    debugHintShown = true;
+    process.stderr.write("  hint: set ZOND_DEBUG=1 to print the full stack trace.\n");
+  }
 }
 
 export function printSuccess(message: string): void {

package/src/cli/program.ts

@@ -14,9 +14,9 @@ import { registerRequest } from "./commands/request.ts";
 import { registerGenerate } from "./commands/generate.ts";
 import { registerPrepareFixtures } from "./commands/prepare-fixtures.ts";
 import { registerFixtures } from "./commands/fixtures.ts";
+import { registerSecrets } from "./commands/secrets.ts";
 import { registerProbes } from "./commands/probe.ts";
 import { bootstrapProbes } from "../core/probe/bootstrap.ts";
-import { bootstrapAntiFp } from "../core/anti-fp/bootstrap.ts";
 import { registerReport } from "./commands/report.ts";
 import { registerCatalog } from "./commands/catalog.ts";
 import { registerCompletions } from "./commands/completions.ts";
@@ -24,6 +24,7 @@ import { registerUse } from "./commands/use.ts";
 import { registerSession } from "./commands/session.ts";
 import { registerDoctor } from "./commands/doctor.ts";
 import { registerRefreshApi } from "./commands/refresh-api.ts";
+import { registerSchemaFromRuns } from "./commands/schema-from-runs.ts";
 import { registerAdd } from "./commands/add-api.ts";
 import { registerRemove } from "./commands/remove-api.ts";
 import { registerAudit } from "./commands/audit.ts";
@@ -83,6 +84,7 @@ export function buildProgram(): Command {
 
   registerUse(program);
   registerRefreshApi(program);
+  registerSchemaFromRuns(program);
   registerDoctor(program);
 
   registerSession(program);
@@ -102,15 +104,13 @@ export function buildProgram(): Command {
   registerGenerate(program);
   registerPrepareFixtures(program);
   registerFixtures(program);
+  registerSecrets(program);
   registerAudit(program);
 
   // m-17 / ARV-49: validate registered probes implement the Probe
   // contract before commander gets to wire them up. Boot-throws on a
   // missing slot, so a regression can't slip past CI.
   bootstrapProbes();
-  // ARV-123/124: populate the anti-FP rule registry before checks run
-  // — checks call applyAntiFp() and need every shipped rule present.
-  bootstrapAntiFp();
   registerProbes(program);
 
   registerCatalog(program);
@@ -130,6 +130,7 @@ export function buildProgram(): Command {
     "add":          "Setup:",
     "remove":       "Setup:",
     "use":          "Setup:",
+    "secrets":      "Setup:",
     "refresh-api":  "Setup:",
     "doctor":       "Setup:",
     "clean":        "Setup:",

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

@@ -89,16 +89,6 @@ export function parseStatusFilter(raw: string): StatusMatcher {
   return out;
 }
 
-/** True if `code` matches the parsed filter. Useful for in-memory filtering. */
-export function statusMatches(matcher: StatusMatcher, code: number | null | undefined): boolean {
-  if (code == null) return false;
-  if (matcher.exacts.includes(code)) return true;
-  for (const [lo, hi] of matcher.ranges) {
-    if (code >= lo && code <= hi) return true;
-  }
-  return false;
-}
-
 /**
  * Compile a `StatusMatcher` to a SQL `WHERE` fragment + bound parameters.
  * The fragment is wrapped in parentheses; combine with other conditions via

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;
+}

package/src/core/checks/checks/cross_call_references.ts

@@ -7,9 +7,15 @@
  * echoed) but the read didn't return surface as drift findings — the
  * server is silently dropping state.
  *
- * Severity policy:
- *   • `state_not_persisted` (POST echoed, GET dropped) is the high-
- *     signal class, so the check is registered as HIGH.
+ * Severity policy (ARV-287, follow-up to ARV-284):
+ *   • Declared check severity is LOW (proof-cap baseline per ARV-250:
+ *     single-signal checks cap at LOW until evidence confirms higher).
+ *   • Per-finding dispatch in the fail branch:
+ *       - state_not_persisted non-empty → HIGH
+ *         (POST echoed field, GET dropped it: two-signal evidence chain —
+ *         the server promised state it later discarded)
+ *       - write-only-only (state_not_persisted=[], writeOnly non-empty) → MEDIUM
+ *         (single-signal contract gap per ARV-250)
  *   • `write_only` (POST accepted, GET never returned) is also surfaced
  *     in the same finding's evidence. Anti-FP: write-only fields the
  *     spec explicitly declares are *not* present on GET (e.g. password
@@ -48,7 +54,9 @@ function safeParse(v: unknown): unknown {
 
 export const crossCallReferences: CrudStatefulCheck = {
   id: "cross_call_references",
-  severity: "high",
+  // ARV-287: proof-cap baseline per ARV-250 (single-signal cap → LOW).
+  // Per-finding dispatch in run() escalates to HIGH / MEDIUM by evidence.
+  severity: "low",
   defaultExpected: "Fields accepted or echoed by POST must be readable via GET on the same resource",
   references: [{ id: "ARV-169" }, { id: "OWASP-API-3-2023" }],
   phase: "crud",
@@ -117,6 +125,11 @@ export const crossCallReferences: CrudStatefulCheck = {
     ];
     return {
       kind: "fail",
+      // ARV-287: per-finding severity dispatch (follow-up to ARV-284).
+      // state_not_persisted → HIGH: two-signal evidence chain (POST echoed,
+      // GET dropped) confirms the server is discarding persisted state.
+      // write-only-only → MEDIUM: single-signal contract gap per ARV-250.
+      severity: stateNotPersisted.length > 0 ? "high" : "medium",
       message:
         stateNotPersisted.length > 0
           ? `POST→GET drift on ${g.resource}: ${stateNotPersisted.length} state-not-persisted field(s)` +