@testsmith/api-spector 0.2.2 → 0.2.4

package/out/main/index.js

@@ -25,24 +25,29 @@ const electron = require("electron");
 const path = require("path");
 const fs = require("fs");
 const promises = require("fs/promises");
-const requestCollection = require("./chunks/request-collection-Dx0ZqB54.js");
+const requestCollection = require("./chunks/request-collection-DIsjTggj.js");
+const authBuilder = require("./chunks/auth-builder-B7-LgcGr.js");
 const uuid = require("uuid");
 const jsYaml = require("js-yaml");
 const undici = require("undici");
 const JSZip = require("jszip");
-const mockServer = require("./chunks/mock-server-Cx-xG4pJ.js");
+const mockServer = require("./chunks/mock-server-DmdvwCgj.js");
 const http = require("http");
 const WebSocket = require("ws");
-const https = require("https");
-const Ajv = require("ajv");
+const soapHandler = require("./chunks/soap-handler-Cpj-JwyA.js");
+const os = require("os");
+const crypto = require("crypto");
+const snapshots = require("./chunks/snapshots-C7YbGHM7.js");
+const ipcValidate = require("./chunks/ipc-validate-CscN4HfG.js");
 const simpleGit = require("simple-git");
 const recorder = require("./chunks/recorder-DFxJgn9c.js");
-require("crypto");
-require("dayjs");
 require("vm");
+require("dayjs");
 require("tv4");
 require("jsonpath-plus");
 require("@xmldom/xmldom");
+require("ajv");
+require("https");
 const LAST_WS_FILE = path.join(electron.app.getPath("userData"), "last-workspace.json");
 async function saveLastWorkspacePath(wsPath) {
   await promises.writeFile(LAST_WS_FILE, JSON.stringify({ path: wsPath }), "utf8");
@@ -60,10 +65,156 @@ let workspaceFile = null;
 function atomicWrite(path2, data) {
   return promises.writeFile(path2, data, "utf8");
 }
+const SPECTOR_GITIGNORE = [
+  "# API Spector — never commit secrets",
+  "*.secrets",
+  ".env",
+  ".env.local",
+  ".env.*.local",
+  "",
+  "# Dependencies",
+  "node_modules/",
+  "",
+  "# Generated API docs",
+  "api-docs.html",
+  "api-docs.md",
+  "docs/",
+  "",
+  "# Run reports (api-spector run --output)",
+  "reports/",
+  "*-report.json",
+  "*-report.xml",
+  "*-report.html",
+  "results.json",
+  "results.xml",
+  "results.html",
+  "coverage/",
+  "",
+  "# OS / editor",
+  ".DS_Store",
+  "Thumbs.db",
+  ".idea/",
+  ""
+].join("\n");
+function readmeContents(workspaceFileName) {
+  return [
+    `# API tests`,
+    ``,
+    `This folder is an [API Spector](https://github.com/testsmith-io/api-spector) workspace.`,
+    `Everything here is plain JSON — diff it, commit it, review it like any other code.`,
+    ``,
+    `## Layout`,
+    ``,
+    "```",
+    `${workspaceFileName}      ← workspace manifest (this is what you "open")`,
+    `collections/              ← your request collections`,
+    `environments/             ← per-env variable files (dev, staging, prod, …)`,
+    `mocks/                    ← saved mock servers (optional)`,
+    `contracts/                ← pinned OpenAPI snapshots (optional)`,
+    `.gitignore                ← excludes secrets, generated docs, run reports`,
+    `.vscode/settings.json     ← maps *.spector to JSON for editor highlighting`,
+    "```",
+    ``,
+    `## Open the workspace`,
+    ``,
+    "```bash",
+    `# launches the GUI in this folder`,
+    `npx -y @testsmith/api-spector ui`,
+    "```",
+    ``,
+    `## Run the tests from CI`,
+    ``,
+    "```bash",
+    `npx -y @testsmith/api-spector run \\`,
+    `  --workspace ./${workspaceFileName} \\`,
+    `  --environment ci \\`,
+    `  --output reports/results.xml --format junit`,
+    "```",
+    ``,
+    `Other useful commands:`,
+    ``,
+    `| Command | What it does |`,
+    `|---|---|`,
+    `| \`api-spector run\`       | Execute requests / assertions |`,
+    `| \`api-spector mock\`      | Start mock servers from this workspace |`,
+    `| \`api-spector contract\`  | Manage and run pinned contract snapshots |`,
+    `| \`api-spector wsdl\`      | Inspect a WSDL or import as collection / mock |`,
+    ``,
+    `## A note on secrets`,
+    ``,
+    `Secret values (passwords, OAuth client secrets, API keys) are stored in your`,
+    `OS keychain — **not** in this folder. Environment files only reference the`,
+    `keychain entry by name, so it's safe to commit them.`,
+    ``
+  ].join("\n");
+}
+async function ensureReadme(workspaceDir2, workspaceFileName) {
+  const path$1 = path.join(workspaceDir2, "README.md");
+  try {
+    await promises.readFile(path$1, "utf8");
+    return;
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.warn("file-handler: could not check README.md", err);
+      return;
+    }
+    await atomicWrite(path$1, readmeContents(workspaceFileName));
+  }
+}
+async function ensureGitignore(workspaceDir2) {
+  const path$1 = path.join(workspaceDir2, ".gitignore");
+  try {
+    await promises.readFile(path$1, "utf8");
+    return;
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.warn("file-handler: could not check .gitignore", err);
+      return;
+    }
+    await atomicWrite(path$1, SPECTOR_GITIGNORE);
+  }
+}
+async function ensureVscodeFileAssociation(workspaceDir2) {
+  const dir = path.join(workspaceDir2, ".vscode");
+  const file = path.join(dir, "settings.json");
+  try {
+    const raw = await promises.readFile(file, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    const associations = parsed["files.associations"] ?? {};
+    if (associations["*.spector"] === "json") return;
+    parsed["files.associations"] = { ...associations, "*.spector": "json" };
+    await atomicWrite(file, JSON.stringify(parsed, null, 2) + "\n");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      console.warn("file-handler: could not read existing .vscode/settings.json", err);
+      return;
+    }
+    await promises.mkdir(dir, { recursive: true });
+    const fresh = { "files.associations": { "*.spector": "json" } };
+    await atomicWrite(file, JSON.stringify(fresh, null, 2) + "\n");
+  }
+}
+function dialogStartDir() {
+  return process.env.API_SPECTOR_LAUNCH_CWD || workspaceDir || void 0;
+}
+function defaultWorkspaceName() {
+  const cwd = process.env.API_SPECTOR_LAUNCH_CWD;
+  if (cwd) {
+    const base = cwd.split(/[\\/]/).filter(Boolean).pop();
+    if (base && /^[a-zA-Z0-9._-]+$/.test(base)) return `${base}.spector`;
+  }
+  return "my-workspace.spector";
+}
 function registerFileHandlers(ipc) {
   ipc.handle("file:openWorkspace", async () => {
     const result = await electron.dialog.showOpenDialog({
       title: "Open Workspace",
+      defaultPath: dialogStartDir(),
       filters: [{ name: "API Spector Workspace", extensions: ["spector", "json"] }],
       properties: ["openFile"]
     });
@@ -77,9 +228,11 @@ function registerFileHandlers(ipc) {
     return { workspace: JSON.parse(raw), workspacePath: wsPath };
   });
   ipc.handle("file:newWorkspace", async () => {
+    const startDir = dialogStartDir();
+    const defaultPath = startDir ? path.join(startDir, defaultWorkspaceName()) : defaultWorkspaceName();
     const result = await electron.dialog.showSaveDialog({
       title: "Create Workspace",
-      defaultPath: "my-workspace.spector",
+      defaultPath,
       filters: [{ name: "API Spector Workspace", extensions: ["spector", "json"] }]
     });
     if (result.canceled || !result.filePath) return null;
@@ -88,8 +241,9 @@ function registerFileHandlers(ipc) {
     await requestCollection.loadGlobals(workspaceDir);
     await promises.mkdir(path.join(workspaceDir, "collections"), { recursive: true });
     await promises.mkdir(path.join(workspaceDir, "environments"), { recursive: true });
-    const gitignore = "# API Spector — never commit secrets\n*.secrets\n.env.local\n\n# Dependencies\nnode_modules/\n";
-    await atomicWrite(path.join(workspaceDir, ".gitignore"), gitignore);
+    await ensureGitignore(workspaceDir);
+    await ensureVscodeFileAssociation(workspaceDir);
+    await ensureReadme(workspaceDir, path.basename(result.filePath));
     const ws = {
       version: "1.0",
       collections: [],
@@ -103,6 +257,7 @@ function registerFileHandlers(ipc) {
   ipc.handle("file:saveWorkspace", async (_e, ws) => {
     if (!workspaceFile) return;
     await atomicWrite(workspaceFile, JSON.stringify(ws, null, 2));
+    if (workspaceDir) await ensureVscodeFileAssociation(workspaceDir);
   });
   ipc.handle("file:loadCollection", async (_e, relPath) => {
     if (!workspaceDir) throw new Error("No workspace open");
@@ -126,6 +281,18 @@ function registerFileHandlers(ipc) {
     await promises.mkdir(path.dirname(fullPath), { recursive: true });
     await atomicWrite(fullPath, JSON.stringify(env, null, 2));
   });
+  ipc.handle("file:deleteWorkspaceFile", async (_e, relPath) => {
+    if (!workspaceDir) throw new Error("No workspace open");
+    const fullPath = path.resolve(workspaceDir, relPath);
+    if (!fullPath.startsWith(path.resolve(workspaceDir) + (process.platform === "win32" ? "\\" : "/"))) {
+      throw new Error(`Refusing to delete file outside the workspace: ${relPath}`);
+    }
+    try {
+      await promises.unlink(fullPath);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  });
   ipc.handle("dialog:pickDir", async () => {
     const result = await electron.dialog.showOpenDialog({
       title: "Select Output Directory",
@@ -157,23 +324,51 @@ function registerFileHandlers(ipc) {
   ipc.handle("file:closeWorkspace", async () => {
     workspaceDir = null;
     workspaceFile = null;
-    await promises.writeFile(LAST_WS_FILE, JSON.stringify({ path: null }), "utf8").catch(() => {
+    await promises.writeFile(LAST_WS_FILE, JSON.stringify({ path: null }), "utf8").catch((err) => {
+      console.warn("file-handler: could not clear last-workspace pointer", err);
     });
   });
   ipc.handle("file:getLastWorkspace", async () => {
+    const cwd = process.env.API_SPECTOR_LAUNCH_CWD;
+    if (cwd) {
+      const fromCwd = await tryOpenWorkspaceInDir(cwd);
+      return fromCwd;
+    }
     const wsPath = await readLastWorkspacePath();
     if (!wsPath) return null;
     try {
+      const raw = await promises.readFile(wsPath, "utf8");
+      const workspace = JSON.parse(raw);
       workspaceDir = path.dirname(wsPath);
       workspaceFile = wsPath;
       await requestCollection.loadGlobals(workspaceDir);
-      const raw = await promises.readFile(wsPath, "utf8");
-      return { workspace: JSON.parse(raw), workspacePath: wsPath };
+      return { workspace, workspacePath: wsPath };
     } catch {
       return null;
     }
   });
 }
+async function tryOpenWorkspaceInDir(dir) {
+  let entries;
+  try {
+    entries = await promises.readdir(dir);
+  } catch {
+    return null;
+  }
+  const candidates = entries.filter((f) => f.endsWith(".spector"));
+  if (candidates.length !== 1) return null;
+  const wsPath = path.join(dir, candidates[0]);
+  try {
+    const raw = await promises.readFile(wsPath, "utf8");
+    const workspace = JSON.parse(raw);
+    workspaceDir = dir;
+    workspaceFile = wsPath;
+    await requestCollection.loadGlobals(workspaceDir);
+    return { workspace, workspacePath: wsPath };
+  } catch {
+    return null;
+  }
+}
 function getWorkspaceDir() {
   return workspaceDir;
 }
@@ -399,7 +594,7 @@ async function importPostman(filePath) {
     requests
   };
 }
-async function loadSpec$1(filePath) {
+async function loadSpec(filePath) {
   const raw = await promises.readFile(filePath, "utf8");
   if (filePath.endsWith(".yaml") || filePath.endsWith(".yml")) {
     return jsYaml.load(raw);
@@ -416,7 +611,7 @@ async function loadSpecFromUrl(url) {
   }
   return JSON.parse(text);
 }
-function resolveRef$1(spec, ref) {
+function resolveRef(spec, ref) {
   const parts = ref.replace(/^#\//, "").split("/");
   return parts.reduce((obj, key) => obj?.[decodeURIComponent(key.replace(/~1/g, "/").replace(/~0/g, "~"))], spec);
 }
@@ -428,7 +623,7 @@ function resolve(spec, obj, seen = /* @__PURE__ */ new Set()) {
     return obj.map((item) => resolve(spec, item, seen));
   }
   if ("$ref" in obj) {
-    const target = resolveRef$1(spec, obj.$ref);
+    const target = resolveRef(spec, obj.$ref);
     if (!target || seen.has(target)) return {};
     return resolve(spec, target, seen);
   }
@@ -626,7 +821,7 @@ function buildCollection(spec) {
   };
 }
 async function importOpenApi(filePath) {
-  return buildCollection(await loadSpec$1(filePath));
+  return buildCollection(await loadSpec(filePath));
 }
 async function importOpenApiFromUrl(url) {
   return buildCollection(await loadSpecFromUrl(url));
@@ -652,7 +847,7 @@ function extractSchemas(spec) {
   return entries;
 }
 async function extractSchemasFromFile(filePath) {
-  return extractSchemas(await loadSpec$1(filePath));
+  return extractSchemas(await loadSpec(filePath));
 }
 async function extractSchemasFromUrl(url) {
   return extractSchemas(await loadSpecFromUrl(url));
@@ -3086,14 +3281,14 @@ async function executeOne(req, collectionVars, envVars, globals, localVars, disp
     resolvedUrl: "",
     status: "running"
   };
-  const dynamicVars = await requestCollection.buildDynamicVars();
-  let vars = requestCollection.mergeVars(envVars, collectionVars, globals, localVars, dynamicVars);
+  const dynamicVars = await authBuilder.buildDynamicVars();
+  let vars = authBuilder.mergeVars(envVars, collectionVars, globals, localVars, dynamicVars);
   let updatedEnvVars = { ...envVars };
   let updatedCollectionVars = { ...collectionVars };
   let updatedGlobals = { ...globals };
   let preScriptError;
   if (req.preRequestScript?.trim()) {
-    const r = await requestCollection.runScript(requestCollection.interpolate(req.preRequestScript, vars), {
+    const r = await requestCollection.runScript(authBuilder.interpolate(req.preRequestScript, vars), {
       envVars: { ...envVars },
       collectionVars: { ...collectionVars },
       globals: { ...globals },
@@ -3106,9 +3301,9 @@ async function executeOne(req, collectionVars, envVars, globals, localVars, disp
     updatedGlobals = r.updatedGlobals;
     requestCollection.patchGlobals(r.updatedGlobals);
     await requestCollection.persistGlobals();
-    vars = requestCollection.mergeVars(updatedEnvVars, updatedCollectionVars, updatedGlobals, localVars, dynamicVars);
+    vars = authBuilder.mergeVars(updatedEnvVars, updatedCollectionVars, updatedGlobals, localVars, dynamicVars);
   }
-  const resolvedUrl = requestCollection.buildUrl(req.url, req.params, vars);
+  const resolvedUrl = authBuilder.buildUrl(req.url, req.params, vars);
   base.resolvedUrl = resolvedUrl;
   const start = Date.now();
   try {
@@ -3117,23 +3312,23 @@ async function executeOne(req, collectionVars, envVars, globals, localVars, disp
       const tokenMissing = !req.auth.oauth2CachedToken;
       const tokenExpired = req.auth.oauth2TokenExpiry ? req.auth.oauth2TokenExpiry <= now + 5e3 : true;
       if (tokenMissing || tokenExpired) {
-        const result = await requestCollection.fetchOAuth2Token(req.auth, vars);
+        const result = await authBuilder.fetchOAuth2Token(req.auth, vars);
         req.auth.oauth2CachedToken = result.accessToken;
         req.auth.oauth2TokenExpiry = result.expiresAt;
       }
     }
-    const authHeaders = await requestCollection.buildAuthHeaders(req.auth, vars);
+    const authHeaders = await authBuilder.buildAuthHeaders(req.auth, vars);
     const headers = new undici.Headers();
     for (const h of req.headers) {
-      if (h.enabled && h.key) headers.set(requestCollection.interpolate(h.key, vars), requestCollection.interpolate(h.value, vars));
+      if (h.enabled && h.key) headers.set(authBuilder.interpolate(h.key, vars), authBuilder.interpolate(h.value, vars));
     }
     for (const [k, v] of Object.entries(authHeaders)) headers.set(k, v);
     let body;
     if (req.body.mode === "json" && req.body.json) {
-      body = requestCollection.interpolate(req.body.json, vars);
+      body = authBuilder.interpolate(req.body.json, vars);
       if (!headers.has("content-type")) headers.set("Content-Type", "application/json");
     } else if (req.body.mode === "raw" && req.body.raw) {
-      body = requestCollection.interpolate(req.body.raw, vars);
+      body = authBuilder.interpolate(req.body.raw, vars);
       if (!headers.has("content-type")) headers.set("Content-Type", req.body.rawContentType ?? "text/plain");
     }
     const methodHasBody = !["GET", "HEAD"].includes(req.method);
@@ -3145,14 +3340,14 @@ async function executeOne(req, collectionVars, envVars, globals, localVars, disp
     });
     let fetchResp;
     if (req.auth.type === "ntlm") {
-      await requestCollection.performNtlmRequest(resolvedUrl, req.method, req.auth, vars);
+      await authBuilder.performNtlmRequest(resolvedUrl, req.method, req.auth, vars);
       fetchResp = await doFetch(headers);
     } else if (req.auth.type === "digest") {
       const probeFetch = (url, init) => undici.fetch(url, {
         ...init,
         dispatcher
       });
-      const digestHeader = await requestCollection.performDigestAuth(resolvedUrl, req.method, req.auth, vars, probeFetch);
+      const digestHeader = await authBuilder.performDigestAuth(resolvedUrl, req.method, req.auth, vars, probeFetch);
       if (digestHeader) headers.set("Authorization", digestHeader);
       fetchResp = await doFetch(headers);
     } else {
@@ -3179,7 +3374,7 @@ async function executeOne(req, collectionVars, envVars, globals, localVars, disp
     let consoleOutput = [];
     let postScriptError;
     if (req.postRequestScript?.trim()) {
-      const r = await requestCollection.runScript(requestCollection.interpolate(req.postRequestScript, vars), {
+      const r = await requestCollection.runScript(authBuilder.interpolate(req.postRequestScript, vars), {
         envVars: updatedEnvVars,
         collectionVars: updatedCollectionVars,
         globals: updatedGlobals,
@@ -3257,7 +3452,7 @@ const sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
 function registerRunnerHandler(ipc) {
   ipc.handle("runner:start", async (event, payload) => {
     const { items, environment, globals: payloadGlobals, proxy, tls, piiMaskPatterns = [], requestDelay = 0 } = payload;
-    const envVars = await requestCollection.buildEnvVars(environment);
+    const envVars = await authBuilder.buildEnvVars(environment);
     const liveGlobals = requestCollection.getGlobals();
     const globals = { ...payloadGlobals, ...liveGlobals };
     const dispatcher = await buildDispatcher(proxy, tls);
@@ -3392,14 +3587,14 @@ function registerOAuth2Handlers(ipc) {
   ipc.handle("oauth2:startFlow", async (_e, auth, vars) => {
     const port = auth.oauth2RedirectPort ?? 9876;
     const redirectUri = `http://localhost:${port}/callback`;
-    const authUrl = requestCollection.interpolate(auth.oauth2AuthUrl ?? "", vars);
-    const tokenUrl = requestCollection.interpolate(auth.oauth2TokenUrl ?? "", vars);
-    const clientId = requestCollection.interpolate(auth.oauth2ClientId ?? "", vars);
+    const authUrl = authBuilder.interpolate(auth.oauth2AuthUrl ?? "", vars);
+    const tokenUrl = authBuilder.interpolate(auth.oauth2TokenUrl ?? "", vars);
+    const clientId = authBuilder.interpolate(auth.oauth2ClientId ?? "", vars);
     let clientSecret = auth.oauth2ClientSecret ?? "";
     if (!clientSecret && auth.oauth2ClientSecretRef) {
-      clientSecret = await requestCollection.getSecret(auth.oauth2ClientSecretRef) ?? "";
+      clientSecret = await authBuilder.getSecret(auth.oauth2ClientSecretRef) ?? "";
     }
-    clientSecret = requestCollection.interpolate(clientSecret, vars);
+    clientSecret = authBuilder.interpolate(clientSecret, vars);
     if (!authUrl) throw new Error("OAuth 2.0: authUrl is required for authorization_code flow.");
     if (!tokenUrl) throw new Error("OAuth 2.0: tokenUrl is required for authorization_code flow.");
     if (!clientId) throw new Error("OAuth 2.0: clientId is required.");
@@ -3474,13 +3669,13 @@ function registerOAuth2Handlers(ipc) {
     };
   });
   ipc.handle("oauth2:refreshToken", async (_e, auth, vars, refreshToken) => {
-    const tokenUrl = requestCollection.interpolate(auth.oauth2TokenUrl ?? "", vars);
-    const clientId = requestCollection.interpolate(auth.oauth2ClientId ?? "", vars);
+    const tokenUrl = authBuilder.interpolate(auth.oauth2TokenUrl ?? "", vars);
+    const clientId = authBuilder.interpolate(auth.oauth2ClientId ?? "", vars);
     let clientSecret = auth.oauth2ClientSecret ?? "";
     if (!clientSecret && auth.oauth2ClientSecretRef) {
-      clientSecret = await requestCollection.getSecret(auth.oauth2ClientSecretRef) ?? "";
+      clientSecret = await authBuilder.getSecret(auth.oauth2ClientSecretRef) ?? "";
     }
-    clientSecret = requestCollection.interpolate(clientSecret, vars);
+    clientSecret = authBuilder.interpolate(clientSecret, vars);
     if (!tokenUrl) throw new Error("OAuth 2.0: tokenUrl is required for refresh.");
     const { fetch: nodeFetch } = await import("undici");
     const params = new URLSearchParams();
@@ -3564,70 +3759,31 @@ function registerWsHandlers(ipc) {
     }
   });
 }
-function fetchUrl(url, headers = {}) {
-  return new Promise((resolve2, reject) => {
-    const lib = url.startsWith("https") ? https : http;
-    const req = lib.get(url, { headers }, (res) => {
-      const chunks = [];
-      res.on("data", (chunk) => chunks.push(chunk));
-      res.on("end", () => resolve2(Buffer.concat(chunks).toString("utf8")));
-      res.on("error", reject);
-    });
-    req.on("error", reject);
-    req.setTimeout(15e3, () => {
-      req.destroy();
-      reject(new Error("WSDL fetch timed out"));
-    });
-  });
+function isJsonContentType(ct) {
+  return !!ct && /\bjson\b/i.test(ct);
 }
-function parseWsdl(wsdlText) {
-  const nsMatch = wsdlText.match(/targetNamespace\s*=\s*["']([^"']+)["']/);
-  const targetNamespace = nsMatch ? nsMatch[1] : "";
-  const operationRegex = /<(?:wsdl:)?operation\s+name\s*=\s*["']([^"']+)["']/g;
-  const operationNames = /* @__PURE__ */ new Set();
-  let m;
-  while ((m = operationRegex.exec(wsdlText)) !== null) {
-    operationNames.add(m[1]);
-  }
-  const soapActionMap = {};
-  const bindingOpRegex = /<(?:wsdl:)?operation\s+name\s*=\s*["']([^"']+)["'][^>]*>([\s\S]*?)<\/(?:wsdl:)?operation>/g;
-  while ((m = bindingOpRegex.exec(wsdlText)) !== null) {
-    const opName = m[1];
-    const block = m[2];
-    const saMatch = block.match(/soapAction\s*=\s*["']([^"']*)["']/);
-    if (saMatch) soapActionMap[opName] = saMatch[1];
-  }
-  const operations = [];
-  for (const name of operationNames) {
-    const soapAction = soapActionMap[name];
-    const inputTemplate = buildEnvelopeTemplate(name, targetNamespace);
-    operations.push({ name, soapAction, inputTemplate });
-  }
-  return { operations, targetNamespace };
-}
-function buildEnvelopeTemplate(operationName, namespace) {
-  return `<?xml version="1.0" encoding="utf-8"?>
-<soap:Envelope
-  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
-  xmlns:tns="${namespace}">
-  <soap:Header/>
-  <soap:Body>
-    <tns:${operationName}>
-      <!-- Add parameters here -->
-    </tns:${operationName}>
-  </soap:Body>
-</soap:Envelope>`;
-}
-function registerSoapHandlers(ipc) {
-  ipc.handle("wsdl:fetch", async (_event, url, extraHeaders = {}) => {
-    const wsdlText = await fetchUrl(url, extraHeaders);
-    return parseWsdl(wsdlText);
-  });
+function formatBody(body, contentType) {
+  if (!body) return "";
+  const trimmed = body.length > 8e3 ? body.slice(0, 8e3) + "\n… (truncated)" : body;
+  if (isJsonContentType(contentType)) {
+    try {
+      return JSON.stringify(JSON.parse(trimmed), null, 2);
+    } catch {
+    }
+  }
+  return trimmed;
+}
+function langForContentType(ct) {
+  if (!ct) return "";
+  if (/\bjson\b/i.test(ct)) return "json";
+  if (/\bxml\b/i.test(ct)) return "xml";
+  if (/\bhtml\b/i.test(ct)) return "html";
+  return "";
 }
 function escMd(s) {
   return s.replace(/[|\\`*_{}[\]()#+\-.!]/g, (c) => `\\${c}`);
 }
-function requestToMarkdown(req) {
+function requestToMarkdown(req, example) {
   const lines = [];
   const methodLabel = req.protocol === "websocket" ? "WS" : req.method;
   lines.push(`#### ${methodLabel} ${escMd(req.name)}`);
@@ -3694,9 +3850,31 @@ function requestToMarkdown(req) {
     lines.push("```");
     lines.push("");
   }
+  if (example?.sent?.body?.trim()) {
+    const ct = example.sent.headers?.["Content-Type"] ?? example.sent.headers?.["content-type"];
+    const lang = langForContentType(ct);
+    lines.push("**Example Request Body**");
+    lines.push("```" + lang);
+    lines.push(formatBody(example.sent.body, ct));
+    lines.push("```");
+    lines.push("");
+  }
+  if (example?.response) {
+    const ct = example.response.headers["content-type"] ?? example.response.headers["Content-Type"];
+    const lang = langForContentType(ct);
+    lines.push(`**Example Response** (${example.response.status})`);
+    if (example.response.body?.trim()) {
+      lines.push("```" + lang);
+      lines.push(formatBody(example.response.body, ct));
+      lines.push("```");
+    } else {
+      lines.push("_(empty body)_");
+    }
+    lines.push("");
+  }
   return lines.join("\n");
 }
-function folderToMarkdown(folder, requests, depth) {
+function folderToMarkdown(folder, requests, depth, examples) {
   const lines = [];
   const heading = "#".repeat(depth);
   if (folder.name !== "root") {
@@ -3710,11 +3888,11 @@ function folderToMarkdown(folder, requests, depth) {
   for (const reqId of folder.requestIds) {
     const req = requests[reqId];
     if (req) {
-      lines.push(requestToMarkdown(req));
+      lines.push(requestToMarkdown(req, examples[reqId]));
     }
   }
   for (const sub of folder.folders) {
-    lines.push(folderToMarkdown(sub, requests, depth + 1));
+    lines.push(folderToMarkdown(sub, requests, depth + 1, examples));
   }
   return lines.join("\n");
 }
@@ -3722,6 +3900,7 @@ function generateMarkdown(payload) {
   const lines = [];
   lines.push("# API Documentation");
   lines.push("");
+  const examples = payload.examples ?? {};
   for (const { collection, requests } of payload.collections) {
     lines.push(`## ${escMd(collection.name)}`);
     lines.push("");
@@ -3729,7 +3908,7 @@ function generateMarkdown(payload) {
       lines.push(collection.description.trim());
       lines.push("");
     }
-    lines.push(folderToMarkdown(collection.rootFolder, requests, 3));
+    lines.push(folderToMarkdown(collection.rootFolder, requests, 3, examples));
   }
   return lines.join("\n");
 }
@@ -3746,7 +3925,7 @@ const METHOD_COLORS = {
   OPTIONS: "#9ca3af",
   WS: "#22d3ee"
 };
-function requestToHtml(req) {
+function requestToHtml(req, example) {
   const methodLabel = req.protocol === "websocket" ? "WS" : req.method;
   const color = METHOD_COLORS[methodLabel] ?? "#9ca3af";
   let html = `<div class="request">`;
@@ -3784,10 +3963,23 @@ function requestToHtml(req) {
   } else if (mode === "soap" && req.body.soap?.envelope?.trim()) {
     html += `<div class="label">Body (SOAP)</div><pre><code>${escHtml(req.body.soap.envelope.trim())}</code></pre>`;
   }
+  if (example?.sent?.body?.trim()) {
+    const ct = example.sent.headers?.["Content-Type"] ?? example.sent.headers?.["content-type"];
+    html += `<div class="label">Example Request Body</div><pre><code class="lang-${escHtml(langForContentType(ct))}">${escHtml(formatBody(example.sent.body, ct))}</code></pre>`;
+  }
+  if (example?.response) {
+    const ct = example.response.headers["content-type"] ?? example.response.headers["Content-Type"];
+    html += `<div class="label">Example Response (${example.response.status})</div>`;
+    if (example.response.body?.trim()) {
+      html += `<pre><code class="lang-${escHtml(langForContentType(ct))}">${escHtml(formatBody(example.response.body, ct))}</code></pre>`;
+    } else {
+      html += `<p class="desc"><em>(empty body)</em></p>`;
+    }
+  }
   html += `</div>`;
   return html;
 }
-function folderToHtml(folder, requests, depth) {
+function folderToHtml(folder, requests, depth, examples) {
   let html = "";
   const tag = `h${Math.min(depth, 6)}`;
   if (folder.name !== "root") {
@@ -3798,21 +3990,22 @@ function folderToHtml(folder, requests, depth) {
   }
   for (const reqId of folder.requestIds) {
     const req = requests[reqId];
-    if (req) html += requestToHtml(req);
+    if (req) html += requestToHtml(req, examples[reqId]);
   }
   for (const sub of folder.folders) {
-    html += folderToHtml(sub, requests, depth + 1);
+    html += folderToHtml(sub, requests, depth + 1, examples);
   }
   return html;
 }
 function generateHtml(payload) {
   let body = "";
+  const examples = payload.examples ?? {};
   for (const { collection, requests } of payload.collections) {
     body += `<section class="collection"><h2>${escHtml(collection.name)}</h2>`;
     if (collection.description?.trim()) {
       body += `<p class="collection-desc">${escHtml(collection.description.trim())}</p>`;
     }
-    body += folderToHtml(collection.rootFolder, requests, 3);
+    body += folderToHtml(collection.rootFolder, requests, 3, examples);
     body += `</section>`;
   }
   return `<!DOCTYPE html>
@@ -3856,475 +4049,6 @@ function registerDocsHandlers(ipc) {
     return generateMarkdown(payload);
   });
 }
-const ajv$1 = new Ajv({ allErrors: true, strict: false });
-function validateConsumerResponse(contract, actualStatus, actualHeaders, bodyText) {
-  const violations = [];
-  if (contract.statusCode !== void 0 && actualStatus !== contract.statusCode) {
-    violations.push({
-      type: "status_mismatch",
-      message: `Expected status ${contract.statusCode}, got ${actualStatus}`,
-      expected: String(contract.statusCode),
-      actual: String(actualStatus)
-    });
-  }
-  for (const expected of contract.headers ?? []) {
-    if (!expected.required) continue;
-    const actual = actualHeaders[expected.key.toLowerCase()];
-    if (actual === void 0) {
-      violations.push({
-        type: "missing_header",
-        message: `Required header "${expected.key}" is absent`,
-        expected: expected.value || "(any)",
-        actual: "(absent)"
-      });
-    } else if (expected.value && actual.split(";")[0].trim().toLowerCase() !== expected.value.split(";")[0].trim().toLowerCase()) {
-      violations.push({
-        type: "missing_header",
-        message: `Header "${expected.key}" has unexpected value`,
-        expected: expected.value,
-        actual
-      });
-    }
-  }
-  if (contract.bodySchema?.trim()) {
-    let schema;
-    try {
-      schema = JSON.parse(contract.bodySchema);
-    } catch {
-      violations.push({
-        type: "schema_violation",
-        message: "Contract bodySchema is not valid JSON"
-      });
-      return violations;
-    }
-    let data;
-    try {
-      data = JSON.parse(bodyText);
-    } catch {
-      violations.push({
-        type: "schema_violation",
-        message: "Response body is not valid JSON — cannot validate against schema"
-      });
-      return violations;
-    }
-    try {
-      const validate = ajv$1.compile(schema);
-      if (!validate(data)) {
-        for (const err of validate.errors ?? []) {
-          violations.push({
-            type: "schema_violation",
-            message: err.message ?? "Schema violation",
-            path: err.instancePath || "/"
-          });
-        }
-      }
-    } catch (e) {
-      violations.push({
-        type: "schema_violation",
-        message: `Schema compile error: ${e instanceof Error ? e.message : String(e)}`
-      });
-    }
-  }
-  return violations;
-}
-async function executeContract(req, vars) {
-  const url = requestCollection.buildUrl(req.url, req.params, vars);
-  const start = Date.now();
-  try {
-    const headers = new undici.Headers();
-    for (const h of req.headers) {
-      if (h.enabled && h.key) headers.set(requestCollection.interpolate(h.key, vars), requestCollection.interpolate(h.value, vars));
-    }
-    const authHeaders = await requestCollection.buildAuthHeaders(req.auth, vars);
-    for (const [k, v] of Object.entries(authHeaders)) headers.set(k, v);
-    let body;
-    if (req.body.mode === "json" && req.body.json) {
-      body = requestCollection.interpolate(req.body.json, vars);
-      if (!headers.has("content-type")) headers.set("Content-Type", "application/json");
-    } else if (req.body.mode === "raw" && req.body.raw) {
-      body = requestCollection.interpolate(req.body.raw, vars);
-    }
-    const resp = await undici.fetch(url, {
-      method: req.method,
-      headers,
-      body: !["GET", "HEAD"].includes(req.method) ? body : void 0
-    });
-    const bodyText = await resp.text();
-    const rawHeaders = {};
-    resp.headers.forEach((v, k) => {
-      rawHeaders[k] = v;
-    });
-    const violations = validateConsumerResponse(req.contract, resp.status, rawHeaders, bodyText);
-    return {
-      requestId: req.id,
-      requestName: req.name,
-      method: req.method,
-      url,
-      passed: violations.length === 0,
-      violations,
-      durationMs: Date.now() - start,
-      actualStatus: resp.status
-    };
-  } catch (err) {
-    return {
-      requestId: req.id,
-      requestName: req.name,
-      method: req.method,
-      url,
-      passed: false,
-      violations: [{
-        type: "status_mismatch",
-        message: `Request failed: ${err instanceof Error ? err.message : String(err)}`
-      }],
-      durationMs: Date.now() - start
-    };
-  }
-}
-async function runConsumerContracts(requests, envVars, collectionVars = {}) {
-  const vars = { ...envVars, ...collectionVars };
-  const contractRequests = requests.filter(
-    (r) => !r.disabled && r.contract && (r.contract.statusCode !== void 0 || r.contract.bodySchema || r.contract.headers?.length)
-  );
-  const start = Date.now();
-  const results = await Promise.all(contractRequests.map((r) => executeContract(r, vars)));
-  const passed = results.filter((r) => r.passed).length;
-  return {
-    mode: "consumer",
-    total: results.length,
-    passed,
-    failed: results.length - passed,
-    results,
-    durationMs: Date.now() - start
-  };
-}
-const ajv = new Ajv({ allErrors: true, strict: false });
-async function loadSpec(specUrl, specPath) {
-  if (specUrl) {
-    const resp = await undici.fetch(specUrl);
-    if (!resp.ok) throw new Error(`HTTP ${resp.status} loading spec from ${specUrl}`);
-    const text = await resp.text();
-    const ct = resp.headers.get("content-type") ?? "";
-    return ct.includes("yaml") || specUrl.endsWith(".yaml") || specUrl.endsWith(".yml") ? jsYaml.load(text) : JSON.parse(text);
-  }
-  if (specPath) {
-    const raw = await promises.readFile(specPath, "utf8");
-    return specPath.endsWith(".yaml") || specPath.endsWith(".yml") ? jsYaml.load(raw) : JSON.parse(raw);
-  }
-  throw new Error("Either specUrl or specPath must be provided");
-}
-function resolveRef(spec, ref) {
-  const parts = ref.replace(/^#\//, "").split("/");
-  return parts.reduce((obj, key) => obj?.[key], spec);
-}
-function resolveSchema(spec, obj, seen = /* @__PURE__ */ new Set()) {
-  if (!obj || typeof obj !== "object") return obj;
-  if (seen.has(obj)) return {};
-  if (Array.isArray(obj)) {
-    seen.add(obj);
-    return obj.map((i) => resolveSchema(spec, i, seen));
-  }
-  const o = obj;
-  if ("$ref" in o) {
-    const target = resolveRef(spec, o["$ref"]);
-    return resolveSchema(spec, target, seen);
-  }
-  seen.add(obj);
-  return Object.fromEntries(Object.entries(o).map(([k, v]) => [k, resolveSchema(spec, v, seen)]));
-}
-function getServerBases(spec) {
-  const servers = spec["servers"] ?? [];
-  if (!servers.length) return [""];
-  return servers.map((s) => {
-    const raw = s.url ?? "";
-    try {
-      return new URL(raw).pathname.replace(/\/$/, "");
-    } catch {
-      return raw.replace(/\/$/, "");
-    }
-  });
-}
-function urlPathname(raw, baseUrl) {
-  try {
-    const pathname = new URL(raw).pathname;
-    if (baseUrl) {
-      try {
-        const basePath = new URL(baseUrl).pathname.replace(/\/$/, "");
-        if (basePath && pathname.startsWith(basePath)) return pathname.slice(basePath.length) || "/";
-      } catch {
-      }
-    }
-    return pathname;
-  } catch {
-    return raw.split("?")[0];
-  }
-}
-function pathTemplateToRegex(base, template) {
-  const combined = (base + template).replace(/\/+/g, "/");
-  const pattern = combined.replace(/\{[^}]+\}/g, "[^/]+");
-  return new RegExp("^" + pattern + "/?$");
-}
-function findOperation(spec, method, reqUrl, requestBaseUrl) {
-  const bases = getServerBases(spec);
-  const pathname = urlPathname(reqUrl, requestBaseUrl);
-  const paths = spec["paths"] ?? {};
-  for (const [template, pathItem] of Object.entries(paths)) {
-    const resolved = resolveSchema(spec, pathItem);
-    for (const base of bases) {
-      if (pathTemplateToRegex(base, template).test(pathname)) {
-        const op = resolved[method.toLowerCase()];
-        return op ? { pathTemplate: template, operation: op } : null;
-      }
-    }
-  }
-  return null;
-}
-function validateRequestAgainstSpec(spec, req, envVars, requestBaseUrl) {
-  const violations = [];
-  const vars = envVars;
-  const url = req.url.replace(/\{\{([^}]+)\}\}/g, (_, k) => vars[k] ?? `{{${k}}}`);
-  const match = findOperation(spec, req.method, url, requestBaseUrl);
-  if (!match) {
-    violations.push({
-      type: "unknown_path",
-      message: `No operation found in spec for ${req.method} ${url}`
-    });
-    return violations;
-  }
-  const { operation } = match;
-  if (req.body.mode === "json" && req.body.json?.trim()) {
-    const requestBody = resolveSchema(spec, operation["requestBody"]);
-    const content = requestBody?.["content"] ?? {};
-    const jsonContent = content["application/json"];
-    if (jsonContent?.["schema"]) {
-      try {
-        const data = JSON.parse(requestCollection.interpolate(req.body.json, vars));
-        const schema = resolveSchema(spec, jsonContent["schema"]);
-        const validate = ajv.compile(schema);
-        if (!validate(data)) {
-          for (const err of validate.errors ?? []) {
-            violations.push({
-              type: "request_body_invalid",
-              message: err.message ?? "Request body schema violation",
-              path: err.instancePath || "/"
-            });
-          }
-        }
-      } catch (e) {
-        violations.push({
-          type: "request_body_invalid",
-          message: `Could not validate request body: ${e instanceof Error ? e.message : String(e)}`
-        });
-      }
-    }
-  }
-  const parameters = resolveSchema(spec, operation["parameters"] ?? []);
-  for (const param of parameters) {
-    const p = param;
-    if (p["in"] === "query" && p["required"] === true) {
-      const name = p["name"];
-      if (!req.params.some((kv) => kv.enabled && kv.key === name)) {
-        violations.push({
-          type: "request_body_invalid",
-          message: `Required query parameter "${name}" is missing`,
-          path: `query.${name}`
-        });
-      }
-    }
-  }
-  return violations;
-}
-async function runProviderVerification(requests, envVars, specUrl, specPath, requestBaseUrl) {
-  const spec = await loadSpec(specUrl, specPath);
-  const start = Date.now();
-  const activeRequests = requests.filter((r) => !r.disabled);
-  const results = activeRequests.map((req) => {
-    const violations = validateRequestAgainstSpec(spec, req, envVars, requestBaseUrl);
-    const url = req.url.replace(/\{\{([^}]+)\}\}/g, (_, k) => envVars[k] ?? `{{${k}}}`);
-    return {
-      requestId: req.id,
-      requestName: req.name,
-      method: req.method,
-      url,
-      passed: violations.length === 0,
-      violations
-    };
-  });
-  const passed = results.filter((r) => r.passed).length;
-  return {
-    mode: "provider",
-    total: results.length,
-    passed,
-    failed: results.length - passed,
-    results,
-    durationMs: Date.now() - start
-  };
-}
-function checkSchemaCompatibility(consumerSchema, providerSchema, path2 = "") {
-  const violations = [];
-  if (!consumerSchema || !providerSchema) return violations;
-  const cType = consumerSchema["type"];
-  const pType = providerSchema["type"];
-  if (cType && pType && cType !== pType) {
-    const ok = cType === "integer" && pType === "number" || cType === "number" && pType === "integer";
-    if (!ok) {
-      violations.push({
-        type: "schema_incompatible",
-        message: `Type mismatch${path2 ? ` at "${path2}"` : ""}: consumer expects "${cType}", provider offers "${pType}"`,
-        path: path2 || "/",
-        expected: cType,
-        actual: pType
-      });
-      return violations;
-    }
-  }
-  if (cType === "array" || Array.isArray(consumerSchema["items"])) {
-    const cItems = consumerSchema["items"];
-    const pItems = providerSchema["items"];
-    if (cItems && pItems) {
-      violations.push(...checkSchemaCompatibility(cItems, pItems, path2 ? `${path2}[]` : "[]"));
-    }
-    return violations;
-  }
-  if (cType === "object" || consumerSchema["properties"]) {
-    const cProps = consumerSchema["properties"] ?? {};
-    const pProps = providerSchema["properties"] ?? {};
-    const cRequired = consumerSchema["required"] ?? [];
-    for (const field of cRequired) {
-      const fieldPath = path2 ? `${path2}.${field}` : field;
-      if (!(field in pProps)) {
-        violations.push({
-          type: "schema_incompatible",
-          message: `Consumer requires field "${fieldPath}" which is not defined in provider schema`,
-          path: fieldPath,
-          expected: "(defined)",
-          actual: "(absent)"
-        });
-      }
-    }
-    for (const [field, cPropSchema] of Object.entries(cProps)) {
-      if (field in pProps) {
-        const fieldPath = path2 ? `${path2}.${field}` : field;
-        violations.push(...checkSchemaCompatibility(
-          cPropSchema,
-          pProps[field],
-          fieldPath
-        ));
-      }
-    }
-  }
-  return violations;
-}
-function getProviderResponseSchema(spec, req, envVars, statusCode, requestBaseUrl) {
-  const url = req.url.replace(/\{\{([^}]+)\}\}/g, (_, k) => envVars[k] ?? `{{${k}}}`);
-  const match = findOperation(spec, req.method, url, requestBaseUrl);
-  if (!match) return null;
-  const responses = match.operation["responses"] ?? {};
-  const candidates = [String(statusCode), `${String(statusCode)[0]}xx`, "2XX", "2xx", "default"];
-  for (const candidate of candidates) {
-    const resp = responses[candidate];
-    if (resp) {
-      const resolved = resolveSchema(spec, resp);
-      const content = resolved["content"] ?? {};
-      const json = content["application/json"];
-      if (json?.["schema"]) {
-        return resolveSchema(spec, json["schema"]);
-      }
-    }
-  }
-  return null;
-}
-async function executeRequest(req, vars) {
-  const url = requestCollection.buildUrl(req.url, req.params, vars);
-  const start = Date.now();
-  try {
-    const headers = new undici.Headers();
-    for (const h of req.headers) {
-      if (h.enabled && h.key) headers.set(requestCollection.interpolate(h.key, vars), requestCollection.interpolate(h.value, vars));
-    }
-    const authHeaders = await requestCollection.buildAuthHeaders(req.auth, vars);
-    for (const [k, v] of Object.entries(authHeaders)) headers.set(k, v);
-    let body;
-    if (req.body.mode === "json" && req.body.json) {
-      body = requestCollection.interpolate(req.body.json, vars);
-      if (!headers.has("content-type")) headers.set("Content-Type", "application/json");
-    }
-    const resp = await undici.fetch(url, {
-      method: req.method,
-      headers,
-      body: !["GET", "HEAD"].includes(req.method) ? body : void 0
-    });
-    const bodyText = await resp.text();
-    const rawHdrs = {};
-    resp.headers.forEach((v, k) => {
-      rawHdrs[k] = v;
-    });
-    return { status: resp.status, headers: rawHdrs, body: bodyText, durationMs: Date.now() - start };
-  } catch (err) {
-    return err instanceof Error ? err : new Error(String(err));
-  }
-}
-async function runBidirectional(requests, envVars, collectionVars = {}, specUrl, specPath, requestBaseUrl) {
-  const spec = await loadSpec(specUrl, specPath);
-  const vars = { ...envVars, ...collectionVars };
-  const start = Date.now();
-  const contractRequests = requests.filter(
-    (r) => !r.disabled && r.contract && (r.contract.statusCode !== void 0 || r.contract.bodySchema || r.contract.headers?.length)
-  );
-  const results = await Promise.all(contractRequests.map(async (req) => {
-    const url = requestCollection.buildUrl(req.url, req.params, vars);
-    const violations = [];
-    const expectedStatus = req.contract.statusCode ?? 200;
-    const consumerSchema = req.contract.bodySchema ? (() => {
-      try {
-        return JSON.parse(req.contract.bodySchema);
-      } catch {
-        return null;
-      }
-    })() : null;
-    if (consumerSchema) {
-      const providerSchema = getProviderResponseSchema(spec, req, vars, expectedStatus, requestBaseUrl);
-      if (!providerSchema) {
-        violations.push({
-          type: "schema_incompatible",
-          message: `No response schema found in spec for ${req.method} ${url} → ${expectedStatus}`
-        });
-      } else {
-        violations.push(...checkSchemaCompatibility(consumerSchema, providerSchema));
-      }
-    }
-    const result = await executeRequest(req, vars);
-    if (result instanceof Error) {
-      violations.push({ type: "status_mismatch", message: `Request failed: ${result.message}` });
-      return { requestId: req.id, requestName: req.name, method: req.method, url, passed: false, violations };
-    }
-    const liveViolations = validateConsumerResponse(
-      req.contract,
-      result.status,
-      result.headers,
-      result.body
-    );
-    violations.push(...liveViolations);
-    return {
-      requestId: req.id,
-      requestName: req.name,
-      method: req.method,
-      url,
-      passed: violations.length === 0,
-      violations,
-      durationMs: result.durationMs,
-      actualStatus: result.status
-    };
-  }));
-  const passed = results.filter((r) => r.passed).length;
-  return {
-    mode: "bidirectional",
-    total: results.length,
-    passed,
-    failed: results.length - passed,
-    results,
-    durationMs: Date.now() - start
-  };
-}
 function inferSchema(data) {
   if (data === null || data === void 0) return { type: "null" };
   if (typeof data === "boolean") return { type: "boolean" };
@@ -4357,22 +4081,60 @@ function inferSchemaFromJson(json) {
     return null;
   }
 }
+async function resolveSnapshotSpec(relPath) {
+  const dir = getWorkspaceDir();
+  if (!dir) throw new Error("No workspace open — cannot resolve snapshot.");
+  const snap = await snapshots.loadSnapshot(dir, relPath);
+  const tmp = path.join(os.tmpdir(), `api-spector-${crypto.randomUUID()}.${snap.format === "yaml" ? "yaml" : "json"}`);
+  await promises.writeFile(tmp, snap.spec, "utf8");
+  return { specPath: tmp };
+}
 function registerContractHandlers(ipc) {
   ipc.handle("contract:run", async (_e, payload) => {
-    const { mode, requests, envVars, collectionVars = {}, specUrl, specPath, requestBaseUrl } = payload;
+    ipcValidate.validateContractRunPayload(payload);
+    const { mode, requests, envVars, collectionVars = {}, requestBaseUrl } = payload;
+    let { specUrl, specPath } = payload;
+    if (payload.specSnapshotRelPath) {
+      const resolved = await resolveSnapshotSpec(payload.specSnapshotRelPath);
+      specPath = resolved.specPath;
+      specUrl = void 0;
+    }
     switch (mode) {
       case "consumer":
-        return runConsumerContracts(requests, envVars, collectionVars);
+        return snapshots.runConsumerContracts(requests, envVars, collectionVars);
       case "provider":
-        return runProviderVerification(requests, envVars, specUrl, specPath, requestBaseUrl);
+        return snapshots.runProviderVerification(requests, envVars, specUrl, specPath, requestBaseUrl);
       case "bidirectional":
-        return runBidirectional(requests, envVars, collectionVars, specUrl, specPath, requestBaseUrl);
+        return snapshots.runBidirectional(requests, envVars, collectionVars, specUrl, specPath, requestBaseUrl);
     }
   });
   ipc.handle("contract:inferSchema", (_e, jsonBody) => {
     const schema = inferSchemaFromJson(jsonBody);
     return schema ? JSON.stringify(schema, null, 2) : null;
   });
+  ipc.handle("contract:captureSnapshot", async (_e, opts) => {
+    const dir = getWorkspaceDir();
+    if (!dir) throw new Error("No workspace open — cannot capture snapshot.");
+    const snapshot = await snapshots.captureSnapshot(dir, opts);
+    const relPath = snapshots.relPathOf(snapshot);
+    if (!relPath) throw new Error("Snapshot created but relPath was not attached.");
+    return { relPath, snapshot };
+  });
+  ipc.handle("contract:listSnapshots", async (_e, registered = []) => {
+    const dir = getWorkspaceDir();
+    if (!dir) return [];
+    return snapshots.listSnapshots(dir, registered);
+  });
+  ipc.handle("contract:loadSnapshot", async (_e, relPath) => {
+    const dir = getWorkspaceDir();
+    if (!dir) throw new Error("No workspace open.");
+    return snapshots.loadSnapshot(dir, relPath);
+  });
+  ipc.handle("contract:deleteSnapshot", async (_e, relPath) => {
+    const dir = getWorkspaceDir();
+    if (!dir) return;
+    await snapshots.deleteSnapshot(dir, relPath);
+  });
 }
 function git() {
   const dir = getWorkspaceDir();
@@ -4390,6 +4152,8 @@ function registerGitHandlers(ipc) {
   });
   ipc.handle("git:init", async () => {
     await git().init();
+    const dir = getWorkspaceDir();
+    if (dir) await ensureGitignore(dir);
   });
   ipc.handle("git:status", async () => {
     const result = await git().status();
@@ -4449,16 +4213,58 @@ function registerGitHandlers(ipc) {
     }));
   });
   ipc.handle("git:branches", async () => {
-    const result = await git().branch(["-a", "--format=%(refname:short)|%(objectname:short)|%(upstream:short)|%(upstream:track)"]);
-    return result.all.filter((name) => !name.includes("HEAD")).map((name) => ({
-      name: name.replace(/^remotes\//, ""),
-      current: name === result.current,
-      remote: name.startsWith("remotes/")
-    }));
+    const raw = await git().raw([
+      "for-each-ref",
+      "--format=%(refname:short)|%(HEAD)|%(upstream:short)|%(upstream:track)",
+      "refs/heads",
+      "refs/remotes"
+    ]);
+    const current = (await git().branch()).current;
+    const branches = [];
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      const [shortName, head, upstream, track] = line.split("|");
+      if (!shortName || shortName.endsWith("/HEAD")) continue;
+      const isRemote = shortName.startsWith("origin/") || shortName.includes("/");
+      const looksLocal = !isRemote;
+      let ahead;
+      let behind;
+      const aheadM = track?.match(/ahead (\d+)/);
+      const behindM = track?.match(/behind (\d+)/);
+      if (aheadM) ahead = Number(aheadM[1]);
+      if (behindM) behind = Number(behindM[1]);
+      branches.push({
+        name: shortName,
+        current: looksLocal && (head === "*" || shortName === current),
+        remote: isRemote,
+        upstream: upstream || void 0,
+        ahead,
+        behind
+      });
+    }
+    return branches;
   });
   ipc.handle("git:checkout", async (_e, branch, create) => {
-    if (create) await git().checkoutLocalBranch(branch);
-    else await git().checkout(branch);
+    if (create) {
+      await git().checkoutLocalBranch(branch);
+      return;
+    }
+    const m = /^([^/]+)\/(.+)$/.exec(branch);
+    if (m) {
+      const remote = m[1];
+      const localName = m[2];
+      const localList = await git().branchLocal();
+      if (!localList.all.includes(localName)) {
+        await git().checkoutBranch(localName, `${remote}/${localName}`);
+        return;
+      }
+      await git().checkout(localName);
+      return;
+    }
+    await git().checkout(branch);
+  });
+  ipc.handle("git:deleteBranch", async (_e, name, force = false) => {
+    await git().deleteLocalBranch(name, force);
   });
   ipc.handle("git:pull", async () => {
     await git().pull();
@@ -4608,17 +4414,17 @@ function createWindow() {
 }
 electron.app.whenReady().then(async () => {
   if (process.platform !== "darwin") electron.Menu.setApplicationMenu(null);
-  await requestCollection.initSecretStore(electron.app.getPath("userData"));
+  await authBuilder.initSecretStore(electron.app.getPath("userData"));
   registerFileHandlers(electron.ipcMain);
   requestCollection.registerRequestHandler(electron.ipcMain);
-  requestCollection.registerSecretHandlers(electron.ipcMain);
+  authBuilder.registerSecretHandlers(electron.ipcMain);
   registerImportHandlers(electron.ipcMain);
   registerGenerateHandlers(electron.ipcMain);
   registerRunnerHandler(electron.ipcMain);
   registerMockHandlers(electron.ipcMain);
   registerOAuth2Handlers(electron.ipcMain);
   registerWsHandlers(electron.ipcMain);
-  registerSoapHandlers(electron.ipcMain);
+  soapHandler.registerSoapHandlers(electron.ipcMain);
   registerDocsHandlers(electron.ipcMain);
   registerContractHandlers(electron.ipcMain);
   registerGitHandlers(electron.ipcMain);