@kirrosh/zond 0.21.0 → 0.23.0

package/README.md

@@ -4,35 +4,69 @@ AI-powered API testing for Claude Code, Cursor, and CI/CD.
 
 Say "test my API" — get working tests, coverage dashboard, and CI config in minutes.
 
-<!-- TODO: add demo GIF (15 sec: plugin install → "cover openapi.json with tests" → 42/47 endpoints covered → dashboard) -->
-
-Zond reads your OpenAPI spec and gives your AI agent everything it needs to test your API: structured tools, safety guardrails, coverage tracking, and run history. You don't need to learn anything new — just describe what you want and the agent handles the rest.
+Zond reads your OpenAPI spec and gives your AI agent everything it needs to test your API: a focused CLI, safety guardrails, coverage tracking, and run history. You don't need to learn anything new — just describe what you want and the agent runs `zond` commands.
 
 ## Quick Start
 
+Install the binary (no Node.js required):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh   # macOS/Linux
+iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex        # Windows
+```
+
+Bootstrap a workspace, register your first API, then fill its fixtures:
+
+```bash
+zond init                                              # bootstrap workspace (no fixture changes)
+zond add api my-api --spec ./openapi.json              # register: copies spec.json + emits manifest
+zond doctor --api my-api --missing-only                # gap report: which vars are UNSET
+zond prepare-fixtures --api my-api --apply [--seed]    # fill apis/my-api/.env.yaml from live API
 ```
-/plugin marketplace add kirrosh/zond
-/plugin install zond@zond-marketplace
+
+For path-FK ids that auto-discover/--seed can't reach (vendor-dashboard
+ids like `cus_*`, GitHub PR numbers, Sentry issue ids), use the manual
+helpers (ARV-195):
+
+```bash
+zond fixtures add --api my-api customer_id=cus_123 --validate --apply
+pbpaste | zond fixtures import --api my-api --from-curl --apply        # paste a curl from devtools
 ```
 
-Then say: _"Safely cover the API from openapi.json with tests"_
+`zond init` writes a self-contained [`AGENTS.md`](AGENTS.md) and Claude Code
+skills — agents read it and use the CLI directly (`zond run`,
+`zond probe static`, `zond db diagnose`, …). No daemon, no transport, no
+extra configuration. `init` is workspace-only — it never touches
+`.env.yaml`; the fixture loop above is the canonical path.
 
-You get auto-validation hooks and CLI tools — all in one package.
+Each registered API gets four files in `apis/<name>/`:
 
-<details>
-<summary>Other installation methods (CLI, binary)</summary>
+- `spec.json` — dereferenced OpenAPI snapshot (canonical machine source).
+- `.api-catalog.yaml` — endpoint index for agents (cheap to read).
+- `.api-resources.yaml` — CRUD chains, FK dependencies, ETag/soft-delete flags.
+- `.api-fixtures.yaml` — **manifest** of required `{{vars}}` (read-only, auto-generated).
+
+Plus a sibling `.env.yaml` that you (or `zond prepare-fixtures`) fill with
+the **values** for those vars. The manifest/values split is strict — see
+the [workspace contract](AGENTS.md#workspace-contract) for details.
+
+Run `zond refresh-api <name> [--spec <new-source>]` to re-snapshot when the
+upstream spec changes.
+
+Then say to your agent: _"Safely cover the API from openapi.json with tests."_
 
-### CLI / Binary
+Want the whole pipeline at once? `zond audit --api my-api` runs
+prepare-fixtures → generate → probes → run → coverage → HTML report in a
+single shot.
+
+<details>
+<summary>Other installation methods (npx)</summary>
 
 ```bash
 npx -y @kirrosh/zond --version
-
-# Standalone binary (no Node.js required)
-curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh   # macOS/Linux
-iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex        # Windows
 ```
 
-See [ZOND.md](ZOND.md) for full CLI reference.
+See [ZOND.md](ZOND.md) for the full CLI reference.
 
 </details>
 
@@ -56,6 +90,11 @@ Claude Code can write pytest from scratch — but it takes 30-60 minutes per flo
 | **Spec-Grounded** | Tests are derived from your OpenAPI schema, not invented from scratch. The spec is the source of truth. |
 | **Full Visibility** | Every run is stored in SQLite. Compare runs, track regressions, see exactly what the server returned. |
 | **Coverage Tracking** | See which endpoints are tested, which aren't, and what broke since last run. |
+| **Schema Validation** | `--validate-schema` checks every JSON response against the OpenAPI schema (types, required, enum, format, `$ref`) — catches contract drift the YAML expectations miss. |
+| **Spec Linting** | `zond check spec` static-analyses the OpenAPI document for internal-consistency bugs (e.g. example violates `format: date-time`) and strictness gaps (path-params without `format`, integer params without min/max) — surfaces issues before any HTTP request. |
+| **Depth Checks (m-15)** | `zond checks run` runs a schemathesis-style catalog of conformance + security probes (`status_code_conformance`, `negative_data_rejection`, `ignored_auth`, `use_after_free`, …) — boundary-value coverage, broken-auth detection, soft-deleted resource leaks. Every finding ships with a `recommended_action` enum so the agent triages without parsing messages. |
+| **SARIF for Code Scanning** | `--report sarif` emits SARIF v2.1.0 with stable `partialFingerprints` — drop-in for `github/codeql-action/upload-sarif@v3` so depth-checks findings show up in GitHub's Security tab. |
+| **Concurrent Workers** | `--workers auto` parallelizes runs at the operation level (bounded async-pool, no threading) — runs that took minutes finish in seconds. Pair with `--rate-limit` to stay within an API's RPS budget. |
 | **CI-Ready** | One command generates GitHub Actions or GitLab CI workflow. Tests in YAML, in git, with code review. |
 
 ## Try It
@@ -67,11 +106,35 @@ Claude Code can write pytest from scratch — but it takes 30-60 minutes per flo
 "Set up CI for API tests"
 ```
 
+## Upgrading
+
+`zond update` was removed in favour of system package managers:
+
+```bash
+# macOS / Linux — re-run the installer
+curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
+
+# npm
+npm install -g @kirrosh/zond@latest
+
+# bun
+bun install -g @kirrosh/zond@latest
+```
+
+## Shell completions
+
+```bash
+zond completions bash > ~/.local/share/bash-completion/completions/zond
+zond completions zsh  > ~/.zsh/completions/_zond   # then `compinit`
+zond completions fish > ~/.config/fish/completions/zond.fish
+```
+
 ## Documentation
 
 - [ZOND.md](ZOND.md) — full CLI reference
 - [docs/quickstart.md](docs/quickstart.md) — step-by-step quickstart (RU)
 - [docs/ci.md](docs/ci.md) — CI/CD integration
+- [backlog/](backlog/) — project tasks (powered by [Backlog.md](https://backlog.md))
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.21.0",
-  "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
+  "version": "0.23.0",
+  "description": "API testing platform — define tests in YAML, run from CLI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
   "type": "module",
@@ -25,17 +25,23 @@
   },
   "scripts": {
     "zond": "bun run src/cli/index.ts",
+    "backlog": "bunx backlog",
+    "board": "bunx backlog board",
     "test": "bun run test:unit && bun run test:mocked",
-    "test:unit": "bun test tests/db/ tests/parser/ tests/runner/ tests/generator/ tests/core/ tests/diagnostics/ tests/cli/args.test.ts tests/cli/ci-init.test.ts tests/cli/commands.test.ts tests/cli/safe-run.test.ts tests/cli/json-envelope.test.ts tests/cli/describe.test.ts tests/cli/catalog.test.ts tests/cli/db.test.ts tests/cli/request.test.ts tests/cli/init.test.ts tests/cli/guide.test.ts tests/integration/ tests/web/ tests/reporter/ tests/version-sync.test.ts",
+    "test:unit": "bun test tests/",
     "test:mocked": "bun run scripts/run-mocked-tests.ts",
     "check": "tsc --noEmit --project tsconfig.json",
-    "build": "bun build --compile src/cli/index.ts --outfile zond",
-    "version:sync": "bun run scripts/sync-version.ts",
-    "postversion": "bun run scripts/sync-version.ts && git add .claude-plugin/plugin.json",
+    "schemas": "bun run scripts/emit-json-schemas.ts",
+    "schemas:check": "bun run scripts/emit-json-schemas.ts --check",
+    "lint:dead": "knip --reporter compact",
+    "build": "bun build --compile src/cli/index.ts --outfile dist/zond && bun run scripts/codesign-darwin.ts ./dist/zond",
     "bench:api": "bun benchmarks/api/server.ts"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "ajv-draft-04": "^1.0.0",
+    "backlog.md": "^1.44.0",
+    "knip": "^6.7.0"
   },
   "engines": {
     "bun": ">=1.1.0"
@@ -44,11 +50,12 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@humanwhocodes/momoa": "^2.0.3",
-    "@hono/zod-openapi": "^1.2.2",
     "@readme/openapi-parser": "^5.5.0",
-    "hono": "^4.12.2",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "commander": "^14.0.0",
     "openapi-types": "^12.1.3",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
   }
 }

package/src/cli/argv.ts

@@ -0,0 +1,122 @@
+/**
+ * Pre-commander argv handling and shared argument parsers used across the
+ * commander tree. Pulled out of program.ts (TASK-190, m-11) so program.ts
+ * shrinks toward "just command registration" and these helpers can be
+ * unit-tested in isolation.
+ */
+
+import { InvalidArgumentError } from "commander";
+import type { ReporterName } from "../core/reporter/types.ts";
+
+// ── MSYS path preprocessing ──
+//
+// Git Bash on Windows converts API paths like "/users" → "C:/Program Files/Git/users".
+// We reverse that for flags whose values are API paths, not filesystem paths.
+
+const MSYS_PREFIX_RE = /^[A-Z]:[\\/](?:Program Files[\\/]Git|msys64|usr)[\\/]/i;
+
+const API_PATH_FLAGS = new Set(["--path", "--json-path"]);
+
+function stripMsysPath(value: string): string {
+  if (!MSYS_PREFIX_RE.test(value)) return value;
+  return value.replace(MSYS_PREFIX_RE, "/");
+}
+
+/**
+ * Pre-process argv before commander sees it: undo Git Bash's MSYS path conversion
+ * for `--path` and `--json-path` values (both `--path X` and `--path=X` forms).
+ */
+export function preprocessArgv(argv: string[]): string[] {
+  const out = [...argv];
+  for (let i = 0; i < out.length; i++) {
+    const arg = out[i]!;
+
+    // --flag=value form
+    const eqIdx = arg.indexOf("=");
+    if (arg.startsWith("--") && eqIdx !== -1) {
+      const flag = arg.slice(0, eqIdx);
+      if (API_PATH_FLAGS.has(flag)) {
+        out[i] = `${flag}=${stripMsysPath(arg.slice(eqIdx + 1))}`;
+      }
+      continue;
+    }
+
+    // --flag value form
+    if (API_PATH_FLAGS.has(arg)) {
+      const next = out[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        out[i + 1] = stripMsysPath(next);
+      }
+    }
+  }
+  return out;
+}
+
+// ── Argument parsers ──
+
+export function parsePositiveInt(name: string): (raw: string) => number {
+  return (raw: string) => {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n) || n <= 0) {
+      throw new InvalidArgumentError(`Invalid ${name} value: ${raw}`);
+    }
+    return n;
+  };
+}
+
+/** `--rate-limit` accepts a positive integer (req/sec cap) or the literal
+ *  string `auto` (no static cap; throttle adaptively from ratelimit-* headers). */
+export function parseRateLimit(raw: string): number | "auto" {
+  if (raw.toLowerCase() === "auto") return "auto";
+  const n = Number.parseInt(raw, 10);
+  if (Number.isNaN(n) || n <= 0) {
+    throw new InvalidArgumentError(`Invalid --rate-limit value: ${raw} (expected a positive integer or "auto")`);
+  }
+  return n;
+}
+
+export function parseNonNegativeInt(name: string): (raw: string) => number {
+  return (raw: string) => {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n) || n < 0 || String(n) !== raw.trim()) {
+      throw new InvalidArgumentError(`Invalid ${name} value: ${raw} (expected a non-negative integer)`);
+    }
+    return n;
+  };
+}
+
+export function parseInteger(name: string): (raw: string) => number {
+  return (raw: string) => {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n)) {
+      throw new InvalidArgumentError(`Invalid ${name} value: ${raw}`);
+    }
+    return n;
+  };
+}
+
+export function parsePercentage(raw: string): number {
+  const n = Number.parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 0 || n > 100) {
+    throw new InvalidArgumentError(`Invalid --fail-on-coverage value: ${raw} (must be 0–100)`);
+  }
+  return n;
+}
+
+export const collect = (val: string, prev: string[]): string[] => [...prev, val];
+
+const VALID_REPORTERS = new Set<string>(["console", "json", "junit"]);
+
+export function parseReporter(raw: string): ReporterName {
+  if (!VALID_REPORTERS.has(raw)) {
+    throw new InvalidArgumentError(`Unknown reporter: ${raw}. Available: console, json, junit`);
+  }
+  return raw as ReporterName;
+}
+
+/** Helper: split repeatable values like ["a,b", "c"] → ["a", "b", "c"] */
+export function flatSplit(values: string[] | undefined): string[] | undefined {
+  if (!values || values.length === 0) return undefined;
+  const out = values.flatMap((v) => v.split(",")).filter(Boolean);
+  return out.length > 0 ? out : undefined;
+}

package/src/cli/commands/add-api.ts

@@ -0,0 +1,134 @@
+/**
+ * `zond add api <name> --spec <path|url>` — register a new API in the
+ * current workspace.
+ *
+ * The split from `zond init --spec` exists so the two operations
+ * (workspace bootstrap vs. API registration) have separate names and
+ * separate skill mentions. `init --spec` still works as a deprecated
+ * alias.
+ *
+ * This command refuses to run when no workspace marker is present,
+ * pointing the user at `zond init` first. setupApi handles spec
+ * snapshot + artifact generation.
+ */
+
+import { setupApi, type SetupApiResult } from "../../core/setup-api.ts";
+import { findWorkspaceRoot } from "../../core/workspace/root.ts";
+import { jsonOk, jsonError, printJson, zerr } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface AddApiOptions {
+  name: string;
+  spec?: string;
+  baseUrl?: string;
+  dir?: string;
+  force?: boolean;
+  insecure?: boolean;
+  dbPath?: string;
+  json?: boolean;
+}
+
+export async function addApiCommand(opts: AddApiOptions): Promise<number> {
+  const ws = findWorkspaceRoot();
+  if (ws.fromFallback) {
+    const m = `No workspace detected (no zond.config.yml / .zond / zond.db / apis marker). Run \`zond init\` first to bootstrap a workspace.`;
+    if (opts.json) printJson(jsonError("add-api", [m])); else printError(m);
+    return 2;
+  }
+
+  const envVars: Record<string, string> = {};
+  if (opts.baseUrl) envVars.base_url = opts.baseUrl;
+
+  let result: SetupApiResult;
+  try {
+    result = await setupApi({
+      name: opts.name,
+      spec: opts.spec,
+      dir: opts.dir,
+      envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
+      dbPath: opts.dbPath,
+      force: opts.force,
+      insecure: opts.insecure,
+    });
+  } catch (err) {
+    const m = (err as Error).message;
+    // Tag known spec-ingest failures with a structured code so downstream
+    // tooling (skills, retry logic) can branch on it (ARV-145). Cyclic
+    // structures escape decycleSchema only when @readme/openapi-parser
+    // builds an unusual graph — surface that as spec_load_failure with a
+    // pointer to the underlying serializer message.
+    const isCycleError = /cyclic structures|spec_serialize_failed/i.test(m);
+    const errInput = isCycleError ? zerr("spec_load_failure", m) : m;
+    if (opts.json) printJson(jsonError("add-api", [errInput])); else printError(m);
+    return 2;
+  }
+
+  const mode: "spec" | "run-only" = opts.spec ? "spec" : "run-only";
+  const artifacts = mode === "spec"
+    ? ["spec.json", ".api-catalog.yaml", ".api-resources.yaml", ".api-fixtures.yaml", ".env.yaml"]
+    : [".env.yaml"];
+
+  if (opts.json) {
+    printJson(jsonOk("add-api", {
+      api: opts.name,
+      mode,
+      collectionId: result.collectionId,
+      baseDir: result.baseDir,
+      testPath: result.testPath,
+      endpoints: result.specEndpoints,
+      artifacts,
+    }, result.warnings));
+  } else {
+    if (mode === "spec") {
+      printSuccess(`Registered API '${opts.name}' at ${result.baseDir} (${result.specEndpoints} endpoints)`);
+      process.stdout.write(`  Artifacts: spec.json + .api-catalog.yaml + .api-resources.yaml + .api-fixtures.yaml\n`);
+      if (result.authVars && result.authVars.length > 0) {
+        const list = result.authVars.map((v) => `\`${v}\``).join(", ");
+        process.stdout.write(`  Auth required: fill ${list} in ${result.baseDir}/.secrets.yaml (already wired via @secret in .env.yaml).\n`);
+      }
+      process.stdout.write(`  Next: run \`zond doctor --api ${opts.name}\` to see required fixtures.\n`);
+    } else {
+      printSuccess(`Registered API '${opts.name}' at ${result.baseDir} (no spec — run-only mode)`);
+      process.stdout.write(`  Artifacts: .env.yaml (base_url=${opts.baseUrl})\n`);
+      process.stdout.write(`  Next: write tests in ${result.testPath}/, run \`zond run --api ${opts.name} <test.yaml>\`.\n`);
+      process.stdout.write(`  To enable generate/probe/validate-schema, attach a spec: \`zond refresh-api ${opts.name} --spec <path|url>\`.\n`);
+    }
+    if (result.warnings) for (const w of result.warnings) process.stderr.write(`Warning: ${w}\n`);
+  }
+  return 0;
+}
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+
+export function registerAdd(program: Command): void {
+  const add = program.command("add").description("Register objects in the workspace");
+  add
+    .command("api <name>")
+    .description("Register an API: from an OpenAPI spec (full toolkit) or just --base-url (run-only mode)")
+    .option("--spec <path>", "Path or URL to OpenAPI spec — enables generate/probe/validate-schema")
+    .option("--base-url <url>", "Base URL recorded in .env.yaml (required if --spec is omitted)")
+    .option("--dir <path>", "Target directory (defaults to apis/<name>/)")
+    .option("--force", "Overwrite an existing API with the same name")
+    .option("--insecure", "Skip TLS verification when fetching the spec from https")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (name: string, opts, cmd: Command) => {
+      const json = globalJson(cmd);
+      if (!opts.spec && !opts.baseUrl) {
+        const m = "Provide --spec <path|url> for a full registration, or --base-url <url> for run-only mode.";
+        if (json) printJson(jsonError("add-api", [m])); else printError(m);
+        process.exitCode = 2;
+        return;
+      }
+      process.exitCode = await addApiCommand({
+        name,
+        spec: opts.spec,
+        baseUrl: opts.baseUrl,
+        dir: opts.dir,
+        force: opts.force === true,
+        insecure: opts.insecure === true,
+        dbPath: typeof opts.db === "string" ? opts.db : undefined,
+        json,
+      });
+    });
+}

package/src/cli/commands/api/annotate/idempotency.ts

@@ -0,0 +1,59 @@
+/**
+ * ARV-187 / idempotency: parser + expected shape.
+ */
+
+import { z } from "zod";
+import type { ResourcePatch } from "./overlay.ts";
+import type { ResourceSlice } from "./prompts.ts";
+
+const IdempotencySchema = z.object({
+  header: z.string().default("Idempotency-Key"),
+  scope: z.enum(["endpoint", "global"]).optional(),
+  ignore_response_fields: z.array(z.string()).optional(),
+});
+
+const ResponseSchema = z.object({
+  resource: z.string(),
+  idempotency: IdempotencySchema.nullable(),
+  rationale: z.string().optional(),
+  confidence: z.enum(["low", "medium", "high"]).optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  resource: "string (echo input)",
+  idempotency: {
+    header: "string (header name, e.g. 'Idempotency-Key')",
+    scope: "endpoint | global (optional)",
+    ignore_response_fields: "string[] (optional — fields that change between replays, e.g. 'created')",
+  },
+  rationale: "string (optional)",
+  confidence: "low | medium | high",
+  null_form: "if create endpoint doesn't support idempotency-replay, return { resource, idempotency: null }",
+};
+
+export function parseIdempotencyResponse(parsed: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
+  const validated = ResponseSchema.safeParse(parsed);
+  if (!validated.success) {
+    throw new Error(`idempotency response failed schema for ${slice.resource}: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  if (v.idempotency == null) {
+    return {
+      patch: { resource: slice.resource },
+      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "no Idempotency-Key support" },
+    };
+  }
+  return {
+    patch: {
+      resource: slice.resource,
+      idempotency: {
+        header: v.idempotency.header,
+        scope: v.idempotency.scope,
+        ignore_response_fields: v.idempotency.ignore_response_fields,
+      },
+    },
+    audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence },
+  };
+}
+
+export function isApplicable(slice: ResourceSlice): boolean { return Boolean(slice.endpoints.create); }