@kirrosh/zond 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -4,6 +4,90 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.28.0] — 2026-07-11
+
+m-28 corpus-driven launch: every fix below came out of four live audits of
+public APIs (GitHub, Vercel, Stripe, Sentry) — evidence-first, no speculative
+checks.
+
+### Added
+- **`zond fuzz` (ARV-436):** property-based fuzz phase in the checks pipeline
+  over fast-check — seeded (deterministic reruns), random bodies per op judged
+  by the existing 12 response checks; on failure the body auto-shrinks to a
+  minimal counterexample in `evidence.minimal_case` + curl repro. Thin alias
+  over `checks run --phase fuzz`; shrink walk survives per-send network flakes.
+- **`seed_body.setup` (ARV-434):** ordered post-create readiness steps for
+  lifecycle tests ("create invoiceitem before finalizing the invoice") — agent
+  authors bodies+order, zond runs them with `{{id}}` bound to the created
+  resource; a non-2xx setup step skips the lifecycle test with the concrete
+  step+status instead of reporting a fake finding.
+- **Currency-aware money bodies (ARV-430):** generator emits
+  `{{account_currency}}` (manifest source: body-value, `usd` default) so
+  non-USD sandboxes stop 400-ing every money create; `.env` scaffold now seeds
+  any manifest `defaultValue` (was always blank).
+
+### Safety (live-mode hardening from the Vercel run)
+- **Unsafe smoke suites disarmed by default (ARV-412):** every destructive
+  step in `smoke-*-unsafe` gets `skip_if "{{zond_allow_unsafe}} != 1"` — a
+  naive `zond run` can no longer DELETE/PATCH pre-existing resources bound to
+  raw `.env` fixtures. `/zond-scan` live runs with `--exclude-tag unsafe`
+  (ARV-413).
+- **Self-cleanup parity (ARV-415, ARV-429):** checks coverage phase
+  best-effort DELETEs resources its own 2xx POSTs created; mass-assignment
+  probe cleanup returns an audit record (id + deletePath + status).
+- **`always:true` cleanup gated on capture provenance (ARV-428):** never fires
+  against a stale env id the create step did not capture this run.
+- **`--safe` marks write steps as skipped with a reason (ARV-427)** instead of
+  deleting them from the plan silently.
+
+### Fixed
+- **lifecycle_transitions (ARV-433):** an overlay with actions but an empty
+  transitions graph no longer flags every legitimate action as
+  `forbidden_transition`; transition-drift repro (declared→open, observed→paid)
+  locked in with a test.
+- **Fail-fast on unresolved request vars (ARV-414):** kills the multi-minute
+  retry_until spin on never-created resources; `--strict-vars` abort still
+  writes the `--output` artifact.
+- **Coverage accounting (ARV-409, ARV-426):** `--union` no longer aborts a
+  checks-only session (audit HTTP touches count as `run_kind='check'`);
+  RowBucket carries `passStatus` so covered2xx stops contradicting
+  chronological lastStatus.
+- **cross_call_references (ARV-416):** empty/non-object 2xx readback skips
+  (broken-baseline guard) instead of reporting maximal drift.
+- **fixtures add --validate (ARV-417, ARV-423, ARV-424):** derives auth via
+  liveAuthHeaders; resolves the readback endpoint via the manifest's
+  affectedEndpoints (namespaced vars validate again); each path-var resolves
+  from its own env var, so an empty sibling is reported, not misattributed.
+- **Misc:** shared soft-delete detection in verify+validate (ARV-418);
+  `checks run --report json --output` writes the file (ARV-419); `add api`
+  merges an existing `.env.yaml` + `.bak` instead of clobbering (ARV-422);
+  form/query numeric coercion (ARV-431); `db run --json` includes bodies
+  (ARV-432).
+
+### Docs
+- Case studies: GitHub (safe), Vercel (live), Stripe money-lifecycle deep-dive
+  (`docs/case-studies/`), linked from README.
+- Head-to-head: zond vs Schemathesis on live Stripe, honest gap-list both ways
+  (ARV-407).
+
+## [0.27.1] — 2026-07-09
+
+m-27 Bucket E (agentic discoverability): metadata release — no engine changes.
+
+### Added
+- **Claude Code plugin / self-serve marketplace (ARV-395):**
+  `.claude-plugin/{plugin,marketplace}.json` — install skills via
+  `/plugin marketplace add kirrosh/zond`; skills mirrored to root
+  `skills/<name>/SKILL.md` (synced from init templates, drift-checked in
+  `bun run check`), also picked up by SkillsMP / `npx skills add kirrosh/zond`.
+- **Agent discovery files (ARV-394):** `llms.txt` (machine index of docs) and
+  `context7.json` (Context7 config with agent rules) at the repo root.
+
+### Changed
+- **Agentic metadata (ARV-393, ARV-400):** canonical tagline in npm
+  `description`, task-shaped `keywords`, `repository`/`homepage`/`bugs` links;
+  agent-first README top (what → when → install → minimal example).
+
 ## [0.27.0] — 2026-07-09
 
 m-27 start-distribution: every install channel works on a clean machine,

package/README.md

@@ -1,8 +1,21 @@
 # zond
 
-API hygiene scanner for small teams — AI-powered API testing for Claude Code, Cursor, and CI/CD.
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kirrosh/zond)
+[![npm](https://img.shields.io/npm/v/%40kirrosh%2Fzond)](https://www.npmjs.com/package/@kirrosh/zond)
 
-Say "test my API" — get working tests, coverage dashboard, and CI config in minutes.
+API hygiene scanner for small teams and their coding agents — test REST API endpoints against the OpenAPI spec, catch contract drift, track coverage.
+
+**Use it when you need to:** test REST API endpoints from an OpenAPI spec,
+verify an API contract after a deploy, debug a failing HTTP request with
+stored run history, or raise endpoint coverage. Works standalone or through
+a coding agent (Claude Code, Cursor) — say "test my API" and the agent
+drives zond for you.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh   # or: npm i -g @kirrosh/zond
+zond init && zond add api my-api --spec ./openapi.json
+zond audit --api my-api --safe    # read-only pass: spec lint → probes → tests → coverage → HTML report
+```
 
 > **Safe by default.** The first run (`zond audit --safe`) sends read-only
 > GET traffic — no writes, no deletes, nothing destructive. Mutating
@@ -21,6 +34,12 @@ Zond reads your OpenAPI spec and gives your AI agent everything it needs to test
 | **npm** (needs Node 20+) | `npm install -g @kirrosh/zond` |
 | **Windows** | `iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 \| iex` |
 | **Manual** | grab a binary from [releases](https://github.com/kirrosh/zond/releases/latest) (darwin arm64/x64, linux x64/arm64, win x64) |
+| **Claude Code plugin** | `/plugin marketplace add kirrosh/zond` then `/plugin install zond@zond` — the agent skills without `zond init` |
+| **Agent skills** ([skills.sh](https://www.skills.sh)) | `npx skills add kirrosh/zond` |
+
+The plugin/skills channels ship the [five zond skills](skills/) (audit
+pipeline, depth checks, fixture seeding, triage, target warm-up); the zond
+binary itself still comes from any of the channels above.
 
 Every channel ships the same self-contained binary — no Bun or Node
 required at runtime (npm uses Node only as a thin launcher).
@@ -87,6 +106,15 @@ The agent does all three steps autonomously. It asks you only when it needs an a
 
 Claude Code can write pytest from scratch — but it takes 30-60 minutes per flow, has no safety guardrails, no coverage tracking, and no run history. Zond gives the agent structured tools to do it in 5 minutes with full visibility.
 
+## Case Studies
+
+Real public-API audits, calibrated findings only — including what was *not* found:
+
+- [GitHub REST API](docs/case-studies/github-rest-api.md) — ~50% of read endpoints return status codes the official spec never declares; 2 live schema violations. Read-only, ~3.5 min.
+- [Vercel API](docs/case-studies/vercel-api.md) — a live intermittent 500, ~150 undeclared status codes, ~45 create endpoints stricter than their spec — with zero requests sent to account-delete/billing endpoints. Live, no sandbox.
+- [Stripe money lifecycle](docs/case-studies/stripe-lifecycle.md) — drove the full invoice/quote state machine live (`draft→finalize→pay/void`, 15/15 green); the trap that nearly hid the whole lifecycle was a `usd`-default body on a EUR account, not a Stripe bug. Live, test-mode.
+- [zond vs Schemathesis](docs/case-studies/zond-vs-schemathesis.md) — same 112 live Stripe endpoints through both tools: they agree on the one hard result (zero 5xx) and drown in the same noise; the gaps are honest in both directions (Schemathesis has the fuzzing engine, zond has 7 extra checks + severity calibration). Live, test-mode.
+
 ## Key Capabilities
 
 | | |
@@ -136,6 +164,7 @@ zond completions fish > ~/.config/fish/completions/zond.fish
 - [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
+- [docs/case-studies/](docs/case-studies/) — public-API audit case studies
 - [backlog/](backlog/) — project tasks (powered by [Backlog.md](https://backlog.md))
 
 ## License

package/package.json

@@ -1,16 +1,31 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.27.0",
-  "description": "API testing platform — define tests in YAML, run from CLI, generate from OpenAPI specs",
+  "version": "0.28.0",
+  "description": "API hygiene scanner for small teams and their coding agents — test REST API endpoints against the OpenAPI spec, catch contract drift, track coverage.",
   "license": "MIT",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kirrosh/zond.git"
+  },
+  "homepage": "https://github.com/kirrosh/zond#readme",
+  "bugs": {
+    "url": "https://github.com/kirrosh/zond/issues"
+  },
   "keywords": [
-    "api",
-    "testing",
+    "api-testing",
+    "rest-api",
     "openapi",
-    "yaml",
+    "contract-testing",
+    "contract-drift",
+    "schema-validation",
+    "api-coverage",
+    "api-hygiene",
+    "coding-agents",
+    "ai-agents",
+    "claude-code",
+    "sarif",
     "cli",
-    "rest",
     "http"
   ],
   "files": [
@@ -31,11 +46,12 @@
     "test": "bun run test:unit && bun run test:mocked",
     "test:unit": "bun test tests/",
     "test:mocked": "bun run scripts/run-mocked-tests.ts",
-    "check": "tsc --noEmit --project tsconfig.json",
+    "check": "tsc --noEmit --project tsconfig.json && bun run scripts/sync-plugin-skills.ts --check",
     "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"
+    "build": "bun build --compile src/cli/index.ts --outfile dist/zond && bun run scripts/codesign-darwin.ts ./dist/zond",
+    "sync:plugin": "bun run scripts/sync-plugin-skills.ts"
   },
   "devDependencies": {
     "@readme/openapi-parser": "^5.5.0",
@@ -45,6 +61,7 @@
     "ajv-formats": "^3.0.1",
     "backlog.md": "^1.44.0",
     "commander": "^14.0.0",
+    "fast-check": "^4.9.0",
     "knip": "^6.7.0",
     "openapi-types": "^12.1.3",
     "typescript": "^5",