@testsmith/api-spector 0.4.6 → 0.4.8

package/out/main/contract.js

@@ -24,15 +24,17 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 const promises = require("fs/promises");
 const path = require("path");
-const snapshots = require("./chunks/snapshots-BDe-B5iQ.js");
+const snapshots = require("./chunks/snapshots-CtYxkSLz.js");
 const crypto = require("crypto");
 const undici = require("undici");
 const os = require("os");
-const cliCommon = require("./chunks/cli-common-CDQY1erJ.js");
+const cliCommon = require("./chunks/cli-common-BKYgsbGB.js");
+const child_process = require("child_process");
+const jsYaml = require("js-yaml");
 const environments = require("./chunks/environments-iM3SUM-4.js");
-require("./chunks/request-exec-CBi2kL6s.js");
+require("./chunks/request-exec-BH-M3KqZ.js");
 require("tls");
-require("./chunks/handle-BGYDylL2.js");
+require("./chunks/handle-rimXXdJH.js");
 require("dayjs");
 require("vm");
 require("tv4");
@@ -40,7 +42,6 @@ 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;");
 }
@@ -72,290 +73,6 @@ function toJUnitXml(report, suiteName = "contract") {
   ];
   return lines.join("\n") + "\n";
 }
-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 "null":
-      return { [snapshots.MATCH_KEY]: "null", value: null };
-    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;
-  }
-  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: "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 }] };
-          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" }
-    }
-  };
-}
 const PENDING_FILE = "contracts/pending.json";
 function interactionKey(req) {
   const contractHash = crypto.createHash("sha256").update(JSON.stringify(req.contract ?? {})).digest("hex").slice(0, 16);
@@ -499,6 +216,127 @@ function watchContractEvents(dir, hooks, intervalMs = 1e4, log = console.log) {
   }, intervalMs);
   return () => clearInterval(timer);
 }
+function brokerConfigFromEnv() {
+  return {
+    endpoint: (process.env["API_SPECTOR_CLOUD_ENDPOINT"] || "https://api-spector.dev").replace(/\/+$/, ""),
+    token: process.env["API_SPECTOR_TOKEN"] || ""
+  };
+}
+async function brokerFetch(cfg, path2, method, body) {
+  if (!cfg.token) throw new Error("No API token. Set API_SPECTOR_TOKEN (create one in the cloud dashboard under Tokens).");
+  const url = cfg.endpoint + path2;
+  let res;
+  try {
+    res = await undici.fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Bearer ${cfg.token}`
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+  } catch (err) {
+    throw new Error(`Could not reach ${url}: ${err.message}`);
+  }
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    json = { raw: text };
+  }
+  return { status: res.status, ok: res.ok, json };
+}
+function fail(r, what) {
+  const detail = r.json?.error || r.json?.message || (r.status === 401 ? "Unauthorized (check API_SPECTOR_TOKEN)" : `HTTP ${r.status}`);
+  throw new Error(`${what}: ${detail}`);
+}
+async function publishPact(cfg, input) {
+  const r = await brokerFetch(cfg, "/api/contracts", "PUT", {
+    consumer: input.consumer,
+    consumerVersion: input.consumerVersion,
+    provider: input.provider,
+    content: input.pact
+  });
+  if (!r.ok) fail(r, "Publish pact failed");
+}
+async function publishSpec(cfg, input) {
+  const r = await brokerFetch(cfg, "/api/provider-contracts", "PUT", {
+    pacticipant: input.pacticipant,
+    version: input.version,
+    spec: input.spec,
+    // Optional provider self-verification (its own tests run against this spec).
+    ...input.results ? { results: input.results } : {}
+  });
+  if (!r.ok) fail(r, "Publish spec failed");
+}
+async function canIDeploy(cfg, input) {
+  const q = new URLSearchParams({ pacticipant: input.pacticipant, version: input.version, environment: input.environment }).toString();
+  const r = await brokerFetch(cfg, "/can-i-deploy?" + q, "GET");
+  if (r.status !== 200 && r.status !== 409) fail(r, "can-i-deploy failed");
+  return { deployable: r.status === 200, reason: r.json?.summary?.reason || "" };
+}
+async function deployPreview(cfg, input) {
+  const q = new URLSearchParams({ pacticipant: input.pacticipant, version: input.version, environment: input.environment }).toString();
+  const r = await brokerFetch(cfg, "/api/deploy-preview?" + q, "GET");
+  if (!r.ok) fail(r, "deploy-preview failed");
+  return r.json;
+}
+async function recordDeployment(cfg, input) {
+  const path2 = `/pacticipants/${encodeURIComponent(input.pacticipant)}/versions/${encodeURIComponent(input.version)}/deployed-versions/environment/${encodeURIComponent(input.environment)}`;
+  const r = await brokerFetch(cfg, path2, "POST", {});
+  if (!r.ok) fail(r, "record-deployment failed");
+}
+function resolveVersion(override) {
+  if (override) return override;
+  const env = process.env["GITHUB_SHA"] || process.env["CI_COMMIT_SHA"] || process.env["GIT_COMMIT"] || process.env["CIRCLE_SHA1"] || process.env["BUILD_SOURCEVERSION"] || process.env["BITBUCKET_COMMIT"];
+  if (env) return env.trim();
+  try {
+    return child_process.execSync("git rev-parse HEAD", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    throw new Error("Could not resolve a version. Pass --version <sha>, or run inside a git repo / CI.");
+  }
+}
+function parseSelfVerification(text, path2) {
+  const trimmed = text.trimStart();
+  const isXml = path2.toLowerCase().endsWith(".xml") || trimmed.startsWith("<");
+  if (isXml) {
+    const num = (tag, name) => {
+      const m = tag.match(new RegExp(`\\b${name}="(\\d+(?:\\.\\d+)?)"`));
+      return m ? Math.round(Number(m[1])) : 0;
+    };
+    const agg = text.match(/<testsuites\b[^>]*>/);
+    let tests = 0, failures = 0, errors = 0;
+    if (agg) {
+      tests = num(agg[0], "tests");
+      failures = num(agg[0], "failures");
+      errors = num(agg[0], "errors");
+    }
+    if (!tests) {
+      for (const t of text.match(/<testsuite\b[^>]*>/g) ?? []) {
+        tests += num(t, "tests");
+        failures += num(t, "failures");
+        errors += num(t, "errors");
+      }
+    }
+    const failed2 = failures + errors;
+    return { success: failed2 === 0, total: tests, passed: tests - failed2, failed: failed2, source: "junit" };
+  }
+  let o;
+  try {
+    o = JSON.parse(text);
+  } catch {
+    throw new Error("Could not parse the results file (expected JUnit XML or JSON).");
+  }
+  if (typeof o.success === "boolean") return o;
+  const total = o.total ?? o.tests;
+  const failed = o.failed ?? o.failures ?? 0;
+  if (typeof total === "number") {
+    return { success: failed === 0, total, passed: total - failed, failed, source: o.source ?? "json" };
+  }
+  throw new Error("Could not read the results file: JSON needs a boolean `success` or a numeric `total`/`tests`.");
+}
 async function cmdList(args) {
   const wsArg = args["workspace"];
   if (typeof wsArg !== "string") {
@@ -587,7 +425,17 @@ 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) => snapshots.hasContract(r.contract));
+  const collectionContracts = allRequests.filter((r) => snapshots.hasContract(r.contract));
+  const keyOf = (r) => `${r.method} ${r.url} ${r.name}`;
+  const collectionKeys = new Set(collectionContracts.map(keyOf));
+  const designContracts = (await snapshots.loadDesignContractRequests(workspace, dir)).filter((r) => !collectionKeys.has(keyOf(r)));
+  const contractRequests = [...collectionContracts, ...designContracts];
+  if (designContracts.length) {
+    console.log(`  + ${designContracts.length} design-first interaction(s) from the Contract Designer / pacts/`);
+    if (envVars["baseUrl"] === void 0 && collectionVars["baseUrl"] === void 0) {
+      collectionVars["baseUrl"] = "";
+    }
+  }
   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;
@@ -987,10 +835,10 @@ async function cmdPactImport(args) {
     console.error("  [error] --file <pact.json> is required");
     process.exit(2);
   }
-  const result = importPact(await promises.readFile(file, "utf8"));
+  const result = snapshots.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);
+    const collection = snapshots.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:`);
@@ -1018,18 +866,132 @@ async function cmdPactExport(args) {
   }
   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);
+  const pact = snapshots.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})`);
 }
+const str = (v) => typeof v === "string" ? v : void 0;
+const die = (msg) => {
+  console.error(`  [error] ${msg}`);
+  process.exit(2);
+};
+function wantsCloud(args) {
+  return !!args["broker"] || !!process.env["API_SPECTOR_TOKEN"] && !args["workspace"];
+}
+function deriveContract(req) {
+  const ex = (req.examples ?? []).find((e) => e.response && typeof e.response.status === "number");
+  if (!ex?.response) return void 0;
+  const c = { statusCode: ex.response.status };
+  try {
+    const body = JSON.parse(ex.response.body || "null");
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+      const jsType = (v) => Array.isArray(v) ? "array" : v === null ? "null" : typeof v === "number" ? Number.isInteger(v) ? "integer" : "number" : typeof v === "boolean" ? "boolean" : typeof v === "object" ? "object" : "string";
+      c.bodySchema = JSON.stringify({
+        type: "object",
+        required: Object.keys(body),
+        properties: Object.fromEntries(Object.entries(body).map(([k, v]) => [k, { type: jsType(v) }]))
+      });
+    }
+  } catch {
+  }
+  return c;
+}
+async function cmdPublish(args) {
+  const wsArg = str(args["workspace"]) ?? die("--workspace <path> is required");
+  const consumer = str(args["consumer"]) ?? die("--consumer <name> is required");
+  const provider = str(args["provider"]) ?? die("--provider <name> is required");
+  const version = resolveVersion(str(args["version"]));
+  const { workspace, dir } = await cliCommon.loadWorkspace(wsArg);
+  const collections = await cliCommon.loadCollections(workspace, dir, { filterName: str(args["collection"]) });
+  let all = collections.flatMap((c) => Object.values(c.requests));
+  const tag = str(args["tag"]);
+  if (tag) all = all.filter((r) => (r.meta?.tags ?? []).includes(tag));
+  let requests = all.filter((r) => snapshots.hasContract(r.contract));
+  if (args["derive"]) {
+    const derived = all.filter((r) => !snapshots.hasContract(r.contract)).map((r) => ({ ...r, contract: deriveContract(r) })).filter((r) => snapshots.hasContract(r.contract));
+    requests = [...requests, ...derived];
+  }
+  if (requests.length === 0) die("No requests with contract expectations found to publish (set them on the Contract tab, or pass --derive to use saved example responses).");
+  const pact = snapshots.exportPact(consumer, provider, requests);
+  await publishPact(brokerConfigFromEnv(), { consumer, provider, consumerVersion: version, pact });
+  console.log(`  Published ${requests.length} interaction(s): ${consumer}@${version.slice(0, 7)} → ${provider}`);
+}
+async function cmdPublishSpecLocal(args) {
+  const norm = { ...args };
+  if (typeof norm["spec"] === "string" && typeof norm["spec-path"] !== "string") norm["spec-path"] = norm["spec"];
+  if (typeof norm["provider"] === "string" && typeof norm["name"] !== "string") norm["name"] = norm["provider"];
+  return cmdPin(norm);
+}
+async function cmdPublishSpec(args) {
+  const pacticipant = str(args["provider"]) ?? str(args["pacticipant"]) ?? die("--provider <name> is required");
+  const version = resolveVersion(str(args["version"]));
+  let specText;
+  const specUrl = str(args["spec-url"]);
+  const specPath = str(args["spec"]) ?? str(args["spec-path"]);
+  if (specUrl) {
+    const res = await undici.fetch(specUrl);
+    if (!res.ok) die(`Could not fetch spec from ${specUrl} (HTTP ${res.status})`);
+    specText = await res.text();
+  } else if (specPath) {
+    specText = await promises.readFile(specPath, "utf8");
+  } else {
+    return die("--spec <path> or --spec-url <url> is required");
+  }
+  let spec;
+  try {
+    spec = JSON.parse(specText);
+  } catch {
+    spec = jsYaml.load(specText);
+  }
+  if (!spec || typeof spec !== "object") die("Could not parse the OpenAPI spec (expected JSON or YAML).");
+  let results;
+  const resultsPath = str(args["results"]);
+  if (resultsPath) results = parseSelfVerification(await promises.readFile(resultsPath, "utf8"), resultsPath);
+  await publishSpec(brokerConfigFromEnv(), { pacticipant, version, spec, results });
+  const selfNote = results ? ` (self-verification: ${results.success ? "passed" : "FAILED"})` : "";
+  console.log(`  Published spec: ${pacticipant}@${version.slice(0, 7)}${selfNote}`);
+}
+async function cmdCloudCanIDeploy(args) {
+  const pacticipant = str(args["pacticipant"]) ?? die("--pacticipant <name> is required");
+  const version = resolveVersion(str(args["version"]));
+  const environment = str(args["environment"]) ?? str(args["to"]) ?? die("--environment <name> is required");
+  const { deployable, reason } = await canIDeploy(brokerConfigFromEnv(), { pacticipant, version, environment });
+  if (deployable) {
+    console.log(`  ✓ ${pacticipant}@${version.slice(0, 7)} can deploy to ${environment}`);
+  } else {
+    console.error(`  ✗ ${pacticipant}@${version.slice(0, 7)} cannot deploy to ${environment}`);
+    if (reason) console.error(`    ${reason}`);
+    process.exit(1);
+  }
+}
+async function cmdPreview(args) {
+  const pacticipant = str(args["pacticipant"]) ?? die("--pacticipant <name> is required");
+  const version = resolveVersion(str(args["version"]));
+  const environment = str(args["environment"]) ?? str(args["to"]) ?? die("--environment <name> is required");
+  const preview = await deployPreview(brokerConfigFromEnv(), { pacticipant, version, environment });
+  console.log(`### ${preview.check.title}
+
+${preview.check.summary}`);
+  if (!preview.deployable && args["fail-on-break"]) process.exit(1);
+}
+async function cmdCloudRecordDeployment(args) {
+  const pacticipant = str(args["pacticipant"]) ?? die("--pacticipant <name> is required");
+  const version = resolveVersion(str(args["version"]));
+  const environment = str(args["environment"]) ?? str(args["env"]) ?? die("--environment <name> is required");
+  await recordDeployment(brokerConfigFromEnv(), { pacticipant, version, environment });
+  console.log(`  Recorded ${pacticipant}@${version.slice(0, 7)} deployed to ${environment}`);
+}
 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 === "publish") return cmdPublish(args);
+  if (sub === "publish-spec") return wantsCloud(args) ? cmdPublishSpec(args) : cmdPublishSpecLocal(args);
+  if (sub === "preview") return cmdPreview(args);
+  if (sub === "deploy-check" || sub === "can-i-deploy") return wantsCloud(args) ? cmdCloudCanIDeploy(args) : cmdCanIDeploy(args);
+  if (sub === "record-deployment") return wantsCloud(args) ? cmdCloudRecordDeployment(args) : cmdRecordDeployment(args);
   if (sub === "environments") return cmdEnvironments(args);
   if (sub === "webhooks") return cmdWebhooks(args);
   if (sub === "fuzz") return cmdFuzz(args);
@@ -1042,7 +1004,7 @@ async function main() {
   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>] [--serve [--port <n>]]
-  api-spector contract can-i-deploy  --workspace <path> --pacticipant <name> --app-version <ver> [--to <env>]
+  api-spector contract deploy-check  --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]
@@ -1050,6 +1012,13 @@ async function main() {
   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>]
 
+  Cloud broker (git-native; auth via API_SPECTOR_TOKEN, version = git SHA):
+  api-spector contract publish       --workspace <path> --consumer <name> --provider <name> [--tag <folder>] [--version <sha>]
+  api-spector contract publish-spec  --provider <name> --spec <file> | --spec-url <url> [--broker] [--version <sha>]
+                                     # --broker → cloud; otherwise pins into --workspace (local / git)
+  api-spector contract deploy-check  --broker --pacticipant <name> --environment <env> [--version <sha>]   # exit 1 = blocked (alias: can-i-deploy)
+  api-spector contract record-deployment --broker --pacticipant <name> --environment <env> [--version <sha>]
+
   Modes:
     consumer       Send requests to the real provider, assert each response (live).
     provider       Static check that requests conform to an OpenAPI spec (no HTTP).