@kirrosh/zond 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
@@ -26,7 +26,7 @@
   "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/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: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/catalog.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",

package/src/cli/commands/catalog.ts

@@ -0,0 +1,62 @@
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import { readOpenApiSpec, extractEndpoints, extractSecuritySchemes } from "../../core/generator/index.ts";
+import { buildCatalog, serializeCatalog } from "../../core/generator/catalog-builder.ts";
+import { decycleSchema } from "../../core/generator/schema-utils.ts";
+import { hashSpec } from "../../core/meta/meta-store.ts";
+import { printError, printSuccess } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface CatalogOptions {
+  specPath: string;
+  output?: string;
+  json?: boolean;
+}
+
+export async function catalogCommand(options: CatalogOptions): Promise<number> {
+  try {
+    const doc = await readOpenApiSpec(options.specPath);
+    const endpoints = extractEndpoints(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+    const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
+    const apiName = (doc as any).info?.title as string | undefined;
+    const apiVersion = (doc as any).info?.version as string | undefined;
+    const specContent = JSON.stringify(decycleSchema(doc));
+
+    const catalog = buildCatalog({
+      endpoints,
+      securitySchemes,
+      specSource: options.specPath,
+      specHash: hashSpec(specContent),
+      apiName,
+      apiVersion,
+      baseUrl,
+    });
+
+    const outputDir = options.output ?? ".";
+    await mkdir(outputDir, { recursive: true });
+
+    const catalogPath = join(outputDir, ".api-catalog.yaml");
+    await Bun.write(catalogPath, serializeCatalog(catalog));
+
+    if (options.json) {
+      printJson(jsonOk("catalog", {
+        path: catalogPath,
+        endpointCount: catalog.endpointCount,
+        apiName: catalog.apiName,
+      }));
+    } else {
+      printSuccess(`Generated API catalog: ${catalogPath} (${catalog.endpointCount} endpoints)`);
+    }
+
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("catalog", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/generate.ts

@@ -7,6 +7,8 @@ import {
   scanCoveredEndpoints,
   filterUncoveredEndpoints,
   serializeSuite,
+  buildCatalog,
+  serializeCatalog,
 } from "../../core/generator/index.ts";
 import { generateSuites, findUnresolvedVars } from "../../core/generator/suite-generator.ts";
 import { filterByTag } from "../../core/generator/chunker.ts";
@@ -30,9 +32,12 @@ export interface GenerateOptions {
 export async function generateCommand(options: GenerateOptions): Promise<number> {
   try {
     const doc = await readOpenApiSpec(options.specPath);
-    let endpoints = extractEndpoints(doc);
+    const allEndpoints = extractEndpoints(doc);
+    let endpoints = allEndpoints;
     const securitySchemes = extractSecuritySchemes(doc);
     const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
+    const apiName = (doc as any).info?.title as string | undefined;
+    const apiVersion = (doc as any).info?.version as string | undefined;
     const warnings: string[] = [];
 
     // Filter to uncovered only
@@ -92,6 +97,18 @@ export async function generateCommand(options: GenerateOptions): Promise<number>
       files: { ...(existingMeta?.files ?? {}), ...metaFiles },
     });
 
+    // Generate .api-catalog.yaml (always uses full unfiltered endpoint list)
+    const catalog = buildCatalog({
+      endpoints: allEndpoints,
+      securitySchemes,
+      specSource: options.specPath,
+      specHash: hashSpec(specContent),
+      apiName,
+      apiVersion,
+      baseUrl,
+    });
+    await Bun.write(join(options.output, ".api-catalog.yaml"), serializeCatalog(catalog));
+
     // Sync DB collection spec reference if one is registered for this output directory
     try {
       getDb();

package/src/cli/commands/sync.ts

@@ -5,6 +5,8 @@ import {
   extractEndpoints,
   extractSecuritySchemes,
   serializeSuite,
+  buildCatalog,
+  serializeCatalog,
 } from "../../core/generator/index.ts";
 import { generateSuites } from "../../core/generator/suite-generator.ts";
 import { filterByTag } from "../../core/generator/chunker.ts";
@@ -78,6 +80,19 @@ export async function syncCommand(options: SyncOptions): Promise<number> {
     }
 
     if (newEndpoints.length === 0) {
+      // Update catalog even when no new endpoints — spec schema may have changed
+      const allEndpoints = extractEndpoints(doc);
+      const catalog = buildCatalog({
+        endpoints: allEndpoints,
+        securitySchemes,
+        specSource: options.specPath,
+        specHash: currentHash,
+        apiName: (doc as any).info?.title,
+        apiVersion: (doc as any).info?.version,
+        baseUrl: (doc as any).servers?.[0]?.url,
+      });
+      await Bun.write(join(options.testsDir, ".api-catalog.yaml"), serializeCatalog(catalog));
+
       const msg = "Spec changed (hash differs) but no new endpoints detected. Existing tests may need manual review.";
       warnings.push(msg);
       if (options.json) {
@@ -168,6 +183,19 @@ export async function syncCommand(options: SyncOptions): Promise<number> {
       files: { ...meta.files, ...updatedMetaFiles },
     });
 
+    // Update .api-catalog.yaml with current spec state
+    const allEndpoints = extractEndpoints(doc);
+    const catalog = buildCatalog({
+      endpoints: allEndpoints,
+      securitySchemes,
+      specSource: options.specPath,
+      specHash: currentHash,
+      apiName: (doc as any).info?.title,
+      apiVersion: (doc as any).info?.version,
+      baseUrl: (doc as any).servers?.[0]?.url,
+    });
+    await Bun.write(join(options.testsDir, ".api-catalog.yaml"), serializeCatalog(catalog));
+
     // Sync DB collection if one is registered for this tests directory
     try {
       getDb();

package/src/cli/index.ts

@@ -14,6 +14,7 @@ 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 { catalogCommand } from "./commands/catalog.ts";
 import { printError } from "./output.ts";
 import { getRuntimeInfo } from "./runtime.ts";
 import { getDb } from "../db/schema.ts";
@@ -107,6 +108,7 @@ Usage:
   zond ui               Alias for 'serve --open' (start dashboard & open browser)
   zond ci init          Generate CI/CD workflow (GitHub Actions, GitLab CI)
   zond export postman <path>  Export YAML tests as Postman Collection v2.1
+  zond catalog <spec>   Generate API catalog (compact endpoint reference)
   zond sync <spec>      Detect new/removed endpoints and generate tests for new ones
   zond update           Check for updates and self-update the binary
 
@@ -186,6 +188,9 @@ Options for 'export postman':
   --env <file>         Also export .env.yaml as Postman environment
   --collection-name <name>  Collection name (default: derived from path)
 
+Options for 'catalog':
+  --output <dir>       Output directory (default: current directory)
+
 Options for 'sync':
   --tests <dir>        Path to test files directory (required)
   --dry-run            Show what would be generated without writing files
@@ -521,6 +526,19 @@ async function main(): Promise<number> {
       });
     }
 
+    case "catalog": {
+      const specPath = positional[0];
+      if (!specPath) {
+        printError("Missing spec path. Usage: zond catalog <spec> [--output <dir>]");
+        return 2;
+      }
+      return catalogCommand({
+        specPath,
+        output: typeof flags["output"] === "string" ? flags["output"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
     case "guide": {
       const specPath = positional[0];
       if (!specPath) {

package/src/core/generator/catalog-builder.ts

@@ -0,0 +1,179 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "./types.ts";
+import { compressSchema, formatParam, isAnySchema } from "./schema-utils.ts";
+
+export interface CatalogEndpoint {
+  method: string;
+  path: string;
+  summary?: string;
+  tags: string[];
+  deprecated?: boolean;
+  parameters?: string[];
+  requestBody?: string;
+  responses: Array<{
+    status: number;
+    schema?: string;
+  }>;
+}
+
+export interface ApiCatalog {
+  generatedAt: string;
+  specSource: string;
+  specHash: string;
+  apiName?: string;
+  apiVersion?: string;
+  baseUrl?: string;
+  auth: string[];
+  endpointCount: number;
+  endpoints: CatalogEndpoint[];
+}
+
+export interface BuildCatalogParams {
+  endpoints: EndpointInfo[];
+  securitySchemes: SecuritySchemeInfo[];
+  specSource: string;
+  specHash: string;
+  apiName?: string;
+  apiVersion?: string;
+  baseUrl?: string;
+}
+
+function formatSecurityScheme(s: SecuritySchemeInfo): string {
+  let desc = `${s.name}: ${s.type}`;
+  if (s.scheme) desc += `/${s.scheme}`;
+  if (s.bearerFormat) desc += ` (${s.bearerFormat})`;
+  if (s.in && s.apiKeyName) desc += ` (${s.apiKeyName} in ${s.in})`;
+  return desc;
+}
+
+function formatParamWithLocation(p: import("openapi-types").OpenAPIV3.ParameterObject): string {
+  const base = formatParam(p);
+  // Insert location before (req) or at the end
+  const reqSuffix = " (req)";
+  if (base.endsWith(reqSuffix)) {
+    return `${base.slice(0, -reqSuffix.length)} (${p.in}, req)`;
+  }
+  return `${base} (${p.in})`;
+}
+
+function buildCatalogEndpoint(ep: EndpointInfo): CatalogEndpoint {
+  const result: CatalogEndpoint = {
+    method: ep.method.toUpperCase(),
+    path: ep.path,
+    tags: ep.tags,
+    responses: [],
+  };
+
+  if (ep.summary) result.summary = ep.summary;
+  if (ep.deprecated) result.deprecated = true;
+
+  if (ep.parameters.length > 0) {
+    result.parameters = ep.parameters.map(formatParamWithLocation);
+  }
+
+  if (ep.requestBodySchema) {
+    result.requestBody = isAnySchema(ep.requestBodySchema)
+      ? "any"
+      : compressSchema(ep.requestBodySchema);
+  }
+
+  for (const resp of ep.responses) {
+    const entry: { status: number; schema?: string } = { status: resp.statusCode };
+    if (resp.schema && !isAnySchema(resp.schema)) {
+      entry.schema = compressSchema(resp.schema);
+    }
+    result.responses.push(entry);
+  }
+
+  return result;
+}
+
+export function buildCatalog(params: BuildCatalogParams): ApiCatalog {
+  return {
+    generatedAt: new Date().toISOString(),
+    specSource: params.specSource,
+    specHash: params.specHash,
+    ...(params.apiName ? { apiName: params.apiName } : {}),
+    ...(params.apiVersion ? { apiVersion: params.apiVersion } : {}),
+    ...(params.baseUrl ? { baseUrl: params.baseUrl } : {}),
+    auth: params.securitySchemes.map(formatSecurityScheme),
+    endpointCount: params.endpoints.length,
+    endpoints: params.endpoints.map(buildCatalogEndpoint),
+  };
+}
+
+// --- YAML serialization ---
+
+function yamlEscape(value: string): string {
+  if (/[:{}\[\],&*#?|<>=!%@`"']/.test(value) || value.includes("\n")) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+function yamlScalar(value: unknown): string {
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return yamlEscape(String(value));
+}
+
+export function serializeCatalog(catalog: ApiCatalog): string {
+  const lines: string[] = [];
+  lines.push("# Auto-generated by zond. Regenerate with: zond catalog <spec>");
+  lines.push(`generatedAt: ${yamlScalar(catalog.generatedAt)}`);
+  lines.push(`specSource: ${yamlScalar(catalog.specSource)}`);
+  lines.push(`specHash: ${yamlScalar(catalog.specHash)}`);
+  if (catalog.apiName) lines.push(`apiName: ${yamlScalar(catalog.apiName)}`);
+  if (catalog.apiVersion) lines.push(`apiVersion: ${yamlScalar(catalog.apiVersion)}`);
+  if (catalog.baseUrl) lines.push(`baseUrl: ${yamlScalar(catalog.baseUrl)}`);
+  lines.push(`endpointCount: ${catalog.endpointCount}`);
+
+  // Auth
+  if (catalog.auth.length > 0) {
+    lines.push("auth:");
+    for (const a of catalog.auth) {
+      lines.push(`  - ${yamlScalar(a)}`);
+    }
+  } else {
+    lines.push("auth: []");
+  }
+
+  // Endpoints
+  if (catalog.endpoints.length === 0) {
+    lines.push("endpoints: []");
+    return lines.join("\n") + "\n";
+  }
+  lines.push("endpoints:");
+  for (const ep of catalog.endpoints) {
+    lines.push(`  - method: ${ep.method}`);
+    lines.push(`    path: ${yamlScalar(ep.path)}`);
+    if (ep.summary) lines.push(`    summary: ${yamlScalar(ep.summary)}`);
+    if (ep.tags.length > 0) {
+      lines.push(`    tags: [${ep.tags.map(yamlScalar).join(", ")}]`);
+    }
+    if (ep.deprecated) lines.push(`    deprecated: true`);
+
+    if (ep.parameters && ep.parameters.length > 0) {
+      lines.push(`    parameters:`);
+      for (const p of ep.parameters) {
+        lines.push(`      - ${yamlScalar(p)}`);
+      }
+    }
+
+    if (ep.requestBody) {
+      lines.push(`    requestBody: ${yamlScalar(ep.requestBody)}`);
+    }
+
+    if (ep.responses.length > 0) {
+      lines.push(`    responses:`);
+      for (const r of ep.responses) {
+        if (r.schema) {
+          lines.push(`      - status: ${r.status}`);
+          lines.push(`        schema: ${yamlScalar(r.schema)}`);
+        } else {
+          lines.push(`      - status: ${r.status}`);
+        }
+      }
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}

package/src/core/generator/index.ts

@@ -10,3 +10,5 @@ export type { GuideOptions } from "./guide-builder.ts";
 export type { EndpointWarning, WarningCode } from "./endpoint-warnings.ts";
 export type { EndpointInfo, ResponseInfo, GenerateOptions, SecuritySchemeInfo, CrudGroup } from "./types.ts";
 export { generateSuites, generateStep, detectCrudGroups, generateCrudSuite, generateSanitySuite, findUnresolvedVars } from "./suite-generator.ts";
+export { buildCatalog, serializeCatalog } from "./catalog-builder.ts";
+export type { ApiCatalog, CatalogEndpoint } from "./catalog-builder.ts";

package/src/web/routes/api.ts

@@ -12,6 +12,7 @@ import {
   RunDetailSchema,
   RunIdParam,
 } from "../schemas.ts";
+import { renderProxyResponse, renderProxyError } from "../views/explorer-tab.ts";
 
 const api = new OpenAPIHono();
 
@@ -114,6 +115,85 @@ api.openapi(runRoute, async (c) => {
   }
 });
 
+// ──────────────────────────────────────────────
+// POST /api/proxy — Explorer proxy for HTTP requests
+// ──────────────────────────────────────────────
+
+api.post("/api/proxy", async (c) => {
+  const form = await c.req.parseBody();
+  const baseUrl = (form["base_url"] as string) ?? "";
+  const method = ((form["method"] as string) ?? "GET").toUpperCase();
+  let path = (form["path"] as string) ?? "/";
+  const body = (form["body"] as string) || undefined;
+  const contentType = (form["content_type"] as string) || undefined;
+
+  if (!baseUrl) {
+    return c.html(renderProxyError("Base URL is required", 0));
+  }
+
+  // Substitute path parameters
+  for (const [key, value] of Object.entries(form)) {
+    if (typeof key === "string" && key.startsWith("param_path_") && value) {
+      const paramName = key.slice("param_path_".length);
+      path = path.replace(`{${paramName}}`, encodeURIComponent(value as string));
+    }
+  }
+
+  // Build query string
+  const queryParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(form)) {
+    if (typeof key === "string" && key.startsWith("param_query_") && value) {
+      queryParams.set(key.slice("param_query_".length), value as string);
+    }
+  }
+
+  // Build headers
+  const headers: Record<string, string> = {};
+  for (const [key, value] of Object.entries(form)) {
+    if (typeof key === "string" && key.startsWith("param_header_") && value) {
+      headers[key.slice("param_header_".length)] = value as string;
+    }
+  }
+  // Custom headers
+  for (let i = 0; i < 50; i++) {
+    const k = form[`custom_header_key_${i}`] as string | undefined;
+    const v = form[`custom_header_value_${i}`] as string | undefined;
+    if (!k && !v) break;
+    if (k && v) headers[k] = v;
+  }
+
+  if (contentType && body) {
+    headers["Content-Type"] = contentType;
+  }
+
+  // Build URL
+  let url: URL;
+  try {
+    url = new URL(path, baseUrl.endsWith("/") ? baseUrl : baseUrl + "/");
+    queryParams.forEach((v, k) => url.searchParams.set(k, v));
+  } catch (err) {
+    return c.html(renderProxyError(`Invalid URL: ${baseUrl}${path} — ${(err as Error).message}`, 0));
+  }
+
+  const startTime = performance.now();
+  try {
+    const resp = await fetch(url.toString(), {
+      method,
+      headers,
+      body: ["GET", "HEAD"].includes(method) ? undefined : (body || undefined),
+    });
+    const elapsed = Math.round(performance.now() - startTime);
+    const respBody = await resp.text();
+    const respHeaders: Record<string, string> = {};
+    resp.headers.forEach((v, k) => { respHeaders[k] = v; });
+
+    return c.html(renderProxyResponse(resp.status, respHeaders, respBody, elapsed));
+  } catch (err) {
+    const elapsed = Math.round(performance.now() - startTime);
+    return c.html(renderProxyError((err as Error).message, elapsed));
+  }
+});
+
 // ──────────────────────────────────────────────
 // Export helpers
 // ──────────────────────────────────────────────

package/src/web/routes/dashboard.ts

@@ -5,6 +5,7 @@ import { renderHealthStrip } from "../views/health-strip.ts";
 import { renderEndpointsTab } from "../views/endpoints-tab.ts";
 import { renderSuitesTab } from "../views/suites-tab.ts";
 import { renderRunsTab, renderRunDetail } from "../views/runs-tab.ts";
+import { renderExplorerTab } from "../views/explorer-tab.ts";
 import { buildCollectionState, invalidateCollectionCache } from "../data/collection-state.ts";
 import {
   listCollections,
@@ -81,6 +82,16 @@ dashboard.get("/panels/endpoints", async (c) => {
   return c.html(renderEndpointsTab(state, filters));
 });
 
+dashboard.get("/panels/explorer", async (c) => {
+  const collectionId = parseInt(c.req.query("collection_id") ?? "", 10);
+  if (isNaN(collectionId)) return c.html("");
+
+  const collection = getCollectionById(collectionId);
+  if (!collection) return c.html("");
+
+  return c.html(await renderExplorerTab(collection));
+});
+
 dashboard.get("/panels/suites", async (c) => {
   const collectionId = parseInt(c.req.query("collection_id") ?? "", 10);
   if (isNaN(collectionId)) return c.html("");
@@ -243,6 +254,10 @@ async function renderCollectionContent(collection: CollectionRecord): Promise<st
         hx-get="/panels/runs-tab?collection_id=${collection.id}"
         hx-target="#tab-content" hx-swap="innerHTML"
         onclick="activateTab(this)">Runs <span class="tab-count">${runCount}</span></button>
+      <button class="tab-btn" data-tab="explorer"
+        hx-get="/panels/explorer?collection_id=${collection.id}"
+        hx-target="#tab-content" hx-swap="innerHTML"
+        onclick="activateTab(this)">Explorer</button>
     </div>`;
 
   // Default tab content (endpoints)

package/src/web/static/style.css

@@ -847,6 +847,294 @@ h3 { font-size: 1.05rem; margin: 1rem 0 0.25rem; }
   100% { background: transparent; }
 }
 
+/* ═══════════════════════════════════════════════════
+   Explorer Tab
+   ═══════════════════════════════════════════════════ */
+
+.explorer-base-url {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1rem;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  margin-bottom: 1rem;
+}
+.explorer-base-url .explorer-label {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text-dim);
+  white-space: nowrap;
+}
+.explorer-input {
+  background: var(--bg-inset);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--text);
+  font-family: var(--font-mono);
+  font-size: 0.85rem;
+  padding: 0.4rem 0.6rem;
+  flex: 1;
+  min-width: 0;
+}
+.explorer-input:focus {
+  outline: none;
+  border-color: var(--accent);
+}
+.explorer-input-sm { flex: unset; width: auto; }
+
+/* Groups */
+.explorer-list { display: flex; flex-direction: column; gap: 0.5rem; }
+.explorer-group {
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow: hidden;
+}
+.explorer-group-title {
+  font-size: 0.85rem;
+  font-weight: 600;
+  padding: 0.6rem 1rem;
+  background: var(--bg-secondary);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+.explorer-group-title .tab-count {
+  font-size: 0.75rem;
+  background: var(--bg-hover);
+  padding: 0.1rem 0.5rem;
+  border-radius: var(--radius-pill);
+  color: var(--text-dim);
+}
+
+/* Endpoint row */
+.explorer-endpoint {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 1rem;
+  cursor: pointer;
+  border-top: 1px solid var(--border-subtle);
+  transition: background 0.15s;
+}
+.explorer-endpoint:hover { background: var(--bg-hover); }
+.explorer-endpoint-path {
+  font-family: var(--font-mono);
+  font-size: 0.85rem;
+  font-weight: 500;
+}
+.explorer-endpoint-summary {
+  color: var(--text-dim);
+  font-size: 0.8rem;
+  margin-left: auto;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.explorer-auth-hint {
+  font-size: 0.65rem;
+  font-weight: 600;
+  padding: 0.1rem 0.35rem;
+  border-radius: var(--radius-sm);
+  background: var(--warn-dim);
+  color: var(--warn);
+}
+
+/* Detail / form */
+.explorer-detail {
+  padding: 1rem;
+  background: var(--bg-raised);
+  border-top: 1px solid var(--border);
+}
+.explorer-section {
+  margin-bottom: 1rem;
+}
+.explorer-section-title {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text-dim);
+  margin-bottom: 0.5rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+/* Parameters */
+.explorer-param-row {
+  display: grid;
+  grid-template-columns: 140px 50px 90px 1fr;
+  gap: 0.5rem;
+  align-items: center;
+  margin-bottom: 0.35rem;
+  font-size: 0.85rem;
+}
+.explorer-param-name {
+  font-family: var(--font-mono);
+  font-weight: 500;
+  font-size: 0.8rem;
+}
+.explorer-param-location {
+  font-size: 0.7rem;
+  color: var(--text-muted);
+  background: var(--bg-inset);
+  padding: 0.1rem 0.3rem;
+  border-radius: var(--radius-sm);
+  text-align: center;
+}
+.explorer-param-type {
+  font-size: 0.75rem;
+  color: var(--text-dim);
+  font-family: var(--font-mono);
+}
+.explorer-required {
+  color: var(--fail);
+  font-weight: 700;
+  margin-left: 0.15rem;
+}
+
+/* Body editor */
+.explorer-body-editor {
+  width: 100%;
+  min-height: 120px;
+  background: var(--bg-inset);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--text);
+  font-family: var(--font-mono);
+  font-size: 0.85rem;
+  padding: 0.5rem;
+  resize: vertical;
+  tab-size: 2;
+}
+.explorer-body-editor:focus { outline: none; border-color: var(--accent); }
+.explorer-content-type {
+  font-size: 0.75rem;
+  padding: 0.15rem 0.35rem;
+}
+
+/* Custom headers */
+.explorer-headers-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+.explorer-header-pair {
+  display: flex;
+  gap: 0.35rem;
+  align-items: center;
+}
+.explorer-header-pair input { flex: 1; }
+.explorer-remove-btn {
+  background: none;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--text-dim);
+  cursor: pointer;
+  font-size: 0.75rem;
+  padding: 0.25rem 0.5rem;
+  line-height: 1;
+}
+.explorer-remove-btn:hover { color: var(--fail); border-color: var(--fail); }
+.explorer-add-header-btn {
+  background: none;
+  border: none;
+  color: var(--accent);
+  cursor: pointer;
+  font-size: 0.8rem;
+  padding: 0.25rem 0;
+  margin-top: 0.25rem;
+}
+.explorer-add-header-btn:hover { text-decoration: underline; }
+
+/* Actions */
+.explorer-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-top: 0.5rem;
+}
+.explorer-send-btn {
+  background: var(--accent);
+  color: #fff;
+  border: none;
+  border-radius: var(--radius);
+  padding: 0.5rem 1.5rem;
+  font-weight: 600;
+  font-size: 0.85rem;
+  cursor: pointer;
+  transition: background 0.15s;
+}
+.explorer-send-btn:hover { background: var(--accent-hover); }
+.explorer-send-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+.explorer-spinner { color: var(--text-dim); font-size: 0.85rem; }
+
+/* Response */
+.explorer-response-container { margin-top: 1rem; }
+.explorer-response {
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow: hidden;
+}
+.explorer-response-error { border-color: var(--fail); }
+.response-meta {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  padding: 0.5rem 0.75rem;
+  background: var(--bg-secondary);
+  border-bottom: 1px solid var(--border);
+  font-size: 0.85rem;
+}
+.response-status {
+  font-weight: 700;
+  font-family: var(--font-mono);
+}
+.response-status.status-2xx { color: var(--pass); }
+.response-status.status-3xx { color: var(--info); }
+.response-status.status-4xx { color: var(--warn); }
+.response-status.status-5xx { color: var(--fail); }
+.response-time { color: var(--text-dim); font-size: 0.8rem; }
+.response-size { color: var(--text-muted); font-size: 0.8rem; }
+.response-headers { padding: 0.5rem 0.75rem; }
+.response-headers summary {
+  font-size: 0.8rem;
+  color: var(--text-dim);
+  cursor: pointer;
+}
+.response-headers-pre {
+  font-size: 0.8rem;
+  margin-top: 0.25rem;
+  white-space: pre-wrap;
+  word-break: break-all;
+}
+.response-body {
+  padding: 0.75rem;
+  background: var(--bg-inset);
+}
+.response-body pre {
+  font-family: var(--font-mono);
+  font-size: 0.8rem;
+  white-space: pre-wrap;
+  word-break: break-all;
+  max-height: 500px;
+  overflow-y: auto;
+  margin: 0;
+}
+.response-error-msg {
+  padding: 0.75rem;
+  color: var(--fail);
+  font-size: 0.85rem;
+}
+
+/* JSON syntax highlighting */
+.json-key { color: var(--accent); }
+.json-string { color: var(--pass); }
+.json-number { color: var(--warn); }
+.json-boolean { color: var(--method-patch); }
+.json-null { color: var(--text-dim); font-style: italic; }
+
 /* ── Responsive ── */
 @media (max-width: 768px) {
   .health-strip { grid-template-columns: 1fr; gap: 1rem; }
@@ -855,4 +1143,6 @@ h3 { font-size: 1.05rem; margin: 1rem 0 0.25rem; }
   .run-row { grid-template-columns: 48px 1fr 60px; }
   .run-time, .run-duration { display: none; }
   .runs-header { display: none; }
+  .explorer-param-row { grid-template-columns: 1fr; }
+  .explorer-endpoint-summary { display: none; }
 }

package/src/web/views/explorer-tab.ts

@@ -0,0 +1,402 @@
+/**
+ * Explorer tab: Swagger-like interactive API explorer.
+ * Renders endpoint forms, executes requests via server proxy, displays responses.
+ */
+
+import type { OpenAPIV3 } from "openapi-types";
+import type { CollectionRecord } from "../../db/queries.ts";
+import type { EndpointInfo } from "../../core/generator/types.ts";
+import { escapeHtml } from "./layout.ts";
+import { methodBadge } from "./results.ts";
+
+// ── Public API ──
+
+export async function renderExplorerTab(collection: CollectionRecord): Promise<string> {
+  if (!collection.openapi_spec) {
+    return `<div class="tab-empty">No OpenAPI spec configured. Register a spec with <code>setup_api</code> to see the explorer.</div>`;
+  }
+
+  let doc: OpenAPIV3.Document;
+  let endpoints: EndpointInfo[];
+  try {
+    const { readOpenApiSpec, extractEndpoints } = await import("../../core/generator/openapi-reader.ts");
+    doc = await readOpenApiSpec(collection.openapi_spec);
+    endpoints = extractEndpoints(doc);
+  } catch (err) {
+    return `<div class="tab-empty">Failed to load OpenAPI spec: ${escapeHtml((err as Error).message)}</div>`;
+  }
+
+  if (endpoints.length === 0) {
+    return `<div class="tab-empty">No endpoints found in the OpenAPI spec.</div>`;
+  }
+
+  // Resolve base URLs from spec servers + env
+  const baseUrls: string[] = [];
+  if (doc.servers && doc.servers.length > 0) {
+    for (const s of doc.servers) {
+      if (s.url) baseUrls.push(s.url);
+    }
+  }
+
+  let envBaseUrl: string | undefined;
+  try {
+    const { loadEnvironment } = await import("../../core/parser/variables.ts");
+    const env = await loadEnvironment(undefined, collection.base_dir ?? collection.test_path);
+    if (env.base_url) {
+      envBaseUrl = env.base_url;
+      if (!baseUrls.includes(envBaseUrl)) baseUrls.unshift(envBaseUrl);
+    }
+  } catch { /* no env file */ }
+
+  // Base URL bar
+  const baseUrlBar = renderBaseUrlBar(baseUrls, envBaseUrl);
+
+  // Group endpoints by first tag
+  const groups = new Map<string, EndpointInfo[]>();
+  for (const ep of endpoints) {
+    const tag = ep.tags.length > 0 ? ep.tags[0]! : "Other";
+    const list = groups.get(tag) ?? [];
+    list.push(ep);
+    groups.set(tag, list);
+  }
+
+  let idx = 0;
+  const groupsHtml = [...groups.entries()].map(([tag, eps]) => {
+    const rows = eps.map(ep => {
+      const html = renderEndpointEntry(ep, idx, collection.id);
+      idx++;
+      return html;
+    }).join("");
+    return `<details class="explorer-group" open>
+      <summary class="explorer-group-title">${escapeHtml(tag)} <span class="tab-count">${eps.length}</span></summary>
+      ${rows}
+    </details>`;
+  }).join("");
+
+  const script = `<script>
+    function explorerToggle(id) {
+      var el = document.getElementById(id);
+      if (!el) return;
+      el.style.display = el.style.display === 'none' ? 'block' : 'none';
+    }
+    function explorerAddHeader(btn) {
+      var container = btn.previousElementSibling;
+      var count = container.querySelectorAll('.explorer-header-pair').length;
+      var row = document.createElement('div');
+      row.className = 'explorer-header-pair';
+      row.innerHTML = '<input type="text" name="custom_header_key_' + count + '" placeholder="Header name" class="explorer-input explorer-input-sm">' +
+        '<input type="text" name="custom_header_value_' + count + '" placeholder="Value" class="explorer-input explorer-input-sm">' +
+        '<button type="button" class="explorer-remove-btn" onclick="this.parentElement.remove()">x</button>';
+      container.appendChild(row);
+    }
+    function explorerGetBaseUrl() {
+      var sel = document.getElementById('explorer-base-url-select');
+      var custom = document.getElementById('explorer-base-url-custom');
+      if (sel && sel.value === '__custom__') return custom ? custom.value : '';
+      return sel ? sel.value : (custom ? custom.value : '');
+    }
+    function explorerBeforeRequest(formId) {
+      var form = document.getElementById(formId);
+      if (!form) return true;
+      var input = form.querySelector('input[name="base_url"]');
+      if (input) input.value = explorerGetBaseUrl();
+      return true;
+    }
+    document.addEventListener('change', function(e) {
+      if (e.target && e.target.id === 'explorer-base-url-select') {
+        var custom = document.getElementById('explorer-base-url-custom');
+        if (custom) custom.style.display = e.target.value === '__custom__' ? 'block' : 'none';
+      }
+    });
+  </script>`;
+
+  return `${baseUrlBar}<div class="explorer-list">${groupsHtml}</div>${script}`;
+}
+
+export function renderProxyResponse(status: number, headers: Record<string, string>, body: string, elapsedMs: number): string {
+  const statusClass = status < 300 ? "status-2xx" : status < 400 ? "status-3xx" : status < 500 ? "status-4xx" : "status-5xx";
+  const statusText = httpStatusText(status);
+  const size = body.length < 1024 ? `${body.length} B` : `${(body.length / 1024).toFixed(1)} KB`;
+
+  // Try to format JSON
+  let formattedBody: string;
+  const contentType = headers["content-type"] ?? "";
+  if (contentType.includes("json") || body.trimStart().startsWith("{") || body.trimStart().startsWith("[")) {
+    try {
+      const pretty = JSON.stringify(JSON.parse(body), null, 2);
+      formattedBody = highlightJson(pretty);
+    } catch {
+      formattedBody = escapeHtml(body);
+    }
+  } else {
+    formattedBody = escapeHtml(body);
+  }
+
+  const headerEntries = Object.entries(headers);
+  const headersHtml = headerEntries.length > 0
+    ? `<details class="response-headers">
+        <summary>Headers (${headerEntries.length})</summary>
+        <pre class="response-headers-pre">${headerEntries.map(([k, v]) => `<span class="json-key">${escapeHtml(k)}</span>: ${escapeHtml(v)}`).join("\n")}</pre>
+      </details>`
+    : "";
+
+  return `<div class="explorer-response">
+    <div class="response-meta">
+      <span class="response-status ${statusClass}">${status} ${escapeHtml(statusText)}</span>
+      <span class="response-time">${elapsedMs}ms</span>
+      <span class="response-size">${size}</span>
+    </div>
+    ${headersHtml}
+    <div class="response-body"><pre><code>${formattedBody}</code></pre></div>
+  </div>`;
+}
+
+export function renderProxyError(message: string, elapsedMs: number): string {
+  return `<div class="explorer-response explorer-response-error">
+    <div class="response-meta">
+      <span class="response-status status-5xx">Error</span>
+      <span class="response-time">${elapsedMs}ms</span>
+    </div>
+    <div class="response-error-msg">${escapeHtml(message)}</div>
+  </div>`;
+}
+
+// ── Private helpers ──
+
+function renderBaseUrlBar(baseUrls: string[], envBaseUrl?: string): string {
+  if (baseUrls.length === 0) {
+    return `<div class="explorer-base-url">
+      <label class="explorer-label">Base URL</label>
+      <input type="text" id="explorer-base-url-custom" class="explorer-input" placeholder="https://api.example.com" value="">
+    </div>`;
+  }
+
+  const options = baseUrls.map(url => {
+    const label = url === envBaseUrl ? `${url} (env)` : url;
+    return `<option value="${escapeHtml(url)}">${escapeHtml(label)}</option>`;
+  }).join("");
+
+  return `<div class="explorer-base-url">
+    <label class="explorer-label">Base URL</label>
+    <select id="explorer-base-url-select" class="explorer-input">
+      ${options}
+      <option value="__custom__">Custom...</option>
+    </select>
+    <input type="text" id="explorer-base-url-custom" class="explorer-input" placeholder="https://api.example.com" style="display:none;">
+  </div>`;
+}
+
+function renderEndpointEntry(ep: EndpointInfo, index: number, collectionId: number): string {
+  const formId = `explorer-form-${index}`;
+  const detailId = `explorer-detail-${index}`;
+  const responseId = `explorer-response-${index}`;
+  const spinnerId = `explorer-spinner-${index}`;
+  const deprecated = ep.deprecated ? ' <span class="warning-badge warning-deprecated">DEPRECATED</span>' : "";
+  const securityHint = ep.security.length > 0
+    ? ` <span class="explorer-auth-hint" title="Requires: ${escapeHtml(ep.security.join(", "))}">Auth</span>`
+    : "";
+
+  // Separate parameters by location
+  const pathParams = ep.parameters.filter(p => p.in === "path");
+  const queryParams = ep.parameters.filter(p => p.in === "query");
+  const headerParams = ep.parameters.filter(p => p.in === "header");
+
+  // Request body
+  const hasBody = ["POST", "PUT", "PATCH"].includes(ep.method);
+  const exampleBody = hasBody && ep.requestBodySchema
+    ? JSON.stringify(generateExample(ep.requestBodySchema), null, 2)
+    : "";
+  const bodyContentType = ep.requestBodyContentType ?? "application/json";
+
+  const paramsHtml = renderParamsSection(pathParams, queryParams, headerParams);
+  const bodyHtml = hasBody ? renderBodySection(exampleBody, bodyContentType) : "";
+  const headersHtml = renderCustomHeadersSection();
+
+  return `
+    <div class="explorer-endpoint" onclick="explorerToggle('${detailId}')">
+      ${methodBadge(ep.method)}
+      <span class="explorer-endpoint-path">${escapeHtml(ep.path)}</span>
+      ${deprecated}${securityHint}
+      ${ep.summary ? `<span class="explorer-endpoint-summary">${escapeHtml(ep.summary)}</span>` : ""}
+    </div>
+    <div class="explorer-detail" id="${detailId}" style="display:none" onclick="event.stopPropagation()">
+      <form id="${formId}" hx-post="/api/proxy" hx-target="#${responseId}" hx-swap="innerHTML"
+            hx-indicator="#${spinnerId}"
+            hx-vals='js:{"base_url": explorerGetBaseUrl()}'
+            hx-disabled-elt="find .explorer-send-btn">
+        <input type="hidden" name="method" value="${ep.method}">
+        <input type="hidden" name="path" value="${escapeHtml(ep.path)}">
+        <input type="hidden" name="collection_id" value="${collectionId}">
+        ${paramsHtml}
+        ${bodyHtml}
+        ${headersHtml}
+        <div class="explorer-actions">
+          <button type="submit" class="btn explorer-send-btn">Send</button>
+          <span id="${spinnerId}" class="htmx-indicator explorer-spinner">Sending...</span>
+        </div>
+      </form>
+      <div id="${responseId}" class="explorer-response-container"></div>
+    </div>`;
+}
+
+function renderParamsSection(
+  pathParams: OpenAPIV3.ParameterObject[],
+  queryParams: OpenAPIV3.ParameterObject[],
+  headerParams: OpenAPIV3.ParameterObject[],
+): string {
+  const all = [
+    ...pathParams.map(p => ({ ...p, prefix: "param_path_" })),
+    ...queryParams.map(p => ({ ...p, prefix: "param_query_" })),
+    ...headerParams.map(p => ({ ...p, prefix: "param_header_" })),
+  ];
+
+  if (all.length === 0) return "";
+
+  const rows = all.map(p => {
+    const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+    const type = schema?.type ?? "string";
+    const required = p.required ? '<span class="explorer-required">*</span>' : "";
+    const locationLabel = p.in === "path" ? "path" : p.in === "query" ? "query" : "header";
+    const placeholder = schema?.example != null ? String(schema.example) : (schema?.enum ? schema.enum[0] : "");
+    const defaultVal = schema?.default != null ? String(schema.default) : "";
+    const description = p.description ? ` title="${escapeHtml(p.description)}"` : "";
+
+    return `<div class="explorer-param-row"${description}>
+      <span class="explorer-param-name">${escapeHtml(p.name)}${required}</span>
+      <span class="explorer-param-location">${locationLabel}</span>
+      <span class="explorer-param-type">${escapeHtml(type)}${schema?.format ? ` (${escapeHtml(schema.format)})` : ""}</span>
+      <input type="text" name="${p.prefix}${escapeHtml(p.name)}" class="explorer-input"
+        placeholder="${escapeHtml(placeholder)}" value="${escapeHtml(defaultVal)}"
+        ${p.required ? "required" : ""}>
+    </div>`;
+  }).join("");
+
+  return `<div class="explorer-section">
+    <div class="explorer-section-title">Parameters</div>
+    ${rows}
+  </div>`;
+}
+
+function renderBodySection(exampleBody: string, contentType: string): string {
+  return `<div class="explorer-section">
+    <div class="explorer-section-title">Request Body
+      <select name="content_type" class="explorer-input explorer-input-sm explorer-content-type">
+        <option value="application/json"${contentType === "application/json" ? " selected" : ""}>application/json</option>
+        <option value="application/x-www-form-urlencoded"${contentType === "application/x-www-form-urlencoded" ? " selected" : ""}>form-urlencoded</option>
+      </select>
+    </div>
+    <textarea name="body" class="explorer-body-editor" rows="8" spellcheck="false">${escapeHtml(exampleBody)}</textarea>
+  </div>`;
+}
+
+function renderCustomHeadersSection(): string {
+  return `<div class="explorer-section">
+    <div class="explorer-section-title">Headers</div>
+    <div class="explorer-headers-list">
+      <div class="explorer-header-pair">
+        <input type="text" name="custom_header_key_0" placeholder="Header name" class="explorer-input explorer-input-sm">
+        <input type="text" name="custom_header_value_0" placeholder="Value" class="explorer-input explorer-input-sm">
+        <button type="button" class="explorer-remove-btn" onclick="this.parentElement.remove()">x</button>
+      </div>
+    </div>
+    <button type="button" class="explorer-add-header-btn" onclick="explorerAddHeader(this)">+ Add header</button>
+  </div>`;
+}
+
+function generateExample(schema: OpenAPIV3.SchemaObject, depth = 0): unknown {
+  if (depth > 5) return {};
+
+  if (schema.example !== undefined) return schema.example;
+
+  if (schema.enum && schema.enum.length > 0) return schema.enum[0];
+
+  if (schema.allOf) {
+    const merged: Record<string, unknown> = {};
+    for (const sub of schema.allOf) {
+      const s = sub as OpenAPIV3.SchemaObject;
+      const val = generateExample(s, depth + 1);
+      if (typeof val === "object" && val !== null && !Array.isArray(val)) {
+        Object.assign(merged, val);
+      }
+    }
+    return merged;
+  }
+
+  if (schema.oneOf && schema.oneOf.length > 0) {
+    return generateExample(schema.oneOf[0] as OpenAPIV3.SchemaObject, depth + 1);
+  }
+
+  if (schema.anyOf && schema.anyOf.length > 0) {
+    return generateExample(schema.anyOf[0] as OpenAPIV3.SchemaObject, depth + 1);
+  }
+
+  switch (schema.type) {
+    case "string":
+      if (schema.format === "email") return "user@example.com";
+      if (schema.format === "date") return "2026-01-01";
+      if (schema.format === "date-time") return "2026-01-01T00:00:00Z";
+      if (schema.format === "uri" || schema.format === "url") return "https://example.com";
+      if (schema.format === "uuid") return "550e8400-e29b-41d4-a716-446655440000";
+      return "string";
+    case "integer":
+      return schema.minimum != null ? schema.minimum : 0;
+    case "number":
+      return schema.minimum != null ? schema.minimum : 0.0;
+    case "boolean":
+      return true;
+    case "array": {
+      const items = schema.items as OpenAPIV3.SchemaObject | undefined;
+      if (items) return [generateExample(items, depth + 1)];
+      return [];
+    }
+    case "object":
+    default:
+      if (schema.properties) {
+        const result: Record<string, unknown> = {};
+        for (const [key, propObj] of Object.entries(schema.properties)) {
+          result[key] = generateExample(propObj as OpenAPIV3.SchemaObject, depth + 1);
+        }
+        return result;
+      }
+      return {};
+  }
+}
+
+function highlightJson(json: string): string {
+  // Split into tokens and non-token text, escape everything properly
+  const tokenRe = /("(?:\\.|[^"\\])*")\s*:|("(?:\\.|[^"\\])*")|([-]?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|\b(true|false)\b|\b(null)\b/g;
+  let result = "";
+  let lastIndex = 0;
+  let m: RegExpExecArray | null;
+
+  while ((m = tokenRe.exec(json)) !== null) {
+    // Escape text between tokens (brackets, commas, whitespace, colons)
+    if (m.index > lastIndex) {
+      result += escapeHtml(json.slice(lastIndex, m.index));
+    }
+    const [, key, str, num, bool, nil] = m;
+    if (key) result += `<span class="json-key">${escapeHtml(key)}</span>:`;
+    else if (str) result += `<span class="json-string">${escapeHtml(str)}</span>`;
+    else if (num) result += `<span class="json-number">${num}</span>`;
+    else if (bool) result += `<span class="json-boolean">${bool}</span>`;
+    else if (nil) result += `<span class="json-null">null</span>`;
+    lastIndex = tokenRe.lastIndex;
+  }
+  // Remaining text after last token
+  if (lastIndex < json.length) {
+    result += escapeHtml(json.slice(lastIndex));
+  }
+  return result;
+}
+
+function httpStatusText(code: number): string {
+  const map: Record<number, string> = {
+    200: "OK", 201: "Created", 204: "No Content",
+    301: "Moved Permanently", 302: "Found", 304: "Not Modified",
+    400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found",
+    405: "Method Not Allowed", 409: "Conflict", 422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error", 502: "Bad Gateway", 503: "Service Unavailable",
+  };
+  return map[code] ?? "";
+}