@testsmith/api-spector 0.3.1 → 0.3.3

package/out/main/contract.js

@@ -2,67 +2,394 @@
 "use strict";
 const promises = require("fs/promises");
 const path = require("path");
-const snapshots = require("./chunks/snapshots-CQliv7WB.js");
-const os = require("os");
+const snapshots = require("./chunks/snapshots-UFd3XgSS.js");
 const crypto = require("crypto");
+const os = require("os");
+const cliCommon = require("./chunks/cli-common-CDQY1erJ.js");
 require("undici");
-require("js-yaml");
-require("ajv");
-require("./chunks/auth-builder-CRQayp8x.js");
+require("./chunks/auth-builder-CUs9yzOF.js");
 require("http");
+require("./chunks/handle-C0IQL-Vl.js");
 require("dayjs");
 require("vm");
-function parseArgs(argv) {
-  const args = {};
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg.startsWith("--")) {
-      const key = arg.slice(2);
-      const next = argv[i + 1];
-      if (!next || next.startsWith("--")) {
-        args[key] = true;
-      } else {
-        args[key] = next;
-        i++;
-      }
-    }
+require("js-yaml");
+require("ajv");
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function caseXml(r) {
+  const name = escapeXml(`${r.method} ${r.requestName}`);
+  const time = ((r.durationMs ?? 0) / 1e3).toFixed(3);
+  const classnm = escapeXml(r.url);
+  if (r.passed) {
+    return `    <testcase name="${name}" classname="${classnm}" time="${time}"/>`;
   }
-  return args;
+  const messages = r.violations.map((v) => `${v.type}: ${v.message}${v.path ? ` (${v.path})` : ""}`);
+  const summary = escapeXml(messages[0] ?? "contract failed");
+  const detail = escapeXml(messages.join("\n"));
+  return [
+    `    <testcase name="${name}" classname="${classnm}" time="${time}">`,
+    `      <failure message="${summary}">${detail}</failure>`,
+    `    </testcase>`
+  ].join("\n");
 }
-async function resolveWorkspacePath(wsPath) {
-  const s = await promises.stat(wsPath);
-  if (!s.isDirectory()) return wsPath;
-  const entries = await promises.readdir(wsPath);
-  const spector = entries.find((e) => e.endsWith(".spector"));
-  if (!spector) throw new Error(`No .spector workspace file found in directory: ${wsPath}`);
-  return path.join(wsPath, spector);
+function toJUnitXml(report, suiteName = "contract") {
+  const time = (report.durationMs / 1e3).toFixed(3);
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<testsuites name="api-spector" tests="${report.total}" failures="${report.failed}" time="${time}">`,
+    `  <testsuite name="${escapeXml(`${suiteName}:${report.mode}`)}" tests="${report.total}" failures="${report.failed}" time="${time}">`,
+    ...report.results.map(caseXml),
+    "  </testsuite>",
+    "</testsuites>"
+  ];
+  return lines.join("\n") + "\n";
 }
-async function loadWorkspace(wsPath) {
-  const resolved = await resolveWorkspacePath(wsPath);
-  const raw = await promises.readFile(resolved, "utf8");
-  return { workspace: JSON.parse(raw), dir: path.dirname(path.resolve(resolved)) };
+const RESULTS_DIR = "contracts/results";
+function safe(part) {
+  return part.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
 }
-async function loadCollections(ws, dir, filterName) {
-  const cols = [];
-  for (const relPath of ws.collections) {
+function resultPath(dir, pacticipant, version) {
+  return path.join(dir, RESULTS_DIR, safe(pacticipant), `${safe(version)}.json`);
+}
+async function recordResult(dir, pacticipant, version, report, now) {
+  const file = resultPath(dir, pacticipant, version);
+  await promises.mkdir(path.join(dir, RESULTS_DIR, safe(pacticipant)), { recursive: true });
+  const record = {
+    pacticipant,
+    version,
+    recordedAt: now,
+    passed: report.failed === 0,
+    report
+  };
+  await promises.writeFile(file, JSON.stringify(record, null, 2), "utf8");
+  return file;
+}
+async function listResults(dir) {
+  const root = path.join(dir, RESULTS_DIR);
+  const out = [];
+  let pacticipants;
+  try {
+    pacticipants = await promises.readdir(root);
+  } catch {
+    return out;
+  }
+  for (const p of pacticipants) {
+    let files;
     try {
-      const raw = await promises.readFile(path.join(dir, relPath), "utf8");
-      const col = JSON.parse(raw);
-      if (!filterName || col.name === filterName) cols.push(col);
+      files = await promises.readdir(path.join(root, p));
     } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (!f.endsWith(".json")) continue;
+      try {
+        out.push(JSON.parse(await promises.readFile(path.join(root, p, f), "utf8")));
+      } catch {
+      }
     }
   }
-  return cols;
+  return out;
 }
-async function loadEnvironments(ws, dir) {
-  const envs = [];
-  for (const relPath of ws.environments) {
-    try {
-      envs.push(JSON.parse(await promises.readFile(path.join(dir, relPath), "utf8")));
-    } catch {
+async function canIDeploy(dir, pacticipant, version) {
+  const file = resultPath(dir, pacticipant, version);
+  let record;
+  try {
+    record = JSON.parse(await promises.readFile(file, "utf8"));
+  } catch {
+    return {
+      deployable: false,
+      reason: `No verification result recorded for ${pacticipant}@${version}. Run \`contract run … --record --pacticipant ${pacticipant} --app-version ${version}\` first.`
+    };
+  }
+  if (record.passed) {
+    return {
+      deployable: true,
+      reason: `${pacticipant}@${version} passed all ${record.report.total} contract checks (verified ${record.recordedAt}).`,
+      record
+    };
+  }
+  return {
+    deployable: false,
+    reason: `${pacticipant}@${version} has ${record.report.failed}/${record.report.total} failing contract checks (verified ${record.recordedAt}).`,
+    record
+  };
+}
+function parsePath(path2) {
+  const tokens = [];
+  const re = /\.([^.[\]]+)|\['([^']*)'\]|\[(\d+|\*)\]/g;
+  let m;
+  while ((m = re.exec(path2)) !== null) {
+    if (m[1] !== void 0) tokens.push({ key: m[1] });
+    else if (m[2] !== void 0) tokens.push({ key: m[2] });
+    else if (m[3] !== void 0) tokens.push({ index: m[3] === "*" ? "*" : Number(m[3]) });
+  }
+  return tokens;
+}
+function ruleToMatcher(value, rule) {
+  switch (rule.match) {
+    case "type":
+      if (Array.isArray(value)) {
+        return { [snapshots.MATCH_KEY]: "eachLike", value: value[0] ?? {}, min: rule.min ?? 1 };
+      }
+      return { [snapshots.MATCH_KEY]: "type", value };
+    case "regex":
+      return { [snapshots.MATCH_KEY]: "regex", regex: rule.regex ?? ".*", value };
+    case "integer":
+      return { [snapshots.MATCH_KEY]: "integer", value };
+    case "number":
+    case "decimal":
+      return { [snapshots.MATCH_KEY]: "decimal", value };
+    case "boolean":
+      return { [snapshots.MATCH_KEY]: "boolean", value };
+    case "datetime":
+    case "timestamp":
+      return { [snapshots.MATCH_KEY]: "datetime", value, format: rule.format };
+    case "date":
+      return { [snapshots.MATCH_KEY]: "date", value };
+    case "time":
+      return { [snapshots.MATCH_KEY]: "time", value };
+    default:
+      return value;
+  }
+}
+function applyAtPath(root, tokens, transform) {
+  if (tokens.length === 0) return transform(root);
+  const [head, ...rest] = tokens;
+  if ("index" in head) {
+    if (!Array.isArray(root)) return root;
+    if (head.index === "*") {
+      return root.map((el) => applyAtPath(el, rest, transform));
     }
+    const arr = [...root];
+    if (head.index < arr.length) arr[head.index] = applyAtPath(arr[head.index], rest, transform);
+    return arr;
   }
-  return envs;
+  if (typeof root !== "object" || root === null || Array.isArray(root)) return root;
+  const obj = { ...root };
+  if (head.key in obj) obj[head.key] = applyAtPath(obj[head.key], rest, transform);
+  return obj;
+}
+function bodyWithMatchers(body, matchingRules) {
+  const bodyRules = matchingRules?.["body"] ?? matchingRules?.["content"];
+  if (!bodyRules || body === void 0) return body;
+  const entries = Object.entries(bodyRules).sort((a, b) => parsePath(b[0]).length - parsePath(a[0]).length);
+  let result = body;
+  for (const [path2, def] of entries) {
+    const rule = def?.matchers?.[0];
+    if (!rule) continue;
+    const tokens = parsePath(path2);
+    result = applyAtPath(result, tokens, (v) => ruleToMatcher(v, rule));
+  }
+  return result;
+}
+function providerStatesOf(interaction) {
+  const v3 = interaction["providerStates"];
+  if (Array.isArray(v3)) return v3.map((s) => s?.name ?? "").filter(Boolean);
+  const v2 = interaction["providerState"] ?? interaction["provider_state"];
+  return typeof v2 === "string" && v2 ? [v2] : [];
+}
+function queryToParams(query) {
+  const params = [];
+  if (!query) return params;
+  if (typeof query === "string") {
+    for (const pair of query.split("&")) {
+      const [k, v = ""] = pair.split("=");
+      if (k) params.push({ key: decodeURIComponent(k), value: decodeURIComponent(v), enabled: true });
+    }
+  } else if (typeof query === "object") {
+    for (const [k, vals] of Object.entries(query)) {
+      const list = Array.isArray(vals) ? vals : [vals];
+      for (const v of list) params.push({ key: k, value: String(v ?? ""), enabled: true });
+    }
+  }
+  return params;
+}
+function headerEntries(headers) {
+  if (!headers || typeof headers !== "object") return [];
+  return Object.entries(headers).map(([key, value]) => ({
+    key,
+    value: Array.isArray(value) ? value.join(", ") : String(value ?? "")
+  }));
+}
+function headersToKv(headers) {
+  return headerEntries(headers).map((h) => ({ ...h, enabled: true }));
+}
+function headersToContract(headers) {
+  return headerEntries(headers).map((h) => ({ ...h, required: true }));
+}
+function importInteraction(interaction) {
+  const request = interaction["request"] ?? {};
+  const response = interaction["response"] ?? {};
+  const method = String(request["method"] ?? "GET").toUpperCase();
+  const path2 = String(request["path"] ?? "/");
+  const reqBody = request["body"];
+  const body = reqBody === void 0 ? { mode: "none" } : typeof reqBody === "string" ? { mode: "raw", raw: reqBody } : { mode: "json", json: JSON.stringify(reqBody, null, 2) };
+  const contract = {};
+  if (typeof response["status"] === "number") contract.statusCode = response["status"];
+  const respHeaders = headersToContract(response["headers"]);
+  if (respHeaders?.length) contract.headers = respHeaders;
+  if (response["body"] !== void 0) {
+    const example = bodyWithMatchers(response["body"], response["matchingRules"]);
+    contract.bodyMatcher = JSON.stringify(example, null, 2);
+  }
+  const states = providerStatesOf(interaction);
+  if (states.length) contract.providerStates = states;
+  return {
+    id: crypto.randomUUID(),
+    name: String(interaction["description"] ?? `${method} ${path2}`),
+    method,
+    url: `{{baseUrl}}${path2}`,
+    headers: headersToKv(request["headers"]),
+    params: queryToParams(request["query"]),
+    auth: { type: "none" },
+    body,
+    contract,
+    meta: { tags: ["pact"] }
+  };
+}
+function importPact(json) {
+  const pact = typeof json === "string" ? JSON.parse(json) : json;
+  const consumer = pact["consumer"]?.name ?? "consumer";
+  const provider = pact["provider"]?.name ?? "provider";
+  const metadata = pact["metadata"];
+  const specVersion = String(
+    metadata?.["pactSpecification"]?.version ?? metadata?.["pact-specification"]?.version ?? "3.0.0"
+  );
+  const interactions = pact["interactions"] ?? [];
+  const httpInteractions = interactions.filter((i) => {
+    const type = i["type"];
+    return type === void 0 || type === "Synchronous/HTTP" || type === "HTTP";
+  });
+  return {
+    consumer,
+    provider,
+    specVersion,
+    requests: httpInteractions.map(importInteraction)
+  };
+}
+function pactToCollection(result) {
+  const requests = {};
+  for (const r of result.requests) requests[r.id] = r;
+  return {
+    version: "1.0",
+    id: crypto.randomUUID(),
+    name: `${result.consumer} → ${result.provider}`,
+    description: `Imported from Pact (spec ${result.specVersion})`,
+    rootFolder: {
+      id: crypto.randomUUID(),
+      name: "root",
+      folders: [],
+      requestIds: result.requests.map((r) => r.id)
+    },
+    requests,
+    collectionVariables: { baseUrl: "" }
+  };
+}
+function isMatcher(node) {
+  return typeof node === "object" && node !== null && !Array.isArray(node) && typeof node[snapshots.MATCH_KEY] === "string";
+}
+function exampleToPactBody(node) {
+  const rules = {};
+  function walk(n, path2) {
+    if (isMatcher(n)) {
+      const kind = n[snapshots.MATCH_KEY];
+      switch (kind) {
+        case "type":
+          rules[path2] = { matchers: [{ match: "type" }] };
+          return walk(n.value, path2);
+        case "eachLike": {
+          rules[path2] = { matchers: [{ match: "type", min: n.min ?? 1 }] };
+          return [walk(n.value, `${path2}[*]`)];
+        }
+        case "regex":
+          rules[path2] = { matchers: [{ match: "regex", regex: n.regex ?? ".*" }] };
+          return n.value ?? "";
+        case "integer":
+          rules[path2] = { matchers: [{ match: "integer" }] };
+          return n.value ?? 0;
+        case "decimal":
+        case "number":
+          rules[path2] = { matchers: [{ match: "decimal" }] };
+          return n.value ?? 0;
+        case "boolean":
+          rules[path2] = { matchers: [{ match: "type" }] };
+          return n.value ?? false;
+        case "datetime":
+        case "timestamp":
+          rules[path2] = { matchers: [{ match: "datetime", format: n.format }] };
+          return n.value ?? "";
+        case "date":
+          rules[path2] = { matchers: [{ match: "date" }] };
+          return n.value ?? "";
+        case "time":
+          rules[path2] = { matchers: [{ match: "time" }] };
+          return n.value ?? "";
+        default:
+          return n.value;
+      }
+    }
+    if (Array.isArray(n)) return n.map((el, i) => walk(el, `${path2}[${i}]`));
+    if (typeof n === "object" && n !== null) {
+      const out = {};
+      for (const [k, v] of Object.entries(n)) out[k] = walk(v, `${path2}.${k}`);
+      return out;
+    }
+    return n;
+  }
+  const body = walk(node, "$");
+  return { body, rules };
+}
+function kvToHeaders(kv) {
+  if (!kv?.length) return void 0;
+  const out = {};
+  for (const h of kv) if (h.enabled !== false && h.key) out[h.key] = h.value;
+  return Object.keys(out).length ? out : void 0;
+}
+function exportPact(consumer, provider, requests) {
+  const interactions = requests.filter((r) => r.contract).map((r) => {
+    const c = r.contract;
+    const path2 = r.url.replace(/^\{\{baseUrl\}\}/, "").replace(/^https?:\/\/[^/]+/, "") || "/";
+    const query = {};
+    for (const p of r.params ?? []) {
+      if (p.enabled === false || !p.key) continue;
+      (query[p.key] ??= []).push(p.value);
+    }
+    const response = {};
+    if (c.statusCode !== void 0) response["status"] = c.statusCode;
+    const respHeaders = kvToHeaders(c.headers);
+    if (respHeaders) response["headers"] = respHeaders;
+    if (c.bodyMatcher?.trim()) {
+      try {
+        const { body, rules } = exampleToPactBody(JSON.parse(c.bodyMatcher));
+        response["body"] = body;
+        if (Object.keys(rules).length) response["matchingRules"] = { body: rules };
+      } catch {
+      }
+    }
+    const request = { method: r.method, path: path2 };
+    if (Object.keys(query).length) request["query"] = query;
+    const reqHeaders = kvToHeaders(r.headers);
+    if (reqHeaders) request["headers"] = reqHeaders;
+    if (r.body?.mode === "json" && r.body.json) {
+      try {
+        request["body"] = JSON.parse(r.body.json);
+      } catch {
+      }
+    } else if (r.body?.mode === "raw" && r.body.raw) request["body"] = r.body.raw;
+    const interaction = { description: r.name, request, response };
+    if (c.providerStates?.length) interaction["providerStates"] = c.providerStates.map((name) => ({ name }));
+    return interaction;
+  });
+  return {
+    consumer: { name: consumer },
+    provider: { name: provider },
+    interactions,
+    metadata: {
+      pactSpecification: { version: "3.0.0" },
+      client: { name: "api-spector" }
+    }
+  };
 }
 async function cmdList(args) {
   const wsArg = args["workspace"];
@@ -70,7 +397,7 @@ async function cmdList(args) {
     console.error("  [error] --workspace <path> is required");
     process.exit(2);
   }
-  const { workspace, dir } = await loadWorkspace(wsArg);
+  const { workspace, dir } = await cliCommon.loadWorkspace(wsArg);
   const snapshots$1 = await snapshots.listSnapshots(dir, workspace.contracts ?? []);
   if (snapshots$1.length === 0) {
     console.log("  No contract snapshots. Capture one from the app or via:");
@@ -110,14 +437,14 @@ async function cmdRun(args) {
     console.error("  [error] --workspace <path> is required");
     process.exit(2);
   }
-  if (mode !== "consumer" && mode !== "provider" && mode !== "bidirectional") {
-    console.error("  [error] --mode must be one of: consumer, provider, bidirectional");
+  if (mode !== "consumer" && mode !== "provider" && mode !== "provider-live" && mode !== "bidirectional") {
+    console.error("  [error] --mode must be one of: consumer, provider, provider-live, bidirectional");
     process.exit(2);
   }
-  const { workspace, dir } = await loadWorkspace(wsArg);
+  const { workspace, dir } = await cliCommon.loadWorkspace(wsArg);
   const collectionName = typeof args["collection"] === "string" ? args["collection"] : void 0;
-  const collections = await loadCollections(workspace, dir, collectionName);
-  const envs = await loadEnvironments(workspace, dir);
+  const collections = await cliCommon.loadCollections(workspace, dir, { filterName: collectionName });
+  const envs = await cliCommon.loadEnvironments(workspace, dir);
   const envName = typeof args["environment"] === "string" ? args["environment"] : void 0;
   const activeEnv = envName ? envs.find((e) => e.name === envName) : envs[0];
   const envVars = {};
@@ -125,9 +452,7 @@ async function cmdRun(args) {
   const collectionVars = {};
   for (const c of collections) Object.assign(collectionVars, c.collectionVariables ?? {});
   const allRequests = collections.flatMap((c) => Object.values(c.requests));
-  const contractRequests = allRequests.filter(
-    (r) => r.contract && (r.contract.statusCode !== void 0 || r.contract.bodySchema || r.contract.headers?.length)
-  );
+  const contractRequests = allRequests.filter((r) => snapshots.hasContract(r.contract));
   let specUrl = typeof args["spec-url"] === "string" ? args["spec-url"] : void 0;
   let specPath = typeof args["spec-path"] === "string" ? args["spec-path"] : void 0;
   let snapshotLabel;
@@ -140,14 +465,21 @@ async function cmdRun(args) {
     snapshotLabel = `${snapshot.name}${snapshot.specVersion ? ` (${snapshot.specVersion})` : ""}`;
   }
   const requestBaseUrl = typeof args["request-base-url"] === "string" ? args["request-base-url"] : void 0;
-  if (mode !== "consumer" && !specUrl && !specPath) {
+  const providerBaseUrl = typeof args["provider-base-url"] === "string" ? args["provider-base-url"] : void 0;
+  const stateHandlerUrl = typeof args["states-url"] === "string" ? args["states-url"] : void 0;
+  if ((mode === "provider" || mode === "bidirectional") && !specUrl && !specPath) {
     console.error("  [error] Provider / bidirectional mode requires --snapshot, --spec-url, or --spec-path");
     process.exit(2);
   }
+  if (mode === "provider-live" && !providerBaseUrl) {
+    console.error("  [error] provider-live mode requires --provider-base-url <url>");
+    process.exit(2);
+  }
   console.log(`  Running ${mode} contracts…`);
   if (snapshotLabel) console.log(`  Spec: snapshot "${snapshotLabel}"`);
   else if (specUrl) console.log(`  Spec: ${specUrl} (live)`);
   else if (specPath) console.log(`  Spec: ${specPath}`);
+  if (providerBaseUrl) console.log(`  Provider: ${providerBaseUrl}`);
   let report;
   const modeValue = mode;
   switch (modeValue) {
@@ -157,6 +489,9 @@ async function cmdRun(args) {
     case "provider":
       report = await snapshots.runProviderVerification(allRequests, envVars, specUrl, specPath, requestBaseUrl);
       break;
+    case "provider-live":
+      report = await snapshots.runLiveProviderVerification(contractRequests, envVars, collectionVars, providerBaseUrl, stateHandlerUrl);
+      break;
     case "bidirectional":
       report = await snapshots.runBidirectional(contractRequests, envVars, collectionVars, specUrl, specPath, requestBaseUrl);
       break;
@@ -179,17 +514,132 @@ async function cmdRun(args) {
     console.log(`
   Report written to ${args["output"]}`);
   }
+  if (typeof args["junit"] === "string") {
+    await promises.writeFile(args["junit"], toJUnitXml(report), "utf8");
+    console.log(`  JUnit report written to ${args["junit"]}`);
+  }
+  if (typeof args["html"] === "string") {
+    const html = snapshots.reportToHtml(report, {
+      consumer: collections[0]?.name,
+      provider: providerBaseUrl,
+      spec: snapshotLabel ?? specUrl ?? specPath,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    await promises.writeFile(args["html"], html, "utf8");
+    console.log(`  HTML report written to ${args["html"]}`);
+  }
+  if (args["record"]) {
+    const appVersion = typeof args["app-version"] === "string" ? args["app-version"] : void 0;
+    if (!appVersion) {
+      console.error("  [error] --record requires --app-version <version>");
+      process.exit(2);
+    }
+    const pacticipant = typeof args["pacticipant"] === "string" ? args["pacticipant"] : collections[0]?.name ?? "app";
+    const file = await recordResult(dir, pacticipant, appVersion, report, (/* @__PURE__ */ new Date()).toISOString());
+    console.log(`  Recorded result for ${pacticipant}@${appVersion} → ${file}`);
+  }
   process.exit(report.failed === 0 ? 0 : 1);
 }
+async function cmdCanIDeploy(args) {
+  const wsArg = args["workspace"];
+  const pacticipant = args["pacticipant"];
+  const appVersion = args["app-version"];
+  if (typeof wsArg !== "string") {
+    console.error("  [error] --workspace <path> is required");
+    process.exit(2);
+  }
+  if (typeof pacticipant !== "string") {
+    console.error("  [error] --pacticipant <name> is required");
+    process.exit(2);
+  }
+  if (typeof appVersion !== "string") {
+    console.error("  [error] --app-version <version> is required");
+    process.exit(2);
+  }
+  const { dir } = await cliCommon.loadWorkspace(wsArg);
+  const verdict = await canIDeploy(dir, pacticipant, appVersion);
+  console.log("");
+  console.log(verdict.deployable ? `  ✓ Computer says yes — safe to deploy.` : `  ✗ Computer says no.`);
+  console.log(`  ${verdict.reason}`);
+  process.exit(verdict.deployable ? 0 : 1);
+}
+async function cmdReport(args) {
+  const wsArg = args["workspace"];
+  if (typeof wsArg !== "string") {
+    console.error("  [error] --workspace <path> is required");
+    process.exit(2);
+  }
+  const out = typeof args["html"] === "string" ? args["html"] : "contract-dashboard.html";
+  const { dir } = await cliCommon.loadWorkspace(wsArg);
+  const records = await listResults(dir);
+  await promises.writeFile(out, snapshots.dashboardToHtml(records, (/* @__PURE__ */ new Date()).toISOString()), "utf8");
+  console.log(`  Dashboard with ${records.length} recorded result(s) written to ${out}`);
+}
+async function cmdPactImport(args) {
+  const file = args["file"];
+  if (typeof file !== "string") {
+    console.error("  [error] --file <pact.json> is required");
+    process.exit(2);
+  }
+  const result = importPact(await promises.readFile(file, "utf8"));
+  console.log(`  Imported ${result.requests.length} interaction(s): ${result.consumer} → ${result.provider} (spec ${result.specVersion})`);
+  if (typeof args["out"] === "string") {
+    const collection = pactToCollection(result);
+    await promises.writeFile(args["out"], JSON.stringify(collection, null, 2), "utf8");
+    console.log(`  Collection written to ${args["out"]}`);
+    console.log(`  Set the "baseUrl" collection variable, then verify with:`);
+    console.log(`    api-spector contract run --workspace <path> --mode provider-live --provider-base-url <url>`);
+  }
+}
+async function cmdPactExport(args) {
+  const wsArg = args["workspace"];
+  const out = args["out"];
+  if (typeof wsArg !== "string") {
+    console.error("  [error] --workspace <path> is required");
+    process.exit(2);
+  }
+  if (typeof out !== "string") {
+    console.error("  [error] --out <pact.json> is required");
+    process.exit(2);
+  }
+  const { workspace, dir } = await cliCommon.loadWorkspace(wsArg);
+  const collectionName = typeof args["collection"] === "string" ? args["collection"] : void 0;
+  const collections = await cliCommon.loadCollections(workspace, dir, { filterName: collectionName });
+  const requests = collections.flatMap((c) => Object.values(c.requests)).filter((r) => snapshots.hasContract(r.contract));
+  if (requests.length === 0) {
+    console.error("  [error] No requests with contracts found to export.");
+    process.exit(2);
+  }
+  const consumer = typeof args["consumer"] === "string" ? args["consumer"] : collections[0]?.name ?? "consumer";
+  const provider = typeof args["provider"] === "string" ? args["provider"] : "provider";
+  const pact = exportPact(consumer, provider, requests);
+  await promises.writeFile(out, JSON.stringify(pact, null, 2), "utf8");
+  console.log(`  Exported ${requests.length} interaction(s) to ${out} (${consumer} → ${provider})`);
+}
 async function main() {
   const [, , sub, ...rest] = process.argv;
-  const args = parseArgs(rest);
+  const args = cliCommon.parseArgs(rest);
   if (sub === "list") return cmdList(args);
   if (sub === "run") return cmdRun(args);
+  if (sub === "can-i-deploy") return cmdCanIDeploy(args);
+  if (sub === "report") return cmdReport(args);
+  if (sub === "pact-import") return cmdPactImport(args);
+  if (sub === "pact-export") return cmdPactExport(args);
   if (args["help"] || !sub) {
     console.log(`
-  api-spector contract list  --workspace <path>
-  api-spector contract run   --workspace <path> --mode <consumer|provider|bidirectional> [options]
+  api-spector contract list          --workspace <path>
+  api-spector contract run           --workspace <path> --mode <consumer|provider|provider-live|bidirectional> [options]
+  api-spector contract report        --workspace <path> [--html <path>]
+  api-spector contract can-i-deploy  --workspace <path> --pacticipant <name> --app-version <ver>
+  api-spector contract pact-import   --file <pact.json> [--out <collection.json>]
+  api-spector contract pact-export   --workspace <path> --out <pact.json> [--consumer <name> --provider <name> --collection <name>]
+
+  Modes:
+    consumer       Send requests to the real provider, assert each response (live).
+    provider       Static check that requests conform to an OpenAPI spec (no HTTP).
+    provider-live  Replay consumer contracts against a running provider, with
+                   provider-state setup. The real Pact-style verification.
+    bidirectional  Static spec/contract compatibility + live response check.
 
   Run options:
     --snapshot <id|name>      Pinned snapshot (run list to see IDs)
@@ -198,7 +648,14 @@ async function main() {
     --collection <name>       Filter to one collection
     --environment <name>      Environment for {{var}} resolution
     --request-base-url <url>  Strip this host before matching spec paths
+    --provider-base-url <url> (provider-live) rebase requests onto this origin
+    --states-url <url>        (provider-live) provider state handler endpoint
     --output <path>           Write ContractReport JSON here
+    --junit <path>            Write JUnit XML here (for CI test reporters)
+    --html <path>             Write a self-contained HTML report here
+    --record                  Record the result for can-i-deploy gating
+    --pacticipant <name>      Name to record under (default: collection name)
+    --app-version <ver>       Version to record under (required with --record)
 `);
     return;
   }