@kirrosh/zond 0.14.0 → 0.17.0

package/CHANGELOG.md

@@ -2,146 +2,166 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.7.0] — Renamed to zond
+## [Unreleased] — fix/generator-quality-improvements
 
-- Renamed package from `@kirrosh/apitool` to `zond`
-- CLI binary: `apitool` → `zond`
-- Database: `apitool.db` → `zond.db`
-- Environment variable: `APITOOL_AI_KEY` → `ZOND_AI_KEY`
-- MCP server name: `apitool` → `zond`
-- Fresh DB schema (no migrations)
+### Breaking changes
 
-## [0.6.1] - 2026-03-04
+- **MCP layer removed** — `zond mcp` command and `@modelcontextprotocol/sdk` dependency deleted.
+  The agent interface is now exclusively the CLI + skills in `skills/`. No migration path needed.
 
-### Changed
+- **`zond migrate` removed** — the migration system was added and then removed in the same branch.
+  Format changes in zond are backward-compatible or require a clean `zond generate`.
 
-- **Web UI redesign** — single-page dashboard with three tabs:
-  - **Endpoints** — all OpenAPI spec endpoints with coverage status (passing/failing/no tests/not run), filters by status and method, expandable details with covering test steps, assertions, and response status
-  - **Suites** — all YAML test files on disk with run results, expandable step details showing assertions, captures, error messages, and response body for failed steps
-  - **Runs** — paginated run history with progress bars, drill-down into run details with JUnit/JSON export
-- **Health strip** — top-of-page overview: coverage donut chart, pass/fail/skip stats, progress bar, environment alert banner
-- **Broken endpoint marking** — `deprecated`, `no_response_schema`, `no_responses_defined`, `required_params_no_examples` warnings shown as badges on endpoints
-- **diagnose_failure** enriched with `failure_type` (api_error / assertion_failed / network_error) and summary counts
+---
 
-### Fixed
+### Features
 
-- Slim npm package — non-essential files excluded via `files` field in package.json
+#### Generator
 
-## [0.5.4] - 2026-03-03
+- **Sanity suite** (`sanity.yaml`) — `zond generate` now produces a 1-2 step sanity file as the
+  first output: an auth step (if the API has auth) + a connectivity probe (healthcheck or first
+  simple GET). Run with `--tag sanity` before the full suite to catch `base_url`/auth issues early.
+  Skill workflow updated with mandatory Step 3.25.
 
-### Fixed
+- **Multipart bodies** — endpoints with `requestBody: multipart/form-data` now generate `multipart:`
+  blocks instead of empty `json:`. Binary (`format: binary` / `format: byte`) fields become
+  `{ file: ./fixtures/<field>.bin, content_type: application/octet-stream }`.
 
-- **`execute-run.ts`**: removed stale `"default"` fallback for `effectiveEnvName` — when no `envName` was passed but a collection existed, the runner looked for `.env.default.yaml` instead of `.env.yaml`, causing all variables (including `base_url`) to be empty and every request to fail with `"URL is invalid"`
+- **Reset endpoint isolation** — `reset`, `flush`, `purge`, `truncate`, `wipe`, `clear-data`,
+  `factory-reset` paths now get tags `[system, reset]` instead of `[smoke, unsafe]`, preventing
+  them from running during smoke passes and accidentally wiping server state.
 
-### Added
+- **Logout exclusion from setup suites** — `logout`, `signout`, `invalidate`, `revoke` endpoints
+  are no longer included in `setup: true` auth suites. Including them would invalidate the captured
+  token for all subsequent suites.
 
-- **`executor.ts`**: early URL validation before `fetch()` — if `base_url` is missing or empty the step now fails immediately with a descriptive error `"base_url is not configured — URL resolved to a relative path: …"` instead of the cryptic `TypeError: URL is invalid`; subsequent steps that depend on captures from the failed step are automatically skipped
-- **`diagnose_failure`**: `envHint()` detector — surfaces actionable `.env.yaml` hints per failure:
-  - relative URL → `"base_url is not set or empty — add base_url to <path>/.env.yaml"`
-  - URL contains `{{variable}}` → `"URL contains unresolved variable — check variable names in .env.yaml"`
-  - error message contains `"URL is invalid"` → `"URL is malformed — likely base_url is empty or invalid"`
-  - env hints take priority over generic `statusHint` (401/404/5xx)
-  - new top-level `env_issue` field when ALL failures share the same env problem category
-  - env file path resolved from `collection.base_dir` — agent sees the exact file to edit
-- **`run_tests` MCP**: always suggests `manage_server(action: 'start')` in `hints` after a run
-- **`generate_tests_guide` / `generate_missing_tests` descriptions**: mention `manage_server` as the next step after saving and running tests
+- **Seed values in smoke path params** — GET smoke steps with path parameters now use concrete seed
+  values (from spec `example` field, or `1` for id-like params) instead of unresolved `{{id}}`
+  placeholders that cause failures at runtime.
 
-## [Unreleased]
+- **Bounded integer generation** — `integer` fields with a `maximum` constraint now generate a
+  concrete in-range value instead of `{{$randomInt}}`, which could exceed server-side validation
+  limits.
 
-### Removed
+- **ETag auto-injection** — when an endpoint has `412` in its responses or an `If-Match` header
+  parameter, the CRUD generator automatically inserts a GET capture step before PUT/PATCH/DELETE
+  to capture the ETag, and adds the `If-Match: "{{resource_etag}}"` header to the mutation step.
 
-- **AI subsystem** — removed `ai-generate` CLI, `chat` CLI, AI agent loop, LLM client, TUI chat UI, and all AI SDK dependencies (`ai`, `@ai-sdk/openai`, `@ai-sdk/anthropic`)
-- **CLI commands** — removed `add-api`, `init`, `collections`, `runs`, `compare`, `doctor`, `update` (available via MCP tools or unnecessary)
-- **Directories** — removed `generated/`, `examples/`, `self-tests/`, `apis/`, `docs/archive/`
-- **Files** — removed `seed-demo.ts`, `BACKLOG.md`, `docs/agent.md`
-
-### Added
-
-- **Extended YAML test format** — 12 new assertion operators, flow control, and data transforms:
-  - **Assertion operators**: `not_equals`, `not_contains`, `gte`, `lte`, `length`, `length_gt/gte/lt/lte`
-  - **Array assertions**: `each` (every element matches), `contains_item` (at least one matches), `set_equals` (order-independent comparison)
-  - **Flow control**: `skip_if` (conditional skip with expression evaluator), `retry_until` (retry with condition/max_attempts/delay_ms), `for_each` (iterate over array)
-  - **Data transforms**: `set` steps with directives — `concat`, `append`, `length`, `get`, `first`, `map_field`
-  - **Generator**: `{{$isoTimestamp}}` — ISO 8601 timestamp string
-  - **Expression evaluator**: supports `==`, `!=`, `>`, `<`, `>=`, `<=` for skip_if/retry_until conditions
-  - Guide-builder YAML cheatsheet updated with all new features
-  - Full backward compatibility — all existing tests continue to work unchanged
-
-- **MCP feedback improvements**
-  - `diagnose_failure` now includes `response_headers` in failure output (e.g. `X-Ably-ErrorMessage`)
-  - `generate_tests_guide`: annotates `any`-typed request bodies with a warning comment
-  - `generate_tests_guide`: added 204 No Content tips in Practical Tips and Common Mistakes sections
-  - `schema-utils.ts`: added `isAnySchema()` helper
-  - DB schema v6: `results.response_headers TEXT` column
-
-- **M22: MCP-first smart test generation**
-  - `generate_tests_guide` MCP tool — returns full API spec with schemas + step-by-step generation algorithm
-  - `save_test_suite` MCP tool — validates YAML and saves test files with structured error reporting
-  - `explore_api` enhanced — new `includeSchemas` parameter for full request/response body schemas
-  - `schema-utils.ts` — extracted `compressSchema()` and `formatParam()` as shared utilities
-  - Improved MCP tool descriptions with "when to use" guidance
+#### Executor
 
-### Removed
+- **`set:` on HTTP steps** — `set:` directives on regular HTTP steps are now evaluated before the
+  request, pinning generators (e.g., `$uuid`) once so the same value can flow into the request body
+  and be reused in subsequent steps.
+
+#### Setup suites
+
+- **Auth token auto-sharing** — `setup: true` flag on a suite causes it to run before all other
+  suites (sequentially). Its captured variables (e.g., `auth_token`) are merged into the environment
+  of every subsequent suite automatically. Generated auth suites now include `setup: true`.
+
+#### Export
+
+- **`zond export postman`** — converts YAML test suites to Postman Collection v2.1 JSON.
+  - Full assertion mapping: `status`, `body`, `headers`, `duration` → `pm.test()`/`pm.expect()`
+  - Captures → `pm.environment.set()` for cross-request variable sharing
+  - `set:` steps → `pm.environment.set()` pre-request scripts on the next HTTP step
+  - `skip_if` → `pm.execution.setNextRequest()` pre-request event
+  - Optional `--env` flag exports `.env.yaml` as a Postman Environment JSON
+  - `each`, `contains_item`, `set_equals` assertions fully translated
+  - `type: integer` → `Number.isInteger()` (not `.be.a('number')`)
+  - Setup suites sorted first to mirror zond runner behaviour
+  - Newman CLI hints embedded in collection description for non-default configs
+
+#### Sync
+
+- **`zond sync`** — incremental test update command. Compares the current spec against the hash
+  stored in `.zond-meta.json`, generates test files only for new endpoints, never overwrites
+  existing files. Reports removed endpoints as warnings. Updates `collections.openapi_spec` in
+  SQLite automatically.
+
+- **`.zond-meta.json`** — metadata file written by `zond generate` and `zond sync`. Stores
+  spec URL, SHA-256 hash, and per-file metadata for drift detection.
+
+#### Diagnostics
+
+- **`recommended_action`** field on every failure in `zond db diagnose --json`:
+  `report_backend_bug` / `fix_auth_config` / `fix_test_logic` / `fix_network_config`.
+
+- **`agent_directive`** top-level field — when `api_error` count > 0, tells the agent explicitly
+  to stop iterating and report the server bug instead of modifying test expectations.
 
-- `list_environments` MCP tool — duplicated by `manage_environment(action: "list")`
+- **`cascade_skips`** field — groups skipped tests by the missing capture variable, making
+  "5 tests skipped because `createCase` step failed" visible instead of a flat skip list.
+
+- **`auth_hint`** — surfaces when ≥30% of tests fail with 401/403, and now mentions
+  `setup: true` as the recommended fix.
+
+- **Soft delete hint** — when a GET returns `200` with a `status`/`state`/`deleted` field instead
+  of the expected `404` (after a DELETE), the diagnostic now surfaces a "likely soft delete" hint
+  with a concrete suggestion to assert the status field value.
 
 ---
 
-## [0.3.0] - Unreleased (post-M21)
+### Fixes
 
-### Added
+#### Parser / runtime
 
-- **Environment management in WebUI** — full CRUD for environments (`/environments`)
-- **Key-value editor** — add/remove variables with inline JavaScript
-- **Environment selector** — `<select name="env">` dropdown in collection "Run Tests" form
-- **DB queries** — `getEnvironmentById()`, `deleteEnvironment()`, `listEnvironmentRecords()`
-- **Navigation** — "Environments" link in navbar
-- **Improved runs filter** — environment dropdown merges defined environments + run history
-- **Self-documented API** — routes use `@hono/zod-openapi`, `GET /api/openapi.json` serves spec
-- **Incremental generation** — `apitool generate` skips already-covered endpoints
-- **Dogfooding** — integration tests run against apitool's own API
-- **Generator: `additionalProperties`** — Record types generate sample key-value pairs instead of `{}`
-- **CI: typecheck** — `tsc --noEmit` step added to CI pipeline
+- **`expect.headers` now accepts `AssertionRule`** — headers can use `capture:`, `equals:`,
+  `type:`, etc. (previously only plain string equality). Enables ETag and other header captures.
 
-### Changed
+- **`filePath` normalized to absolute** — `yaml-parser.ts` now stores absolute paths so
+  `multipart: file:` paths resolve correctly regardless of CWD at execution time.
 
-- **Auth-flow test** — rewritten with inline OpenAPI server (no external `test-server/` dependency)
+- **`multipart:` bodies now reach the HTTP client** — `formData` field added to `HttpRequest`;
+  `http-client.ts` sends `formData` when present (previously only `body` was sent, so multipart
+  requests were sent empty).
 
-### Removed
+- **`multipart:` variable substitution** — `substituteStep` now processes `multipart:` field
+  values, so `{{variables}}` inside multipart blocks are interpolated correctly.
 
-- **`test-server/`** — replaced by inline test servers in integration tests
-- **Duplicate spec files** — `openapi-self.json`, `self-tests-spec.json` removed from project root
+- **Safe mode preserves auth endpoints** — `execute-run.ts` safe mode now keeps
+  `login`/`token`/`oauth` endpoints consistent with `run.ts` behaviour.
 
-### Fixed
+#### Generator data quality
 
-- **Type errors** — `z.coerce.number()` in schemas, `c.body()` return type in export route
-- **Environments CRUD skeleton** — `variables` field now generates test data correctly
+- **Nested object serialization** — `serializeValue` in `serializer.ts` now recurses into objects
+  instead of calling `String(val)`, fixing `[object Object]` in array item bodies.
 
-## [0.1.0] - 2025-02-27
+- **`format: date`** returns `"2025-01-01"` (date-only), not a full datetime string.
 
-Initial public release.
+- **`format: uuid`** overrides type — `integer` fields with `format: uuid` now correctly get
+  `{{$uuid}}` instead of `{{$randomInt}}`.
 
-### Features
+#### Skill / documentation
+
+- **SKILL.md NEVER rules** — added explicit stop rules for: in-memory auth tokens, ETag, soft
+  delete, rate limits, setup suite design, `--tag` without setup tag.
+
+- **SKILL.md generator smart behaviors** — documents all generator improvements so agents know
+  what to expect from generated output.
+
+---
+
+### Removed
+
+- `src/mcp/` and all MCP tooling (~1900 lines deleted)
+- `zond mcp` CLI command
+- `@modelcontextprotocol/sdk` dependency
+- `zond migrate` command and `src/core/migrations/` module
+- `docs/mcp-guide.md`
+
+---
 
-- **YAML test definitions** — declarative API tests with steps, assertions, variables, and captures
-- **Test runner** — sequential HTTP execution with variable substitution, chained captures, and configurable timeouts
-- **Assertions** — status code, JSON body (exact, contains, path), headers, response time
-- **Environment files** — `.env.<name>.yaml` for per-environment variables (base URLs, tokens, etc.)
-- **OpenAPI test generator** — generate skeleton YAML tests from OpenAPI 3.x specs (CRUD operations, auth-aware)
-- **AI-powered test generation** — generate tests using LLM providers (Ollama, OpenAI, Anthropic, custom)
-- **Reporters** — console (colored), JSON, JUnit XML output formats
-- **SQLite storage** — persist test runs, results, and collections in `apitool.db`
-- **WebUI dashboard** — Hono + HTMX web interface with:
-  - Health strip: coverage donut, pass/fail/skip stats, progress bar
-  - Endpoints tab: spec endpoints with coverage status and warning badges
-  - Suites tab: test files with step-level results, assertions, captures
-  - Runs tab: paginated history with drill-down and JUnit/JSON export
-- **CLI commands**:
-  - `apitool run <path>` — execute tests with env, reporter, timeout, bail options
-  - `apitool validate <path>` — validate YAML test files
-  - `apitool generate --from <spec>` — generate tests from OpenAPI
-  - `apitool ai-generate --from <spec> --prompt "..."` — AI test generation
-  - `apitool serve` — start web dashboard
-  - `apitool collections` — list test collections
-- **Multi-auth support** — Basic, Bearer, API Key auth in CLI (`--auth-token`) and WebUI
-- **Standalone binary** — single-file executable via `bun build --compile`
+### Tests
+
+- 502 tests total (499 unit + 3 mocked), 0 failures
+- New tests: `suite-generator` — reset tag, smoke seeds, logout filter, ETag injection, multipart
+- New tests: `data-factory` — maximum constraint, `generateMultipartFromSchema`
+- New tests: `serializer` — nested object serialization, `setup: true`
+- New tests: `failure-hints` — soft delete hint, `recommended_action`, `classifyFailure`
+- New tests: `executor` — header capture, `set:` pinning, setup capture propagation
+- New tests: `schema` — `setup: true` round-trip
+- Fixed: `mock.module()` cache pollution — coverage tests moved to `tests/mocked/coverage.ts`
+  and run in a separate subprocess via `scripts/run-mocked-tests.ts` (bun#7823, bun#12823)
+- Fixed: `test:unit` script — added `tests/diagnostics/`, corrected `tests/web/` and
+  `tests/reporter/` paths

package/README.md

@@ -17,16 +17,10 @@ Zond reads your OpenAPI spec and gives your AI agent everything it needs to test
 
 Then say: _"Safely cover the API from openapi.json with tests"_
 
-You get skills, slash commands, and 12 MCP tools in one package.
+You get auto-validation hooks and CLI tools — all in one package.
 
 <details>
-<summary>Other installation methods (MCP, CLI, binary)</summary>
-
-### MCP Server (Cursor, Windsurf, other editors)
-
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zond&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraXJyb3NoL3pvbmQiLCJtY3AiXX0K)
-
-Or add manually — see [MCP setup guide](docs/mcp-guide.md) for Cursor, Claude Code, and Windsurf config.
+<summary>Other installation methods (CLI, binary)</summary>
 
 ### CLI / Binary
 
@@ -75,8 +69,7 @@ Claude Code can write pytest from scratch — but it takes 30-60 minutes per flo
 
 ## Documentation
 
-- [ZOND.md](ZOND.md) — full CLI and MCP tools reference
-- [docs/mcp-guide.md](docs/mcp-guide.md) — MCP agent workflow guide
+- [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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.14.0",
+  "version": "0.17.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
@@ -26,12 +26,13 @@
   "scripts": {
     "zond": "bun run src/cli/index.ts",
     "test": "bun run test:unit && bun run test:mocked",
-    "test:unit": "bun test tests/db/ tests/parser/ tests/runner/ tests/generator/ tests/core/ tests/cli/args.test.ts tests/cli/ci-init.test.ts tests/cli/commands.test.ts tests/cli/safe-run.test.ts tests/integration/ tests/web/ tests/mcp/tools.test.ts tests/mcp/save-test-suite.test.ts tests/reporter/ tests/version-sync.test.ts",
+    "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/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: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 .claude-plugin/marketplace.json"
+    "postversion": "bun run scripts/sync-version.ts && git add .claude-plugin/plugin.json",
+    "bench:api": "bun benchmarks/api/server.ts"
   },
   "devDependencies": {
     "@types/bun": "latest"
@@ -42,7 +43,6 @@
   "dependencies": {
     "@humanwhocodes/momoa": "^2.0.3",
     "@hono/zod-openapi": "^1.2.2",
-    "@modelcontextprotocol/sdk": "^1.27.1",
     "@readme/openapi-parser": "^5.5.0",
     "hono": "^4.12.2",
     "openapi-types": "^12.1.3",

package/src/cli/commands/ci-init.ts

@@ -1,11 +1,13 @@
 import { resolve, dirname } from "path";
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { printSuccess, printError } from "../output.ts";
+import { jsonOk, printJson } from "../json-envelope.ts";
 
 export interface CiInitOptions {
   platform?: "github" | "gitlab";
   force: boolean;
   dir?: string;
+  json?: boolean;
 }
 
 const GH_ACTIONS_TEMPLATE = `name: API Tests
@@ -155,7 +157,16 @@ export async function ciInitCommand(options: CiInitOptions): Promise<number> {
     created = writeIfMissing(targetPath, GITLAB_CI_TEMPLATE, options.force);
   }
 
-  if (created) {
+  if (options.json) {
+    const targetPath = platform === "github"
+      ? resolve(cwd, ".github/workflows/api-tests.yml")
+      : resolve(cwd, ".gitlab-ci.yml");
+    printJson(jsonOk("ci init", {
+      platform,
+      filePath: targetPath,
+      created,
+    }));
+  } else if (created) {
     printSuccess("CI workflow created. Commit and push to activate.");
   }
 

package/src/cli/commands/coverage.ts

@@ -2,12 +2,14 @@ import { readOpenApiSpec, extractEndpoints, scanCoveredEndpoints, filterUncovere
 import { getDb } from "../../db/schema.ts";
 import { getResultsByRunId, getRunById } from "../../db/queries.ts";
 import { printError, printSuccess } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 
 export interface CoverageOptions {
   spec: string;
   tests: string;
   failOnCoverage?: number;
   runId?: number;
+  json?: boolean;
 }
 
 const RESET = "\x1b[0m";
@@ -145,12 +147,30 @@ export async function coverageCommand(options: CoverageOptions): Promise<number>
       }
     }
 
+    if (options.json) {
+      const coveredEndpoints = allEndpoints.filter(ep => !uncovered.includes(ep)).map(ep => `${ep.method} ${ep.path}`);
+      const uncoveredEndpoints = uncovered.map(ep => `${ep.method} ${ep.path}`);
+      printJson(jsonOk("coverage", {
+        covered: coveredCount,
+        uncovered: uncovered.length,
+        total: allEndpoints.length,
+        percentage,
+        coveredEndpoints,
+        uncoveredEndpoints,
+      }));
+    }
+
     if (options.failOnCoverage !== undefined) {
       return percentage < options.failOnCoverage ? 1 : 0;
     }
     return uncovered.length > 0 ? 1 : 0;
   } catch (err) {
-    printError(err instanceof Error ? err.message : String(err));
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("coverage", [message]));
+    } else {
+      printError(message);
+    }
     return 2;
   }
 }

package/src/cli/commands/db.ts

@@ -0,0 +1,121 @@
+import { getCollections, getRuns, getRunDetail, diagnoseRun, compareRuns } from "../../core/diagnostics/db-analysis.ts";
+import { printError } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface DbOptions {
+  subcommand: string;
+  positional: string[];
+  limit?: number;
+  verbose?: boolean;
+  dbPath?: string;
+  json?: boolean;
+}
+
+export async function dbCommand(options: DbOptions): Promise<number> {
+  const { subcommand, positional, json } = options;
+
+  try {
+    switch (subcommand) {
+      case "collections": {
+        const collections = getCollections(options.dbPath);
+        if (json) {
+          printJson(jsonOk("db collections", { collections }));
+        } else {
+          if (collections.length === 0) {
+            console.log("No collections found.");
+          } else {
+            for (const c of collections) {
+              console.log(`[${(c as any).id}] ${(c as any).name} — ${(c as any).test_path ?? "no test path"}`);
+            }
+          }
+        }
+        return 0;
+      }
+
+      case "runs": {
+        const runs = getRuns(options.limit ?? 10, options.dbPath);
+        if (json) {
+          printJson(jsonOk("db runs", { runs }));
+        } else {
+          if (runs.length === 0) {
+            console.log("No runs found.");
+          } else {
+            for (const r of runs) {
+              const run = r as any;
+              const status = run.failed > 0 ? "FAIL" : "PASS";
+              console.log(`#${run.id} ${status} ${run.passed}/${run.total} passed (${run.started_at})`);
+            }
+          }
+        }
+        return 0;
+      }
+
+      case "run": {
+        const id = parseInt(positional[0] ?? "", 10);
+        if (isNaN(id)) {
+          const msg = "Missing run ID. Usage: zond db run <id>";
+          if (json) printJson(jsonError("db run", [msg]));
+          else printError(msg);
+          return 2;
+        }
+        const detail = getRunDetail(id, options.verbose, options.dbPath);
+        if (json) {
+          printJson(jsonOk("db run", detail));
+        } else {
+          console.log(JSON.stringify(detail, null, 2));
+        }
+        return 0;
+      }
+
+      case "diagnose": {
+        const id = parseInt(positional[0] ?? "", 10);
+        if (isNaN(id)) {
+          const msg = "Missing run ID. Usage: zond db diagnose <id>";
+          if (json) printJson(jsonError("db diagnose", [msg]));
+          else printError(msg);
+          return 2;
+        }
+        const result = diagnoseRun(id, options.verbose, options.dbPath);
+        if (json) {
+          printJson(jsonOk("db diagnose", result));
+        } else {
+          console.log(JSON.stringify(result, null, 2));
+        }
+        return 0;
+      }
+
+      case "compare": {
+        const idA = parseInt(positional[0] ?? "", 10);
+        const idB = parseInt(positional[1] ?? "", 10);
+        if (isNaN(idA) || isNaN(idB)) {
+          const msg = "Missing run IDs. Usage: zond db compare <idA> <idB>";
+          if (json) printJson(jsonError("db compare", [msg]));
+          else printError(msg);
+          return 2;
+        }
+        const result = compareRuns(idA, idB, options.dbPath);
+        if (json) {
+          printJson(jsonOk("db compare", result));
+        } else {
+          console.log(JSON.stringify(result, null, 2));
+        }
+        return 0;
+      }
+
+      default: {
+        const msg = `Unknown db subcommand: ${subcommand}. Available: collections, runs, run, diagnose, compare`;
+        if (json) printJson(jsonError("db", [msg]));
+        else printError(msg);
+        return 2;
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (json) {
+      printJson(jsonError(`db ${subcommand}`, [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/describe.ts

@@ -0,0 +1,60 @@
+import { describeEndpoint, describeCompact } from "../../core/generator/describe.ts";
+import { printError } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface DescribeOptions {
+  specPath: string;
+  method?: string;
+  path?: string;
+  compact?: boolean;
+  json?: boolean;
+}
+
+export async function describeCommand(options: DescribeOptions): Promise<number> {
+  try {
+    if (options.compact) {
+      const endpoints = await describeCompact(options.specPath);
+
+      if (options.json) {
+        printJson(jsonOk("describe", { endpoints }));
+      } else {
+        for (const ep of endpoints) {
+          const parts = [ep.method.padEnd(7), ep.path];
+          if (ep.operationId) parts.push(`(${ep.operationId})`);
+          if (ep.summary) parts.push(`— ${ep.summary}`);
+          if (ep.deprecated) parts.push("[deprecated]");
+          console.log(parts.join(" "));
+        }
+        console.log(`\n${endpoints.length} endpoint(s)`);
+      }
+      return 0;
+    }
+
+    if (!options.method || !options.path) {
+      const msg = "Missing --method and --path. Use --compact for all endpoints, or specify --method and --path for one.";
+      if (options.json) {
+        printJson(jsonError("describe", [msg]));
+      } else {
+        printError(msg);
+      }
+      return 2;
+    }
+
+    const result = await describeEndpoint(options.specPath, options.method, options.path);
+
+    if (options.json) {
+      printJson(jsonOk("describe", result));
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("describe", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}