@kirrosh/zond 0.12.3 → 0.12.5

package/README.md

@@ -1,128 +1,83 @@
 # zond
 
-Point your AI agent at an OpenAPI spec. Get working tests in minutes. No config, no cloud, no Postman.
+AI-powered API testing for Claude Code, Cursor, and CI/CD.
 
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zond&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraXJyb3NoL3pvbmQiLCJtY3AiXX0K)
+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) -->
 
-## Claude Code Plugin
+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.
 
-Install in Claude Code:
+## Quick Start
 
 ```
 /plugin marketplace add kirrosh/zond
 /plugin install zond@zond-marketplace
 ```
 
-This gives you:
-- **17 MCP tools** for API testing (test generation, execution, diagnostics, coverage)
-- **Skills** for test generation, debugging failures, and CI setup
-- **Slash commands**: `/zond:api-test`, `/zond:api-coverage`
-
-After installation, just say: _"Safely cover the API from openapi.json with tests"_ — the agent handles everything.
-
-## Install
-
-```bash
-# Option 1: via npx (recommended — works everywhere with Node.js)
-npx -y @kirrosh/zond --version
-
-# Option 2: Binary (no Node.js required)
-# macOS / Linux
-curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
-
-# Windows
-iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex
-```
+Then say: _"Safely cover the API from openapi.json with tests"_
 
-[All releases](https://github.com/kirrosh/zond/releases) (Linux x64, macOS ARM, Windows x64)
-
-## MCP Setup (Cursor / Claude Code / Windsurf)
-
-Click the badge above, or add manually:
-
-```json
-{
-  "mcpServers": {
-    "zond": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@kirrosh/zond@latest",
-        "mcp",
-        "--dir",
-        "${workspaceFolder}"
-      ]
-    }
-  }
-}
-```
+You get skills, slash commands, and 12 MCP tools in one package.
 
-> `@latest` ensures npx always pulls the newest version on each restart — no manual update needed.
+<details>
+<summary>Other installation methods (MCP, CLI, binary)</summary>
 
-**Where to put this:**
+### MCP Server (Cursor, Windsurf, other editors)
 
-| Editor      | Config file                                           |
-| ----------- | ----------------------------------------------------- |
-| Cursor      | Settings > MCP, or `.cursor/mcp.json` in project root |
-| Claude Code | `.mcp.json` in project root                           |
-| Windsurf    | `.windsurfrules/mcp.json` or settings                 |
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zond&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraXJyb3NoL3pvbmQiLCJtY3AiXX0K)
 
-## Main Flow (5 steps)
+Or add manually — see [MCP setup guide](docs/mcp-guide.md) for Cursor, Claude Code, and Windsurf config.
 
-Once MCP is connected, ask your AI agent to cover your API with tests:
+### CLI / Binary
 
-**1. Register your API**
+```bash
+npx -y @kirrosh/zond --version
 
-```
-setup_api(name: "myapi", specPath: "openapi.json")
+# 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
 ```
 
-**2. Generate a test guide** (agent reads OpenAPI + gets instructions)
-
-```
-generate_and_save(specPath: "openapi.json")
-```
+See [ZOND.md](ZOND.md) for full CLI reference.
 
-For large APIs (>30 endpoints), auto-chunks by tags and returns a plan. Call with `tag` for each chunk.
+</details>
 
-**3. Save test suites** (agent writes YAML based on the guide)
+## What Happens
 
-```
-save_test_suite(filePath: "apis/myapi/tests/smoke.yaml", content: "...")
-```
+1. **Point** — you give the agent an OpenAPI spec
+2. **Generate** — zond reads the spec, produces YAML test suites (smoke + CRUD)
+3. **Run** — tests execute, failures are diagnosed, coverage is tracked
 
-**4. Run tests**
+The agent does all three steps autonomously. It asks you only when it needs an auth token or permission to run write operations.
 
-```
-run_tests(testPath: "apis/myapi/tests/", safe: true)
-```
+## Why Not Just Ask Claude to Write pytest?
 
-**5. Diagnose failures**
+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.
 
-```
-query_db(action: "diagnose_failure", runId: 42)
-```
+## Key Capabilities
 
-Or just say: _"Safely cover the API from openapi.json with tests"_ — the agent will do all 5 steps.
+| | |
+|---|---|
+| **Safe by Default** | `--safe` runs only GET requests. `--dry-run` previews without sending. The agent never touches production data without your explicit approval. |
+| **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. |
+| **CI-Ready** | One command generates GitHub Actions or GitLab CI workflow. Tests in YAML, in git, with code review. |
 
-## CLI
+## Try It
 
 ```
-zond run <path>           Run tests (--env, --safe, --tag, --dry-run, --env-var, --report)
-zond add-api <name>       Register API (--spec <openapi>)
-zond coverage             API test coverage (--spec, --tests, --fail-on-coverage)
-zond compare <runA> <runB> Compare two test runs
-zond serve                Web dashboard with health strip + endpoints/suites/runs tabs (--port 8080)
-zond mcp                  Start MCP server
-zond chat                 AI chat agent (--provider ollama|openai|anthropic)
-zond doctor               Diagnostics
+"Cover openapi.json with tests"
+"Run only smoke tests against staging"
+"What broke since last run?"
+"Set up CI for API tests"
 ```
 
 ## Documentation
 
-- [docs/quickstart.md](docs/quickstart.md) — step-by-step quickstart guide (RU)
 - [ZOND.md](ZOND.md) — full CLI and MCP tools reference
 - [docs/mcp-guide.md](docs/mcp-guide.md) — MCP agent workflow guide
+- [docs/quickstart.md](docs/quickstart.md) — step-by-step quickstart (RU)
 - [docs/ci.md](docs/ci.md) — CI/CD integration
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",

package/src/core/generator/suite-generator.ts

@@ -24,7 +24,7 @@ function escapeRegex(s: string): string {
 function getExpectedStatus(ep: EndpointInfo): number {
   const success = ep.responses.find(r => r.statusCode >= 200 && r.statusCode < 300);
   if (success) return success.statusCode;
-  if (ep.responses.length > 0) return ep.responses[0].statusCode;
+  if (ep.responses.length > 0) return ep.responses[0]!.statusCode;
   return 200;
 }
 
@@ -182,10 +182,10 @@ export function detectCrudGroups(endpoints: EndpointInfo[]): CrudGroup[] {
 
     if (itemEndpoints.length === 0) continue;
 
-    const itemPath = itemEndpoints[0].path;
+    const itemPath = itemEndpoints[0]!.path;
     const idMatch = itemPath.match(/\{([^}]+)\}$/);
     if (!idMatch) continue;
-    const idParam = idMatch[1];
+    const idParam = idMatch[1]!;
 
     const read = itemEndpoints.find(ep => ep.method.toUpperCase() === "GET");
     if (!read) continue; // Minimum: POST + GET/{id}
@@ -316,7 +316,7 @@ export function findUnresolvedVars(suite: RawSuite, envKeys?: Set<string>): stri
   const scan = (obj: unknown) => {
     if (typeof obj === "string") {
       for (const m of obj.matchAll(/\{\{([^$}][^}]*)\}\}/g)) {
-        if (!KNOWN.has(m[1]) && !captured.has(m[1])) vars.add(m[1]);
+        if (!KNOWN.has(m[1]!) && !captured.has(m[1]!)) vars.add(m[1]!);
       }
     } else if (obj && typeof obj === "object") {
       for (const v of Object.values(obj)) scan(v);

package/src/mcp/tools/generate-and-save.ts

@@ -101,7 +101,7 @@ export function registerGenerateAndSaveTool(server: McpServer) {
             (effectiveMode === "guide"
               ? `Pass includeFormat: false for subsequent chunks to save tokens. `
               : "") +
-            `Example: generate_and_save(specPath: '${specPath}', tag: '${plan.chunks[0].tag}'` +
+            `Example: generate_and_save(specPath: '${specPath}', tag: '${plan.chunks[0]!.tag}'` +
             (effectiveMode === "guide" ? `, mode: 'guide'` : "") + `)`,
         };
         if (coverageInfo) {