@kirrosh/zond 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.7.0] — Renamed to zond
+
+- 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)
+
+## [0.6.1] - 2026-03-04
+
+### Changed
+
+- **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
+
+- Slim npm package — non-essential files excluded via `files` field in package.json
+
+## [0.5.4] - 2026-03-03
+
+### Fixed
+
+- **`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"`
+
+### Added
+
+- **`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
+
+## [Unreleased]
+
+### Added
+
+- **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
+
+### Removed
+
+- `list_environments` MCP tool — duplicated by `manage_environment(action: "list")`
+
+---
+
+## [0.3.0] - Unreleased (post-M21)
+
+### Added
+
+- **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
+
+### Changed
+
+- **Auth-flow test** — rewritten with inline OpenAPI server (no external `test-server/` dependency)
+
+### Removed
+
+- **`test-server/`** — replaced by inline test servers in integration tests
+- **Duplicate spec files** — `openapi-self.json`, `self-tests-spec.json` removed from project root
+
+### Fixed
+
+- **Type errors** — `z.coerce.number()` in schemas, `c.body()` return type in export route
+- **Environments CRUD skeleton** — `variables` field now generates test data correctly
+
+## [0.1.0] - 2025-02-27
+
+Initial public release.
+
+### Features
+
+- **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`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 apitool contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @kirrosh/zond
+
+Point your AI agent at an OpenAPI spec. Get working tests in minutes. No config, no cloud, no Postman.
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zond&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBraXJyb3NoL3pvbmQiLCJtY3AiXX0K)
+
+## Claude Code Plugin
+
+Install in Claude Code:
+
+```
+/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
+```
+
+[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}"
+      ]
+    }
+  }
+}
+```
+
+> `@latest` ensures npx always pulls the newest version on each restart — no manual update needed.
+
+**Where to put this:**
+
+| 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                 |
+
+## Main Flow (5 steps)
+
+Once MCP is connected, ask your AI agent to cover your API with tests:
+
+**1. Register your API**
+
+```
+setup_api(name: "myapi", specPath: "openapi.json")
+```
+
+**2. Generate a test guide** (agent reads OpenAPI + gets instructions)
+
+```
+generate_and_save(specPath: "openapi.json")
+```
+
+For large APIs (>30 endpoints), auto-chunks by tags and returns a plan. Call with `tag` for each chunk.
+
+**3. Save test suites** (agent writes YAML based on the guide)
+
+```
+save_test_suite(filePath: "apis/myapi/tests/smoke.yaml", content: "...")
+```
+
+**4. Run tests**
+
+```
+run_tests(testPath: "apis/myapi/tests/", safe: true)
+```
+
+**5. Diagnose failures**
+
+```
+query_db(action: "diagnose_failure", runId: 42)
+```
+
+Or just say: _"Safely cover the API from openapi.json with tests"_ — the agent will do all 5 steps.
+
+## CLI
+
+```
+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
+```
+
+## 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/ci.md](docs/ci.md) — CI/CD integration
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kirrosh/zond",
+  "version": "0.7.0",
+  "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
+  "license": "MIT",
+  "module": "index.ts",
+  "type": "module",
+  "keywords": [
+    "api",
+    "testing",
+    "openapi",
+    "yaml",
+    "cli",
+    "rest",
+    "http"
+  ],
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "zond": "src/cli/index.ts"
+  },
+  "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/chat.test.ts tests/cli/ci-init.test.ts tests/cli/commands.test.ts tests/cli/doctor.test.ts tests/cli/init.test.ts tests/cli/runs.test.ts tests/cli/safe-run.test.ts tests/cli/update.test.ts tests/integration/ tests/web/ tests/mcp/tools.test.ts tests/mcp/save-test-suite.test.ts tests/agent/agent-loop.test.ts tests/agent/context-manager.test.ts tests/agent/system-prompt.test.ts tests/reporter/",
+    "test:mocked": "bun run scripts/run-mocked-tests.ts",
+    "test:ai": "bun test tests/ai/",
+    "check": "tsc --noEmit --project tsconfig.json",
+    "build": "bun build --compile src/cli/index.ts --outfile zond"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@humanwhocodes/momoa": "^2.0.3",
+    "@ai-sdk/anthropic": "^2",
+    "@ai-sdk/openai": "^2",
+    "@hono/zod-openapi": "^1.2.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@readme/openapi-parser": "^5.5.0",
+    "ai": "^6",
+    "hono": "^4.12.2",
+    "openapi-types": "^12.1.3",
+    "zod": "^4.3.6"
+  }
+}

package/src/bun-types.d.ts

@@ -0,0 +1,5 @@
+declare module "*.css" {
+  const path: string;
+  export default path;
+}
+

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

@@ -0,0 +1,51 @@
+import { setupApi } from "../../core/setup-api.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface AddApiOptions {
+  name: string;
+  spec?: string;
+  dir?: string;
+  envPairs?: string[];
+  dbPath?: string;
+}
+
+export async function addApiCommand(options: AddApiOptions): Promise<number> {
+  const { name, spec, envPairs, dbPath, dir } = options;
+
+  // Parse --env key=value pairs into a record
+  const envVars: Record<string, string> = {};
+  if (envPairs) {
+    for (const pair of envPairs) {
+      const idx = pair.indexOf("=");
+      if (idx === -1) continue;
+      const key = pair.slice(0, idx).trim();
+      const value = pair.slice(idx + 1).trim();
+      if (key) envVars[key] = value;
+    }
+  }
+
+  try {
+    const result = await setupApi({
+      name,
+      spec,
+      dir,
+      envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
+      dbPath,
+    });
+
+    printSuccess(`API '${name}' created (id=${result.collectionId})`);
+    console.log(`  Directory: ${result.testPath.replace(/\/tests$/, "")}`);
+    console.log(`  Tests:     ${result.testPath}/`);
+    if (spec) console.log(`  Spec:      ${spec}`);
+    if (result.baseUrl) console.log(`  Base URL:  ${result.baseUrl}`);
+    console.log();
+    console.log("Next steps:");
+    console.log(`  zond ai-generate --api ${name} --prompt "test the user endpoints"`);
+    console.log(`  zond run --api ${name}`);
+
+    return 0;
+  } catch (err) {
+    printError((err as Error).message);
+    return 1;
+  }
+}

package/src/cli/commands/ai-generate.ts

@@ -0,0 +1,106 @@
+import { resolve, dirname } from "path";
+import { generateWithAI } from "../../core/generator/ai/ai-generator.ts";
+import { resolveProviderConfig } from "../../core/generator/ai/types.ts";
+import type { AIProviderConfig } from "../../core/generator/ai/types.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface AIGenerateCommandOptions {
+  from: string;
+  prompt: string;
+  provider: string;
+  model?: string;
+  apiKey?: string;
+  baseUrl?: string;
+  output?: string;
+}
+
+export async function aiGenerateCommand(options: AIGenerateCommandOptions): Promise<number> {
+  try {
+    const providerName = options.provider as AIProviderConfig["provider"];
+    if (!["ollama", "openai", "anthropic", "custom"].includes(providerName)) {
+      printError(`Unknown provider: ${options.provider}. Use: ollama, openai, anthropic, custom`);
+      return 2;
+    }
+
+    const provider = resolveProviderConfig({
+      provider: providerName,
+      model: options.model,
+      baseUrl: options.baseUrl,
+      apiKey: options.apiKey ?? process.env.ZOND_AI_KEY,
+    });
+
+    console.log(`Provider: ${provider.provider} (${provider.model})`);
+    console.log(`Spec: ${options.from}`);
+    console.log(`Prompt: ${options.prompt}`);
+    console.log(`Generating...`);
+
+    const startTime = Date.now();
+    const result = await generateWithAI({
+      specPath: options.from,
+      prompt: options.prompt,
+      provider,
+    });
+    const durationMs = Date.now() - startTime;
+
+    console.log(`Done in ${(durationMs / 1000).toFixed(1)}s (model: ${result.model})`);
+    if (result.promptTokens) {
+      console.log(`Tokens: ${result.promptTokens} prompt + ${result.completionTokens} completion`);
+    }
+
+    // Write output
+    const outputDir = options.output ?? "./generated/ai/";
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(outputDir, { recursive: true });
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const fileName = `ai-generated-${timestamp}.yaml`;
+    const filePath = resolve(outputDir, fileName);
+
+    await Bun.write(filePath, result.yaml);
+    printSuccess(`Written: ${filePath}`);
+
+    // Auto-create collection if DB is available
+    try {
+      const { getDb } = await import("../../db/schema.ts");
+      getDb();
+      const { findCollectionByTestPath, findCollectionBySpec, createCollection, normalizePath, saveAIGeneration } = await import("../../db/queries.ts");
+      const { resolveSpecPath } = await import("../../core/generator/serializer.ts");
+      const normalizedOutput = normalizePath(outputDir);
+      const resolvedSpec = resolveSpecPath(options.from);
+
+      let collectionId: number | undefined;
+      const existing = findCollectionByTestPath(normalizedOutput) ?? findCollectionBySpec(resolvedSpec);
+      if (existing) {
+        collectionId = existing.id;
+      } else {
+        const specName = `AI Tests (${new Date().toLocaleDateString()})`;
+        collectionId = createCollection({
+          name: specName,
+          test_path: normalizedOutput,
+          openapi_spec: resolvedSpec,
+        });
+        printSuccess(`Created collection "${specName}" (id: ${collectionId})`);
+      }
+
+      saveAIGeneration({
+        collection_id: collectionId,
+        prompt: options.prompt,
+        model: result.model,
+        provider: providerName,
+        generated_yaml: result.yaml,
+        output_path: filePath,
+        status: "success",
+        prompt_tokens: result.promptTokens,
+        completion_tokens: result.completionTokens,
+        duration_ms: durationMs,
+      });
+    } catch {
+      // DB not critical
+    }
+
+    return 0;
+  } catch (err) {
+    printError(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+}

package/src/cli/commands/chat.ts

@@ -0,0 +1,43 @@
+import { resolveProviderConfig, PROVIDER_DEFAULTS } from "../../core/generator/ai/types.ts";
+import type { AIProviderConfig } from "../../core/generator/ai/types.ts";
+import { printError } from "../output.ts";
+
+export interface ChatCommandOptions {
+  provider?: string;
+  model?: string;
+  apiKey?: string;
+  baseUrl?: string;
+  safe?: boolean;
+  dbPath?: string;
+}
+
+const VALID_PROVIDERS = new Set(["ollama", "openai", "anthropic", "custom"]);
+
+export async function chatCommand(options: ChatCommandOptions): Promise<number> {
+  const providerName = options.provider ?? "ollama";
+
+  if (!VALID_PROVIDERS.has(providerName)) {
+    printError(`Unknown provider: ${providerName}. Available: ollama, openai, anthropic, custom`);
+    return 2;
+  }
+
+  const providerConfig = resolveProviderConfig({
+    provider: providerName as AIProviderConfig["provider"],
+    model: options.model,
+    apiKey: options.apiKey ?? process.env["ZOND_AI_KEY"],
+    baseUrl: options.baseUrl,
+  });
+
+  try {
+    const { startChatUI } = await import("../../tui/chat-ui.ts");
+    await startChatUI({
+      provider: providerConfig,
+      safeMode: options.safe,
+      dbPath: options.dbPath,
+    });
+    return 0;
+  } catch (err) {
+    printError(`Chat error: ${(err as Error).message}`);
+    return 2;
+  }
+}