@kirrosh/zond 0.14.0 → 0.17.0

package/src/cli/commands/export.ts

@@ -0,0 +1,144 @@
+import { dirname, basename, join } from "path";
+import { parse } from "../../core/parser/yaml-parser.ts";
+import {
+  buildCollection,
+  buildEnvironment,
+  deriveCollectionName,
+} from "../../core/exporter/postman.ts";
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface ExportOptions {
+  testsPath: string;
+  output: string;
+  env?: string;
+  collectionName?: string;
+  json?: boolean;
+}
+
+export async function exportCommand(options: ExportOptions): Promise<number> {
+  // 1. Parse test suites
+  let suites;
+  try {
+    suites = await parse(options.testsPath);
+  } catch (err) {
+    const msg = `Failed to parse tests: ${(err as Error).message}`;
+    if (options.json) {
+      printJson(jsonError("export postman", [msg]));
+    } else {
+      printError(msg);
+    }
+    return 2;
+  }
+
+  if (suites.length === 0) {
+    const msg = "No test suites found";
+    if (options.json) {
+      printJson(jsonError("export postman", [msg]));
+    } else {
+      printError(msg);
+    }
+    return 1;
+  }
+
+  // 2. Derive collection name
+  const collectionName =
+    options.collectionName ?? deriveCollectionName(options.testsPath);
+
+  // 3. Build collection
+  const { collection, warnings } = buildCollection(suites, collectionName);
+
+  // Count total items across all folders
+  const totalItems = collection.item.reduce((sum, folder) => sum + folder.item.length, 0);
+
+  // 4. Write collection file
+  try {
+    await Bun.write(options.output, JSON.stringify(collection, null, 2));
+  } catch (err) {
+    const msg = `Failed to write collection file: ${(err as Error).message}`;
+    if (options.json) {
+      printJson(jsonError("export postman", [msg], warnings));
+    } else {
+      printError(msg);
+    }
+    return 2;
+  }
+
+  // 5. Optional env export
+  let envOutput: string | undefined;
+  if (options.env) {
+    let envVars: Record<string, string>;
+    try {
+      const text = await Bun.file(options.env).text();
+      const parsed = Bun.YAML.parse(text);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Environment file must be a YAML object");
+      }
+      // Convert all values to strings
+      envVars = {};
+      for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+        envVars[k] = String(v);
+      }
+    } catch (err) {
+      const msg = `Failed to read env file: ${(err as Error).message}`;
+      if (options.json) {
+        printJson(jsonError("export postman", [msg], warnings));
+      } else {
+        printError(msg);
+      }
+      return 2;
+    }
+
+    // Derive env name: e.g. ".env.staging.yaml" → "staging", ".env.yaml" → collectionName
+    const envBasename = basename(options.env);
+    const envNameMatch = envBasename.match(/^\.?env\.(.+?)\.ya?ml$/);
+    const envName = envNameMatch ? envNameMatch[1]! : collectionName;
+
+    const environment = buildEnvironment(envVars, envName);
+
+    // Output path: same directory as output, same base name with .postman_environment.json
+    const outBase = basename(options.output).replace(/\.postman\.json$/, "").replace(/\.json$/, "");
+    const outDir = dirname(options.output);
+    envOutput = join(outDir, `${outBase}.postman_environment.json`);
+
+    try {
+      await Bun.write(envOutput, JSON.stringify(environment, null, 2));
+    } catch (err) {
+      const msg = `Failed to write environment file: ${(err as Error).message}`;
+      if (options.json) {
+        printJson(jsonError("export postman", [msg], warnings));
+      } else {
+        printError(msg);
+      }
+      return 2;
+    }
+  }
+
+  // 6. Output result
+  if (options.json) {
+    printJson(
+      jsonOk(
+        "export postman",
+        {
+          output: options.output,
+          suites: suites.length,
+          items: totalItems,
+          ...(envOutput !== undefined ? { envOutput } : {}),
+        },
+        warnings
+      )
+    );
+  } else {
+    for (const w of warnings) {
+      printWarning(w);
+    }
+    printSuccess(
+      `Exported ${suites.length} suite(s) / ${totalItems} request(s) → ${options.output}`
+    );
+    if (envOutput) {
+      printSuccess(`Environment exported → ${envOutput}`);
+    }
+  }
+
+  return 0;
+}

package/src/cli/commands/generate.ts

@@ -0,0 +1,158 @@
+import { join, dirname } from "path";
+import { mkdir } from "fs/promises";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  scanCoveredEndpoints,
+  filterUncoveredEndpoints,
+  serializeSuite,
+} from "../../core/generator/index.ts";
+import { generateSuites } from "../../core/generator/suite-generator.ts";
+import { filterByTag } from "../../core/generator/chunker.ts";
+import { parse } from "../../core/parser/yaml-parser.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";
+import { version as ZOND_VERSION } from "../../../package.json";
+import { getDb } from "../../db/schema.ts";
+import { findCollectionByTestPath, updateCollection } from "../../db/queries.ts";
+
+export interface GenerateOptions {
+  specPath: string;
+  output: string;
+  tag?: string;
+  uncoveredOnly?: boolean;
+  json?: boolean;
+}
+
+export async function generateCommand(options: GenerateOptions): Promise<number> {
+  try {
+    const doc = await readOpenApiSpec(options.specPath);
+    let endpoints = extractEndpoints(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+    const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
+    const warnings: string[] = [];
+
+    // Filter to uncovered only
+    if (options.uncoveredOnly) {
+      const covered = await scanCoveredEndpoints(options.output);
+      const before = endpoints.length;
+      endpoints = filterUncoveredEndpoints(endpoints, covered);
+      const coveredCount = before - endpoints.length;
+      if (coveredCount > 0) {
+        warnings.push(`Skipped ${coveredCount} already-covered endpoints`);
+      }
+    }
+
+    // Filter by tag
+    if (options.tag) {
+      endpoints = filterByTag(endpoints, options.tag);
+    }
+
+    if (endpoints.length === 0) {
+      if (options.json) {
+        printJson(jsonOk("generate", { files: [], message: "No endpoints to generate tests for" }, warnings));
+      } else {
+        console.log("No endpoints to generate tests for.");
+      }
+      return 0;
+    }
+
+    // Generate suites
+    const suites = generateSuites({ endpoints, securitySchemes });
+
+    // Ensure output directory exists
+    await mkdir(options.output, { recursive: true });
+
+    // Write suite files
+    const createdFiles: Array<{ file: string; suite: string; tests: number }> = [];
+
+    // Build metadata for written files
+    const metaFiles: Record<string, import("../../core/meta/types.ts").FileMeta> = {};
+
+    for (const suite of suites) {
+      const yaml = serializeSuite(suite);
+      const fileName = `${suite.fileStem ?? suite.name}.yaml`;
+      const filePath = join(options.output, fileName);
+      await Bun.write(filePath, yaml);
+      createdFiles.push({ file: filePath, suite: suite.name, tests: suite.tests.length });
+      metaFiles[fileName] = buildFileMeta(suite, ZOND_VERSION);
+    }
+
+    // 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);
+    await writeMeta(options.output, {
+      zondVersion: ZOND_VERSION,
+      lastSyncedAt: new Date().toISOString(),
+      specUrl: options.specPath,
+      specHash: hashSpec(specContent),
+      files: { ...(existingMeta?.files ?? {}), ...metaFiles },
+    });
+
+    // Sync DB collection spec reference if one is registered for this output directory
+    try {
+      getDb();
+      const collection = findCollectionByTestPath(options.output);
+      if (collection && collection.openapi_spec !== options.specPath) {
+        updateCollection(collection.id, { openapi_spec: options.specPath });
+        warnings.push(`Updated collection '${collection.name}' spec reference → ${options.specPath}`);
+      }
+    } catch {
+      // DB unavailable — not fatal
+    }
+
+    // Create .env.yaml with base_url if it doesn't exist
+    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`);
+    }
+
+    // Validate generated files
+    const validationErrors: string[] = [];
+    try {
+      await parse(options.output);
+    } catch (err) {
+      validationErrors.push(err instanceof Error ? err.message : String(err));
+    }
+
+    if (validationErrors.length > 0) {
+      warnings.push(`Validation warnings: ${validationErrors.join("; ")}`);
+    }
+
+    // Output
+    const totalTests = createdFiles.reduce((sum, f) => sum + f.tests, 0);
+
+    if (options.json) {
+      printJson(jsonOk("generate", {
+        files: createdFiles,
+        totalSuites: suites.length,
+        totalTests,
+        outputDir: options.output,
+      }, warnings));
+    } else {
+      printSuccess(`Generated ${suites.length} suite(s) with ${totalTests} test(s) in ${options.output}`);
+      for (const f of createdFiles) {
+        console.log(`  ${f.file} (${f.tests} tests)`);
+      }
+      if (warnings.length > 0) {
+        for (const w of warnings) {
+          console.log(`  ⚠ ${w}`);
+        }
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("generate", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/guide.ts

@@ -0,0 +1,127 @@
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  scanCoveredEndpoints,
+  filterUncoveredEndpoints,
+} from "../../core/generator/index.ts";
+import { compressEndpointsWithSchemas, buildGenerationGuide } from "../../core/generator/guide-builder.ts";
+import { planChunks, filterByTag } from "../../core/generator/chunker.ts";
+import { findCollectionBySpec } from "../../db/queries.ts";
+import { printError } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface GuideOptions {
+  specPath: string;
+  testsDir?: string;
+  tag?: string;
+  json?: boolean;
+}
+
+export async function guideCommand(options: GuideOptions): Promise<number> {
+  try {
+    const doc = await readOpenApiSpec(options.specPath);
+    let endpoints = extractEndpoints(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+    const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
+    const title = (doc as any).info?.title as string | undefined;
+
+    let outputDir = options.testsDir;
+    if (!outputDir) {
+      try {
+        const collection = findCollectionBySpec(options.specPath);
+        outputDir = collection?.test_path ?? "./tests/";
+      } catch {
+        outputDir = "./tests/";
+      }
+    }
+
+    let coverageInfo: { covered: number; total: number; percentage: number } | undefined;
+    if (options.testsDir) {
+      const totalBefore = endpoints.length;
+      const covered = await scanCoveredEndpoints(options.testsDir);
+      const uncovered = filterUncoveredEndpoints(endpoints, covered);
+      const coveredCount = totalBefore - uncovered.length;
+      const percentage = totalBefore > 0 ? Math.round((coveredCount / totalBefore) * 100) : 100;
+      coverageInfo = { covered: coveredCount, total: totalBefore, percentage };
+      endpoints = uncovered;
+    }
+
+    if (endpoints.length === 0) {
+      if (options.json) {
+        printJson(jsonOk("guide", { fullyCovered: true, ...coverageInfo }));
+      } else {
+        console.log("All endpoints are covered.");
+      }
+      return 0;
+    }
+
+    if (options.tag) {
+      endpoints = filterByTag(endpoints, options.tag);
+      if (endpoints.length === 0) {
+        const msg = `No endpoints found for tag "${options.tag}"`;
+        if (options.json) printJson(jsonError("guide", [msg]));
+        else printError(msg);
+        return 1;
+      }
+    }
+
+    const plan = planChunks(endpoints);
+
+    if (plan.needsChunking && !options.tag) {
+      if (options.json) {
+        printJson(jsonOk("guide", {
+          mode: "plan",
+          title: title ?? "API",
+          totalEndpoints: plan.totalEndpoints,
+          chunks: plan.chunks,
+          ...(coverageInfo ? { coverage: coverageInfo } : {}),
+        }));
+      } else {
+        console.log(`API has ${plan.totalEndpoints} endpoints across ${plan.chunks.length} tags.`);
+        console.log("Generate per-tag with --tag <name>:\n");
+        for (const chunk of plan.chunks) {
+          console.log(`  --tag ${chunk.tag} (${chunk.count} endpoints)`);
+        }
+      }
+      return 0;
+    }
+
+    const coverageHeader = coverageInfo
+      ? `## Coverage: ${coverageInfo.covered}/${coverageInfo.total} endpoints covered (${coverageInfo.percentage}%). Generating tests for ${endpoints.length} uncovered endpoints:`
+      : undefined;
+
+    const apiContext = compressEndpointsWithSchemas(endpoints, securitySchemes);
+    const guide = buildGenerationGuide({
+      title: options.tag ? `${title ?? "API"} — tag: ${options.tag}` : (title ?? "API"),
+      baseUrl,
+      apiContext,
+      outputDir,
+      securitySchemes,
+      endpointCount: endpoints.length,
+      coverageHeader,
+      includeFormat: true,
+    });
+
+    if (options.json) {
+      printJson(jsonOk("guide", {
+        title: title ?? "API",
+        endpointCount: endpoints.length,
+        outputDir,
+        guide,
+        ...(coverageInfo ? { coverage: coverageInfo } : {}),
+      }));
+    } else {
+      console.log(guide);
+    }
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("guide", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,57 @@
+import { setupApi } from "../../core/setup-api.ts";
+import { printError, printSuccess } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface InitOptions {
+  name?: string;
+  spec?: string;
+  baseUrl?: string;
+  dir?: string;
+  force?: boolean;
+  insecure?: boolean;
+  dbPath?: string;
+  json?: boolean;
+}
+
+export async function initCommand(options: InitOptions): Promise<number> {
+  try {
+    const envVars: Record<string, string> = {};
+    if (options.baseUrl) envVars.base_url = options.baseUrl;
+
+    const result = await setupApi({
+      name: options.name,
+      spec: options.spec,
+      dir: options.dir,
+      envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
+      dbPath: options.dbPath,
+      force: options.force,
+      insecure: options.insecure,
+    });
+
+    if (options.json) {
+      printJson(jsonOk("init", {
+        collectionId: result.collectionId,
+        baseDir: result.baseDir,
+        testPath: result.testPath,
+        endpoints: result.specEndpoints,
+        warnings: result.warnings ?? [],
+      }, result.warnings));
+    } else {
+      printSuccess(`Created API '${options.name ?? "api"}' at ${result.baseDir} (${result.specEndpoints} endpoints)`);
+      if (result.warnings) {
+        for (const w of result.warnings) {
+          process.stderr.write(`Warning: ${w}\n`);
+        }
+      }
+    }
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("init", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/request.ts

@@ -0,0 +1,57 @@
+import { sendAdHocRequest } from "../../core/runner/send-request.ts";
+import { printError } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+
+export interface RequestOptions {
+  method: string;
+  url: string;
+  headers?: string[];
+  body?: string;
+  timeout?: number;
+  env?: string;
+  api?: string;
+  jsonPath?: string;
+  dbPath?: string;
+  json?: boolean;
+}
+
+export async function requestCommand(options: RequestOptions): Promise<number> {
+  try {
+    const headers: Record<string, string> = {};
+    if (options.headers) {
+      for (const h of options.headers) {
+        const colonIdx = h.indexOf(":");
+        if (colonIdx > 0) {
+          headers[h.slice(0, colonIdx).trim()] = h.slice(colonIdx + 1).trim();
+        }
+      }
+    }
+
+    const result = await sendAdHocRequest({
+      method: options.method.toUpperCase(),
+      url: options.url,
+      headers: Object.keys(headers).length > 0 ? headers : undefined,
+      body: options.body,
+      timeout: options.timeout,
+      envName: options.env,
+      collectionName: options.api,
+      jsonPath: options.jsonPath,
+      dbPath: options.dbPath,
+    });
+
+    if (options.json) {
+      printJson(jsonOk("request", result));
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("request", [message]));
+    } else {
+      printError(message);
+    }
+    return 1;
+  }
+}

package/src/cli/commands/run.ts

@@ -9,8 +9,10 @@ import type { ReporterName } from "../../core/reporter/types.ts";
 import type { TestSuite } from "../../core/parser/types.ts";
 import type { TestRunResult } from "../../core/runner/types.ts";
 import { printError, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 import { getDb } from "../../db/schema.ts";
 import { createRun, finalizeRun, saveResults, findCollectionByTestPath } from "../../db/queries.ts";
+import { AUTH_PATH_RE } from "../../core/runner/execute-run.ts";
 
 export interface RunOptions {
   path: string;
@@ -25,6 +27,7 @@ export interface RunOptions {
   tag?: string[];
   envVars?: string[];
   dryRun?: boolean;
+  json?: boolean;
 }
 
 export async function runCommand(options: RunOptions): Promise<number> {
@@ -51,14 +54,18 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   }
 
-  // 1c. Safe mode: filter to GET-only tests
+  // 1c. Safe mode: keep GET, set-only steps, and auth-related requests
   if (options.safe) {
     for (const suite of suites) {
-      suite.tests = suite.tests.filter(t => t.method === "GET");
+      suite.tests = suite.tests.filter(t => {
+        if (t.method === "GET" || !t.method) return true;
+        if (AUTH_PATH_RE.test(t.path)) return true;
+        return false;
+      });
     }
     suites = suites.filter(s => s.tests.length > 0);
     if (suites.length === 0) {
-      printWarning("No GET tests found. Nothing to run in safe mode.");
+      printWarning("No safe tests found. Nothing to run in safe mode.");
       return 0;
     }
   }
@@ -110,13 +117,30 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   }
 
-  // 4. Run suites
+  // 4. Run suites — setup suites run first (sequentially), their captures flow into regular suites
   const results: TestRunResult[] = [];
   const dryRun = options.dryRun === true;
+
+  const setupSuites = suites.filter(s => s.setup);
+  const regularSuites = suites.filter(s => !s.setup);
+  const setupCaptures: Record<string, string> = {};
+
+  for (const suite of setupSuites) {
+    const result = await runSuite(suite, env, dryRun);
+    results.push(result);
+    for (const step of result.steps) {
+      for (const [k, v] of Object.entries(step.captures)) {
+        setupCaptures[k] = String(v);
+      }
+    }
+  }
+
+  const enrichedEnv = { ...env, ...setupCaptures };
+
   if (options.bail) {
     // Sequential with bail at suite level
-    for (const suite of suites) {
-      const result = await runSuite(suite, env, dryRun);
+    for (const suite of regularSuites) {
+      const result = await runSuite(suite, enrichedEnv, dryRun);
       results.push(result);
       if (!dryRun && (result.failed > 0 || result.steps.some((s) => s.status === "error"))) {
         break;
@@ -124,33 +148,69 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   } else {
     // Parallel
-    const all = await Promise.all(suites.map((suite) => runSuite(suite, env, dryRun)));
+    const all = await Promise.all(regularSuites.map((suite) => runSuite(suite, enrichedEnv, dryRun)));
     results.push(...all);
   }
 
-  // 5. Report
-  const reporter = getReporter(options.report);
-  reporter.report(results);
+  // 5. Collect warnings
+  const warnings: string[] = [];
+  const rateLimited = results.flatMap(r => r.steps)
+    .filter(s => s.response?.status === 429);
+  if (rateLimited.length > 0) {
+    warnings.push(`${rateLimited.length} request(s) hit rate limit (429). Consider: consolidating login steps, adding --bail, or using retry_until with delay.`);
+  }
+
+  // 5b. Report
+  if (!options.json) {
+    const reporter = getReporter(options.report);
+    reporter.report(results);
+    for (const w of warnings) {
+      printWarning(w);
+    }
+  }
 
   // 6. Save to DB
+  let savedRunId: number | undefined;
   if (!options.noDb) {
     try {
       getDb(options.dbPath);
       const collection = findCollectionByTestPath(options.path);
-      const runId = createRun({
+      savedRunId = createRun({
         started_at: results[0]?.started_at ?? new Date().toISOString(),
         environment: options.env,
         collection_id: collection?.id,
       });
-      finalizeRun(runId, results);
-      saveResults(runId, results);
+      finalizeRun(savedRunId, results);
+      saveResults(savedRunId, results);
     } catch (err) {
       printWarning(`Failed to save results to DB: ${(err as Error).message}`);
     }
   }
 
   // 7. Exit code (always 0 in dry-run mode)
-  if (dryRun) return 0;
+  if (dryRun) {
+    if (options.json) {
+      printJson(jsonOk("run", { summary: { total: results.length, passed: 0, failed: 0 }, dryRun: true }));
+    }
+    return 0;
+  }
   const hasFailures = results.some((r) => r.failed > 0 || r.steps.some((s) => s.status === "error"));
+
+  if (options.json) {
+    const total = results.reduce((s, r) => s + r.total, 0);
+    const passed = results.reduce((s, r) => s + r.passed, 0);
+    const failed = results.reduce((s, r) => s + r.failed, 0);
+    const failures = results.flatMap(r =>
+      r.steps.filter(s => s.status === "fail" || s.status === "error").map(s => ({
+        suite: r.suite_name,
+        test: s.name,
+        ...(r.suite_file ? { file: r.suite_file } : {}),
+        status: s.status,
+        error: s.error,
+      }))
+    );
+    printJson(jsonOk("run", { summary: { total, passed, failed }, failures, warnings, runId: savedRunId }));
+  }
+
   return hasFailures ? 1 : 0;
 }