@kirrosh/zond 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
@@ -37,6 +37,9 @@
   "devDependencies": {
     "@types/bun": "latest"
   },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
   "peerDependencies": {
     "typescript": "^5"
   },

package/src/cli/commands/coverage.ts

@@ -50,6 +50,10 @@ export async function coverageCommand(options: CoverageOptions): Promise<number>
     const color = useColor();
 
     // Enriched mode with run results
+    let passing = 0;
+    let apiError = 0;
+    let testFailed = 0;
+
     if (options.runId != null) {
       getDb();
       const run = getRunById(options.runId);
@@ -88,62 +92,63 @@ export async function coverageCommand(options: CoverageOptions): Promise<number>
         }
       }
 
-      let passing = 0;
-      let apiError = 0;
-      let testFailed = 0;
       for (const status of endpointStatus.values()) {
         if (status === "passing") passing++;
         else if (status === "api_error") apiError++;
         else if (status === "test_failed") testFailed++;
       }
+    }
 
-      console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%) — Run #${options.runId}`);
-      console.log("");
+    if (!options.json) {
+      if (options.runId != null) {
+        console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%) — Run #${options.runId}`);
+        console.log("");
 
-      if (passing > 0) {
-        console.log(`  ${color ? GREEN : ""}✅ ${passing} covered and passing${color ? RESET : ""}`);
-      }
-      if (apiError > 0) {
-        console.log(`  ${color ? YELLOW : ""}⚠️  ${apiError} covered but returning 5xx (possibly broken API)${color ? RESET : ""}`);
-      }
-      if (testFailed > 0) {
-        console.log(`  ${color ? RED : ""}❌ ${testFailed} covered, test assertions failed${color ? RESET : ""}`);
-      }
-      if (uncovered.length > 0) {
-        console.log(`  ${color ? DIM : ""}⬜ ${uncovered.length} not covered${color ? RESET : ""}`);
-      }
-    } else {
-      // Standard mode
-      console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%)`);
-      console.log("");
+        if (passing > 0) {
+          console.log(`  ${color ? GREEN : ""}✅ ${passing} covered and passing${color ? RESET : ""}`);
+        }
+        if (apiError > 0) {
+          console.log(`  ${color ? YELLOW : ""}⚠️  ${apiError} covered but returning 5xx (possibly broken API)${color ? RESET : ""}`);
+        }
+        if (testFailed > 0) {
+          console.log(`  ${color ? RED : ""}❌ ${testFailed} covered, test assertions failed${color ? RESET : ""}`);
+        }
+        if (uncovered.length > 0) {
+          console.log(`  ${color ? DIM : ""}⬜ ${uncovered.length} not covered${color ? RESET : ""}`);
+        }
+      } else {
+        // Standard mode
+        console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%)`);
+        console.log("");
 
-      // Covered endpoints
-      if (coveredCount > 0) {
-        console.log(`${color ? GREEN : ""}Covered:${color ? RESET : ""}`);
-        for (const ep of allEndpoints) {
-          if (!uncovered.includes(ep)) {
-            console.log(`  ${color ? GREEN : ""}✓${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+        // Covered endpoints
+        if (coveredCount > 0) {
+          console.log(`${color ? GREEN : ""}Covered:${color ? RESET : ""}`);
+          for (const ep of allEndpoints) {
+            if (!uncovered.includes(ep)) {
+              console.log(`  ${color ? GREEN : ""}✓${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+            }
           }
+          console.log("");
         }
-        console.log("");
-      }
 
-      // Uncovered endpoints
-      if (uncovered.length > 0) {
-        console.log(`${color ? RED : ""}Uncovered:${color ? RESET : ""}`);
-        for (const ep of uncovered) {
-          console.log(`  ${color ? RED : ""}✗${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+        // Uncovered endpoints
+        if (uncovered.length > 0) {
+          console.log(`${color ? RED : ""}Uncovered:${color ? RESET : ""}`);
+          for (const ep of uncovered) {
+            console.log(`  ${color ? RED : ""}✗${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+          }
         }
       }
-    }
 
-    // Static warnings (always shown)
-    const warnings = analyzeEndpoints(allEndpoints);
-    if (warnings.length > 0) {
-      console.log("");
-      console.log(`${color ? YELLOW : ""}Spec warnings:${color ? RESET : ""}`);
-      for (const w of warnings) {
-        console.log(`  ${color ? YELLOW : ""}⚠${color ? RESET : ""} ${w.method.padEnd(7)} ${w.path}: ${w.warnings.join(", ")}`);
+      // Static warnings (always shown in human-readable mode)
+      const warnings = analyzeEndpoints(allEndpoints);
+      if (warnings.length > 0) {
+        console.log("");
+        console.log(`${color ? YELLOW : ""}Spec warnings:${color ? RESET : ""}`);
+        for (const w of warnings) {
+          console.log(`  ${color ? YELLOW : ""}⚠${color ? RESET : ""} ${w.method.padEnd(7)} ${w.path}: ${w.warnings.join(", ")}`);
+        }
       }
     }
 

package/src/cli/commands/db.ts

@@ -1,4 +1,6 @@
 import { getCollections, getRuns, getRunDetail, diagnoseRun, compareRuns } from "../../core/diagnostics/db-analysis.ts";
+import { getFilteredResults } from "../../db/queries.ts";
+import { getDb } from "../../db/schema.ts";
 import { printError } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 
@@ -9,6 +11,8 @@ export interface DbOptions {
   verbose?: boolean;
   dbPath?: string;
   json?: boolean;
+  method?: string;
+  status?: number;
 }
 
 export async function dbCommand(options: DbOptions): Promise<number> {
@@ -58,11 +62,22 @@ export async function dbCommand(options: DbOptions): Promise<number> {
           else printError(msg);
           return 2;
         }
-        const detail = getRunDetail(id, options.verbose, options.dbPath);
-        if (json) {
-          printJson(jsonOk("db run", detail));
+        // If filtering by method/status, show filtered results instead of full detail
+        if (options.method || options.status !== undefined) {
+          getDb(options.dbPath);
+          const results = getFilteredResults(id, { method: options.method, status: options.status });
+          if (json) {
+            printJson(jsonOk("db run", { run_id: id, count: results.length, results }));
+          } else {
+            console.log(JSON.stringify({ run_id: id, count: results.length, results }, null, 2));
+          }
         } else {
-          console.log(JSON.stringify(detail, null, 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;
       }
@@ -75,7 +90,7 @@ export async function dbCommand(options: DbOptions): Promise<number> {
           else printError(msg);
           return 2;
         }
-        const result = diagnoseRun(id, options.verbose, options.dbPath);
+        const result = diagnoseRun(id, options.verbose, options.dbPath, options.limit);
         if (json) {
           printJson(jsonOk("db diagnose", result));
         } else {

package/src/cli/commands/describe.ts

@@ -1,4 +1,4 @@
-import { describeEndpoint, describeCompact } from "../../core/generator/describe.ts";
+import { describeEndpoint, describeCompact, describeAllParams } from "../../core/generator/describe.ts";
 import { printError } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 
@@ -7,11 +7,36 @@ export interface DescribeOptions {
   method?: string;
   path?: string;
   compact?: boolean;
+  listParams?: boolean;
   json?: boolean;
 }
 
 export async function describeCommand(options: DescribeOptions): Promise<number> {
   try {
+    if (options.listParams) {
+      const params = await describeAllParams(options.specPath);
+      if (options.json) {
+        printJson(jsonOk("describe", { params }));
+      } else {
+        const grouped = new Map<string, typeof params>();
+        for (const p of params) {
+          const arr = grouped.get(p.in) ?? [];
+          arr.push(p);
+          grouped.set(p.in, arr);
+        }
+        for (const [location, locationParams] of grouped) {
+          console.log(`\n${location.toUpperCase()} parameters:`);
+          for (const p of locationParams) {
+            const req = p.required ? " (required)" : "";
+            const type = p.type ? ` [${p.type}]` : "";
+            console.log(`  ${p.name}${type}${req} — used in ${p.usedBy.length} endpoint(s)`);
+          }
+        }
+        console.log(`\n${params.length} unique parameter(s)`);
+      }
+      return 0;
+    }
+
     if (options.compact) {
       const endpoints = await describeCompact(options.specPath);
 

package/src/cli/commands/generate.ts

@@ -8,9 +8,10 @@ import {
   filterUncoveredEndpoints,
   serializeSuite,
 } from "../../core/generator/index.ts";
-import { generateSuites } from "../../core/generator/suite-generator.ts";
+import { generateSuites, findUnresolvedVars } from "../../core/generator/suite-generator.ts";
 import { filterByTag } from "../../core/generator/chunker.ts";
 import { parse } from "../../core/parser/yaml-parser.ts";
+import { decycleSchema } from "../../core/generator/schema-utils.ts";
 import { printError, printSuccess } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 import { readMeta, writeMeta, hashSpec, buildFileMeta } from "../../core/meta/meta-store.ts";
@@ -82,7 +83,7 @@ export async function generateCommand(options: GenerateOptions): Promise<number>
 
     // Write .zond-meta.json (merge with existing meta to preserve info about prior files)
     const existingMeta = await readMeta(options.output);
-    const specContent = typeof doc === "object" ? JSON.stringify(doc) : String(doc);
+    const specContent = typeof doc === "object" ? JSON.stringify(decycleSchema(doc)) : String(doc);
     await writeMeta(options.output, {
       zondVersion: ZOND_VERSION,
       lastSyncedAt: new Date().toISOString(),
@@ -103,12 +104,23 @@ export async function generateCommand(options: GenerateOptions): Promise<number>
       // DB unavailable — not fatal
     }
 
-    // Create .env.yaml with base_url if it doesn't exist
+    // Create .env.yaml with base_url and unresolved variables as placeholders
     const envPath = join(options.output, ".env.yaml");
     const envFile = Bun.file(envPath);
-    if (!(await envFile.exists()) && baseUrl) {
-      await Bun.write(envPath, `base_url: ${baseUrl}\n`);
-      warnings.push(`Created ${envPath} with base_url from spec`);
+    if (!(await envFile.exists())) {
+      const unresolvedVars = new Set<string>();
+      for (const suite of suites) {
+        for (const v of findUnresolvedVars(suite)) unresolvedVars.add(v);
+      }
+      const lines: string[] = [];
+      if (baseUrl) lines.push(`base_url: ${baseUrl}`);
+      for (const v of [...unresolvedVars].sort()) {
+        lines.push(`${v}: "" # TODO: fill in`);
+      }
+      if (lines.length > 0) {
+        await Bun.write(envPath, lines.join("\n") + "\n");
+        warnings.push(`Created ${envPath} with ${unresolvedVars.size} placeholder variable(s)`);
+      }
     }
 
     // Validate generated files

package/src/cli/commands/run.ts

@@ -2,7 +2,7 @@ import { dirname } from "path";
 import { stat } from "node:fs/promises";
 import { parse } from "../../core/parser/yaml-parser.ts";
 import { loadEnvironment } from "../../core/parser/variables.ts";
-import { filterSuitesByTags } from "../../core/parser/filter.ts";
+import { filterSuitesByTags, excludeSuitesByTags, filterSuitesByMethod } from "../../core/parser/filter.ts";
 import { runSuite } from "../../core/runner/executor.ts";
 import { getReporter } from "../../core/reporter/index.ts";
 import type { ReporterName } from "../../core/reporter/types.ts";
@@ -25,6 +25,8 @@ export interface RunOptions {
   authToken?: string;
   safe?: boolean;
   tag?: string[];
+  excludeTag?: string[];
+  method?: string;
   envVars?: string[];
   dryRun?: boolean;
   json?: boolean;
@@ -54,6 +56,24 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   }
 
+  // 1b2. Exclude-tag filter
+  if (options.excludeTag && options.excludeTag.length > 0) {
+    suites = excludeSuitesByTags(suites, options.excludeTag);
+    if (suites.length === 0) {
+      printWarning("All suites excluded by --exclude-tag");
+      return 0;
+    }
+  }
+
+  // 1b3. Method filter
+  if (options.method) {
+    suites = filterSuitesByMethod(suites, options.method);
+    if (suites.length === 0) {
+      printWarning(`No tests found with method ${options.method.toUpperCase()}`);
+      return 0;
+    }
+  }
+
   // 1c. Safe mode: keep GET, set-only steps, and auth-related requests
   if (options.safe) {
     for (const suite of suites) {

package/src/cli/commands/sync.ts

@@ -10,6 +10,7 @@ import { generateSuites } from "../../core/generator/suite-generator.ts";
 import { filterByTag } from "../../core/generator/chunker.ts";
 import { readMeta, writeMeta, hashSpec, buildFileMeta } from "../../core/meta/meta-store.ts";
 import { diffEndpoints } from "../../core/sync/spec-differ.ts";
+import { decycleSchema } from "../../core/generator/schema-utils.ts";
 import { printError, printSuccess, printWarning } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 import { version as ZOND_VERSION } from "../../../package.json";
@@ -41,7 +42,7 @@ export async function syncCommand(options: SyncOptions): Promise<number> {
 
     // Load current spec
     const doc = await readOpenApiSpec(options.specPath);
-    const specContent = JSON.stringify(doc);
+    const specContent = JSON.stringify(decycleSchema(doc));
     const currentHash = hashSpec(specContent);
 
     if (currentHash === meta.specHash) {

package/src/cli/commands/update.ts

@@ -0,0 +1,189 @@
+import { VERSION } from "../index.ts";
+import { isCompiledBinary } from "../runtime.ts";
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface UpdateOptions {
+  json?: boolean;
+  check?: boolean;
+}
+
+const REPO = "kirrosh/zond";
+const GITHUB_API = `https://api.github.com/repos/${REPO}/releases/latest`;
+
+interface GitHubRelease {
+  tag_name: string;
+  assets: { name: string; browser_download_url: string }[];
+}
+
+function getTarget(): { target: string; ext: string } | null {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === "linux" && arch === "x64") return { target: "linux-x64", ext: "tar.gz" };
+  if (platform === "darwin" && arch === "arm64") return { target: "darwin-arm64", ext: "tar.gz" };
+  if (platform === "win32" && arch === "x64") return { target: "win-x64", ext: "zip" };
+  return null;
+}
+
+async function fetchLatestRelease(): Promise<GitHubRelease> {
+  const resp = await fetch(GITHUB_API, {
+    headers: { "User-Agent": `zond/${VERSION}` },
+  });
+  if (!resp.ok) {
+    throw new Error(`GitHub API returned ${resp.status}: ${resp.statusText}`);
+  }
+  return resp.json() as Promise<GitHubRelease>;
+}
+
+export async function updateCommand(options: UpdateOptions): Promise<number> {
+  try {
+    if (!isCompiledBinary()) {
+      const msg = "Self-update is only available for standalone binaries. Install binary: curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh";
+      if (options.json) {
+        printJson(jsonOk("update", { action: "skip", reason: "not-standalone", installHint: "curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh" }, [msg]));
+      } else {
+        printWarning(msg);
+      }
+      return 3;
+    }
+
+    const target = getTarget();
+    if (!target) {
+      const msg = `Unsupported platform: ${process.platform}-${process.arch}`;
+      if (options.json) {
+        printJson(jsonError("update", [msg]));
+      } else {
+        printError(msg);
+      }
+      return 2;
+    }
+
+    const release = await fetchLatestRelease();
+    const latest = release.tag_name.replace(/^v/, "");
+
+    if (latest === VERSION) {
+      const msg = `Already up to date (${VERSION})`;
+      if (options.json) {
+        printJson(jsonOk("update", { action: "none", currentVersion: VERSION, latestVersion: latest }));
+      } else {
+        console.log(msg);
+      }
+      return 0;
+    }
+
+    if (options.check) {
+      const msg = `Update available: ${VERSION} → ${latest}`;
+      if (options.json) {
+        printJson(jsonOk("update", { action: "available", currentVersion: VERSION, latestVersion: latest }));
+      } else {
+        console.log(msg);
+      }
+      return 0;
+    }
+
+    // Find the right asset
+    const assetName = `zond-${target.target}.${target.ext}`;
+    const asset = release.assets.find(a => a.name === assetName);
+    if (!asset) {
+      const msg = `Binary not found for ${target.target} in release ${release.tag_name}`;
+      if (options.json) {
+        printJson(jsonError("update", [msg]));
+      } else {
+        printError(msg);
+      }
+      return 2;
+    }
+
+    console.log(`Updating zond ${VERSION} → ${latest}...`);
+    console.log(`Downloading ${assetName}...`);
+
+    // Download the archive
+    const resp = await fetch(asset.browser_download_url, {
+      headers: { "User-Agent": `zond/${VERSION}` },
+    });
+    if (!resp.ok) {
+      throw new Error(`Download failed: ${resp.status} ${resp.statusText}`);
+    }
+    const archiveData = new Uint8Array(await resp.arrayBuffer());
+
+    const currentBinary = process.execPath;
+    const { join, dirname } = await import("path");
+    const tmpDir = join(dirname(currentBinary), `.zond-update-${Date.now()}`);
+    const { mkdir, rm, rename, chmod } = await import("fs/promises");
+    await mkdir(tmpDir, { recursive: true });
+
+    try {
+      const archivePath = join(tmpDir, assetName);
+      await Bun.write(archivePath, archiveData);
+
+      // Extract
+      if (target.ext === "tar.gz") {
+        const proc = Bun.spawn(["tar", "-xzf", archivePath, "-C", tmpDir]);
+        const exitCode = await proc.exited;
+        if (exitCode !== 0) throw new Error(`tar extraction failed (exit ${exitCode})`);
+      } else {
+        // Windows zip
+        const proc = Bun.spawn([
+          "powershell", "-NoProfile", "-Command",
+          `Expand-Archive -Path '${archivePath}' -DestinationPath '${tmpDir}' -Force`,
+        ]);
+        const exitCode = await proc.exited;
+        if (exitCode !== 0) throw new Error(`Zip extraction failed (exit ${exitCode})`);
+      }
+
+      // Find the extracted binary
+      const binaryName = process.platform === "win32" ? "zond.exe" : "zond";
+      const newBinary = join(tmpDir, binaryName);
+      const file = Bun.file(newBinary);
+      if (!await file.exists()) {
+        throw new Error(`Binary '${binaryName}' not found in archive`);
+      }
+
+      // Replace current binary
+      try {
+        if (process.platform === "win32") {
+          // Windows: rename current to .old, move new, clean up
+          const oldBinary = currentBinary + ".old";
+          try { await rm(oldBinary, { force: true }); } catch {}
+          await rename(currentBinary, oldBinary);
+          await rename(newBinary, currentBinary);
+          try { await rm(oldBinary, { force: true }); } catch {}
+        } else {
+          await rename(newBinary, currentBinary);
+          await chmod(currentBinary, 0o755);
+        }
+      } catch (replaceErr: any) {
+        if (replaceErr?.code === "EACCES" || replaceErr?.code === "EPERM") {
+          const hint = process.platform === "win32"
+            ? `Permission denied. Run the terminal as Administrator.`
+            : `Permission denied writing to ${currentBinary}. Run: sudo zond update`;
+          if (options.json) {
+            printJson(jsonError("update", [hint]));
+          } else {
+            printError(hint);
+          }
+          return 2;
+        }
+        throw replaceErr;
+      }
+
+      if (options.json) {
+        printJson(jsonOk("update", { action: "updated", previousVersion: VERSION, newVersion: latest }));
+      } else {
+        printSuccess(`Updated zond ${VERSION} → ${latest}`);
+      }
+      return 0;
+    } finally {
+      try { await rm(tmpDir, { recursive: true, force: true }); } catch {}
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("update", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/index.ts

@@ -13,6 +13,7 @@ import { guideCommand } from "./commands/guide.ts";
 import { generateCommand } from "./commands/generate.ts";
 import { exportCommand } from "./commands/export.ts";
 import { syncCommand } from "./commands/sync.ts";
+import { updateCommand } from "./commands/update.ts";
 import { printError } from "./output.ts";
 import { getRuntimeInfo } from "./runtime.ts";
 import { getDb } from "../db/schema.ts";
@@ -107,6 +108,7 @@ Usage:
   zond ci init          Generate CI/CD workflow (GitHub Actions, GitLab CI)
   zond export postman <path>  Export YAML tests as Postman Collection v2.1
   zond sync <spec>      Detect new/removed endpoints and generate tests for new ones
+  zond update           Check for updates and self-update the binary
 
 Options for 'run':
   --dry-run            Show requests without sending them (exit code always 0)
@@ -121,6 +123,8 @@ Options for 'run':
   --auth-token <token> Auth token injected as {{auth_token}} variable
   --safe               Run only GET tests (read-only, safe mode)
   --tag <tag>          Filter suites by tag (repeatable, comma-separated, OR logic)
+  --exclude-tag <tag>  Exclude suites by tag (repeatable, comma-separated)
+  --method <method>    Filter tests by HTTP method (e.g. GET, POST)
 
 Options for 'init':
   --name <name>        API name (auto-detected from spec title if omitted)
@@ -130,14 +134,15 @@ Options for 'init':
 
 Options for 'describe':
   --compact            List all endpoints briefly
+  --list-params        List all unique parameters across all endpoints
   --method <method>    HTTP method for single endpoint detail
   --path <path>        Endpoint path for single endpoint detail
 
 Options for 'db':
   zond db collections           List all API collections
   zond db runs [--limit N]      List recent test runs
-  zond db run <id> [--verbose]  Show run details
-  zond db diagnose <id>         Diagnose run failures
+  zond db run <id> [--verbose]  Show run details (--method GET, --status 403 to filter)
+  zond db diagnose <id>         Diagnose run failures (--limit N examples per group, --verbose for all)
   zond db compare <idA> <idB>   Compare two runs
 
 Options for 'request':
@@ -186,6 +191,9 @@ Options for 'sync':
   --dry-run            Show what would be generated without writing files
   --tag <tag>          Limit sync to endpoints with this tag
 
+Options for 'update':
+  --check              Only check for updates, do not download
+
 General:
   --json               Output in JSON envelope format (available for all commands)
   --help, -h           Show this help
@@ -251,8 +259,9 @@ async function main(): Promise<number> {
         }
       }
 
-      // Collect all --tag and --env-var flags (parseArgs only stores last one, so re-parse)
+      // Collect all --tag, --exclude-tag, and --env-var flags (parseArgs only stores last one, so re-parse)
       const tagValues: string[] = [];
+      const excludeTagValues: string[] = [];
       const envVarValues: string[] = [];
       const rawRunArgs = process.argv.slice(2);
       for (let i = 0; i < rawRunArgs.length; i++) {
@@ -262,6 +271,11 @@ async function main(): Promise<number> {
           i++;
         } else if (arg.startsWith("--tag=")) {
           tagValues.push(arg.slice("--tag=".length));
+        } else if (arg === "--exclude-tag" && rawRunArgs[i + 1]) {
+          excludeTagValues.push(rawRunArgs[i + 1]!);
+          i++;
+        } else if (arg.startsWith("--exclude-tag=")) {
+          excludeTagValues.push(arg.slice("--exclude-tag=".length));
         } else if (arg === "--env-var" && rawRunArgs[i + 1]) {
           envVarValues.push(rawRunArgs[i + 1]!);
           i++;
@@ -271,6 +285,7 @@ async function main(): Promise<number> {
       }
       // Support comma-separated: --tag smoke,crud → ["smoke", "crud"]
       const tags = tagValues.flatMap(v => v.split(",")).filter(Boolean);
+      const excludeTags = excludeTagValues.flatMap(v => v.split(",")).filter(Boolean);
 
       return runCommand({
         path,
@@ -283,6 +298,8 @@ async function main(): Promise<number> {
         authToken: typeof flags["auth-token"] === "string" ? flags["auth-token"] : undefined,
         safe: flags["safe"] === true,
         tag: tags.length > 0 ? tags : undefined,
+        excludeTag: excludeTags.length > 0 ? excludeTags : undefined,
+        method: typeof flags["method"] === "string" ? flags["method"] : undefined,
         envVars: envVarValues.length > 0 ? envVarValues : undefined,
         dryRun: flags["dry-run"] === true,
         json: jsonFlag,
@@ -405,6 +422,7 @@ async function main(): Promise<number> {
       return describeCommand({
         specPath,
         compact: flags["compact"] === true,
+        listParams: flags["list-params"] === true,
         method: typeof flags["method"] === "string" ? flags["method"] : undefined,
         path: typeof flags["path"] === "string" ? flags["path"] : undefined,
         json: jsonFlag,
@@ -423,6 +441,13 @@ async function main(): Promise<number> {
         limit = parseInt(limitRaw, 10);
         if (isNaN(limit) || limit <= 0) limit = undefined;
       }
+      const statusRaw = flags["status"];
+      let statusFilter: number | undefined;
+      if (typeof statusRaw === "string") {
+        statusFilter = parseInt(statusRaw, 10);
+        if (isNaN(statusFilter)) statusFilter = undefined;
+      }
+
       return dbCommand({
         subcommand: dbSub,
         positional: positional.slice(1),
@@ -430,6 +455,8 @@ async function main(): Promise<number> {
         verbose: flags["verbose"] === true,
         dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
         json: jsonFlag,
+        method: typeof flags["method"] === "string" ? flags["method"] : undefined,
+        status: statusFilter,
       });
     }
 
@@ -528,6 +555,14 @@ async function main(): Promise<number> {
       });
     }
 
+    case "update":
+    case "self-update": {
+      return updateCommand({
+        check: flags["check"] === true,
+        json: jsonFlag,
+      });
+    }
+
     case "sync": {
       const specPath = positional[0];
       if (!specPath) {

package/src/core/diagnostics/db-analysis.ts

@@ -169,7 +169,7 @@ export interface DiagnoseResult {
   grouped_failures?: FailureGroup[];
 }
 
-export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string): DiagnoseResult {
+export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string, maxExamples?: number): DiagnoseResult {
   getDb(dbPath);
   const diagRun = getRunById(runId);
   if (!diagRun) throw new Error(`Run ${runId} not found`);
@@ -272,7 +272,7 @@ export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string):
 
   const { grouped_failures, compactFailures } = verbose
     ? { grouped_failures: undefined, compactFailures: failures }
-    : groupFailures(failures);
+    : groupFailures(failures, maxExamples);
 
   return {
     run: {
@@ -301,7 +301,7 @@ export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string):
 type FailureItem = { suite_name: string; test_name: string; failure_type: string; recommended_action: RecommendedAction; hint?: string; response_status: number | null };
 
 /** Group similar failures for compact output. Exported for testing. */
-export function groupFailures<T extends FailureItem>(failures: T[]): { grouped_failures?: FailureGroup[]; compactFailures: T[] } {
+export function groupFailures<T extends FailureItem>(failures: T[], maxExamples = 2): { grouped_failures?: FailureGroup[]; compactFailures: T[] } {
   if (failures.length <= 5) {
     return { compactFailures: failures };
   }
@@ -341,7 +341,7 @@ export function groupFailures<T extends FailureItem>(failures: T[]): { grouped_f
       failure_type: group.failure_type,
       recommended_action: group.items[0]!.recommended_action,
       hint: group.hint,
-      examples: group.items.slice(0, 2).map(f => `${f.suite_name}/${f.test_name}`),
+      examples: (maxExamples === 0 ? group.items : group.items.slice(0, maxExamples)).map(f => `${f.suite_name}/${f.test_name}`),
       response_status: group.response_status,
     });
     compactFailures.push(group.items[0]!);

package/src/core/generator/data-factory.ts

@@ -7,7 +7,10 @@ import type { OpenAPIV3 } from "openapi-types";
 export function generateFromSchema(
   schema: OpenAPIV3.SchemaObject,
   propertyName?: string,
+  _depth = 0,
 ): unknown {
+  if (_depth > 5) return {};
+
   // allOf: merge all schemas
   if (schema.allOf) {
     const merged: OpenAPIV3.SchemaObject = { type: "object", properties: {} };
@@ -17,15 +20,15 @@ export function generateFromSchema(
         merged.properties = { ...merged.properties, ...s.properties };
       }
     }
-    return generateFromSchema(merged, propertyName);
+    return generateFromSchema(merged, propertyName, _depth + 1);
   }
 
   // oneOf / anyOf: use first variant
   if (schema.oneOf) {
-    return generateFromSchema(schema.oneOf[0] as OpenAPIV3.SchemaObject, propertyName);
+    return generateFromSchema(schema.oneOf[0] as OpenAPIV3.SchemaObject, propertyName, _depth + 1);
   }
   if (schema.anyOf) {
-    return generateFromSchema(schema.anyOf[0] as OpenAPIV3.SchemaObject, propertyName);
+    return generateFromSchema(schema.anyOf[0] as OpenAPIV3.SchemaObject, propertyName, _depth + 1);
   }
 
   // enum: first value
@@ -51,7 +54,7 @@ export function generateFromSchema(
 
     case "array": {
       if (schema.items) {
-        const item = generateFromSchema(schema.items as OpenAPIV3.SchemaObject);
+        const item = generateFromSchema(schema.items as OpenAPIV3.SchemaObject, undefined, _depth + 1);
         return [item];
       }
       return [];
@@ -63,14 +66,14 @@ export function generateFromSchema(
       if (schema.properties) {
         const obj: Record<string, unknown> = {};
         for (const [key, propSchema] of Object.entries(schema.properties)) {
-          obj[key] = generateFromSchema(propSchema as OpenAPIV3.SchemaObject, key);
+          obj[key] = generateFromSchema(propSchema as OpenAPIV3.SchemaObject, key, _depth + 1);
         }
         return obj;
       }
       // Record type: additionalProperties defines value schema
       if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
         const valSchema = schema.additionalProperties as OpenAPIV3.SchemaObject;
-        return { key1: generateFromSchema(valSchema, "key1"), key2: generateFromSchema(valSchema, "key2") };
+        return { key1: generateFromSchema(valSchema, "key1", _depth + 1), key2: generateFromSchema(valSchema, "key2", _depth + 1) };
       }
       if (schema.additionalProperties === true) {
         return { key1: "value1", key2: "value2" };

package/src/core/generator/describe.ts

@@ -248,3 +248,55 @@ export async function describeCompact(
 
   return result;
 }
+
+export interface ParamInfo {
+  name: string;
+  in: string;
+  type?: string;
+  required: boolean;
+  usedBy: string[];
+}
+
+export async function describeAllParams(
+  specPath: string,
+  options?: { insecure?: boolean },
+): Promise<ParamInfo[]> {
+  const doc = await readOpenApiSpec(specPath, options) as OpenAPIV3.Document;
+  const paths = doc.paths ?? {};
+  const paramMap = new Map<string, ParamInfo>();
+
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const pathParams = ((pathItem as any)?.parameters ?? []) as OpenAPIV3.ParameterObject[];
+
+    for (const method of ["get", "post", "put", "patch", "delete"]) {
+      const op = (pathItem as any)?.[method] as OpenAPIV3.OperationObject | undefined;
+      if (!op) continue;
+
+      const allParams = [...pathParams, ...((op.parameters ?? []) as OpenAPIV3.ParameterObject[])];
+      const endpoint = `${method.toUpperCase()} ${path}`;
+
+      for (const p of allParams) {
+        const key = `${p.in}:${p.name}`;
+        const existing = paramMap.get(key);
+        const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+        if (existing) {
+          existing.usedBy.push(endpoint);
+          if (p.required) existing.required = true;
+        } else {
+          paramMap.set(key, {
+            name: p.name,
+            in: p.in,
+            type: schema?.type,
+            required: p.required ?? false,
+            usedBy: [endpoint],
+          });
+        }
+      }
+    }
+  }
+
+  return [...paramMap.values()].sort((a, b) => {
+    if (a.in !== b.in) return a.in.localeCompare(b.in);
+    return a.name.localeCompare(b.name);
+  });
+}

package/src/core/generator/endpoint-warnings.ts

@@ -1,6 +1,6 @@
 import type { EndpointInfo } from "./types.ts";
 
-export type WarningCode = "deprecated" | "no_response_schema" | "no_responses_defined" | "required_params_no_examples";
+export type WarningCode = "deprecated" | "no_response_schema" | "no_responses_defined" | "required_params_no_examples" | "post_body_as_query";
 
 export interface EndpointWarning {
   method: string;
@@ -34,6 +34,15 @@ export function analyzeEndpoints(endpoints: EndpointInfo[]): EndpointWarning[] {
       warnings.push(`required_params_no_examples: ${missingExamples.join(", ")}`);
     }
 
+    // SpringDoc quirk: POST/PUT/PATCH with query param named "body" or single complex object query param
+    if (["POST", "PUT", "PATCH"].includes(ep.method)) {
+      const queryParams = ep.parameters.filter(p => p.in === "query");
+      const hasBodyQuery = queryParams.some(p => p.name.toLowerCase() === "body");
+      if (hasBodyQuery) {
+        warnings.push("post_body_as_query: query param 'body' on POST/PUT/PATCH likely means request body (SpringDoc quirk)");
+      }
+    }
+
     if (warnings.length > 0) {
       result.push({ method: ep.method, path: ep.path, warnings });
     }

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

@@ -15,8 +15,8 @@ function convertPath(path: string): string {
 
 /**
  * Convert path params to seed values for smoke suites (no capture context).
- * Uses the parameter's example/default from the spec, or falls back to "1" for
- * id-like params. Non-id string params keep the {{placeholder}} form.
+ * Uses the parameter's example/default from the spec, or falls back to
+ * {{placeholder}} form so the user fills them in via .env.yaml.
  */
 function convertPathWithSeeds(path: string, ep: EndpointInfo): string {
   return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
@@ -24,7 +24,6 @@ function convertPathWithSeeds(path: string, ep: EndpointInfo): string {
     const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
     const example = (param as any)?.example ?? schema?.example ?? schema?.default;
     if (example !== undefined) return String(example);
-    if (schema?.type === "integer" || /^id$|_id$|Id$/i.test(name)) return "1";
     return `{{${name}}}`;
   });
 }
@@ -81,6 +80,20 @@ function getBodyAssertions(ep: EndpointInfo): Record<string, Record<string, stri
   return undefined;
 }
 
+/** Derive a variable name for a security scheme's token */
+function schemeVarName(scheme: SecuritySchemeInfo, allSchemes: SecuritySchemeInfo[]): string {
+  // Count how many bearer-like schemes exist
+  const bearerSchemes = allSchemes.filter(s =>
+    (s.type === "http" && (s.scheme === "bearer" || !s.scheme)) ||
+    (s.type === "apiKey" && s.in === "header" && s.apiKeyName === "Authorization")
+  );
+  // If only one bearer scheme → keep generic auth_token for backward compat
+  if (bearerSchemes.length <= 1) return "auth_token";
+  // Multiple → derive from scheme name (e.g. "platformAuth" → "platform_auth_token")
+  const slug = scheme.name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/_token$|_auth$/, "");
+  return `${slug}_token`;
+}
+
 function getAuthHeaders(
   ep: EndpointInfo,
   schemes: SecuritySchemeInfo[],
@@ -93,16 +106,15 @@ function getAuthHeaders(
 
     if (scheme.type === "http") {
       if (scheme.scheme === "bearer" || !scheme.scheme) {
-        return { Authorization: "Bearer {{auth_token}}" };
+        return { Authorization: `Bearer {{${schemeVarName(scheme, schemes)}}}` };
       }
       if (scheme.scheme === "basic") {
-        return { Authorization: "Basic {{auth_token}}" };
+        return { Authorization: `Basic {{${schemeVarName(scheme, schemes)}}}` };
       }
     }
     if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
-      // When apiKey scheme uses Authorization header, it's typically a Bearer token
       if (scheme.apiKeyName === "Authorization") {
-        return { Authorization: "Bearer {{auth_token}}" };
+        return { Authorization: `Bearer {{${schemeVarName(scheme, schemes)}}}` };
       }
       return { [scheme.apiKeyName]: "{{api_key}}" };
     }
@@ -111,14 +123,15 @@ function getAuthHeaders(
   return undefined;
 }
 
-function getRequiredQueryParams(ep: EndpointInfo): Record<string, unknown> | undefined {
+function getRequiredQueryParams(ep: EndpointInfo): Record<string, string> | undefined {
   const queryParams = ep.parameters.filter(p => p.in === "query" && p.required);
   if (queryParams.length === 0) return undefined;
 
-  const query: Record<string, unknown> = {};
+  const query: Record<string, string> = {};
   for (const p of queryParams) {
     if (p.schema) {
-      query[p.name] = generateFromSchema(p.schema as OpenAPIV3.SchemaObject, p.name);
+      const val = generateFromSchema(p.schema as OpenAPIV3.SchemaObject, p.name);
+      query[p.name] = typeof val === "object" ? JSON.stringify(val) : String(val);
     } else {
       query[p.name] = "{{$randomString}}";
     }
@@ -387,9 +400,10 @@ export function generateCrudSuite(
 }
 
 /** Find unresolved template variables in a suite (excluding known globals, captured vars, and env keys) */
-export function findUnresolvedVars(suite: RawSuite, envKeys?: Set<string>): string[] {
+export function findUnresolvedVars(suite: RawSuite, envKeys?: Set<string>, extraKnown?: Set<string>): string[] {
   const KNOWN = new Set(["base_url", "auth_token", "api_key"]);
   if (envKeys) for (const k of envKeys) KNOWN.add(k);
+  if (extraKnown) for (const k of extraKnown) KNOWN.add(k);
   const captured = new Set<string>();
   for (const step of suite.tests) {
     if (step.expect?.body) {
@@ -518,8 +532,13 @@ function generateConsistentAuthSuite(
       /token|access_token|accessToken|jwt/i.test(k)
     );
     if (tokenField) {
+      // Determine the capture variable name based on the login endpoint's security scheme
+      const loginScheme = loginEp.security.length > 0
+        ? securitySchemes.find(s => s.name === loginEp.security[0])
+        : undefined;
+      const captureVar = loginScheme ? schemeVarName(loginScheme, securitySchemes) : "auth_token";
       if (!loginStep.expect.body) loginStep.expect.body = {};
-      loginStep.expect.body[tokenField] = { capture: "auth_token" };
+      loginStep.expect.body[tokenField] = { capture: captureVar };
     }
   }
   tests.push(loginStep);

package/src/core/parser/filter.ts

@@ -12,3 +12,29 @@ export function filterSuitesByTags(suites: TestSuite[], tags: string[]): TestSui
     return suite.tags.some(t => normalizedTags.includes(t.toLowerCase()));
   });
 }
+
+/**
+ * Exclude suites whose tags intersect with the exclusion set (OR logic, case-insensitive).
+ * Suites without tags are kept.
+ */
+export function excludeSuitesByTags(suites: TestSuite[], excludeTags: string[]): TestSuite[] {
+  if (excludeTags.length === 0) return suites;
+  const normalizedTags = excludeTags.map(t => t.toLowerCase());
+  return suites.filter(suite => {
+    if (!suite.tags || suite.tags.length === 0) return true;
+    return !suite.tags.some(t => normalizedTags.includes(t.toLowerCase()));
+  });
+}
+
+/**
+ * Filter test steps within suites by HTTP method (case-insensitive).
+ * Suites with no remaining tests are removed.
+ */
+export function filterSuitesByMethod(suites: TestSuite[], method: string): TestSuite[] {
+  const upperMethod = method.toUpperCase();
+  const filtered = suites.map(suite => ({
+    ...suite,
+    tests: suite.tests.filter(t => (t.method ?? "GET").toUpperCase() === upperMethod),
+  }));
+  return filtered.filter(s => s.tests.length > 0);
+}

package/src/db/queries.ts

@@ -292,6 +292,30 @@ export function getResultsByRunId(runId: number): StoredStepResult[] {
   }));
 }
 
+export function getFilteredResults(runId: number, filters: { method?: string; status?: number }): StoredStepResult[] {
+  const db = getDb();
+  const conditions = ["run_id = ?"];
+  const params: (string | number)[] = [runId];
+
+  if (filters.method) {
+    conditions.push("request_method = ?");
+    params.push(filters.method.toUpperCase());
+  }
+  if (filters.status !== undefined) {
+    conditions.push("response_status = ?");
+    params.push(filters.status);
+  }
+
+  const rows = db.query(`SELECT * FROM results WHERE ${conditions.join(" AND ")} ORDER BY id`).all(...params) as Array<
+    Omit<StoredStepResult, "assertions" | "captures"> & { assertions: string | null; captures: string | null }
+  >;
+  return rows.map((row) => ({
+    ...row,
+    assertions: row.assertions ? JSON.parse(row.assertions) : [],
+    captures: row.captures ? JSON.parse(row.captures) : {},
+  }));
+}
+
 // ──────────────────────────────────────────────
 // Dashboard metrics
 // ──────────────────────────────────────────────

package/src/web/server.ts

@@ -4,7 +4,7 @@ import dashboard from "./routes/dashboard.ts";
 import runs from "./routes/runs.ts";
 import api from "./routes/api.ts";
 import styleCssPath from "./static/style.css" with { type: "file" };
-import htmxJsPath from "./static/htmx.min.js" with { type: "file" };
+import htmxJsPath from "./static/htmx.min.cjs" with { type: "file" };
 
 export interface ServerOptions {
   port?: number;