x-openapi-flow 1.2.3 → 1.3.1

package/bin/x-openapi-flow.js

@@ -8,7 +8,18 @@ const {
   run,
   loadApi,
   extractFlows,
+  buildStateGraph,
+  detectDuplicateTransitions,
+  detectInvalidOperationReferences,
+  detectTerminalCoverage,
 } = require("../lib/validator");
+const { generateSdk } = require("../lib/sdk-generator");
+const {
+  exportDocFlows,
+  generatePostmanCollection,
+  generateInsomniaWorkspace,
+  generateRedocPackage,
+} = require("../adapters/flow-output-adapters");
 
 const DEFAULT_CONFIG_NAME = "x-openapi-flow.config.json";
 const DEFAULT_FLOWS_FILE = "x-openapi-flow.flows.yaml";
@@ -43,8 +54,16 @@ function printHelp() {
 
 Usage:
   x-openapi-flow validate <openapi-file> [--format pretty|json] [--profile core|relaxed|strict] [--strict-quality] [--config path]
-  x-openapi-flow init [openapi-file] [--flows path]
+  x-openapi-flow init [openapi-file] [--flows path] [--force] [--dry-run]
   x-openapi-flow apply [openapi-file] [--flows path] [--out path] [--in-place]
+  x-openapi-flow diff [openapi-file] [--flows path] [--format pretty|json]
+  x-openapi-flow lint [openapi-file] [--format pretty|json] [--config path]
+  x-openapi-flow analyze [openapi-file] [--format pretty|json] [--out path] [--merge] [--flows path]
+  x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]
+  x-openapi-flow export-doc-flows [openapi-file] [--output path] [--format markdown|json]
+  x-openapi-flow generate-postman [openapi-file] [--output path] [--with-scripts]
+  x-openapi-flow generate-insomnia [openapi-file] [--output path]
+  x-openapi-flow generate-redoc [openapi-file] [--output path]
   x-openapi-flow graph <openapi-file> [--format mermaid|json]
   x-openapi-flow doctor [--config path]
   x-openapi-flow --help
@@ -53,11 +72,26 @@ Examples:
   x-openapi-flow validate examples/order-api.yaml
   x-openapi-flow validate examples/order-api.yaml --profile relaxed
   x-openapi-flow validate examples/order-api.yaml --strict-quality
-  x-openapi-flow init openapi.yaml --flows openapi-openapi-flow.yaml
+  x-openapi-flow init openapi.yaml --flows openapi.x.yaml
+  x-openapi-flow init openapi.yaml --force
+  x-openapi-flow init openapi.yaml --dry-run
   x-openapi-flow init
   x-openapi-flow apply openapi.yaml
   x-openapi-flow apply openapi.yaml --in-place
   x-openapi-flow apply openapi.yaml --out openapi.flow.yaml
+  x-openapi-flow diff openapi.yaml
+  x-openapi-flow diff openapi.yaml --format json
+  x-openapi-flow lint openapi.yaml
+  x-openapi-flow lint openapi.yaml --format json
+  x-openapi-flow analyze openapi.yaml
+  x-openapi-flow analyze openapi.yaml --out openapi.x.yaml
+  x-openapi-flow analyze openapi.yaml --format json
+  x-openapi-flow analyze openapi.yaml --merge --flows openapi.x.yaml
+  x-openapi-flow generate-sdk openapi.yaml --lang typescript --output ./sdk
+  x-openapi-flow export-doc-flows openapi.yaml --output ./docs/api-flows.md
+  x-openapi-flow generate-postman openapi.yaml --output ./x-openapi-flow.postman_collection.json --with-scripts
+  x-openapi-flow generate-insomnia openapi.yaml --output ./x-openapi-flow.insomnia.json
+  x-openapi-flow generate-redoc openapi.yaml --output ./redoc-flow
   x-openapi-flow graph examples/order-api.yaml
   x-openapi-flow doctor
 `);
@@ -69,6 +103,73 @@ function deriveFlowOutputPath(openApiFile) {
   return path.join(parsed.dir, `${parsed.name}.flow${extension}`);
 }
 
+function readSingleLineFromStdin() {
+  const sleepBuffer = new SharedArrayBuffer(4);
+  const sleepView = new Int32Array(sleepBuffer);
+  const chunks = [];
+  const buffer = Buffer.alloc(256);
+  const maxEagainRetries = 200;
+  let eagainRetries = 0;
+
+  while (true) {
+    let bytesRead;
+    try {
+      bytesRead = fs.readSync(0, buffer, 0, buffer.length, null);
+    } catch (err) {
+      if (err && (err.code === "EAGAIN" || err.code === "EWOULDBLOCK")) {
+        eagainRetries += 1;
+        if (eagainRetries >= maxEagainRetries) {
+          const retryError = new Error("Could not read interactive input from stdin.");
+          retryError.code = "EAGAIN";
+          throw retryError;
+        }
+        Atomics.wait(sleepView, 0, 0, 25);
+        continue;
+      }
+      throw err;
+    }
+
+    eagainRetries = 0;
+    if (bytesRead === 0) {
+      break;
+    }
+
+    const chunk = buffer.toString("utf8", 0, bytesRead);
+    chunks.push(chunk);
+    if (chunk.includes("\n")) {
+      break;
+    }
+  }
+
+  const input = chunks.join("");
+  const firstLine = input.split(/\r?\n/)[0] || "";
+  return firstLine.trim();
+}
+
+function askForConfirmation(question) {
+  process.stdout.write(`${question} [y/N]: `);
+  const answer = readSingleLineFromStdin().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+function getNextBackupPath(filePath) {
+  let index = 1;
+  while (true) {
+    const candidate = `${filePath}.backup-${index}`;
+    if (!fs.existsSync(candidate)) {
+      return candidate;
+    }
+    index += 1;
+  }
+}
+
+function applyFlowsAndWrite(openApiFile, flowsDoc, outputPath) {
+  const api = loadApi(openApiFile);
+  const appliedCount = applyFlowsToOpenApi(api, flowsDoc);
+  saveOpenApi(outputPath, api);
+  return appliedCount;
+}
+
 function getOptionValue(args, optionName) {
   const index = args.indexOf(optionName);
   if (index === -1) {
@@ -175,7 +276,7 @@ function parseValidateArgs(args) {
 }
 
 function parseInitArgs(args) {
-  const unknown = findUnknownOptions(args, ["--flows"], []);
+  const unknown = findUnknownOptions(args, ["--flows"], ["--force", "--dry-run"]);
   if (unknown) {
     return { error: `Unknown option: ${unknown}` };
   }
@@ -189,6 +290,12 @@ function parseInitArgs(args) {
     if (token === "--flows") {
       return false;
     }
+    if (token === "--force") {
+      return false;
+    }
+    if (token === "--dry-run") {
+      return false;
+    }
     if (index > 0 && args[index - 1] === "--flows") {
       return false;
     }
@@ -202,6 +309,203 @@ function parseInitArgs(args) {
   return {
     openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
     flowsPath: flowsOpt.found ? path.resolve(flowsOpt.value) : undefined,
+    force: args.includes("--force"),
+    dryRun: args.includes("--dry-run"),
+  };
+}
+
+function summarizeSidecarDiff(existingFlowsDoc, mergedFlowsDoc) {
+  const existingOps = new Map();
+  for (const entry of (existingFlowsDoc && existingFlowsDoc.operations) || []) {
+    if (!entry || !entry.operationId) continue;
+    existingOps.set(entry.operationId, entry["x-openapi-flow"] || null);
+  }
+
+  const mergedOps = new Map();
+  for (const entry of (mergedFlowsDoc && mergedFlowsDoc.operations) || []) {
+    if (!entry || !entry.operationId) continue;
+    mergedOps.set(entry.operationId, entry["x-openapi-flow"] || null);
+  }
+
+  let added = 0;
+  let removed = 0;
+  let changed = 0;
+  const addedOperationIds = [];
+  const removedOperationIds = [];
+  const changedOperationIds = [];
+  const changedOperationDetails = [];
+
+  function collectLeafPaths(value, prefix = "") {
+    if (value === null || value === undefined) {
+      return [prefix || "(root)"];
+    }
+
+    if (Array.isArray(value)) {
+      return [prefix || "(root)"];
+    }
+
+    if (typeof value !== "object") {
+      return [prefix || "(root)"];
+    }
+
+    const keys = Object.keys(value);
+    if (keys.length === 0) {
+      return [prefix || "(root)"];
+    }
+
+    return keys.flatMap((key) => {
+      const nextPrefix = prefix ? `${prefix}.${key}` : key;
+      return collectLeafPaths(value[key], nextPrefix);
+    });
+  }
+
+  function diffPaths(left, right, prefix = "") {
+    if (JSON.stringify(left) === JSON.stringify(right)) {
+      return [];
+    }
+
+    const leftIsObject = left && typeof left === "object" && !Array.isArray(left);
+    const rightIsObject = right && typeof right === "object" && !Array.isArray(right);
+
+    if (leftIsObject && rightIsObject) {
+      const keys = Array.from(new Set([...Object.keys(left), ...Object.keys(right)])).sort();
+      return keys.flatMap((key) => {
+        const nextPrefix = prefix ? `${prefix}.${key}` : key;
+        return diffPaths(left[key], right[key], nextPrefix);
+      });
+    }
+
+    if (rightIsObject && !leftIsObject) {
+      return collectLeafPaths(right, prefix);
+    }
+
+    if (leftIsObject && !rightIsObject) {
+      return collectLeafPaths(left, prefix);
+    }
+
+    return [prefix || "(root)"];
+  }
+
+  for (const [operationId, mergedFlow] of mergedOps.entries()) {
+    if (!existingOps.has(operationId)) {
+      added += 1;
+      addedOperationIds.push(operationId);
+      continue;
+    }
+
+    const existingFlow = existingOps.get(operationId);
+    if (JSON.stringify(existingFlow) !== JSON.stringify(mergedFlow)) {
+      changed += 1;
+      changedOperationIds.push(operationId);
+      changedOperationDetails.push({
+        operationId,
+        changedPaths: Array.from(new Set(diffPaths(existingFlow, mergedFlow))).sort(),
+      });
+    }
+  }
+
+  for (const operationId of existingOps.keys()) {
+    if (!mergedOps.has(operationId)) {
+      removed += 1;
+      removedOperationIds.push(operationId);
+    }
+  }
+
+  return {
+    added,
+    removed,
+    changed,
+    addedOperationIds: addedOperationIds.sort(),
+    removedOperationIds: removedOperationIds.sort(),
+    changedOperationIds: changedOperationIds.sort(),
+    changedOperationDetails: changedOperationDetails.sort((a, b) => a.operationId.localeCompare(b.operationId)),
+  };
+}
+
+function parseDiffArgs(args) {
+  const unknown = findUnknownOptions(args, ["--flows", "--format"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const flowsOpt = getOptionValue(args, "--flows");
+  if (flowsOpt.error) {
+    return { error: flowsOpt.error };
+  }
+
+  const formatOpt = getOptionValue(args, "--format");
+  if (formatOpt.error) {
+    return { error: `${formatOpt.error} Use 'pretty' or 'json'.` };
+  }
+
+  const format = formatOpt.found ? formatOpt.value : "pretty";
+  if (!["pretty", "json"].includes(format)) {
+    return { error: `Invalid --format '${format}'. Use 'pretty' or 'json'.` };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--flows" || token === "--format") {
+      return false;
+    }
+    if (index > 0 && (args[index - 1] === "--flows" || args[index - 1] === "--format")) {
+      return false;
+    }
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    flowsPath: flowsOpt.found ? path.resolve(flowsOpt.value) : undefined,
+    format,
+  };
+}
+
+function parseLintArgs(args) {
+  const unknown = findUnknownOptions(args, ["--format", "--config"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const formatOpt = getOptionValue(args, "--format");
+  if (formatOpt.error) {
+    return { error: `${formatOpt.error} Use 'pretty' or 'json'.` };
+  }
+
+  const configOpt = getOptionValue(args, "--config");
+  if (configOpt.error) {
+    return { error: configOpt.error };
+  }
+
+  const format = formatOpt.found ? formatOpt.value : "pretty";
+  if (![
+    "pretty",
+    "json",
+  ].includes(format)) {
+    return { error: `Invalid --format '${format}'. Use 'pretty' or 'json'.` };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--format" || token === "--config") {
+      return false;
+    }
+    if (index > 0 && (args[index - 1] === "--format" || args[index - 1] === "--config")) {
+      return false;
+    }
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    format,
+    configPath: configOpt.found ? configOpt.value : undefined,
   };
 }
 
@@ -285,6 +589,58 @@ function parseGraphArgs(args) {
   return { filePath: path.resolve(positional[0]), format };
 }
 
+function parseAnalyzeArgs(args) {
+  const unknown = findUnknownOptions(args, ["--format", "--out", "--flows"], ["--merge"]);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const formatOpt = getOptionValue(args, "--format");
+  if (formatOpt.error) {
+    return { error: `${formatOpt.error} Use 'pretty' or 'json'.` };
+  }
+
+  const outOpt = getOptionValue(args, "--out");
+  if (outOpt.error) {
+    return { error: outOpt.error };
+  }
+
+  const flowsOpt = getOptionValue(args, "--flows");
+  if (flowsOpt.error) {
+    return { error: flowsOpt.error };
+  }
+
+  const format = formatOpt.found ? formatOpt.value : "pretty";
+  if (!["pretty", "json"].includes(format)) {
+    return { error: `Invalid --format '${format}'. Use 'pretty' or 'json'.` };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--format" || token === "--out" || token === "--flows" || token === "--merge") {
+      return false;
+    }
+    if (
+      index > 0
+      && (args[index - 1] === "--format" || args[index - 1] === "--out" || args[index - 1] === "--flows")
+    ) {
+      return false;
+    }
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    format,
+    outPath: outOpt.found ? path.resolve(outOpt.value) : undefined,
+    merge: args.includes("--merge"),
+    flowsPath: flowsOpt.found ? path.resolve(flowsOpt.value) : undefined,
+  };
+}
+
 function parseDoctorArgs(args) {
   const unknown = findUnknownOptions(args, ["--config"], []);
   if (unknown) {
@@ -301,71 +657,281 @@ function parseDoctorArgs(args) {
   };
 }
 
-function parseArgs(argv) {
-  const args = argv.slice(2);
-  const command = args[0];
-
-  if (!command || command === "--help" || command === "-h") {
-    return { help: true };
+function parseGenerateSdkArgs(args) {
+  const unknown = findUnknownOptions(args, ["--lang", "--output"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
   }
 
-  const commandArgs = args.slice(1);
-  if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
-    return { help: true, command };
+  const langOpt = getOptionValue(args, "--lang");
+  if (langOpt.error) {
+    return { error: `${langOpt.error} Use 'typescript'.` };
   }
 
-  if (command === "validate") {
-    const parsed = parseValidateArgs(commandArgs);
-    return parsed.error ? parsed : { command, ...parsed };
+  const outputOpt = getOptionValue(args, "--output");
+  if (outputOpt.error) {
+    return { error: outputOpt.error };
   }
 
-  if (command === "init") {
-    const parsed = parseInitArgs(commandArgs);
-    return parsed.error ? parsed : { command, ...parsed };
+  if (!langOpt.found) {
+    return { error: "Missing --lang option. Usage: x-openapi-flow generate-sdk [openapi-file] --lang typescript [--output path]" };
   }
 
-  if (command === "graph") {
-    const parsed = parseGraphArgs(commandArgs);
-    return parsed.error ? parsed : { command, ...parsed };
+  const language = langOpt.value;
+  if (language !== "typescript") {
+    return { error: `Unsupported --lang '${language}'. MVP currently supports only 'typescript'.` };
   }
 
-  if (command === "apply") {
-    const parsed = parseApplyArgs(commandArgs);
-    return parsed.error ? parsed : { command, ...parsed };
-  }
+  const positional = args.filter((token, index) => {
+    if (token === "--lang" || token === "--output") {
+      return false;
+    }
+    if (index > 0 && (args[index - 1] === "--lang" || args[index - 1] === "--output")) {
+      return false;
+    }
+    return !token.startsWith("--");
+  });
 
-  if (command === "doctor") {
-    const parsed = parseDoctorArgs(commandArgs);
-    return parsed.error ? parsed : { command, ...parsed };
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
   }
 
-  return { error: `Unknown command: ${command}` };
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    language,
+    outputPath: outputOpt.found ? path.resolve(outputOpt.value) : path.resolve(process.cwd(), "sdk"),
+  };
 }
 
-function findOpenApiFile(startDirectory) {
-  const preferredNames = [
-    "openapi.yaml",
-    "openapi.yml",
-    "openapi.json",
-    "swagger.yaml",
-    "swagger.yml",
-    "swagger.json",
-  ];
+function parseExportDocFlowsArgs(args) {
+  const unknown = findUnknownOptions(args, ["--output", "--format"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
 
-  for (const fileName of preferredNames) {
-    const candidate = path.join(startDirectory, fileName);
-    if (fs.existsSync(candidate)) {
-      return candidate;
-    }
+  const outputOpt = getOptionValue(args, "--output");
+  if (outputOpt.error) {
+    return { error: outputOpt.error };
   }
 
-  const ignoredDirs = new Set(["node_modules", ".git", "dist", "build"]);
+  const formatOpt = getOptionValue(args, "--format");
+  if (formatOpt.error) {
+    return { error: `${formatOpt.error} Use 'markdown' or 'json'.` };
+  }
 
-  function walk(directory) {
-    let entries = [];
-    try {
-      entries = fs.readdirSync(directory, { withFileTypes: true });
-    } catch (_err) {
+  const format = formatOpt.found ? formatOpt.value : "markdown";
+  if (!["markdown", "json"].includes(format)) {
+    return { error: `Invalid --format '${format}'. Use 'markdown' or 'json'.` };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--output" || token === "--format") return false;
+    if (index > 0 && (args[index - 1] === "--output" || args[index - 1] === "--format")) return false;
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    outputPath: outputOpt.found ? path.resolve(outputOpt.value) : path.resolve(process.cwd(), "api-flows.md"),
+    format,
+  };
+}
+
+function parseGeneratePostmanArgs(args) {
+  const unknown = findUnknownOptions(args, ["--output"], ["--with-scripts"]);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const outputOpt = getOptionValue(args, "--output");
+  if (outputOpt.error) {
+    return { error: outputOpt.error };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--output" || token === "--with-scripts") return false;
+    if (index > 0 && args[index - 1] === "--output") return false;
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    outputPath: outputOpt.found
+      ? path.resolve(outputOpt.value)
+      : path.resolve(process.cwd(), "x-openapi-flow.postman_collection.json"),
+    withScripts: args.includes("--with-scripts"),
+  };
+}
+
+function parseGenerateInsomniaArgs(args) {
+  const unknown = findUnknownOptions(args, ["--output"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const outputOpt = getOptionValue(args, "--output");
+  if (outputOpt.error) {
+    return { error: outputOpt.error };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--output") return false;
+    if (index > 0 && args[index - 1] === "--output") return false;
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    outputPath: outputOpt.found
+      ? path.resolve(outputOpt.value)
+      : path.resolve(process.cwd(), "x-openapi-flow.insomnia.json"),
+  };
+}
+
+function parseGenerateRedocArgs(args) {
+  const unknown = findUnknownOptions(args, ["--output"], []);
+  if (unknown) {
+    return { error: `Unknown option: ${unknown}` };
+  }
+
+  const outputOpt = getOptionValue(args, "--output");
+  if (outputOpt.error) {
+    return { error: outputOpt.error };
+  }
+
+  const positional = args.filter((token, index) => {
+    if (token === "--output") return false;
+    if (index > 0 && args[index - 1] === "--output") return false;
+    return !token.startsWith("--");
+  });
+
+  if (positional.length > 1) {
+    return { error: `Unexpected argument: ${positional[1]}` };
+  }
+
+  return {
+    openApiFile: positional[0] ? path.resolve(positional[0]) : undefined,
+    outputPath: outputOpt.found ? path.resolve(outputOpt.value) : path.resolve(process.cwd(), "redoc-flow"),
+  };
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "--help" || command === "-h") {
+    return { help: true };
+  }
+
+  const commandArgs = args.slice(1);
+  if (commandArgs.includes("--help") || commandArgs.includes("-h")) {
+    return { help: true, command };
+  }
+
+  if (command === "validate") {
+    const parsed = parseValidateArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "init") {
+    const parsed = parseInitArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "graph") {
+    const parsed = parseGraphArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "analyze") {
+    const parsed = parseAnalyzeArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "apply") {
+    const parsed = parseApplyArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "diff") {
+    const parsed = parseDiffArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "lint") {
+    const parsed = parseLintArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "doctor") {
+    const parsed = parseDoctorArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "generate-sdk") {
+    const parsed = parseGenerateSdkArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "export-doc-flows") {
+    const parsed = parseExportDocFlowsArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "generate-postman") {
+    const parsed = parseGeneratePostmanArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "generate-insomnia") {
+    const parsed = parseGenerateInsomniaArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  if (command === "generate-redoc") {
+    const parsed = parseGenerateRedocArgs(commandArgs);
+    return parsed.error ? parsed : { command, ...parsed };
+  }
+
+  return { error: `Unknown command: ${command}` };
+}
+
+function findOpenApiFile(startDirectory) {
+  const preferredNames = [
+    "openapi.yaml",
+    "openapi.yml",
+    "openapi.json",
+    "swagger.yaml",
+    "swagger.yml",
+    "swagger.json",
+  ];
+
+  for (const fileName of preferredNames) {
+    const candidate = path.join(startDirectory, fileName);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  const ignoredDirs = new Set(["node_modules", ".git", "dist", "build"]);
+
+  function walk(directory) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch (_err) {
       return null;
     }
 
@@ -401,13 +967,40 @@ function resolveFlowsPath(openApiFile, customFlowsPath) {
   if (openApiFile) {
     const parsed = path.parse(openApiFile);
     const extension = parsed.ext.toLowerCase() === ".json" ? ".json" : ".yaml";
-    const fileName = `${parsed.name}-openapi-flow${extension}`;
-    return path.join(path.dirname(openApiFile), fileName);
+    const baseDir = path.dirname(openApiFile);
+    const newFileName = `${parsed.name}.x${extension}`;
+    const legacyFileName = `${parsed.name}-openapi-flow${extension}`;
+    const newPath = path.join(baseDir, newFileName);
+    const legacyPath = path.join(baseDir, legacyFileName);
+
+    if (fs.existsSync(newPath)) {
+      return newPath;
+    }
+
+    if (fs.existsSync(legacyPath)) {
+      return legacyPath;
+    }
+
+    return newPath;
   }
 
   return path.resolve(process.cwd(), DEFAULT_FLOWS_FILE);
 }
 
+function looksLikeFlowsSidecar(filePath) {
+  if (!filePath) return false;
+  const normalized = filePath.toLowerCase();
+  return normalized.endsWith(".x.yaml")
+    || normalized.endsWith(".x.yml")
+    || normalized.endsWith(".x.json")
+    || normalized.endsWith("-openapi-flow.yaml")
+    || normalized.endsWith("-openapi-flow.yml")
+    || normalized.endsWith("-openapi-flow.json")
+    || normalized.endsWith("x-openapi-flow.flows.yaml")
+    || normalized.endsWith("x-openapi-flow.flows.yml")
+    || normalized.endsWith("x-openapi-flow.flows.json");
+}
+
 function getOpenApiFormat(filePath) {
   return filePath.endsWith(".json") ? "json" : "yaml";
 }
@@ -494,8 +1087,8 @@ function buildFlowTemplate(operationId) {
   const safeOperationId = operationId || "operation";
   return {
     version: "1.0",
-    id: `${safeOperationId}_FLOW_ID`,
-    current_state: `${safeOperationId}_STATE`,
+    id: safeOperationId,
+    current_state: safeOperationId,
     transitions: [],
   };
 }
@@ -606,6 +1199,7 @@ function runInit(parsed) {
   }
 
   const flowsPath = resolveFlowsPath(targetOpenApiFile, parsed.flowsPath);
+  const flowOutputPath = deriveFlowOutputPath(targetOpenApiFile);
 
   let api;
   try {
@@ -624,12 +1218,91 @@ function runInit(parsed) {
   }
 
   const mergedFlows = mergeFlowsWithOpenApi(api, flowsDoc);
-  writeFlowsFile(flowsPath, mergedFlows);
   const trackedCount = mergedFlows.operations.length;
+  const sidecarDiff = summarizeSidecarDiff(flowsDoc, mergedFlows);
+
+  let applyMessage = "Init completed without regenerating flow output.";
+  const flowOutputExists = fs.existsSync(flowOutputPath);
+  let shouldRecreateFlowOutput = !flowOutputExists;
+  let sidecarBackupPath = null;
+
+  if (parsed.dryRun) {
+    let dryRunFlowPlan;
+    if (!flowOutputExists) {
+      dryRunFlowPlan = `Would generate flow output: ${flowOutputPath}`;
+    } else if (parsed.force) {
+      dryRunFlowPlan = `Would recreate flow output: ${flowOutputPath} (with sidecar backup).`;
+    } else {
+      dryRunFlowPlan = `Flow output exists at ${flowOutputPath}; would require interactive confirmation to recreate (or use --force).`;
+    }
+
+    console.log(`[dry-run] Using existing OpenAPI file: ${targetOpenApiFile}`);
+    console.log(`[dry-run] Flows sidecar target: ${flowsPath}`);
+    console.log(`[dry-run] Tracked operations: ${trackedCount}`);
+    console.log(`[dry-run] Sidecar changes -> added: ${sidecarDiff.added}, changed: ${sidecarDiff.changed}, removed: ${sidecarDiff.removed}`);
+    console.log(`[dry-run] ${dryRunFlowPlan}`);
+    console.log("[dry-run] No files were written.");
+    return 0;
+  }
+
+  if (flowOutputExists) {
+    if (parsed.force) {
+      shouldRecreateFlowOutput = true;
+      if (fs.existsSync(flowsPath)) {
+        sidecarBackupPath = getNextBackupPath(flowsPath);
+        fs.copyFileSync(flowsPath, sidecarBackupPath);
+      }
+    } else {
+      const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+      if (isInteractive) {
+      let shouldRecreate;
+      try {
+        shouldRecreate = askForConfirmation(
+          `Flow output already exists at ${flowOutputPath}. Recreate it from current OpenAPI + sidecar?`
+        );
+      } catch (err) {
+        if (err && (err.code === "EAGAIN" || err.code === "EWOULDBLOCK")) {
+          console.error("ERROR: Could not read interactive confirmation from stdin (EAGAIN).");
+          console.error("Run `x-openapi-flow apply` to update the existing flow output in this environment.");
+          return 1;
+        }
+        throw err;
+      }
+
+      if (shouldRecreate) {
+        shouldRecreateFlowOutput = true;
+        if (fs.existsSync(flowsPath)) {
+          sidecarBackupPath = getNextBackupPath(flowsPath);
+          fs.copyFileSync(flowsPath, sidecarBackupPath);
+        }
+      } else {
+        applyMessage = "Flow output kept as-is (recreate cancelled by user).";
+      }
+      } else {
+        console.error(`ERROR: Flow output already exists at ${flowOutputPath}.`);
+        console.error("Use `x-openapi-flow init --force` to recreate, or `x-openapi-flow apply` to update in non-interactive mode.");
+        return 1;
+      }
+    }
+  }
+
+  writeFlowsFile(flowsPath, mergedFlows);
+
+  if (shouldRecreateFlowOutput) {
+    const appliedCount = applyFlowsAndWrite(targetOpenApiFile, mergedFlows, flowOutputPath);
+    if (flowOutputExists) {
+      applyMessage = sidecarBackupPath
+        ? `Flow output recreated: ${flowOutputPath} (applied entries: ${appliedCount}). Sidecar backup: ${sidecarBackupPath}.`
+        : `Flow output recreated: ${flowOutputPath} (applied entries: ${appliedCount}).`;
+    } else {
+      applyMessage = `Flow output generated: ${flowOutputPath} (applied entries: ${appliedCount}).`;
+    }
+  }
 
   console.log(`Using existing OpenAPI file: ${targetOpenApiFile}`);
   console.log(`Flows sidecar synced: ${flowsPath}`);
   console.log(`Tracked operations: ${trackedCount}`);
+  console.log(applyMessage);
   console.log("OpenAPI source unchanged. Edit the sidecar and run apply to generate the full spec.");
 
   console.log(`Validate now: x-openapi-flow validate ${targetOpenApiFile}`);
@@ -637,18 +1310,28 @@ function runInit(parsed) {
 }
 
 function runApply(parsed) {
-  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  let targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  let flowsPathFromPositional = null;
+
+  if (!parsed.flowsPath && parsed.openApiFile && looksLikeFlowsSidecar(parsed.openApiFile)) {
+    flowsPathFromPositional = parsed.openApiFile;
+    targetOpenApiFile = findOpenApiFile(process.cwd());
+  }
 
   if (!targetOpenApiFile) {
     console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
     console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    if (flowsPathFromPositional) {
+      console.error(`Detected sidecar argument: ${flowsPathFromPositional}`);
+      console.error("Provide an OpenAPI file explicitly or run the command from the OpenAPI project root.");
+    }
     return 1;
   }
 
-  const flowsPath = resolveFlowsPath(targetOpenApiFile, parsed.flowsPath);
+  const flowsPath = resolveFlowsPath(targetOpenApiFile, parsed.flowsPath || flowsPathFromPositional);
   if (!fs.existsSync(flowsPath)) {
     console.error(`ERROR: Flows sidecar not found: ${flowsPath}`);
-    console.error("Run `x-openapi-flow init` first to create and sync the sidecar.");
+    console.error("Run `x-openapi-flow init` first to create and sync the sidecar, or use --flows <sidecar-file>.");
     return 1;
   }
 
@@ -681,6 +1364,68 @@ function runApply(parsed) {
   return 0;
 }
 
+function runDiff(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  const flowsPath = resolveFlowsPath(targetOpenApiFile, parsed.flowsPath);
+
+  let api;
+  let existingFlows;
+  try {
+    api = loadApi(targetOpenApiFile);
+  } catch (err) {
+    console.error(`ERROR: Could not parse OpenAPI file — ${err.message}`);
+    return 1;
+  }
+
+  try {
+    existingFlows = readFlowsFile(flowsPath);
+  } catch (err) {
+    console.error(`ERROR: Could not parse flows file — ${err.message}`);
+    return 1;
+  }
+
+  const mergedFlows = mergeFlowsWithOpenApi(api, existingFlows);
+  const diff = summarizeSidecarDiff(existingFlows, mergedFlows);
+
+  if (parsed.format === "json") {
+    console.log(JSON.stringify({
+      openApiFile: targetOpenApiFile,
+      flowsPath,
+      trackedOperations: mergedFlows.operations.length,
+      exists: fs.existsSync(flowsPath),
+      diff,
+    }, null, 2));
+    return 0;
+  }
+
+  const addedText = diff.addedOperationIds.length ? diff.addedOperationIds.join(", ") : "-";
+  const changedText = diff.changedOperationIds.length ? diff.changedOperationIds.join(", ") : "-";
+  const removedText = diff.removedOperationIds.length ? diff.removedOperationIds.join(", ") : "-";
+
+  console.log(`OpenAPI source: ${targetOpenApiFile}`);
+  console.log(`Flows sidecar: ${flowsPath}${fs.existsSync(flowsPath) ? "" : " (not found; treated as empty)"}`);
+  console.log(`Tracked operations: ${mergedFlows.operations.length}`);
+  console.log(`Sidecar diff -> added: ${diff.added}, changed: ${diff.changed}, removed: ${diff.removed}`);
+  console.log(`Added operationIds: ${addedText}`);
+  console.log(`Changed operationIds: ${changedText}`);
+  if (diff.changedOperationDetails.length > 0) {
+    console.log("Changed details:");
+    diff.changedOperationDetails.forEach((detail) => {
+      const paths = detail.changedPaths.length ? detail.changedPaths.join(", ") : "(root)";
+      console.log(`- ${detail.operationId}: ${paths}`);
+    });
+  }
+  console.log(`Removed operationIds: ${removedText}`);
+  return 0;
+}
+
 function runDoctor(parsed) {
   const config = loadConfig(parsed.configPath);
   let hasErrors = false;
@@ -723,13 +1468,173 @@ function runDoctor(parsed) {
   return hasErrors ? 1 : 0;
 }
 
+function collectOperationIds(api) {
+  const operationsById = new Map();
+  const paths = (api && api.paths) || {};
+  const methods = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+
+  for (const [pathKey, pathItem] of Object.entries(paths)) {
+    for (const method of methods) {
+      const operation = pathItem[method];
+      if (!operation || !operation.operationId) {
+        continue;
+      }
+      operationsById.set(operation.operationId, {
+        endpoint: `${method.toUpperCase()} ${pathKey}`,
+      });
+    }
+  }
+
+  return operationsById;
+}
+
+function runLint(parsed, configData = {}) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  let api;
+  try {
+    api = loadApi(targetOpenApiFile);
+  } catch (err) {
+    console.error(`ERROR: Could not parse OpenAPI file — ${err.message}`);
+    return 1;
+  }
+
+  const flows = extractFlows(api);
+  const lintConfig = (configData && configData.lint && configData.lint.rules) || {};
+  const ruleConfig = {
+    next_operation_id_exists: lintConfig.next_operation_id_exists !== false,
+    prerequisite_operation_ids_exist: lintConfig.prerequisite_operation_ids_exist !== false,
+    duplicate_transitions: lintConfig.duplicate_transitions !== false,
+    terminal_path: lintConfig.terminal_path !== false,
+  };
+
+  const operationsById = collectOperationIds(api);
+  const graph = buildStateGraph(flows);
+  const invalidOperationReferences = detectInvalidOperationReferences(operationsById, flows);
+  const duplicateTransitions = detectDuplicateTransitions(flows);
+  const terminalCoverage = detectTerminalCoverage(graph);
+
+  const nextOperationIssues = invalidOperationReferences
+    .filter((entry) => entry.type === "next_operation_id")
+    .map((entry) => ({
+      operation_id: entry.operation_id,
+      declared_in: entry.declared_in,
+    }));
+
+  const prerequisiteIssues = invalidOperationReferences
+    .filter((entry) => entry.type === "prerequisite_operation_ids")
+    .map((entry) => ({
+      operation_id: entry.operation_id,
+      declared_in: entry.declared_in,
+    }));
+
+  const issues = {
+    next_operation_id_exists: ruleConfig.next_operation_id_exists ? nextOperationIssues : [],
+    prerequisite_operation_ids_exist: ruleConfig.prerequisite_operation_ids_exist ? prerequisiteIssues : [],
+    duplicate_transitions: ruleConfig.duplicate_transitions ? duplicateTransitions : [],
+    terminal_path: {
+      terminal_states: ruleConfig.terminal_path ? terminalCoverage.terminal_states : [],
+      non_terminating_states: ruleConfig.terminal_path ? terminalCoverage.non_terminating_states : [],
+    },
+  };
+
+  const errorCount =
+    issues.next_operation_id_exists.length +
+    issues.prerequisite_operation_ids_exist.length +
+    issues.duplicate_transitions.length +
+    issues.terminal_path.non_terminating_states.length;
+
+  const result = {
+    ok: errorCount === 0,
+    path: targetOpenApiFile,
+    flowCount: flows.length,
+    ruleConfig,
+    issues,
+    summary: {
+      errors: errorCount,
+      violated_rules: Object.entries({
+        next_operation_id_exists: issues.next_operation_id_exists.length,
+        prerequisite_operation_ids_exist: issues.prerequisite_operation_ids_exist.length,
+        duplicate_transitions: issues.duplicate_transitions.length,
+        terminal_path: issues.terminal_path.non_terminating_states.length,
+      })
+        .filter(([, count]) => count > 0)
+        .map(([rule]) => rule),
+    },
+  };
+
+  if (parsed.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+    return result.ok ? 0 : 1;
+  }
+
+  console.log(`Linting: ${targetOpenApiFile}`);
+  console.log(`Found ${flows.length} x-openapi-flow definition(s).`);
+  console.log("Rules:");
+  Object.entries(ruleConfig).forEach(([ruleName, enabled]) => {
+    console.log(`- ${ruleName}: ${enabled ? "enabled" : "disabled"}`);
+  });
+
+  if (flows.length === 0) {
+    console.log("No x-openapi-flow definitions found.");
+    return 0;
+  }
+
+  if (issues.next_operation_id_exists.length === 0) {
+    console.log("✔ next_operation_id_exists: no invalid references.");
+  } else {
+    console.error(`✘ next_operation_id_exists: ${issues.next_operation_id_exists.length} invalid reference(s).`);
+    issues.next_operation_id_exists.forEach((entry) => {
+      console.error(`  - ${entry.operation_id} (declared in ${entry.declared_in})`);
+    });
+  }
+
+  if (issues.prerequisite_operation_ids_exist.length === 0) {
+    console.log("✔ prerequisite_operation_ids_exist: no invalid references.");
+  } else {
+    console.error(`✘ prerequisite_operation_ids_exist: ${issues.prerequisite_operation_ids_exist.length} invalid reference(s).`);
+    issues.prerequisite_operation_ids_exist.forEach((entry) => {
+      console.error(`  - ${entry.operation_id} (declared in ${entry.declared_in})`);
+    });
+  }
+
+  if (issues.duplicate_transitions.length === 0) {
+    console.log("✔ duplicate_transitions: none found.");
+  } else {
+    console.error(`✘ duplicate_transitions: ${issues.duplicate_transitions.length} duplicate transition group(s).`);
+    issues.duplicate_transitions.forEach((entry) => {
+      console.error(`  - ${entry.from} -> ${entry.to} (${entry.trigger_type}), count=${entry.count}`);
+    });
+  }
+
+  if (issues.terminal_path.non_terminating_states.length === 0) {
+    console.log("✔ terminal_path: all states can reach a terminal state.");
+  } else {
+    console.error(
+      `✘ terminal_path: states without path to terminal -> ${issues.terminal_path.non_terminating_states.join(", ")}`
+    );
+  }
+
+  if (result.ok) {
+    console.log("Lint checks passed ✔");
+  } else {
+    console.error("Lint checks finished with errors.");
+  }
+
+  return result.ok ? 0 : 1;
+}
+
 function buildMermaidGraph(filePath) {
   const flows = extractFlowsForGraph(filePath);
   if (flows.length === 0) {
     throw new Error("No x-openapi-flow definitions found in OpenAPI or sidecar file");
   }
 
-  const lines = ["stateDiagram-v2"];
   const nodes = new Set();
   const edges = [];
   const edgeSeen = new Set();
@@ -771,19 +1676,47 @@ function buildMermaidGraph(filePath) {
         next_operation_id: transition.next_operation_id,
         prerequisite_operation_ids: transition.prerequisite_operation_ids || [],
       });
-
-      lines.push(`  ${from} --> ${to}${label ? `: ${label}` : ""}`);
     }
   }
 
-  for (const state of nodes) {
-    lines.splice(1, 0, `  state ${state}`);
+  const sortedNodes = [...nodes].sort((a, b) => a.localeCompare(b));
+  const sortedEdges = [...edges].sort((left, right) => {
+    const leftKey = [
+      left.from,
+      left.to,
+      left.next_operation_id || "",
+      (left.prerequisite_operation_ids || []).join(","),
+    ].join("::");
+    const rightKey = [
+      right.from,
+      right.to,
+      right.next_operation_id || "",
+      (right.prerequisite_operation_ids || []).join(","),
+    ].join("::");
+    return leftKey.localeCompare(rightKey);
+  });
+
+  const lines = ["stateDiagram-v2"];
+  for (const state of sortedNodes) {
+    lines.push(`  state ${state}`);
+  }
+  for (const edge of sortedEdges) {
+    const labelParts = [];
+    if (edge.next_operation_id) {
+      labelParts.push(`next:${edge.next_operation_id}`);
+    }
+    if (Array.isArray(edge.prerequisite_operation_ids) && edge.prerequisite_operation_ids.length > 0) {
+      labelParts.push(`requires:${edge.prerequisite_operation_ids.join(",")}`);
+    }
+    const label = labelParts.join(" | ");
+    lines.push(`  ${edge.from} --> ${edge.to}${label ? `: ${label}` : ""}`);
   }
 
   return {
+    format_version: "1.0",
     flowCount: flows.length,
-    nodes: [...nodes],
-    edges,
+    nodes: sortedNodes,
+    edges: sortedEdges,
     mermaid: lines.join("\n"),
   };
 }
@@ -848,6 +1781,474 @@ function runGraph(parsed) {
   }
 }
 
+function toKebabCase(value) {
+  if (!value) {
+    return "operation";
+  }
+
+  const normalized = String(value)
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+
+  return normalized || "operation";
+}
+
+function deriveResourceKey(pathKey) {
+  const tokens = String(pathKey || "")
+    .split("/")
+    .filter((token) => token && !token.startsWith("{") && !token.endsWith("}"));
+
+  return tokens[0] || "root";
+}
+
+function inferCurrentState(entry) {
+  const fingerprint = [entry.method, entry.path, entry.resolvedOperationId]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+
+  const keywordToState = [
+    { match: /cancel|void/, state: "CANCELED" },
+    { match: /refund/, state: "REFUNDED" },
+    { match: /fail|error|decline|reject/, state: "FAILED" },
+    { match: /deliver|received/, state: "DELIVERED" },
+    { match: /ship|dispatch/, state: "SHIPPED" },
+    { match: /complete|done|close|finish/, state: "COMPLETED" },
+    { match: /pay|charge|collect/, state: "PAID" },
+    { match: /confirm|approve|accept/, state: "CONFIRMED" },
+    { match: /process|fulfill/, state: "PROCESSING" },
+    { match: /create|submit|register/, state: "CREATED" },
+    { match: /get|list|find|fetch|read/, state: "OBSERVED" },
+  ];
+
+  for (const rule of keywordToState) {
+    if (rule.match.test(fingerprint)) {
+      return rule.state;
+    }
+  }
+
+  if (entry.method === "post") {
+    return "CREATED";
+  }
+  if (entry.method === "delete") {
+    return "CANCELED";
+  }
+  if (entry.method === "patch" || entry.method === "put") {
+    return "PROCESSING";
+  }
+
+  return "OBSERVED";
+}
+
+function inferTriggerType(fromEntry, toEntry) {
+  const toFingerprint = `${toEntry.method} ${toEntry.path} ${toEntry.resolvedOperationId}`.toLowerCase();
+  if (/(webhook|callback|event)/.test(toFingerprint)) {
+    return "webhook";
+  }
+
+  if (fromEntry.method === "get" || fromEntry.method === "head") {
+    return "polling";
+  }
+
+  return "synchronous";
+}
+
+function buildAnalyzedFlowsDoc(api) {
+  const stateOrder = {
+    CREATED: 10,
+    CONFIRMED: 20,
+    PAID: 30,
+    PROCESSING: 40,
+    SHIPPED: 50,
+    DELIVERED: 60,
+    COMPLETED: 70,
+    REFUNDED: 80,
+    CANCELED: 90,
+    FAILED: 100,
+    OBSERVED: 1000,
+  };
+
+  const terminalStates = new Set(["COMPLETED", "DELIVERED", "REFUNDED", "CANCELED", "FAILED"]);
+  const entries = extractOperationEntries(api);
+
+  const inferred = entries.map((entry) => ({
+    ...entry,
+    resourceKey: deriveResourceKey(entry.path),
+    inferredState: inferCurrentState(entry),
+    inferredRank: stateOrder[inferCurrentState(entry)] || 1000,
+  }));
+
+  const transitionInsights = [];
+
+  const operations = inferred.map((entry) => {
+    const sameResource = inferred.filter((candidate) => candidate.resourceKey === entry.resourceKey);
+    const prioritized = sameResource.length > 1 ? sameResource : inferred;
+
+    let transition = null;
+    if (!terminalStates.has(entry.inferredState)) {
+      const nextCandidates = prioritized
+        .filter((candidate) => candidate.resolvedOperationId !== entry.resolvedOperationId)
+        .filter((candidate) => candidate.inferredRank > entry.inferredRank)
+        .sort((left, right) => {
+          const rankDelta = (left.inferredRank - entry.inferredRank) - (right.inferredRank - entry.inferredRank);
+          if (rankDelta !== 0) {
+            return rankDelta;
+          }
+          return left.resolvedOperationId.localeCompare(right.resolvedOperationId);
+        });
+
+      const next = nextCandidates[0];
+      if (next) {
+        const confidence = Math.min(
+          0.95,
+          0.55
+            + (sameResource.length > 1 ? 0.25 : 0)
+            + (entry.inferredRank < 1000 && next.inferredRank < 1000 ? 0.1 : 0)
+            + (nextCandidates.length === 1 ? 0.1 : 0)
+        );
+
+        const confidenceReasons = [];
+        if (sameResource.length > 1) {
+          confidenceReasons.push("same_resource");
+        }
+        if (entry.inferredRank < 1000 && next.inferredRank < 1000) {
+          confidenceReasons.push("known_state_progression");
+        }
+        if (nextCandidates.length === 1) {
+          confidenceReasons.push("single_candidate");
+        }
+        if (confidenceReasons.length === 0) {
+          confidenceReasons.push("fallback_ordering");
+        }
+
+        transition = {
+          target_state: next.inferredState,
+          trigger_type: inferTriggerType(entry, next),
+          next_operation_id: next.resolvedOperationId,
+        };
+
+        transitionInsights.push({
+          from_operation_id: entry.resolvedOperationId,
+          to_operation_id: next.resolvedOperationId,
+          from_state: entry.inferredState,
+          target_state: next.inferredState,
+          trigger_type: transition.trigger_type,
+          confidence: Number(confidence.toFixed(2)),
+          confidence_reasons: confidenceReasons,
+        });
+      }
+    }
+
+    return {
+      operationId: entry.resolvedOperationId,
+      "x-openapi-flow": {
+        version: "1.0",
+        id: toKebabCase(entry.resolvedOperationId),
+        current_state: entry.inferredState,
+        description: "Auto-generated by x-openapi-flow analyze",
+        transitions: transition ? [transition] : [],
+      },
+    };
+  });
+
+  return {
+    version: "1.0",
+    operations,
+    analysis: {
+      operationCount: inferred.length,
+      uniqueStates: Array.from(new Set(inferred.map((entry) => entry.inferredState))).sort(),
+      inferredTransitions: operations.reduce((total, operation) => {
+        const transitions = operation["x-openapi-flow"].transitions || [];
+        return total + transitions.length;
+      }, 0),
+      transitionConfidence: transitionInsights,
+    },
+  };
+}
+
+function mergeSidecarOperations(existingDoc, inferredDoc) {
+  const existingOps = Array.isArray(existingDoc && existingDoc.operations)
+    ? existingDoc.operations
+    : [];
+  const inferredOps = Array.isArray(inferredDoc && inferredDoc.operations)
+    ? inferredDoc.operations
+    : [];
+
+  const existingByOperationId = new Map();
+  for (const operationEntry of existingOps) {
+    if (operationEntry && operationEntry.operationId) {
+      existingByOperationId.set(operationEntry.operationId, operationEntry);
+    }
+  }
+
+  const mergedOps = [];
+  const consumedExisting = new Set();
+
+  for (const inferredEntry of inferredOps) {
+    const existingEntry = existingByOperationId.get(inferredEntry.operationId);
+    if (!existingEntry) {
+      mergedOps.push(inferredEntry);
+      continue;
+    }
+
+    consumedExisting.add(inferredEntry.operationId);
+
+    const existingFlow = existingEntry["x-openapi-flow"] || {};
+    const inferredFlow = inferredEntry["x-openapi-flow"] || {};
+    const existingTransitions = Array.isArray(existingFlow.transitions) ? existingFlow.transitions : [];
+
+    mergedOps.push({
+      operationId: inferredEntry.operationId,
+      "x-openapi-flow": {
+        ...inferredFlow,
+        ...existingFlow,
+        transitions: existingTransitions.length > 0
+          ? existingTransitions
+          : (Array.isArray(inferredFlow.transitions) ? inferredFlow.transitions : []),
+      },
+    });
+  }
+
+  for (const existingEntry of existingOps) {
+    if (!existingEntry || !existingEntry.operationId) {
+      continue;
+    }
+    if (!consumedExisting.has(existingEntry.operationId)) {
+      mergedOps.push(existingEntry);
+    }
+  }
+
+  return {
+    version: "1.0",
+    operations: mergedOps,
+    mergeStats: {
+      existingOperations: existingOps.length,
+      inferredOperations: inferredOps.length,
+      mergedOperations: mergedOps.length,
+      preservedExistingOnly: Math.max(0, mergedOps.length - inferredOps.length),
+    },
+  };
+}
+
+function runAnalyze(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  let api;
+  try {
+    api = loadApi(targetOpenApiFile);
+  } catch (err) {
+    console.error(`ERROR: Could not parse OpenAPI file — ${err.message}`);
+    return 1;
+  }
+
+  const analysisResult = buildAnalyzedFlowsDoc(api);
+  let sidecarDoc = {
+    version: analysisResult.version,
+    operations: analysisResult.operations,
+  };
+  let mergeStats = null;
+
+  if (parsed.merge) {
+    const mergeFlowsPath = resolveFlowsPath(targetOpenApiFile, parsed.flowsPath);
+    let existingFlows = { version: "1.0", operations: [] };
+    if (fs.existsSync(mergeFlowsPath)) {
+      try {
+        existingFlows = readFlowsFile(mergeFlowsPath);
+      } catch (err) {
+        console.error(`ERROR: Could not parse flows file for merge — ${err.message}`);
+        return 1;
+      }
+    }
+
+    const merged = mergeSidecarOperations(existingFlows, sidecarDoc);
+    sidecarDoc = {
+      version: merged.version,
+      operations: merged.operations,
+    };
+    mergeStats = {
+      enabled: true,
+      flowsPath: mergeFlowsPath,
+      ...merged.mergeStats,
+    };
+  }
+
+  if (parsed.outPath) {
+    writeFlowsFile(parsed.outPath, sidecarDoc);
+  }
+
+  if (parsed.format === "json") {
+    console.log(JSON.stringify({
+      openApiFile: targetOpenApiFile,
+      outputPath: parsed.outPath || null,
+      merge: mergeStats || { enabled: false },
+      analysis: analysisResult.analysis,
+      sidecar: sidecarDoc,
+    }, null, 2));
+    return 0;
+  }
+
+  console.log(`Analyzed OpenAPI source: ${targetOpenApiFile}`);
+  console.log(`Inferred operations: ${analysisResult.analysis.operationCount}`);
+  console.log(`Inferred transitions: ${analysisResult.analysis.inferredTransitions}`);
+  console.log(`States: ${analysisResult.analysis.uniqueStates.join(", ") || "-"}`);
+  if (mergeStats && mergeStats.enabled) {
+    console.log(`Merged with sidecar: ${mergeStats.flowsPath}`);
+    console.log(`Merged operations total: ${mergeStats.mergedOperations}`);
+  }
+
+  if (parsed.outPath) {
+    console.log(`Suggested sidecar written to: ${parsed.outPath}`);
+    return 0;
+  }
+
+  console.log("---");
+  console.log(yaml.dump(sidecarDoc, { noRefs: true, lineWidth: -1 }).trimEnd());
+  return 0;
+}
+
+function runGenerateSdk(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  try {
+    const result = generateSdk({
+      apiPath: targetOpenApiFile,
+      language: parsed.language,
+      outputDir: parsed.outputPath,
+    });
+
+    console.log(`OpenAPI source: ${targetOpenApiFile}`);
+    console.log(`SDK language: ${result.language}`);
+    console.log(`Output directory: ${result.outputDir}`);
+    console.log(`Flow definitions processed: ${result.flowCount}`);
+    console.log(`Resources generated: ${result.resourceCount}`);
+    for (const resource of result.resources) {
+      console.log(`- ${resource.name}: operations=${resource.operations}, states=${resource.states}, initial=[${resource.initialStates.join(", ")}]`);
+    }
+    return 0;
+  } catch (err) {
+    console.error(`ERROR: Could not generate SDK — ${err.message}`);
+    return 1;
+  }
+}
+
+function runExportDocFlows(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  try {
+    const result = exportDocFlows({
+      apiPath: targetOpenApiFile,
+      outputPath: parsed.outputPath,
+      format: parsed.format,
+    });
+
+    console.log(`OpenAPI source: ${targetOpenApiFile}`);
+    console.log(`Output: ${result.outputPath}`);
+    console.log(`Format: ${result.format}`);
+    console.log(`Resources: ${result.resources}`);
+    console.log(`Flow definitions: ${result.flowCount}`);
+    return 0;
+  } catch (err) {
+    console.error(`ERROR: Could not export doc flows — ${err.message}`);
+    return 1;
+  }
+}
+
+function runGeneratePostman(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  try {
+    const result = generatePostmanCollection({
+      apiPath: targetOpenApiFile,
+      outputPath: parsed.outputPath,
+      withScripts: parsed.withScripts,
+    });
+
+    console.log(`OpenAPI source: ${targetOpenApiFile}`);
+    console.log(`Output: ${result.outputPath}`);
+    console.log(`Resources: ${result.resources}`);
+    console.log(`Flow definitions: ${result.flowCount}`);
+    console.log(`Scripts enabled: ${result.withScripts}`);
+    return 0;
+  } catch (err) {
+    console.error(`ERROR: Could not generate Postman collection — ${err.message}`);
+    return 1;
+  }
+}
+
+function runGenerateInsomnia(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  try {
+    const result = generateInsomniaWorkspace({
+      apiPath: targetOpenApiFile,
+      outputPath: parsed.outputPath,
+    });
+
+    console.log(`OpenAPI source: ${targetOpenApiFile}`);
+    console.log(`Output: ${result.outputPath}`);
+    console.log(`Resources: ${result.resources}`);
+    console.log(`Flow definitions: ${result.flowCount}`);
+    return 0;
+  } catch (err) {
+    console.error(`ERROR: Could not generate Insomnia workspace — ${err.message}`);
+    return 1;
+  }
+}
+
+function runGenerateRedoc(parsed) {
+  const targetOpenApiFile = parsed.openApiFile || findOpenApiFile(process.cwd());
+  if (!targetOpenApiFile) {
+    console.error("ERROR: Could not find an existing OpenAPI file in this repository.");
+    console.error("Expected one of: openapi.yaml|yml|json, swagger.yaml|yml|json");
+    return 1;
+  }
+
+  try {
+    const result = generateRedocPackage({
+      apiPath: targetOpenApiFile,
+      outputDir: parsed.outputPath,
+    });
+
+    console.log(`OpenAPI source: ${targetOpenApiFile}`);
+    console.log(`Output directory: ${result.outputDir}`);
+    console.log(`Redoc index: ${result.indexPath}`);
+    console.log(`Resources: ${result.resources}`);
+    console.log(`Flow definitions: ${result.flowCount}`);
+    return 0;
+  } catch (err) {
+    console.error(`ERROR: Could not generate Redoc package — ${err.message}`);
+    return 1;
+  }
+}
+
 function main() {
   const parsed = parseArgs(process.argv);
 
@@ -875,10 +2276,47 @@ function main() {
     process.exit(runGraph(parsed));
   }
 
+  if (parsed.command === "analyze") {
+    process.exit(runAnalyze(parsed));
+  }
+
+  if (parsed.command === "generate-sdk") {
+    process.exit(runGenerateSdk(parsed));
+  }
+
+  if (parsed.command === "export-doc-flows") {
+    process.exit(runExportDocFlows(parsed));
+  }
+
+  if (parsed.command === "generate-postman") {
+    process.exit(runGeneratePostman(parsed));
+  }
+
+  if (parsed.command === "generate-insomnia") {
+    process.exit(runGenerateInsomnia(parsed));
+  }
+
+  if (parsed.command === "generate-redoc") {
+    process.exit(runGenerateRedoc(parsed));
+  }
+
   if (parsed.command === "apply") {
     process.exit(runApply(parsed));
   }
 
+  if (parsed.command === "diff") {
+    process.exit(runDiff(parsed));
+  }
+
+  if (parsed.command === "lint") {
+    const config = loadConfig(parsed.configPath);
+    if (config.error) {
+      console.error(`ERROR: ${config.error}`);
+      process.exit(1);
+    }
+    process.exit(runLint(parsed, config.data));
+  }
+
   const config = loadConfig(parsed.configPath);
   if (config.error) {
     console.error(`ERROR: ${config.error}`);