@eventcatalog/cli 0.4.11 → 0.5.1

package/dist/cli/index.mjs

@@ -10,7 +10,7 @@ var __dirname = /* @__PURE__ */ getDirname();
 // src/cli/index.ts
 import { program } from "commander";
 import { readFileSync as readFileSync2 } from "fs";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 
 // src/cli/executor.ts
 import { existsSync } from "fs";
@@ -481,8 +481,8 @@ ${messages.join("\n")}`);
   }
   return { outputs, program: program2 };
 }
-function extractResourceTypeFolder(path2) {
-  const segments = path2.split("/");
+function extractResourceTypeFolder(path4) {
+  const segments = path4.split("/");
   let lastTypeFolder = segments[0];
   for (const seg of segments) {
     if (RESOURCE_TYPE_FROM_FOLDER[seg]) {
@@ -674,8 +674,8 @@ function extractServiceContainerRefs(program2, nested = false) {
         ...stmt.ref.version ? { version: stmt.ref.version } : {}
       }));
       if (writesTo.length === 0 && readsFrom.length === 0) continue;
-      const path2 = buildServiceOutputPath(def.name, body, nested, parentPath);
-      refsByPath.set(path2, {
+      const path4 = buildServiceOutputPath(def.name, body, nested, parentPath);
+      refsByPath.set(path4, {
         ...writesTo.length > 0 ? { writesTo } : {},
         ...readsFrom.length > 0 ? { readsFrom } : {}
       });
@@ -766,21 +766,21 @@ function getReader(sdk, type) {
   }
 }
 function promptConfirm(message) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     rl.question(`${message} `, (answer) => {
       rl.close();
       const normalized = answer.trim().toLowerCase();
-      resolve4(normalized === "" || normalized === "y" || normalized === "yes");
+      resolve5(normalized === "" || normalized === "y" || normalized === "yes");
     });
   });
 }
 function promptInput(message, defaultValue) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     rl.question(`${message} `, (answer) => {
       rl.close();
-      resolve4(answer.trim() || defaultValue);
+      resolve5(answer.trim() || defaultValue);
     });
   });
 }
@@ -1136,18 +1136,495 @@ function formatResult(result, dryRun) {
   return lines.join("\n");
 }
 function readStdin() {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const chunks = [];
     process.stdin.on("data", (chunk) => chunks.push(chunk));
-    process.stdin.on("end", () => resolve4(Buffer.concat(chunks).toString("utf-8")));
+    process.stdin.on("end", () => resolve5(Buffer.concat(chunks).toString("utf-8")));
     process.stdin.on("error", reject);
   });
 }
 
+// src/cli/snapshot.ts
+import { resolve as resolve3 } from "path";
+import { rmSync } from "fs";
+import createSDK5 from "@eventcatalog/sdk";
+var snapshotCreate = async (opts) => {
+  const dir = resolve3(opts.dir);
+  const sdk = createSDK5(dir);
+  const result = await sdk.createSnapshot({
+    label: opts.label,
+    outputDir: opts.output ? resolve3(opts.output) : void 0
+  });
+  if (opts.stdout) {
+    rmSync(result.filePath, { force: true });
+    return JSON.stringify(result.snapshot, null, 2);
+  }
+  const resources = result.snapshot.resources;
+  const counts = [
+    resources.services.length && `${resources.services.length} services`,
+    resources.messages.events.length && `${resources.messages.events.length} events`,
+    resources.messages.commands.length && `${resources.messages.commands.length} commands`,
+    resources.messages.queries.length && `${resources.messages.queries.length} queries`,
+    resources.domains.length && `${resources.domains.length} domains`,
+    resources.channels.length && `${resources.channels.length} channels`
+  ].filter(Boolean).join(", ");
+  return `Snapshot created: ${result.filePath}
+Resources: ${counts}`;
+};
+var formatDiffText = (diff) => {
+  const lines = [];
+  const labelA = diff.snapshotA.label;
+  const labelB = diff.snapshotB.label;
+  lines.push(`Comparing: ${labelA} vs ${labelB}`);
+  lines.push("");
+  if (diff.resources.length > 0) {
+    lines.push(`Resources (${diff.resources.length} changes):`);
+    for (const r of diff.resources) {
+      const prefix = r.changeType === "added" ? "+" : r.changeType === "removed" ? "-" : r.changeType === "versioned" ? "^" : "~";
+      const version2 = r.changeType === "versioned" ? `${r.previousVersion} -> ${r.newVersion}` : r.version;
+      const fields = r.changedFields ? ` (${r.changedFields.join(", ")})` : "";
+      lines.push(`  ${prefix} ${r.resourceId}@${version2}  [${r.type}] ${r.changeType}${fields}`);
+    }
+    lines.push("");
+  }
+  if (diff.relationships.length > 0) {
+    lines.push(`Relationships (${diff.relationships.length} changes):`);
+    for (const r of diff.relationships) {
+      const prefix = r.changeType === "added" ? "+" : "-";
+      lines.push(
+        `  ${prefix} ${r.serviceId} --${r.direction}--> ${r.resourceId}${r.resourceVersion ? `@${r.resourceVersion}` : ""}`
+      );
+    }
+    lines.push("");
+  }
+  if (diff.summary.totalChanges === 0) {
+    lines.push("No changes detected.");
+  } else {
+    lines.push(`Summary: ${diff.resources.length} resource changes, ${diff.relationships.length} relationship changes`);
+  }
+  return lines.join("\n");
+};
+var snapshotDiff = async (opts) => {
+  const dir = resolve3(opts.dir);
+  const sdk = createSDK5(dir);
+  const diff = await sdk.diffSnapshots(resolve3(opts.fileA), resolve3(opts.fileB));
+  if (opts.format === "json") {
+    return JSON.stringify(diff, null, 2);
+  }
+  return formatDiffText(diff);
+};
+var snapshotList = async (opts) => {
+  const dir = resolve3(opts.dir);
+  const sdk = createSDK5(dir);
+  const snapshots = await sdk.listSnapshots();
+  if (opts.format === "json") {
+    return JSON.stringify(snapshots, null, 2);
+  }
+  if (snapshots.length === 0) {
+    return "No snapshots found.";
+  }
+  const lines = ["Snapshots:", ""];
+  for (const s of snapshots) {
+    const git = s.git ? ` (${s.git.branch} ${s.git.commit})` : "";
+    lines.push(`  ${s.label}  ${s.createdAt}${git}`);
+    lines.push(`    ${s.filePath}`);
+  }
+  return lines.join("\n");
+};
+
+// src/cli/governance/rules.ts
+import fs from "fs";
+import path2 from "path";
+import yaml from "js-yaml";
+var loadGovernanceConfig = (catalogDir) => {
+  const yamlPath = path2.join(catalogDir, "governance.yaml");
+  const ymlPath = path2.join(catalogDir, "governance.yml");
+  const configPath = fs.existsSync(yamlPath) ? yamlPath : fs.existsSync(ymlPath) ? ymlPath : null;
+  if (!configPath) {
+    return { rules: [] };
+  }
+  const content = fs.readFileSync(configPath, "utf-8");
+  const parsed = yaml.load(content);
+  return { rules: parsed?.rules || [] };
+};
+var TRIGGER_FILTERS = {
+  consumer_added: (c2) => c2.direction === "receives" && c2.changeType === "added",
+  consumer_removed: (c2) => c2.direction === "receives" && c2.changeType === "removed",
+  producer_added: (c2) => c2.direction === "sends" && c2.changeType === "added",
+  producer_removed: (c2) => c2.direction === "sends" && c2.changeType === "removed"
+};
+var buildServiceMessageSets = (snapshot2) => {
+  const produces = /* @__PURE__ */ new Map();
+  const consumes = /* @__PURE__ */ new Map();
+  for (const service of snapshot2.resources.services) {
+    const serviceId = service.id;
+    if (service.sends) {
+      const ids = /* @__PURE__ */ new Set();
+      for (const s of service.sends) ids.add(s.id);
+      produces.set(serviceId, ids);
+    }
+    if (service.receives) {
+      const ids = /* @__PURE__ */ new Set();
+      for (const r of service.receives) ids.add(r.id);
+      consumes.set(serviceId, ids);
+    }
+  }
+  return { produces, consumes };
+};
+var matchesResourceId = (resourceId, serviceId, resources, messageSets) => {
+  return resources.some((r) => {
+    if (r === "*") return true;
+    if (r.startsWith("service:")) {
+      if (serviceId) return serviceId === r.slice(8);
+      return messageSets?.produces.get(r.slice(8))?.has(resourceId) ?? false;
+    }
+    if (r.startsWith("message:")) return resourceId === r.slice(8);
+    if (r.startsWith("produces:")) return messageSets?.produces.get(r.slice(9))?.has(resourceId) ?? false;
+    if (r.startsWith("consumes:")) return messageSets?.consumes.get(r.slice(9))?.has(resourceId) ?? false;
+    return false;
+  });
+};
+var REMOVED_TRIGGERS = /* @__PURE__ */ new Set(["consumer_removed", "producer_removed"]);
+var MESSAGE_RESOURCE_TYPES = /* @__PURE__ */ new Set(["event", "command", "query"]);
+var buildMessageMap = (snapshot2) => {
+  const map = /* @__PURE__ */ new Map();
+  for (const msg of snapshot2.resources.messages.events) map.set(msg.id, msg);
+  for (const msg of snapshot2.resources.messages.commands) map.set(msg.id, msg);
+  for (const msg of snapshot2.resources.messages.queries) map.set(msg.id, msg);
+  return map;
+};
+var buildProducerIndex = (snapshot2) => {
+  const index = /* @__PURE__ */ new Map();
+  for (const service of snapshot2.resources.services) {
+    if (!service.sends) continue;
+    for (const s of service.sends) {
+      let producers = index.get(s.id);
+      if (!producers) {
+        producers = [];
+        index.set(s.id, producers);
+      }
+      const entry = {
+        id: service.id,
+        version: service.version
+      };
+      if (service.owners && Array.isArray(service.owners) && service.owners.length > 0) {
+        entry.owners = service.owners;
+      }
+      producers.push(entry);
+    }
+  }
+  return index;
+};
+var evaluateDeprecationRules = (diff, config, targetSnapshot, targetMessageSets, baseSnapshot) => {
+  const deprecationRules = config.rules.filter((rule) => rule.when.includes("message_deprecated"));
+  if (deprecationRules.length === 0) return [];
+  const targetMessages = buildMessageMap(targetSnapshot);
+  const baseMessages = baseSnapshot ? buildMessageMap(baseSnapshot) : void 0;
+  const producerIndex = buildProducerIndex(targetSnapshot);
+  const deprecatedResources = diff.resources.filter((rc) => {
+    if (!MESSAGE_RESOURCE_TYPES.has(rc.type)) return false;
+    if (!rc.changedFields?.includes("deprecated")) return false;
+    const targetMessage = targetMessages.get(rc.resourceId);
+    if (!targetMessage || !targetMessage.deprecated) return false;
+    if (baseMessages) {
+      const baseMessage = baseMessages.get(rc.resourceId);
+      if (baseMessage && baseMessage.deprecated) return false;
+    }
+    return true;
+  });
+  if (deprecatedResources.length === 0) return [];
+  const results = [];
+  for (const rule of deprecationRules) {
+    const matched = [];
+    for (const rc of deprecatedResources) {
+      if (!matchesResourceId(rc.resourceId, void 0, rule.resources, targetMessageSets)) continue;
+      const producers = producerIndex.get(rc.resourceId) || [];
+      matched.push({ resourceChange: rc, producerServices: producers });
+    }
+    if (matched.length > 0) {
+      results.push({ rule, trigger: "message_deprecated", matchedChanges: [], deprecationChanges: matched });
+    }
+  }
+  return results;
+};
+var evaluateGovernanceRules = (diff, config, targetSnapshot, baseSnapshot) => {
+  const results = [];
+  const targetMessageSets = targetSnapshot ? buildServiceMessageSets(targetSnapshot) : void 0;
+  const baseMessageSets = baseSnapshot ? buildServiceMessageSets(baseSnapshot) : void 0;
+  for (const rule of config.rules) {
+    for (const trigger of rule.when) {
+      const filter = TRIGGER_FILTERS[trigger];
+      if (!filter) continue;
+      const messageSets = REMOVED_TRIGGERS.has(trigger) && baseMessageSets ? baseMessageSets : targetMessageSets;
+      const matchedChanges = diff.relationships.filter(
+        (c2) => filter(c2) && matchesResourceId(c2.resourceId, c2.serviceId, rule.resources, messageSets)
+      );
+      if (matchedChanges.length > 0) {
+        results.push({ rule, trigger, matchedChanges });
+      }
+    }
+  }
+  if (targetSnapshot && targetMessageSets) {
+    results.push(...evaluateDeprecationRules(diff, config, targetSnapshot, targetMessageSets, baseSnapshot));
+  }
+  return results;
+};
+var PRODUCER_TRIGGERS = /* @__PURE__ */ new Set(["producer_added", "producer_removed"]);
+var isProducerTrigger = (trigger) => PRODUCER_TRIGGERS.has(trigger);
+var getChangeVerb = (trigger, changeType) => {
+  const producer = isProducerTrigger(trigger);
+  return changeType === "added" ? producer ? "now producing" : "now consuming" : producer ? "no longer producing" : "no longer consuming";
+};
+var resolveEnvVars = (value) => {
+  return value.replace(/\$([A-Z_][A-Z0-9_]*)/g, (match, varName) => {
+    const envValue = process.env[varName];
+    if (envValue === void 0) {
+      throw new Error(`Environment variable ${varName} is not set`);
+    }
+    return envValue;
+  });
+};
+
+// src/cli/governance/actions.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var buildMessageTypeMap = (snapshot2) => {
+  const map = /* @__PURE__ */ new Map();
+  for (const event of snapshot2.resources.messages.events) {
+    map.set(event.id, "event");
+  }
+  for (const command of snapshot2.resources.messages.commands) {
+    map.set(command.id, "command");
+  }
+  for (const query of snapshot2.resources.messages.queries) {
+    map.set(query.id, "query");
+  }
+  return map;
+};
+var buildServiceOwnersMap = (snapshot2) => {
+  const map = /* @__PURE__ */ new Map();
+  for (const service of snapshot2.resources.services) {
+    if (service.owners && Array.isArray(service.owners) && service.owners.length > 0) {
+      map.set(service.id, service.owners);
+    }
+  }
+  return map;
+};
+var executeGovernanceActions = async (results, opts = {}) => {
+  const { messageTypes, status, serviceOwners } = opts;
+  const webhookCalls = [];
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const result of results) {
+    for (const action of result.rule.actions) {
+      if (action.type !== "webhook") continue;
+      const url = resolveEnvVars(action.url);
+      const headers = { "Content-Type": "application/json" };
+      if (action.headers) {
+        for (const [key, value] of Object.entries(action.headers)) {
+          headers[key] = resolveEnvVars(value);
+        }
+      }
+      if (result.deprecationChanges && result.deprecationChanges.length > 0) {
+        for (const dc of result.deprecationChanges) {
+          const messageType = messageTypes?.get(dc.resourceChange.resourceId) || "message";
+          const producers = dc.producerServices.length > 0 ? dc.producerServices : [{ id: "unknown", version: "unknown" }];
+          for (const producer of producers) {
+            const payload = {
+              specversion: "1.0",
+              type: `eventcatalog.governance.message_deprecated`,
+              source: "eventcatalog/governance",
+              id: randomUUID2(),
+              time: now,
+              datacontenttype: "application/json",
+              data: {
+                schemaVersion: 1,
+                ...status && { status },
+                summary: `${dc.resourceChange.resourceId} (${messageType}) has been deprecated by ${producer.id}`,
+                producer: {
+                  id: producer.id,
+                  version: producer.version,
+                  ...producer.owners && { owners: producer.owners }
+                },
+                message: {
+                  id: dc.resourceChange.resourceId,
+                  version: dc.resourceChange.version,
+                  type: messageType
+                }
+              }
+            };
+            webhookCalls.push({
+              urlTemplate: action.url,
+              request: fetch(url, { method: "POST", headers, body: JSON.stringify(payload) })
+            });
+          }
+        }
+        continue;
+      }
+      for (const change of result.matchedChanges) {
+        const verb = getChangeVerb(result.trigger, change.changeType);
+        const messageType = messageTypes?.get(change.resourceId) || "message";
+        const serviceRole = isProducerTrigger(result.trigger) ? "producer" : "consumer";
+        const payload = {
+          specversion: "1.0",
+          type: `eventcatalog.governance.${result.trigger}`,
+          source: "eventcatalog/governance",
+          id: randomUUID2(),
+          time: now,
+          datacontenttype: "application/json",
+          data: {
+            schemaVersion: 1,
+            ...status && { status },
+            summary: `${change.serviceId} is ${verb} the ${messageType} ${change.resourceId}`,
+            [serviceRole]: {
+              id: change.serviceId,
+              version: change.serviceVersion,
+              ...serviceOwners?.get(change.serviceId) && { owners: serviceOwners.get(change.serviceId) }
+            },
+            message: {
+              id: change.resourceId,
+              version: change.resourceVersion,
+              type: messageType
+            }
+          }
+        };
+        webhookCalls.push({
+          urlTemplate: action.url,
+          request: fetch(url, { method: "POST", headers, body: JSON.stringify(payload) })
+        });
+      }
+    }
+  }
+  const settled = await Promise.allSettled(webhookCalls.map((c2) => c2.request));
+  return settled.map((result, i) => {
+    const url = webhookCalls[i].urlTemplate;
+    if (result.status === "fulfilled") {
+      const res = result.value;
+      if (!res.ok) {
+        return `  Webhook failed: ${url} \u2717 (HTTP ${res.status})`;
+      }
+      return `  Webhook sent: ${url} \u2713`;
+    }
+    return `  Webhook failed: ${url} \u2717 (${result.reason instanceof Error ? result.reason.message : String(result.reason)})`;
+  });
+};
+
+// src/cli/governance/format.ts
+var formatGovernanceOutput = (results) => {
+  if (results.length === 0) {
+    return "No governance rules triggered. Catalog is compliant.";
+  }
+  const lines = ["Governance:", ""];
+  for (const result of results) {
+    lines.push(`  Rule "${result.rule.name}" triggered (${result.trigger}):`);
+    if (result.deprecationChanges && result.deprecationChanges.length > 0) {
+      for (const dc of result.deprecationChanges) {
+        const producers = dc.producerServices.length > 0 ? dc.producerServices.map((p) => p.id).join(", ") : "unknown producer";
+        lines.push(`    ! ${dc.resourceChange.resourceId} (${dc.resourceChange.type}) deprecated by ${producers}`);
+      }
+    } else {
+      for (const change of result.matchedChanges) {
+        const prefix = change.changeType === "added" ? "+" : "-";
+        const verb = getChangeVerb(result.trigger, change.changeType);
+        lines.push(`    ${prefix} ${change.serviceId} is ${verb} ${change.resourceId}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+};
+
+// src/cli/governance/check.ts
+import path3 from "path";
+import { execSync } from "child_process";
+import { mkdtempSync, rmSync as rmSync2 } from "fs";
+import { tmpdir } from "os";
+import dotenv from "dotenv";
+import createSDK6 from "@eventcatalog/sdk";
+import { isEventCatalogScaleEnabled } from "@eventcatalog/license";
+var BRANCH_NAME_RE = /^[a-zA-Z0-9._\-/]+$/;
+var extractBranchToTempDir = (branch, catalogDir, tempDirs) => {
+  if (!BRANCH_NAME_RE.test(branch)) {
+    throw new Error(`Invalid branch name: "${branch}"`);
+  }
+  const tmpDir = mkdtempSync(path3.join(tmpdir(), "ec-governance-"));
+  tempDirs.push(tmpDir);
+  try {
+    execSync(`git archive ${branch} | tar -x -C ${tmpDir}`, { cwd: catalogDir, stdio: "pipe" });
+  } catch {
+    throw new Error(`Failed to extract branch "${branch}". Is it a valid git branch?`);
+  }
+  return tmpDir;
+};
+var governanceCheck = async (opts) => {
+  const dir = path3.resolve(opts.dir);
+  dotenv.config({ path: path3.join(dir, ".env") });
+  const isScale = await isEventCatalogScaleEnabled();
+  if (!isScale) {
+    throw new Error("Governance requires an EventCatalog Scale plan. Learn more at https://eventcatalog.dev/pricing");
+  }
+  const baseBranch = opts.base || "main";
+  const tempDirs = [];
+  const trackTempDir = (prefix) => {
+    const d = mkdtempSync(path3.join(tmpdir(), prefix));
+    tempDirs.push(d);
+    return d;
+  };
+  try {
+    const baseTmpDir = extractBranchToTempDir(baseBranch, dir, tempDirs);
+    const baseSnapshotDir = trackTempDir("ec-snap-base-");
+    const targetSnapshotDir = trackTempDir("ec-snap-target-");
+    const baseSDK = createSDK6(baseTmpDir);
+    const baseResult = await baseSDK.createSnapshot({ label: `base-${baseBranch}`, outputDir: baseSnapshotDir });
+    let targetResult;
+    if (opts.target) {
+      const targetTmpDir = extractBranchToTempDir(opts.target, dir, tempDirs);
+      const targetSDK = createSDK6(targetTmpDir);
+      targetResult = await targetSDK.createSnapshot({ label: `target-${opts.target}`, outputDir: targetSnapshotDir });
+    } else {
+      const targetSDK = createSDK6(dir);
+      targetResult = await targetSDK.createSnapshot({ label: "current", outputDir: targetSnapshotDir });
+    }
+    const diff = await baseSDK.diffSnapshots(baseResult.filePath, targetResult.filePath);
+    const config = loadGovernanceConfig(dir);
+    if (config.rules.length === 0) {
+      return "No governance.yaml (or governance.yml) found or no rules defined.";
+    }
+    const results = evaluateGovernanceRules(diff, config, targetResult.snapshot, baseResult.snapshot);
+    const messageTypes = buildMessageTypeMap(targetResult.snapshot);
+    const serviceOwners = buildServiceOwnersMap(targetResult.snapshot);
+    const actionOutput = await executeGovernanceActions(results, {
+      messageTypes,
+      status: opts.status,
+      serviceOwners
+    });
+    if (opts.format === "json") {
+      return JSON.stringify({ baseBranch, target: opts.target || "working directory", results, diff: diff.summary }, null, 2);
+    }
+    const targetLabel = opts.target || "working directory";
+    const lines = [`Governance check: comparing ${targetLabel} against ${baseBranch}`, ""];
+    lines.push(formatGovernanceOutput(results));
+    if (actionOutput.length > 0) {
+      lines.push("");
+      lines.push(...actionOutput);
+    }
+    if (results.length > 0) {
+      const webhookCount = actionOutput.filter((l) => l.includes("Webhook sent")).length;
+      const parts = [`${results.length} rule${results.length === 1 ? "" : "s"} triggered`];
+      if (webhookCount > 0) parts.push(`${webhookCount} webhook${webhookCount === 1 ? "" : "s"} sent`);
+      lines.push("");
+      lines.push(parts.join(", ") + ".");
+    }
+    return lines.join("\n");
+  } finally {
+    for (const d of tempDirs) {
+      rmSync2(d, { recursive: true, force: true });
+    }
+  }
+};
+
 // src/cli/index.ts
 var version = "1.0.0";
 try {
-  const packageJsonPath = resolve3(__dirname, "../../package.json");
+  const packageJsonPath = resolve4(__dirname, "../../package.json");
   const packageJson = JSON.parse(readFileSync2(packageJsonPath, "utf-8"));
   version = packageJson.version;
 } catch {
@@ -1216,6 +1693,58 @@ program.command("import [files...]").description("Import EventCatalog DSL (.ec)
     process.exit(1);
   }
 });
+var snapshot = program.command("snapshot").description("Create, diff, and list catalog snapshots");
+snapshot.command("create").description("Take a point-in-time snapshot of the catalog").option("--label <label>", "Human-readable label (default: ISO timestamp)").option("-o, --output <path>", "Output directory for the snapshot file").option("--stdout", "Print JSON to stdout instead of writing a file", false).action(async (opts) => {
+  try {
+    const globalOpts = program.opts();
+    const dir = globalOpts.dir || ".";
+    const result = await snapshotCreate({ label: opts.label, output: opts.output, stdout: opts.stdout, dir });
+    console.log(result);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+});
+snapshot.command("diff <fileA> <fileB>").description("Compare two snapshot files and output a structured diff").option("--format <format>", "Output format: text or json", "text").action(async (fileA, fileB, opts) => {
+  try {
+    const globalOpts = program.opts();
+    const dir = globalOpts.dir || ".";
+    const result = await snapshotDiff({ fileA, fileB, format: opts.format, dir });
+    console.log(result);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+});
+snapshot.command("list").description("List all snapshots in the catalog").option("--format <format>", "Output format: text or json", "text").action(async (opts) => {
+  try {
+    const globalOpts = program.opts();
+    const dir = globalOpts.dir || ".";
+    const result = await snapshotList({ format: opts.format, dir });
+    console.log(result);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+});
+var governance = program.command("governance").description("Run governance rules against catalog changes");
+governance.command("check").description("Compare catalog against a base branch and evaluate governance rules").option("--base <branch>", "Base branch to compare against (default: main)").option("--target <branch>", "Target branch to compare (default: current working directory)").option("--format <format>", "Output format: text or json", "text").option("--status <status>", "Status label to include in webhook payloads (e.g. proposed, approved)").action(async (opts) => {
+  try {
+    const globalOpts = program.opts();
+    const dir = globalOpts.dir || ".";
+    const result = await governanceCheck({
+      base: opts.base,
+      target: opts.target,
+      format: opts.format,
+      status: opts.status,
+      dir
+    });
+    console.log(result);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+});
 program.arguments("<function> [args...]").action(async (functionName, args) => {
   try {
     const options = program.opts();