@kirrosh/zond 0.16.0 → 0.18.0

package/src/cli/commands/sync.ts

@@ -0,0 +1,241 @@
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  serializeSuite,
+} from "../../core/generator/index.ts";
+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";
+import { getDb } from "../../db/schema.ts";
+import { findCollectionByTestPath, updateCollection } from "../../db/queries.ts";
+
+export interface SyncOptions {
+  specPath: string;
+  testsDir: string;
+  dryRun?: boolean;
+  tag?: string;
+  json?: boolean;
+}
+
+export async function syncCommand(options: SyncOptions): Promise<number> {
+  try {
+    // Load existing metadata
+    const meta = await readMeta(options.testsDir);
+    if (!meta) {
+      const msg =
+        "No .zond-meta.json found. Run `zond generate <spec> --output <dir>` first to initialize metadata.";
+      if (options.json) {
+        printJson(jsonError("sync", [msg]));
+      } else {
+        printError(msg);
+      }
+      return 2;
+    }
+
+    // Load current spec
+    const doc = await readOpenApiSpec(options.specPath);
+    const specContent = JSON.stringify(decycleSchema(doc));
+    const currentHash = hashSpec(specContent);
+
+    if (currentHash === meta.specHash) {
+      const msg = "Spec unchanged — nothing to sync.";
+      if (options.json) {
+        printJson(jsonOk("sync", { newEndpoints: [], generatedFiles: [], removedKeys: [], specChanged: false }, [msg]));
+      } else {
+        console.log(msg);
+      }
+      return 0;
+    }
+
+    // Extract current endpoints
+    let currentEndpoints = extractEndpoints(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+
+    if (options.tag) {
+      currentEndpoints = filterByTag(currentEndpoints, options.tag);
+    }
+
+    // Collect all previously known endpoint keys from meta
+    const prevKeys = Object.values(meta.files).flatMap((f) => f.endpoints);
+
+    // Compute diff
+    const { newEndpoints, removedKeys } = diffEndpoints(prevKeys, currentEndpoints);
+
+    const warnings: string[] = [];
+
+    if (removedKeys.length > 0) {
+      for (const key of removedKeys) {
+        warnings.push(`Removed endpoint not deleted from tests (review manually): ${key}`);
+      }
+    }
+
+    if (newEndpoints.length === 0) {
+      const msg = "Spec changed (hash differs) but no new endpoints detected. Existing tests may need manual review.";
+      warnings.push(msg);
+      if (options.json) {
+        printJson(jsonOk("sync", {
+          newEndpoints: [],
+          removedKeys,
+          generatedFiles: [],
+          specChanged: true,
+        }, warnings));
+      } else {
+        console.log(msg);
+        for (const w of warnings) {
+          printWarning(w);
+        }
+      }
+      return 0;
+    }
+
+    // Generate suites for new endpoints only
+    const suites = generateSuites({ endpoints: newEndpoints, securitySchemes });
+
+    if (options.dryRun) {
+      const newEndpointKeys = newEndpoints.map((ep) => `${ep.method.toUpperCase()} ${ep.path}`);
+      const plannedFiles = suites.map((s) => ({
+        file: `${s.fileStem ?? s.name}.yaml`,
+        suite: s.name,
+        tests: s.tests.length,
+      }));
+
+      if (options.json) {
+        printJson(jsonOk("sync", {
+          dryRun: true,
+          newEndpoints: newEndpointKeys,
+          removedKeys,
+          plannedFiles,
+          specChanged: true,
+        }, warnings));
+      } else {
+        console.log(`[dry-run] Detected ${newEndpoints.length} new endpoint(s):`);
+        for (const ep of newEndpoints) {
+          console.log(`  + ${ep.method.toUpperCase()} ${ep.path}`);
+        }
+        console.log(`\nWould generate ${suites.length} new suite file(s):`);
+        for (const f of plannedFiles) {
+          console.log(`  ${f.file}  (${f.tests} tests)`);
+        }
+        if (removedKeys.length > 0) {
+          console.log("\nRemoved endpoints (not deleted — review tests):");
+          for (const key of removedKeys) {
+            console.log(`  - ${key}`);
+          }
+        }
+        console.log("\nNo files written (dry-run).");
+      }
+      return 0;
+    }
+
+    // Write new files (skip if file already exists)
+    await mkdir(options.testsDir, { recursive: true });
+
+    const generatedFiles: Array<{ file: string; suite: string; tests: number }> = [];
+    const skippedFiles: string[] = [];
+    const updatedMetaFiles: Record<string, import("../../core/meta/types.ts").FileMeta> = {};
+
+    for (const suite of suites) {
+      const fileName = `${suite.fileStem ?? suite.name}.yaml`;
+      const filePath = join(options.testsDir, fileName);
+      const existing = Bun.file(filePath);
+
+      if (await existing.exists()) {
+        skippedFiles.push(fileName);
+        warnings.push(`Skipped ${fileName} (already exists — add new endpoints manually)`);
+        continue;
+      }
+
+      const yaml = serializeSuite(suite);
+      await Bun.write(filePath, yaml);
+      generatedFiles.push({ file: filePath, suite: suite.name, tests: suite.tests.length });
+      updatedMetaFiles[fileName] = buildFileMeta(suite, ZOND_VERSION);
+    }
+
+    // Update metadata: merge new file entries, update hash and timestamp
+    await writeMeta(options.testsDir, {
+      zondVersion: ZOND_VERSION,
+      lastSyncedAt: new Date().toISOString(),
+      specUrl: options.specPath,
+      specHash: currentHash,
+      files: { ...meta.files, ...updatedMetaFiles },
+    });
+
+    // Sync DB collection if one is registered for this tests directory
+    try {
+      getDb();
+      const collection = findCollectionByTestPath(options.testsDir);
+      if (collection && collection.openapi_spec !== options.specPath) {
+        updateCollection(collection.id, { openapi_spec: options.specPath });
+        warnings.push(`Updated collection '${collection.name}' spec reference: ${collection.openapi_spec ?? "(none)"} → ${options.specPath}`);
+      }
+    } catch {
+      // DB unavailable (e.g. no zond.db yet) — not a fatal error for sync
+    }
+
+    const newEndpointKeys = newEndpoints.map((ep) => `${ep.method.toUpperCase()} ${ep.path}`);
+
+    if (options.json) {
+      printJson(jsonOk("sync", {
+        newEndpoints: newEndpointKeys,
+        removedKeys,
+        generatedFiles,
+        skippedFiles,
+        specChanged: true,
+      }, warnings));
+    } else {
+      console.log(`Spec changed. Detected ${newEndpoints.length} new endpoint(s):`);
+      for (const ep of newEndpoints) {
+        console.log(`  + ${ep.method.toUpperCase()} ${ep.path}`);
+      }
+
+      if (generatedFiles.length > 0) {
+        console.log(`\nGenerated ${generatedFiles.length} new suite file(s):`);
+        for (const f of generatedFiles) {
+          console.log(`  ${f.file}  (${f.tests} tests)`);
+        }
+      }
+
+      if (skippedFiles.length > 0) {
+        console.log("\nSkipped (file exists, review manually):");
+        for (const f of skippedFiles) {
+          console.log(`  ${f}`);
+        }
+      }
+
+      if (removedKeys.length > 0) {
+        console.log("\nRemoved endpoints (not deleted — review tests):");
+        for (const key of removedKeys) {
+          console.log(`  - ${key}`);
+        }
+      }
+
+      if (generatedFiles.length > 0) {
+        printSuccess(`\nSync complete. ${generatedFiles.length} file(s) written.`);
+      } else {
+        printWarning("No new files written — all target files already exist.");
+      }
+
+      for (const w of warnings) {
+        printWarning(w);
+      }
+    }
+
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      printJson(jsonError("sync", [message]));
+    } else {
+      printError(message);
+    }
+    return 2;
+  }
+}

package/src/cli/commands/update.ts

@@ -0,0 +1,174 @@
+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. Update via: npm update -g @kirrosh/zond  or  bun update -g @kirrosh/zond";
+      if (options.json) {
+        printJson(jsonOk("update", { action: "skip", reason: "not-standalone" }, [msg]));
+      } else {
+        printWarning(msg);
+      }
+      return 0;
+    }
+
+    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
+      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);
+      }
+
+      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

@@ -3,7 +3,6 @@
 import { runCommand } from "./commands/run.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { serveCommand } from "./commands/serve.ts";
-import { mcpCommand } from "./commands/mcp.ts";
 import { coverageCommand } from "./commands/coverage.ts";
 import { ciInitCommand } from "./commands/ci-init.ts";
 import { initCommand } from "./commands/init.ts";
@@ -12,6 +11,9 @@ import { dbCommand } from "./commands/db.ts";
 import { requestCommand } from "./commands/request.ts";
 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";
@@ -103,9 +105,10 @@ Usage:
   zond guide <spec>     Generate test generation guide from OpenAPI spec
   zond serve            Start web dashboard
   zond ui               Alias for 'serve --open' (start dashboard & open browser)
-  zond mcp              Start MCP server (stdio transport for AI agents)
-                           --dir <path>  Set working directory (relative paths resolve here)
   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)
@@ -175,6 +178,19 @@ Options for 'ci init':
   --dir <path>         Project root directory (default: current directory)
   --force              Overwrite existing CI config
 
+Options for 'export postman':
+  --output <file>      Output file path (default: collection.postman.json)
+  --env <file>         Also export .env.yaml as Postman environment
+  --collection-name <name>  Collection name (default: derived from path)
+
+Options for 'sync':
+  --tests <dir>        Path to test files directory (required)
+  --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
@@ -308,13 +324,6 @@ async function main(): Promise<number> {
       });
     }
 
-    case "mcp": {
-      return mcpCommand({
-        dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
-        dir: typeof flags["dir"] === "string" ? flags["dir"] : undefined,
-      });
-    }
-
     case "ci": {
       const ciSub = positional[0];
       if (ciSub !== "init") {
@@ -504,6 +513,54 @@ async function main(): Promise<number> {
       });
     }
 
+    case "export": {
+      const subcommand = positional[0];
+      if (subcommand !== "postman") {
+        printError(`Unknown export subcommand: ${subcommand ?? "(none)"}. Usage: zond export postman <path>`);
+        return 2;
+      }
+      const testsPath = positional[1];
+      if (!testsPath) {
+        printError("Missing tests path. Usage: zond export postman <path> [--output <file>]");
+        return 2;
+      }
+      return exportCommand({
+        testsPath,
+        output: typeof flags["output"] === "string" ? flags["output"] : "collection.postman.json",
+        env: typeof flags["env"] === "string" ? flags["env"] : undefined,
+        collectionName: typeof flags["collection-name"] === "string" ? flags["collection-name"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
+    case "update":
+    case "self-update": {
+      return updateCommand({
+        check: flags["check"] === true,
+        json: jsonFlag,
+      });
+    }
+
+    case "sync": {
+      const specPath = positional[0];
+      if (!specPath) {
+        printError("Missing spec path. Usage: zond sync <spec> --tests <dir> [--dry-run] [--tag <tag>]");
+        return 2;
+      }
+      const testsDir = typeof flags["tests"] === "string" ? flags["tests"] : undefined;
+      if (!testsDir) {
+        printError("Missing --tests <dir>. Usage: zond sync <spec> --tests <dir>");
+        return 2;
+      }
+      return syncCommand({
+        specPath,
+        testsDir,
+        dryRun: flags["dry-run"] === true,
+        tag: typeof flags["tag"] === "string" ? flags["tag"] : undefined,
+        json: jsonFlag,
+      });
+    }
+
     default: {
       printError(`Unknown command: ${command}`);
       printUsage();