@testsmith/api-spector 0.3.4 → 0.3.6

package/out/main/contract.js

@@ -1,19 +1,45 @@
 #!/usr/bin/env node
 "use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 const promises = require("fs/promises");
 const path = require("path");
-const snapshots = require("./chunks/snapshots-UFd3XgSS.js");
+const snapshots = require("./chunks/snapshots-rV5tPwAd.js");
 const crypto = require("crypto");
+const undici = require("undici");
 const os = require("os");
 const cliCommon = require("./chunks/cli-common-CDQY1erJ.js");
-require("undici");
-require("./chunks/auth-builder-CUs9yzOF.js");
-require("http");
-require("./chunks/handle-C0IQL-Vl.js");
+const environments = require("./chunks/environments-iM3SUM-4.js");
+require("./chunks/request-exec-DbNHbA8x.js");
+require("./chunks/handle-BtRMtQJg.js");
 require("dayjs");
 require("vm");
-require("js-yaml");
+require("tv4");
+require("jsonpath-plus");
+require("@xmldom/xmldom");
+require("http");
 require("ajv");
+require("js-yaml");
 function escapeXml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
@@ -45,76 +71,6 @@ function toJUnitXml(report, suiteName = "contract") {
   ];
   return lines.join("\n") + "\n";
 }
-const RESULTS_DIR = "contracts/results";
-function safe(part) {
-  return part.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
-}
-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 {
-      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 out;
-}
-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;
@@ -142,6 +98,8 @@ function ruleToMatcher(value, rule) {
       return { [snapshots.MATCH_KEY]: "decimal", value };
     case "boolean":
       return { [snapshots.MATCH_KEY]: "boolean", value };
+    case "null":
+      return { [snapshots.MATCH_KEY]: "null", value: null };
     case "datetime":
     case "timestamp":
       return { [snapshots.MATCH_KEY]: "datetime", value, format: rule.format };
@@ -313,8 +271,14 @@ function exampleToPactBody(node) {
           rules[path2] = { matchers: [{ match: "decimal" }] };
           return n.value ?? 0;
         case "boolean":
-          rules[path2] = { matchers: [{ match: "type" }] };
+          rules[path2] = { matchers: [{ match: "boolean" }] };
           return n.value ?? false;
+        case "string":
+          rules[path2] = { matchers: [{ match: "type" }] };
+          return n.value ?? "";
+        case "null":
+          rules[path2] = { matchers: [{ match: "null" }] };
+          return null;
         case "datetime":
         case "timestamp":
           rules[path2] = { matchers: [{ match: "datetime", format: n.format }] };
@@ -391,6 +355,149 @@ function exportPact(consumer, provider, requests) {
     }
   };
 }
+const PENDING_FILE = "contracts/pending.json";
+function interactionKey(req) {
+  const contractHash = crypto.createHash("sha256").update(JSON.stringify(req.contract ?? {})).digest("hex").slice(0, 16);
+  return `${req.id}:${contractHash}`;
+}
+async function loadPendingStore(dir) {
+  try {
+    return JSON.parse(await promises.readFile(path.join(dir, PENDING_FILE), "utf8"));
+  } catch {
+    return { firstPassed: {} };
+  }
+}
+async function savePendingStore(dir, store) {
+  const file = path.join(dir, PENDING_FILE);
+  await promises.mkdir(path.dirname(file), { recursive: true });
+  await promises.writeFile(file, JSON.stringify(store, null, 2), "utf8");
+}
+function applyPendingSemantics(report, requests, store, now) {
+  const byId = new Map(requests.map((r) => [r.id, r]));
+  const newlyPassed = [];
+  let pendingCount = 0;
+  for (const result of report.results) {
+    const req = byId.get(result.requestId);
+    if (!req) continue;
+    const key = interactionKey(req);
+    if (result.passed) {
+      if (!store.firstPassed[key]) {
+        store.firstPassed[key] = now;
+        newlyPassed.push(key);
+      }
+      continue;
+    }
+    if (!store.firstPassed[key]) {
+      result.pending = true;
+      pendingCount++;
+    }
+  }
+  if (pendingCount > 0) {
+    report.failed -= pendingCount;
+    report.pending = pendingCount;
+  }
+  return { newlyPassed };
+}
+const WEBHOOKS_FILE = "contracts/webhooks.json";
+function substituteEnv(value, env) {
+  return value.replace(/\$([A-Z_][A-Z0-9_]*)/g, (_, name) => env[name] ?? "");
+}
+async function loadWebhookConfig(dir) {
+  let raw;
+  try {
+    raw = await promises.readFile(path.join(dir, WEBHOOKS_FILE), "utf8");
+  } catch {
+    return [];
+  }
+  const parsed = JSON.parse(raw);
+  const hooks = parsed.webhooks ?? [];
+  return hooks.filter((h) => typeof h.url === "string" && h.url.trim().length > 0);
+}
+async function fireWebhooks(hooks, payload, env = process.env, log = console.log) {
+  const matching = hooks.filter((h) => !h.events?.length || h.events.includes(payload.event));
+  await Promise.all(matching.map(async (hook) => {
+    const url = substituteEnv(hook.url, env);
+    const headers = { "Content-Type": "application/json" };
+    for (const [k, v] of Object.entries(hook.headers ?? {})) headers[k] = substituteEnv(v, env);
+    const label = hook.name ?? url;
+    try {
+      const res = await undici.fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(1e4)
+      });
+      log(`  [webhook] ${payload.event} → ${label}: ${res.status}`);
+    } catch (e) {
+      log(`  [webhook] ${payload.event} → ${label}: failed (${e instanceof Error ? e.message : String(e)})`);
+    }
+  }));
+}
+function snapshotState(results, envs) {
+  const state = { results: {}, deployments: {} };
+  for (const r of results) state.results[`${r.pacticipant}@@${r.version}`] = r.recordedAt;
+  for (const e of envs) {
+    for (const [p, d] of Object.entries(e.deployed)) {
+      state.deployments[`${e.name}@@${p}`] = `${d.version}@@${d.recordedAt}`;
+    }
+  }
+  return state;
+}
+function diffState(prev, next, results) {
+  const events = [];
+  for (const [key, recordedAt] of Object.entries(next.results)) {
+    if (prev.results[key] === recordedAt) continue;
+    const [pacticipant, version] = key.split("@@");
+    const rec = results.find((r) => r.pacticipant === pacticipant && r.version === version);
+    events.push({
+      event: "result-recorded",
+      pacticipant,
+      version,
+      passed: rec?.passed,
+      recordedAt
+    });
+  }
+  for (const [key, value] of Object.entries(next.deployments)) {
+    if (prev.deployments[key] === value) continue;
+    const [environment, pacticipant] = key.split("@@");
+    const [version, recordedAt] = value.split("@@");
+    events.push({
+      event: "deployment-recorded",
+      pacticipant,
+      version,
+      environment,
+      recordedAt
+    });
+  }
+  return events;
+}
+function watchContractEvents(dir, hooks, intervalMs = 1e4, log = console.log) {
+  let prev = null;
+  let running = false;
+  const tick = async () => {
+    if (running) return;
+    running = true;
+    try {
+      const [results, envs] = await Promise.all([snapshots.listResults(dir), snapshots.listEnvironments(dir)]);
+      const next = snapshotState(results, envs);
+      if (prev !== null) {
+        for (const payload of diffState(prev, next, results)) {
+          await fireWebhooks(hooks, payload, process.env, log);
+        }
+      }
+      prev = next;
+    } catch (e) {
+      log(`  [webhook] scan failed: ${e instanceof Error ? e.message : String(e)}`);
+    } finally {
+      running = false;
+    }
+  };
+  void tick();
+  const timer = setInterval(() => {
+    void tick();
+  }, intervalMs);
+  return () => clearInterval(timer);
+}
 async function cmdList(args) {
   const wsArg = args["workspace"];
   if (typeof wsArg !== "string") {
@@ -401,7 +508,7 @@ async function cmdList(args) {
   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:");
-    console.log("    api-spector contract run --workspace <path> --spec-url <url> --pin");
+    console.log("    api-spector contract pin --workspace <path> --spec-url <url>");
     return;
   }
   console.log("");
@@ -410,7 +517,7 @@ async function cmdList(args) {
   for (const { snapshot } of snapshots$1) {
     const id = snapshot.id.slice(0, 8);
     const name = snapshot.name.slice(0, 35).padEnd(35);
-    const version = (snapshot.specVersion ?? "—").slice(0, 11).padEnd(11);
+    const version = (snapshot.specVersion ?? "-").slice(0, 11).padEnd(11);
     const when = snapshot.capturedAt.slice(0, 19).replace("T", " ");
     console.log(`  ${id} ${name} ${version} ${when}`);
   }
@@ -418,6 +525,33 @@ async function cmdList(args) {
   console.log("  Run against a snapshot:");
   console.log("    api-spector contract run --workspace <path> --mode provider --snapshot <id>");
 }
+async function cmdPin(args) {
+  const wsArg = args["workspace"];
+  if (typeof wsArg !== "string") {
+    console.error("  [error] --workspace <path> is required");
+    process.exit(2);
+  }
+  const specUrl = typeof args["spec-url"] === "string" ? args["spec-url"] : void 0;
+  const specPath = typeof args["spec-path"] === "string" ? path.resolve(args["spec-path"]) : void 0;
+  if (!specUrl && !specPath) {
+    console.error("  [error] --spec-url <url> or --spec-path <file> is required");
+    process.exit(2);
+  }
+  const name = typeof args["name"] === "string" ? args["name"] : void 0;
+  const { workspace, dir, file } = await cliCommon.loadWorkspace(wsArg);
+  const snapshot = await snapshots.captureSnapshot(dir, { specUrl, specPath, name });
+  const relPath = snapshots.relPathOf(snapshot);
+  if (relPath && !(workspace.contracts ?? []).includes(relPath)) {
+    workspace.contracts = [...workspace.contracts ?? [], relPath];
+    await promises.writeFile(file, JSON.stringify(workspace, null, 2), "utf8");
+  }
+  console.log(`  Pinned "${snapshot.name}" (spec version ${snapshot.specVersion ?? "unknown"}, sha256 ${snapshot.sha256.slice(0, 12)}...)`);
+  console.log(`  ID:   ${snapshot.id.slice(0, 8)}`);
+  if (relPath) console.log(`  File: ${relPath}`);
+  console.log("");
+  console.log("  Run against it:");
+  console.log(`    api-spector contract run --workspace ${wsArg} --mode provider --snapshot ${snapshot.id.slice(0, 8)}`);
+}
 async function resolveSnapshot(ws, dir, needle) {
   const all = await snapshots.listSnapshots(dir, ws.contracts ?? []);
   const matches = all.filter(
@@ -446,7 +580,7 @@ async function cmdRun(args) {
   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 activeEnv = environments.selectEnvironment(workspace, envs, envName) ?? (envName ? void 0 : envs[0] ? environments.resolveEnvironmentChain(envs[0], envs) : void 0);
   const envVars = {};
   for (const v of activeEnv?.variables ?? []) if (v.enabled) envVars[v.key] = v.value;
   const collectionVars = {};
@@ -487,7 +621,7 @@ async function cmdRun(args) {
       report = await snapshots.runConsumerContracts(contractRequests, envVars, collectionVars);
       break;
     case "provider":
-      report = await snapshots.runProviderVerification(allRequests, envVars, specUrl, specPath, requestBaseUrl);
+      report = await snapshots.runProviderVerification(allRequests, envVars, collectionVars, specUrl, specPath, requestBaseUrl);
       break;
     case "provider-live":
       report = await snapshots.runLiveProviderVerification(contractRequests, envVars, collectionVars, providerBaseUrl, stateHandlerUrl);
@@ -496,13 +630,29 @@ async function cmdRun(args) {
       report = await snapshots.runBidirectional(contractRequests, envVars, collectionVars, specUrl, specPath, requestBaseUrl);
       break;
   }
+  if (args["allow-pending"]) {
+    const store = await loadPendingStore(dir);
+    const verified = mode === "provider" ? allRequests : contractRequests;
+    applyPendingSemantics(report, verified, store, (/* @__PURE__ */ new Date()).toISOString());
+    await savePendingStore(dir, store);
+  }
   console.log("");
   if (report.failed === 0) {
-    console.log(`  ✓ All ${report.passed}/${report.total} passed in ${report.durationMs}ms`);
+    console.log(`  ✓ All ${report.passed}/${report.total - (report.pending ?? 0)} required passed in ${report.durationMs}ms`);
   } else {
     console.log(`  ✗ ${report.failed}/${report.total} failed (${report.passed} passed) in ${report.durationMs}ms`);
     console.log("");
-    for (const r of report.results.filter((r2) => !r2.passed)) {
+    for (const r of report.results.filter((r2) => !r2.passed && !r2.pending)) {
+      console.log(`    ${r.method} ${r.requestName}`);
+      for (const v of r.violations) {
+        console.log(`      · ${v.type}: ${v.message}`);
+      }
+    }
+  }
+  if (report.pending) {
+    console.log("");
+    console.log(`  ⚠ ${report.pending} pending contract${report.pending === 1 ? "" : "s"} failed (never verified before; not blocking):`);
+    for (const r of report.results.filter((r2) => r2.pending)) {
       console.log(`    ${r.method} ${r.requestName}`);
       for (const v of r.violations) {
         console.log(`      · ${v.type}: ${v.message}`);
@@ -535,7 +685,7 @@ async function cmdRun(args) {
       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());
+    const file = await snapshots.recordResult(dir, pacticipant, appVersion, report, (/* @__PURE__ */ new Date()).toISOString());
     console.log(`  Recorded result for ${pacticipant}@${appVersion} → ${file}`);
   }
   process.exit(report.failed === 0 ? 0 : 1);
@@ -556,23 +706,278 @@ async function cmdCanIDeploy(args) {
     console.error("  [error] --app-version <version> is required");
     process.exit(2);
   }
+  const toEnv = typeof args["to"] === "string" ? args["to"] : void 0;
   const { dir } = await cliCommon.loadWorkspace(wsArg);
-  const verdict = await canIDeploy(dir, pacticipant, appVersion);
+  const verdict = await snapshots.canIDeploy(dir, pacticipant, appVersion, toEnv);
   console.log("");
-  console.log(verdict.deployable ? `  ✓ Computer says yes — safe to deploy.` : `  ✗ Computer says no.`);
+  console.log(verdict.deployable ? `  ✓ Computer says yes - safe to deploy.` : `  ✗ Computer says no.`);
   console.log(`  ${verdict.reason}`);
+  if (toEnv) {
+    if (verdict.currentlyDeployed) {
+      console.log(`  ${toEnv} currently runs ${pacticipant}@${verdict.currentlyDeployed.version} (since ${verdict.currentlyDeployed.recordedAt}).`);
+    } else {
+      console.log(`  ${toEnv} has no recorded deployment of ${pacticipant} yet.`);
+    }
+    if (verdict.deployable) {
+      console.log(`  After deploying, record it:`);
+      console.log(`    api-spector contract record-deployment --workspace ${wsArg} --pacticipant ${pacticipant} --app-version ${appVersion} --env ${toEnv}`);
+    }
+  }
   process.exit(verdict.deployable ? 0 : 1);
 }
+async function cmdRecordDeployment(args) {
+  const wsArg = args["workspace"];
+  const pacticipant = args["pacticipant"];
+  const appVersion = args["app-version"];
+  const env = args["env"];
+  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);
+  }
+  if (typeof env !== "string") {
+    console.error("  [error] --env <name> is required (e.g. staging, prod)");
+    process.exit(2);
+  }
+  const { dir } = await cliCommon.loadWorkspace(wsArg);
+  const verdict = await snapshots.canIDeploy(dir, pacticipant, appVersion);
+  const { file, previous } = await snapshots.recordDeployment(dir, env, pacticipant, appVersion, (/* @__PURE__ */ new Date()).toISOString());
+  console.log(`  Recorded: ${pacticipant}@${appVersion} deployed to ${env}`);
+  if (previous) console.log(`  Replaces: ${pacticipant}@${previous.version} (deployed ${previous.recordedAt})`);
+  console.log(`  File:     ${file}`);
+  if (!verdict.deployable) {
+    console.log("");
+    console.log(`  [warn] ${verdict.reason}`);
+    console.log(`  [warn] This version was deployed without a passing contract verification.`);
+  }
+}
+async function cmdEnvironments(args) {
+  const wsArg = args["workspace"];
+  if (typeof wsArg !== "string") {
+    console.error("  [error] --workspace <path> is required");
+    process.exit(2);
+  }
+  const { dir } = await cliCommon.loadWorkspace(wsArg);
+  const envs = await snapshots.listEnvironments(dir);
+  if (envs.length === 0) {
+    console.log("  No deployments recorded. After a deploy, run:");
+    console.log("    api-spector contract record-deployment --workspace <path> --pacticipant <name> --app-version <ver> --env <name>");
+    return;
+  }
+  for (const e of envs) {
+    console.log("");
+    console.log(`  ${e.name}`);
+    for (const [p, d] of Object.entries(e.deployed).sort((a, b) => a[0].localeCompare(b[0]))) {
+      console.log(`    ${p}@${d.version}    since ${d.recordedAt.slice(0, 19).replace("T", " ")}`);
+    }
+  }
+  console.log("");
+}
+async function cmdFuzz(args) {
+  const wsArg = args["workspace"];
+  if (typeof wsArg !== "string") {
+    console.error("  [error] --workspace <path> 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 envs = await cliCommon.loadEnvironments(workspace, dir);
+  const envName = typeof args["environment"] === "string" ? args["environment"] : void 0;
+  const activeEnv = environments.selectEnvironment(workspace, envs, envName) ?? (envName ? void 0 : envs[0] ? environments.resolveEnvironmentChain(envs[0], envs) : void 0);
+  const envVars = {};
+  for (const v of activeEnv?.variables ?? []) if (v.enabled) envVars[v.key] = v.value;
+  const collectionVars = {};
+  for (const c of collections) Object.assign(collectionVars, c.collectionVariables ?? {});
+  const allRequests = collections.flatMap((c) => Object.values(c.requests));
+  let specUrl = typeof args["spec-url"] === "string" ? args["spec-url"] : void 0;
+  let specPath = typeof args["spec-path"] === "string" ? args["spec-path"] : void 0;
+  if (typeof args["snapshot"] === "string") {
+    const { snapshot } = await resolveSnapshot(workspace, dir, args["snapshot"]);
+    const tmp = path.join(os.tmpdir(), `api-spector-${crypto.randomUUID()}.${snapshot.format === "yaml" ? "yaml" : "json"}`);
+    await promises.writeFile(tmp, snapshot.spec, "utf8");
+    specPath = tmp;
+    specUrl = void 0;
+  }
+  const providerBaseUrl = typeof args["provider-base-url"] === "string" ? args["provider-base-url"] : void 0;
+  if (!providerBaseUrl && !specUrl && !specPath) {
+    console.error("  [error] fuzz needs a target: --provider-base-url <url> (and optionally a spec via --snapshot / --spec-url / --spec-path)");
+    process.exit(2);
+  }
+  const includeWrites = Boolean(args["include-writes"]);
+  console.log(`  Fuzzing ${allRequests.length} request(s)${specUrl || specPath ? " against the spec" : " from request bodies"}...`);
+  if (!includeWrites) console.log("  Write methods (POST/PUT/PATCH/DELETE) are skipped. Add --include-writes to fuzz them (sends malformed writes; target staging or a mock).");
+  const report = await snapshots.runFuzz({
+    requests: allRequests,
+    envVars,
+    collectionVars,
+    specUrl,
+    specPath,
+    providerBaseUrl,
+    requestBaseUrl: typeof args["request-base-url"] === "string" ? args["request-base-url"] : void 0,
+    casesPerOperation: typeof args["cases"] === "string" ? Math.max(1, Number(args["cases"])) : void 0,
+    seed: typeof args["seed"] === "string" ? Number(args["seed"]) : void 0,
+    includeWrites,
+    strictStatus: Boolean(args["strict-status"]),
+    checkResponses: Boolean(args["check-responses"]),
+    trace: Boolean(args["trace"])
+  });
+  console.log("");
+  if (report.totalFindings === 0) {
+    console.log(`  ✓ No findings across ${report.totalCases} malformed cases (seed ${report.seed}, ${report.durationMs}ms)`);
+  } else {
+    console.log(`  ✗ ${report.totalFindings} finding(s) across ${report.totalCases} cases (seed ${report.seed}, ${report.durationMs}ms)`);
+    for (const op of report.results.filter((r) => r.findings.length > 0)) {
+      console.log("");
+      console.log(`    ${op.method} ${op.requestName}  (${op.findings.length}/${op.cases})`);
+      for (const f of op.findings) {
+        console.log(`      · [${f.oracle}] HTTP ${f.status} on ${f.mutation.target} (${f.mutation.kind}): ${f.message}`);
+      }
+    }
+  }
+  if (report.skippedWrites) console.log(`
+  ${report.skippedWrites} write-method request(s) skipped (use --include-writes).`);
+  if (report.skippedNoBody) console.log(`  ${report.skippedNoBody} request(s) had no body to fuzz.`);
+  if (args["trace"]) {
+    for (const op of report.results) {
+      if (!op.trace?.length) continue;
+      console.log("");
+      console.log(`  ${op.method} ${op.requestName} - ${op.trace.length} cases sent:`);
+      for (const t of op.trace) {
+        const mark = t.finding ? "✗" : "·";
+        console.log(`    ${mark} HTTP ${t.status}  ${t.mutation.target} (${t.mutation.kind})`);
+        console.log(`        req:  ${(t.request.body ?? "").slice(0, 200)}`);
+        console.log(`        resp: ${(t.responseSample ?? "").replace(/\s+/g, " ").slice(0, 200)}`);
+      }
+    }
+  }
+  if (typeof args["output"] === "string") {
+    await promises.writeFile(args["output"], JSON.stringify(report, null, 2), "utf8");
+    console.log(`
+  Report written to ${args["output"]}`);
+  }
+  if (typeof args["html"] === "string") {
+    await promises.writeFile(args["html"], snapshots.fuzzReportToHtml(report, (/* @__PURE__ */ new Date()).toISOString()), "utf8");
+    console.log(`  HTML report written to ${args["html"]}`);
+  }
+  process.exit(report.totalFindings === 0 ? 0 : 1);
+}
+async function cmdWebhooks(args) {
+  const wsArg = args["workspace"];
+  if (typeof wsArg !== "string") {
+    console.error("  [error] --workspace <path> is required");
+    process.exit(2);
+  }
+  const { dir } = await cliCommon.loadWorkspace(wsArg);
+  const hooks = await loadWebhookConfig(dir);
+  if (hooks.length === 0) {
+    console.log("  No webhooks configured. Create contracts/webhooks.json in the workspace:");
+    console.log("");
+    console.log("    {");
+    console.log('      "webhooks": [');
+    console.log("        {");
+    console.log('          "name": "trigger provider CI",');
+    console.log('          "url": "https://ci.example.com/api/trigger",');
+    console.log('          "events": ["result-recorded", "deployment-recorded"],');
+    console.log('          "headers": { "Authorization": "Bearer $CI_TOKEN" }');
+    console.log("        }");
+    console.log("      ]");
+    console.log("    }");
+    console.log("");
+    console.log("  $NAME tokens are replaced from the serving process environment.");
+    console.log("  The dashboard (`contract report --serve`) fires them when new results appear.");
+    return;
+  }
+  console.log("");
+  for (const h of hooks) {
+    console.log(`  ${h.name ?? "(unnamed)"}`);
+    console.log(`    url:    ${h.url}`);
+    console.log(`    events: ${h.events?.length ? h.events.join(", ") : "all"}`);
+  }
+  console.log("");
+  if (args["test"]) {
+    console.log("  Sending test event...");
+    await fireWebhooks(hooks, {
+      event: "result-recorded",
+      pacticipant: "webhook-test",
+      version: "0.0.0",
+      passed: true,
+      recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+}
 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");
+  if (args["serve"]) {
+    const port = typeof args["port"] === "string" ? Number(args["port"]) : 8080;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      console.error("  [error] --port must be a number between 1 and 65535");
+      process.exit(2);
+    }
+    const { createServer } = await import("http");
+    const server = createServer(async (req, res) => {
+      try {
+        const url = req.url ?? "/";
+        if (url === "/healthz") {
+          res.writeHead(200, { "Content-Type": "text/plain" });
+          res.end("ok");
+          return;
+        }
+        const records2 = await snapshots.listResults(dir);
+        const runMatch = /^\/run\/([^/]+)\/([^/]+)$/.exec(url);
+        if (runMatch) {
+          const pacticipant = decodeURIComponent(runMatch[1]);
+          const version = decodeURIComponent(runMatch[2]);
+          const rec = records2.find((r) => r.pacticipant === pacticipant && r.version === version);
+          if (!rec) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("No recorded result for that pacticipant/version");
+            return;
+          }
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(snapshots.reportToHtml(rec.report, {
+            title: `${pacticipant} @ ${version}`,
+            generatedAt: rec.recordedAt
+          }));
+          return;
+        }
+        const environments22 = await snapshots.listEnvironments(dir);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(snapshots.dashboardToHtml(records2, (/* @__PURE__ */ new Date()).toISOString(), { runLinkBase: "/run", environments: environments22 }));
+      } catch (e) {
+        res.writeHead(500, { "Content-Type": "text/plain" });
+        res.end(e instanceof Error ? e.message : String(e));
+      }
+    });
+    server.listen(port, () => {
+      console.log(`  Contract dashboard serving at http://localhost:${port}`);
+      console.log(`  Workspace: ${wsArg} (results re-read on every request)`);
+      console.log("  Read-only: record new results via `contract run --record`, then refresh.");
+    });
+    const hooks = await loadWebhookConfig(dir);
+    if (hooks.length > 0) {
+      const intervalMs = typeof args["webhook-interval"] === "string" ? Math.max(2, Number(args["webhook-interval"])) * 1e3 : 1e4;
+      watchContractEvents(dir, hooks, intervalMs);
+      console.log(`  Webhooks: ${hooks.length} configured (polling every ${intervalMs / 1e3}s)`);
+    }
+    return;
+  }
+  const out = typeof args["html"] === "string" ? args["html"] : "contract-dashboard.html";
+  const records = await snapshots.listResults(dir);
+  const environments2 = await snapshots.listEnvironments(dir);
+  await promises.writeFile(out, snapshots.dashboardToHtml(records, (/* @__PURE__ */ new Date()).toISOString(), { environments: environments2 }), "utf8");
   console.log(`  Dashboard with ${records.length} recorded result(s) written to ${out}`);
 }
 async function cmdPactImport(args) {
@@ -620,17 +1025,27 @@ async function main() {
   const [, , sub, ...rest] = process.argv;
   const args = cliCommon.parseArgs(rest);
   if (sub === "list") return cmdList(args);
+  if (sub === "pin") return cmdPin(args);
   if (sub === "run") return cmdRun(args);
   if (sub === "can-i-deploy") return cmdCanIDeploy(args);
+  if (sub === "record-deployment") return cmdRecordDeployment(args);
+  if (sub === "environments") return cmdEnvironments(args);
+  if (sub === "webhooks") return cmdWebhooks(args);
+  if (sub === "fuzz") return cmdFuzz(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 pin           --workspace <path> --spec-url <url> | --spec-path <file> [--name <label>]
   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 report        --workspace <path> [--html <path>] [--serve [--port <n>]]
+  api-spector contract can-i-deploy  --workspace <path> --pacticipant <name> --app-version <ver> [--to <env>]
+  api-spector contract record-deployment --workspace <path> --pacticipant <name> --app-version <ver> --env <name>
+  api-spector contract environments  --workspace <path>
+  api-spector contract webhooks      --workspace <path> [--test]
+  api-spector contract fuzz          --workspace <path> --provider-base-url <url> [--snapshot <id> | --spec-url <url>] [--cases <n>] [--seed <n>] [--include-writes] [--trace] [--html <path>]
   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>]
 
@@ -656,6 +1071,8 @@ async function main() {
     --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)
+    --allow-pending           Failures of never-verified interactions report as
+                              pending instead of blocking (exit 0)
 `);
     return;
   }