@kirrosh/zond 0.7.0

package/src/mcp/tools/setup-api.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { setupApi } from "../../core/setup-api.ts";
+import { resetDb } from "../../db/schema.ts";
+import { TOOL_DESCRIPTIONS } from "../descriptions.js";
+
+function findProjectRoot(fromPath: string): string | null {
+  let current = existsSync(fromPath) ? fromPath : dirname(fromPath);
+  while (true) {
+    if (existsSync(join(current, ".git")) || existsSync(join(current, "package.json"))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export function registerSetupApiTool(server: McpServer, dbPath?: string) {
+  server.registerTool("setup_api", {
+    description: TOOL_DESCRIPTIONS.setup_api,
+    inputSchema: {
+      name: z.string().describe("API name (e.g. 'petstore')"),
+      specPath: z.optional(z.string()).describe("Path or URL to OpenAPI spec"),
+      dir: z.optional(z.string()).describe("Base directory (default: ./apis/<name>/)"),
+      envVars: z.optional(z.string()).describe("Environment variables as JSON string (e.g. '{\"base_url\": \"...\", \"token\": \"...\"}')"),
+      force: z.optional(z.boolean()).describe("If true, delete existing API with same name and recreate from scratch"),
+    },
+  }, async ({ name, specPath, dir, envVars, force }) => {
+    try {
+      let parsedEnvVars: Record<string, string> | undefined;
+      if (envVars) {
+        try {
+          parsedEnvVars = JSON.parse(envVars);
+        } catch {
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ error: "envVars must be a valid JSON string" }, null, 2) }],
+            isError: true,
+          };
+        }
+      }
+
+      // Auto-chdir to project root when dir is an absolute path
+      if (dir && isAbsolute(resolve(dir))) {
+        const resolvedDir = resolve(dir);
+        const root = findProjectRoot(resolvedDir);
+        if (root && root !== process.cwd()) {
+          process.chdir(root);
+          resetDb();
+        }
+      }
+
+      const result = await setupApi({
+        name,
+        spec: specPath,
+        dir,
+        envVars: parsedEnvVars,
+        dbPath,
+        force,
+      });
+
+      const envFilePath = join(result.baseDir, ".env.yaml");
+      const response = {
+        ...result,
+        nextSteps: [
+          `Edit ${envFilePath} to add credentials (auth_token, api_key, base_url, etc.)`,
+          `File is already git-ignored via .gitignore`,
+          `Then run: run_tests(testPath: "${result.testPath}")`,
+        ],
+      };
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ error: (err as Error).message }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

package/src/mcp/tools/validate-tests.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { parse } from "../../core/parser/yaml-parser.ts";
+import { TOOL_DESCRIPTIONS } from "../descriptions.js";
+
+export function registerValidateTestsTool(server: McpServer) {
+  server.registerTool("validate_tests", {
+    description: TOOL_DESCRIPTIONS.validate_tests,
+    inputSchema: {
+      testPath: z.string().describe("Path to test YAML file or directory"),
+    },
+  }, async ({ testPath }) => {
+    try {
+      const suites = await parse(testPath);
+      const totalSteps = suites.reduce((sum, s) => sum + s.tests.length, 0);
+
+      const result = {
+        valid: true,
+        suites: suites.length,
+        tests: totalSteps,
+        details: suites.map(s => ({
+          name: s.name,
+          tests: s.tests.length,
+          tags: s.tags,
+          description: s.description,
+          source: (s as any)._source,
+        })),
+      };
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          valid: false,
+          error: (err as Error).message,
+        }, null, 2) }],
+        isError: true,
+      };
+    }
+  });
+}

package/src/tui/chat-ui.ts

@@ -0,0 +1,150 @@
+import { createInterface } from "readline";
+import { runAgentTurn } from "../core/agent/agent-loop.ts";
+import { trimContext } from "../core/agent/context-manager.ts";
+import type { AgentConfig, ToolEvent } from "../core/agent/types.ts";
+import type { ModelMessage } from "ai";
+
+// ── ANSI helpers ──
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const MAGENTA = "\x1b[35m";
+
+// Mouse reporting escape sequences
+const DISABLE_MOUSE = "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l";
+// Regex to strip mouse escape sequences from input
+// Covers SGR extended, X10, urxvt mouse protocols
+const MOUSE_SEQ_RE = /\x1b\[\<[\d;]*[mM]|\x1b\[M[\s\S]{3}|\x1b\[\d+;\d+;\d+M/g;
+
+function printToolEvent(event: ToolEvent) {
+  const args = Object.entries(event.args)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+    .slice(0, 3)
+    .join(", ");
+
+  const result = event.result as Record<string, unknown> | null;
+  let summary = "done";
+  if (result) {
+    if ("error" in result) summary = `error: ${result.error}`;
+    else if ("status" in result) summary = String(result.status);
+    else if ("valid" in result) summary = result.valid ? "valid" : "invalid";
+    else if ("runId" in result) summary = `run #${result.runId}`;
+  }
+
+  process.stdout.write(`  ${MAGENTA}↳ ${event.toolName}${RESET}${DIM}(${args})${RESET} → ${summary}\n`);
+}
+
+export async function startChatUI(config: AgentConfig): Promise<void> {
+  const { provider } = config.provider;
+  const model = config.provider.model;
+  const safeLabel = config.safeMode ? ` ${YELLOW}[SAFE]${RESET}` : "";
+
+  // Disable mouse reporting that may be left over from other TUI apps
+  process.stdout.write(DISABLE_MOUSE);
+
+  console.log(`\n${BOLD}${CYAN}zond chat${RESET} — ${provider}/${model}${safeLabel}`);
+  console.log(`${DIM}Commands: /clear, /tokens, /quit  |  Ctrl+C to exit${RESET}\n`);
+
+  const messages: ModelMessage[] = [];
+  let totalIn = 0;
+  let totalOut = 0;
+  let busy = false;
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: `${BOLD}${CYAN}> ${RESET}`,
+    terminal: true,
+  });
+
+  rl.prompt();
+
+  rl.on("line", async (raw: string) => {
+    // Strip mouse escape sequences that leak into input
+    const text = raw.replace(MOUSE_SEQ_RE, "").trim();
+
+    if (!text || busy) {
+      if (!busy) rl.prompt();
+      return;
+    }
+
+    if (text === "/quit" || text === "/exit") {
+      rl.close();
+      return;
+    }
+
+    if (text === "/clear") {
+      messages.length = 0;
+      totalIn = 0;
+      totalOut = 0;
+      console.log(`${DIM}Conversation cleared.${RESET}\n`);
+      rl.prompt();
+      return;
+    }
+
+    if (text === "/tokens") {
+      console.log(`${DIM}Tokens: ${totalIn} in / ${totalOut} out${RESET}\n`);
+      rl.prompt();
+      return;
+    }
+
+    busy = true;
+    messages.push({ role: "user", content: text });
+
+    // Trim context if conversation is long
+    const trimmed = trimContext(
+      messages.map((m) => ({
+        role: m.role as "user" | "assistant",
+        content: typeof m.content === "string" ? m.content : "",
+      })),
+    );
+
+    process.stdout.write(`\n${DIM}thinking...${RESET}`);
+
+    try {
+      const result = await runAgentTurn(
+        trimmed.map((m) => ({ role: m.role, content: m.content })),
+        config,
+        (event) => {
+          process.stdout.write(`\r\x1b[K`);
+          printToolEvent(event);
+          process.stdout.write(`${DIM}thinking...${RESET}`);
+        },
+      );
+
+      process.stdout.write(`\r\x1b[K`);
+
+      const responseText = result.text || "(no response)";
+      console.log(`\n${GREEN}${BOLD}AI${RESET} ${responseText}\n`);
+
+      totalIn += result.inputTokens;
+      totalOut += result.outputTokens;
+      messages.push({ role: "assistant", content: responseText });
+    } catch (err) {
+      process.stdout.write(`\r\x1b[K`);
+      console.log(`\n${YELLOW}Error: ${(err as Error).message}${RESET}\n`);
+    }
+
+    busy = false;
+    rl.prompt();
+  });
+
+  rl.on("close", () => {
+    // Disable mouse reporting on exit too
+    process.stdout.write(DISABLE_MOUSE);
+    console.log(`\n${DIM}Bye! (${totalIn} in / ${totalOut} out tokens)${RESET}`);
+    process.exit(0);
+  });
+
+  // Also disable mouse on SIGINT
+  process.on("SIGINT", () => {
+    process.stdout.write(DISABLE_MOUSE);
+    rl.close();
+  });
+
+  await new Promise<void>(() => {});
+}

package/src/web/data/collection-state.ts

@@ -0,0 +1,360 @@
+/**
+ * Unified collection state builder for Web UI.
+ * Aggregates spec endpoints, disk suites, coverage, run results, warnings, env diagnostics.
+ */
+
+import type { CollectionRecord, RunRecord, StoredStepResult } from "../../db/queries.ts";
+import { listRunsByCollection, getResultsByRunId, getRunById } from "../../db/queries.ts";
+import type { EndpointWarning } from "../../core/generator/endpoint-warnings.ts";
+import { envHint, statusHint, classifyFailure, computeSharedEnvIssue } from "../../core/diagnostics/failure-hints.ts";
+import { join, basename } from "node:path";
+
+// ── Types ──
+
+export interface CoveringStep {
+  suiteName: string;
+  file: string;            // relative filename (e.g. "auth-login.yaml")
+  stepName: string;
+  status: "pass" | "fail" | "error" | "skip" | null; // null = not run
+  responseStatus?: number;
+  durationMs?: number;
+  hint?: string;           // failure hint
+  assertions?: { field: string; rule: string; passed: boolean; actual?: unknown; expected?: unknown }[];
+}
+
+export interface EndpointViewState {
+  method: string;
+  path: string;
+  summary?: string;
+  deprecated: boolean;
+  hasCoverage: boolean;
+  runStatus: "passing" | "api_error" | "test_failed" | "not_run" | "no_tests";
+  warnings: string[];
+  coveringFiles: string[];
+  coveringSteps: CoveringStep[];
+}
+
+export interface StepViewState {
+  name: string;
+  status: "pass" | "fail" | "error" | "skip";
+  durationMs?: number;
+  requestMethod?: string;
+  requestUrl?: string;
+  responseStatus?: number;
+  responseBody?: string;
+  assertions?: { field: string; rule: string; passed: boolean; actual?: unknown; expected?: unknown }[];
+  captures?: Record<string, unknown>;
+  hint?: string;
+  errorMessage?: string;
+}
+
+export interface SuiteViewState {
+  name: string;
+  description?: string;
+  tags: string[];
+  stepCount: number;
+  filePath: string;
+  status: "passed" | "failed" | "not_run" | "parse_error";
+  runResult?: { passed: number; failed: number; skipped: number };
+  parseError?: string;
+  steps: StepViewState[];
+}
+
+export interface CollectionState {
+  collection: CollectionRecord;
+  endpoints: EndpointViewState[];
+  totalEndpoints: number;
+  coveragePct: number;
+  coveredCount: number;
+  suites: SuiteViewState[];
+  latestRun: RunRecord | null;
+  latestRunResults: StoredStepResult[];
+  envAlert: string | null;
+  warnings: EndpointWarning[];
+  // Run stats
+  runPassed: number;
+  runFailed: number;
+  runSkipped: number;
+  runTotal: number;
+  runDurationMs: number | null;
+}
+
+// ── Cache ──
+
+interface CacheEntry {
+  state: CollectionState;
+  timestamp: number;
+}
+
+const cache = new Map<number, CacheEntry>();
+const CACHE_TTL_MS = 30_000;
+
+export function invalidateCollectionCache(collectionId: number): void {
+  cache.delete(collectionId);
+}
+
+// ── Builder ──
+
+export async function buildCollectionState(collection: CollectionRecord): Promise<CollectionState> {
+  const cached = cache.get(collection.id);
+  if (cached && Date.now() - cached.timestamp < CACHE_TTL_MS) {
+    return cached.state;
+  }
+
+  // Load spec endpoints
+  let specEndpoints: import("../../core/generator/types.ts").EndpointInfo[] = [];
+  let warnings: EndpointWarning[] = [];
+  if (collection.openapi_spec) {
+    try {
+      const { readOpenApiSpec, extractEndpoints } = await import("../../core/generator/openapi-reader.ts");
+      const { analyzeEndpoints } = await import("../../core/generator/endpoint-warnings.ts");
+      const doc = await readOpenApiSpec(collection.openapi_spec);
+      specEndpoints = extractEndpoints(doc);
+      warnings = analyzeEndpoints(specEndpoints);
+    } catch { /* spec unavailable */ }
+  }
+
+  // Scan coverage from disk
+  const { scanCoveredEndpoints } = await import("../../core/generator/coverage-scanner.ts");
+  const { specPathToRegex, normalizePath } = await import("../../core/generator/coverage-scanner.ts");
+  let coveredEndpoints: import("../../core/generator/coverage-scanner.ts").CoveredEndpoint[] = [];
+  try {
+    coveredEndpoints = await scanCoveredEndpoints(collection.test_path);
+  } catch { /* no tests on disk */ }
+
+  // Parse suites from disk
+  const { parseDirectorySafe } = await import("../../core/parser/yaml-parser.ts");
+  let diskSuites: import("../../core/parser/yaml-parser.ts").ParseDirectoryResult = { suites: [], errors: [] };
+  try {
+    diskSuites = await parseDirectorySafe(collection.test_path);
+  } catch { /* test dir missing */ }
+
+  // Get latest run
+  const runs = listRunsByCollection(collection.id, 1, 0);
+  const latestRun = runs.length > 0 ? (getRunById(runs[0]!.id) ?? null) : null;
+  const latestRunResults = latestRun ? getResultsByRunId(latestRun.id) : [];
+
+  // Build result maps: suite_name -> step statuses
+  const suiteResultMap = new Map<string, StoredStepResult[]>();
+  for (const r of latestRunResults) {
+    const list = suiteResultMap.get(r.suite_name) ?? [];
+    list.push(r);
+    suiteResultMap.set(r.suite_name, list);
+  }
+
+  // Build endpoint -> run status map
+  // key: "METHOD /path" from results
+  const endpointRunStatusMap = new Map<string, "passing" | "api_error" | "test_failed">();
+  for (const r of latestRunResults) {
+    if (r.request_method && r.request_url) {
+      // Extract path from URL
+      let urlPath: string;
+      try {
+        const u = new URL(r.request_url);
+        urlPath = u.pathname;
+      } catch {
+        urlPath = r.request_url;
+      }
+      const key = `${r.request_method} ${normalizePath(urlPath)}`;
+      const current = endpointRunStatusMap.get(key);
+      if (r.status === "fail" || r.status === "error") {
+        const ft = classifyFailure(r.status, r.response_status);
+        endpointRunStatusMap.set(key, ft === "api_error" ? "api_error" : "test_failed");
+      } else if (r.status === "pass" && current !== "test_failed" && current !== "api_error") {
+        endpointRunStatusMap.set(key, "passing");
+      }
+    }
+  }
+
+  // Build endpoint view states
+  const warningsMap = new Map<string, string[]>();
+  for (const w of warnings) {
+    warningsMap.set(`${w.method} ${w.path}`, w.warnings);
+  }
+
+  // Build map: normalized "METHOD /path" -> list of StoredStepResult
+  const resultsByEndpoint = new Map<string, StoredStepResult[]>();
+  for (const r of latestRunResults) {
+    if (r.request_method && r.request_url) {
+      let urlPath: string;
+      try { urlPath = new URL(r.request_url).pathname; } catch { urlPath = r.request_url; }
+      const key = `${r.request_method} ${normalizePath(urlPath)}`;
+      const list = resultsByEndpoint.get(key) ?? [];
+      list.push(r);
+      resultsByEndpoint.set(key, list);
+    }
+  }
+
+  // Map suite name -> file basename for display
+  const suiteNameToFile = new Map<string, string>();
+  for (const s of diskSuites.suites) {
+    suiteNameToFile.set(s.name, basename(s.filePath ?? s.name));
+  }
+
+  // Env file path for hints
+  const envFilePath = collection.base_dir
+    ? join(collection.base_dir, ".env.yaml").replace(/\\/g, "/")
+    : undefined;
+
+  const endpoints: EndpointViewState[] = specEndpoints.map(ep => {
+    const specRegex = specPathToRegex(ep.path);
+    const covering = coveredEndpoints.filter(
+      c => c.method === ep.method && specRegex.test(normalizePath(c.path)),
+    );
+    const hasCoverage = covering.length > 0;
+
+    // Determine run status
+    let runStatus: EndpointViewState["runStatus"] = "no_tests";
+    if (hasCoverage) {
+      runStatus = "not_run";
+      for (const [key, status] of endpointRunStatusMap) {
+        const [method, path] = [key.split(" ")[0], key.split(" ").slice(1).join(" ")];
+        if (method === ep.method && specRegex.test(path!)) {
+          runStatus = status;
+          break;
+        }
+      }
+    }
+
+    // Build covering steps from run results
+    const coveringSteps: CoveringStep[] = [];
+    for (const [key, results] of resultsByEndpoint) {
+      const [method, path] = [key.split(" ")[0], key.split(" ").slice(1).join(" ")];
+      if (method === ep.method && specRegex.test(path!)) {
+        for (const r of results) {
+          const hint = (r.status === "fail" || r.status === "error")
+            ? (envHint(r.request_url, r.error_message, envFilePath) ?? statusHint(r.response_status) ?? undefined)
+            : undefined;
+          coveringSteps.push({
+            suiteName: r.suite_name,
+            file: suiteNameToFile.get(r.suite_name) ?? r.suite_name,
+            stepName: r.test_name,
+            status: r.status as CoveringStep["status"],
+            responseStatus: r.response_status ?? undefined,
+            durationMs: r.duration_ms ?? undefined,
+            hint,
+            assertions: Array.isArray(r.assertions) ? r.assertions : undefined,
+          });
+        }
+      }
+    }
+
+    return {
+      method: ep.method,
+      path: ep.path,
+      summary: ep.summary,
+      deprecated: ep.deprecated ?? false,
+      hasCoverage,
+      runStatus,
+      warnings: warningsMap.get(`${ep.method} ${ep.path}`) ?? [],
+      coveringFiles: covering.map(c => c.file),
+      coveringSteps,
+    };
+  });
+
+  // Coverage stats
+  const totalEndpoints = endpoints.length;
+  const coveredCount = endpoints.filter(e => e.hasCoverage).length;
+  const coveragePct = totalEndpoints > 0 ? Math.round((coveredCount / totalEndpoints) * 100) : 0;
+
+  // Build suite view states
+  const suites: SuiteViewState[] = diskSuites.suites.map(s => {
+    const results = suiteResultMap.get(s.name);
+    let status: SuiteViewState["status"] = "not_run";
+    let runResult: SuiteViewState["runResult"] | undefined;
+    const steps: StepViewState[] = [];
+
+    if (results) {
+      const passed = results.filter(r => r.status === "pass").length;
+      const failed = results.filter(r => r.status === "fail" || r.status === "error").length;
+      const skipped = results.filter(r => r.status === "skip").length;
+      runResult = { passed, failed, skipped };
+      status = failed > 0 ? "failed" : "passed";
+
+      for (const r of results) {
+        const hint = (r.status === "fail" || r.status === "error")
+          ? (envHint(r.request_url, r.error_message, envFilePath) ?? statusHint(r.response_status) ?? undefined)
+          : undefined;
+        steps.push({
+          name: r.test_name,
+          status: r.status as StepViewState["status"],
+          durationMs: r.duration_ms ?? undefined,
+          requestMethod: r.request_method ?? undefined,
+          requestUrl: r.request_url ?? undefined,
+          responseStatus: r.response_status ?? undefined,
+          responseBody: r.response_body ?? undefined,
+          assertions: Array.isArray(r.assertions) ? r.assertions : undefined,
+          captures: r.captures && typeof r.captures === "object" ? r.captures as Record<string, unknown> : undefined,
+          hint,
+          errorMessage: r.error_message ?? undefined,
+        });
+      }
+    }
+
+    return {
+      name: s.name,
+      description: s.description,
+      tags: s.tags ?? [],
+      stepCount: s.tests.length,
+      filePath: s.filePath ?? "",
+      status,
+      runResult,
+      steps,
+    };
+  });
+
+  // Add parse errors as suites
+  for (const err of diskSuites.errors) {
+    suites.push({
+      name: err.file,
+      tags: [],
+      stepCount: 0,
+      filePath: err.file,
+      status: "parse_error",
+      parseError: err.error,
+      steps: [],
+    });
+  }
+
+  // Env diagnostics
+  let envAlert: string | null = null;
+  const failedResults = latestRunResults.filter(r => r.status === "fail" || r.status === "error");
+  if (failedResults.length > 0) {
+    const envFilePath = collection.base_dir
+      ? join(collection.base_dir, ".env.yaml").replace(/\\/g, "/")
+      : undefined;
+
+    const failuresWithHints = failedResults.map(r => ({
+      hint: envHint(r.request_url, r.error_message, envFilePath) ?? undefined,
+    }));
+    envAlert = computeSharedEnvIssue(failuresWithHints, envFilePath);
+  }
+
+  // Run stats
+  const runPassed = latestRun?.passed ?? 0;
+  const runFailed = latestRun?.failed ?? 0;
+  const runSkipped = latestRun?.skipped ?? 0;
+  const runTotal = latestRun?.total ?? 0;
+  const runDurationMs = latestRun?.duration_ms ?? null;
+
+  const state: CollectionState = {
+    collection,
+    endpoints,
+    totalEndpoints,
+    coveragePct,
+    coveredCount,
+    suites,
+    latestRun,
+    latestRunResults,
+    envAlert,
+    warnings,
+    runPassed,
+    runFailed,
+    runSkipped,
+    runTotal,
+    runDurationMs,
+  };
+
+  cache.set(collection.id, { state, timestamp: Date.now() });
+  return state;
+}