@kosdev-code/kos-ui-cli 2.1.26 → 2.1.28

package/README.md

@@ -8,6 +8,7 @@ The KOS UI CLI (`kosui`) provides tools for:
 
 - Generating KOS models with proper architecture patterns
 - Creating OpenAPI type definitions and service wrappers from device APIs
+- Comparing API versions for breaking change detection
 - Managing workspace configurations
 - Scaffolding new KOS projects
 
@@ -31,6 +32,7 @@ npx @kosdev-code/kos-ui-cli <command>
 |---------|-------------|---------|
 | `model` | Generate KOS models | `kosui model UserProfile` |
 | `api:generate` | Generate API types from OpenAPI | `kosui api:generate --project my-app` |
+| `api:compare` | Compare API versions for compatibility | `kosui api:compare --project my-app --app kos --base v1.8.0 --target v1.9.0` |
 | `workspace` | Workspace utilities | `kosui workspace:list-models` |
 
 ## Commands
@@ -176,6 +178,139 @@ private onDeviceStatusLoaded(ctx: ExecutionContext<typeof PATH_DEVICE_STATUS>):
 }
 ```
 
+### kosui api:compare
+
+Compare OpenAPI versions to detect breaking changes and API compatibility issues.
+
+Analyzes two generated API type definitions to identify:
+- Removed endpoints or HTTP methods
+- New or removed parameters
+- Parameter requirement changes
+- Request body modifications
+
+#### Prerequisites
+
+Generate types for both versions before comparing:
+
+```bash
+# Connect to base version device and generate types
+kosui api:generate --project my-models --apps kos
+
+# Connect to target version device and generate types
+kosui api:generate --project my-models --apps kos
+```
+
+#### Options
+
+**Required:**
+- `--project <name>` - Project containing generated API types
+- `--app <name>` - App namespace to compare (kos, dispense, freestyle)
+- `--base <version>` - Base version to compare from
+- `--target <version>` - Target version to compare to
+
+**Optional:**
+- `--format <format>` - Output format: console (default), json, markdown
+- `--output <file>` - Write output to file instead of stdout
+- `--apps <apps>` - Compare multiple apps (comma-separated)
+
+#### Examples
+
+**Basic comparison:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --app kos \
+  --base v1.8.0 \
+  --target v1.9.0
+```
+
+**Generate markdown release notes:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --app kos \
+  --base v1.8.0 \
+  --target v1.9.0 \
+  --format markdown \
+  --output CHANGELOG-API.md
+```
+
+**JSON output for automation:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --app kos \
+  --base v1.8.0 \
+  --target v1.9.0 \
+  --format json
+```
+
+**Compare multiple apps:**
+```bash
+kosui api:compare \
+  --project device-models \
+  --apps kos,dispense,freestyle \
+  --base v1.8.0 \
+  --target v1.9.0
+```
+
+#### Output Formats
+
+**Console (default):**
+- Colored terminal output with compatibility status
+- Summary statistics (added/removed/modified endpoints)
+- Breaking changes highlighted
+- Recommendations for safe upgrade
+
+**JSON:**
+- Machine-readable format for automation
+- Complete comparison data structure
+- Suitable for CI/CD pipelines
+
+**Markdown:**
+- Ready for release notes and documentation
+- Organized sections for breaking/non-breaking changes
+- Suitable for commit messages or changelogs
+
+#### Exit Codes
+
+The command uses exit codes for automation:
+
+- **Exit 0** - Versions are backward compatible
+- **Exit 1** - Breaking changes detected
+
+Example CI/CD usage:
+```bash
+kosui api:compare --project models --app kos --base v1 --target v2
+if [ $? -eq 0 ]; then
+  echo "Safe to upgrade"
+else
+  echo "Breaking changes detected"
+fi
+```
+
+#### Integration with Build Process
+
+Add comparison target to `project.json`:
+
+```json
+{
+  "targets": {
+    "api:compare": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "kosui api:compare --project device-models --app kos --base ${BASE} --target ${TARGET}"
+      }
+    }
+  }
+}
+```
+
+Run via Nx:
+```bash
+BASE=v1.8.0 TARGET=v1.9.0 npx nx run device-models:api:compare
+```
+
 ### kosui model
 
 Generate KOS models with proper architecture patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-ui-cli",
-  "version": "2.1.26",
+  "version": "2.1.28",
   "bin": {
     "kosui": "./src/lib/cli.mjs"
   },
@@ -22,7 +22,7 @@
   "main": "./src/index.js",
   "kos": {
     "build": {
-      "gitHash": "5af05d3d902c4ddbee74f34723b5acd86dfbdeb7"
+      "gitHash": "de3ec24ed2fd4a39115ae0c10eeb3876aedb2c22"
     }
   },
   "publishConfig": {

package/src/lib/generators/api/compare.mjs

@@ -0,0 +1,139 @@
+import { compareApiVersions } from "./lib/compare-api.mjs";
+
+/**
+ * Registers the api:compare generator with Plop for comparing OpenAPI versions
+ * and detecting breaking changes between API type definitions.
+ *
+ * This generator analyzes two generated API type definition files to identify
+ * compatibility issues such as removed endpoints, changed parameters, and
+ * breaking changes. Essential for safe API upgrades and release planning.
+ *
+ * @param {import('plop').NodePlopAPI} plop - The Plop API instance
+ * @returns {Promise<void>} Resolves when generator is registered
+ *
+ * @example
+ * ```javascript
+ * // In plopfile.mjs
+ * import registerApiCompare from './generators/api/compare.mjs';
+ * await registerApiCompare(plop);
+ * ```
+ */
+export default async function register(plop) {
+  plop.setGenerator("api:compare", {
+    description: "Compare OpenAPI versions for compatibility analysis",
+    prompts: [
+      {
+        type: "input",
+        name: "project",
+        message: "Project name containing generated API types",
+        validate: (input) => {
+          if (!input || input.trim() === "") {
+            return "Project name is required";
+          }
+          return true;
+        },
+      },
+      {
+        type: "input",
+        name: "app",
+        message: "App namespace to compare (kos, dispense, freestyle, etc.)",
+        validate: (input) => {
+          if (!input || input.trim() === "") {
+            return "App namespace is required";
+          }
+          return true;
+        },
+      },
+      {
+        type: "input",
+        name: "baseVersion",
+        message: "Base version to compare from",
+        validate: (input) => {
+          if (!input || input.trim() === "") {
+            return "Base version is required";
+          }
+          return true;
+        },
+      },
+      {
+        type: "input",
+        name: "targetVersion",
+        message: "Target version to compare to",
+        validate: (input) => {
+          if (!input || input.trim() === "") {
+            return "Target version is required";
+          }
+          return true;
+        },
+      },
+      {
+        type: "list",
+        name: "format",
+        message: "Output format",
+        choices: ["console", "json", "markdown"],
+        default: "console",
+      },
+      {
+        type: "input",
+        name: "outputFile",
+        message: "Output file path (optional, leave empty for stdout)",
+        default: "",
+      },
+    ],
+    actions: function (answers) {
+      return [
+        async function compareApi() {
+          try {
+            const options = {
+              project: answers.project,
+              app: answers.app,
+              apps: answers.apps, // Support multi-app comparison
+              baseVersion: answers.baseVersion,
+              targetVersion: answers.targetVersion,
+              format: answers.format,
+              outputFile: answers.outputFile || undefined,
+            };
+
+            const result = await compareApiVersions(options);
+
+            if (answers.outputFile) {
+              return `[ok] Comparison written to ${answers.outputFile}`;
+            } else {
+              return `[ok] Comparison complete`;
+            }
+          } catch (error) {
+            console.error("Error comparing API versions:", error);
+            throw new Error(`Failed to compare API versions: ${error.message}`);
+          }
+        },
+      ];
+    },
+  });
+}
+
+/**
+ * Metadata for CLI integration describing the api:compare command.
+ *
+ * Provides command key, description, and argument mappings for the CLI
+ * help system and command-line argument parsing.
+ *
+ * @type {Object}
+ * @property {string} key - Command identifier used in CLI
+ * @property {string} name - Human-readable command name
+ * @property {string} description - Command description for help text
+ * @property {Object} namedArguments - Maps CLI argument names to prompt property names
+ */
+export const metadata = {
+  key: "api:compare",
+  name: "Compare API Versions",
+  description: "Analyze compatibility between OpenAPI versions and detect breaking changes",
+  namedArguments: {
+    project: "project",
+    app: "app",
+    apps: "apps", // For multi-app comparison
+    base: "baseVersion",
+    target: "targetVersion",
+    format: "format",
+    output: "outputFile",
+  },
+};

package/src/lib/generators/api/lib/compare-api.mjs

@@ -0,0 +1,748 @@
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { getProjectDetails } from '../../../utils/nx-context.mjs';
+
+/**
+ * Compares two OpenAPI versions and generates a detailed compatibility report.
+ *
+ * Analyzes generated TypeScript type definitions (openapi.d.ts files) to detect
+ * breaking changes, new endpoints, and API modifications. Supports multiple output
+ * formats and can compare multiple app namespaces simultaneously.
+ *
+ * @param {Object} options - Comparison options
+ * @param {string} options.project - Project name containing generated API types
+ * @param {string} [options.app] - Single app namespace to compare (e.g., 'kos', 'dispense')
+ * @param {string[]} [options.apps] - Array of app namespaces for multi-app comparison
+ * @param {string} options.baseVersion - Base version identifier (e.g., 'v1.8.0')
+ * @param {string} options.targetVersion - Target version identifier (e.g., 'v1.9.0')
+ * @param {('console'|'json'|'markdown')} [options.format='console'] - Output format
+ * @param {string} [options.outputFile] - Optional file path to write output
+ * @returns {Promise<{compatible: boolean, results: Array}>} Comparison results with compatibility status
+ * @throws {Error} When project not found or required type files don't exist
+ *
+ * @example
+ * ```javascript
+ * // Basic comparison
+ * const result = await compareApiVersions({
+ *   project: 'device-models',
+ *   app: 'kos',
+ *   baseVersion: 'v1.8.0',
+ *   targetVersion: 'v1.9.0',
+ *   format: 'console'
+ * });
+ *
+ * if (!result.compatible) {
+ *   console.error('Breaking changes detected!');
+ *   process.exit(1);
+ * }
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Multi-app comparison with markdown output
+ * await compareApiVersions({
+ *   project: 'device-models',
+ *   apps: ['kos', 'dispense', 'freestyle'],
+ *   baseVersion: 'v1.8.0',
+ *   targetVersion: 'v1.9.0',
+ *   format: 'markdown',
+ *   outputFile: 'CHANGELOG-API.md'
+ * });
+ * ```
+ */
+export async function compareApiVersions(options) {
+  const {
+    project,
+    app,
+    apps, // Array for multi-app comparison
+    baseVersion,
+    targetVersion,
+    format = 'console',
+    outputFile,
+  } = options;
+
+  // Get project configuration (following generate-api.mjs pattern exactly)
+  let projectConfig, src, outputPath;
+
+  try {
+    projectConfig = await getProjectDetails(project);
+    src = projectConfig.sourceRoot || projectConfig.root;
+    outputPath = projectConfig.targets?.api?.options?.outputPath;
+  } catch (error) {
+    throw new Error(`Project "${project}" not found in workspace: ${error.message}`);
+  }
+
+  // Use custom output path if specified, otherwise default to src/utils
+  const utilsDir = outputPath ? join(src, outputPath) : join(src, "utils");
+  const servicesDir = join(utilsDir, "services");
+
+  // Determine which apps to compare
+  const appsToCompare = apps || [app];
+  const results = [];
+
+  // Compare each app
+  for (const appName of appsToCompare) {
+    const baseSpecPath = join(servicesDir, appName, baseVersion, 'openapi.d.ts');
+    const targetSpecPath = join(servicesDir, appName, targetVersion, 'openapi.d.ts');
+
+    // Validate files exist
+    if (!existsSync(baseSpecPath)) {
+      throw new Error(
+        `Base version not found: ${baseSpecPath}\n` +
+        `Generate it by running: kosui api:generate --project ${project}\n` +
+        `(Point to ${baseVersion} device first)`
+      );
+    }
+
+    if (!existsSync(targetSpecPath)) {
+      throw new Error(
+        `Target version not found: ${targetSpecPath}\n` +
+        `Generate it by running: kosui api:generate --project ${project}\n` +
+        `(Point to ${targetVersion} device first)`
+      );
+    }
+
+    // Load and parse specs
+    const baseContent = readFileSync(baseSpecPath, 'utf-8');
+    const targetContent = readFileSync(targetSpecPath, 'utf-8');
+
+    const basePaths = extractPaths(baseContent);
+    const targetPaths = extractPaths(targetContent);
+
+    // Perform comparison
+    const comparison = compareSpecs(basePaths, targetPaths, {
+      app: appName,
+      baseVersion,
+      targetVersion,
+    });
+
+    results.push(comparison);
+  }
+
+  // Format and output results
+  const formatted = formatResults(results, format);
+
+  if (outputFile) {
+    writeFileSync(outputFile, formatted, 'utf-8');
+  } else {
+    console.log(formatted);
+  }
+
+  // Return exit code based on compatibility
+  const hasBreakingChanges = results.some(r => !r.summary.compatible);
+  process.exitCode = hasBreakingChanges ? 1 : 0;
+
+  return {
+    compatible: !hasBreakingChanges,
+    results,
+  };
+}
+
+/**
+ * Extracts API paths and their HTTP methods from OpenAPI TypeScript type definitions.
+ *
+ * Parses the `export interface paths` section of a generated openapi.d.ts file
+ * to build a map of endpoint paths to their available HTTP methods and parameters.
+ *
+ * @param {string} content - Content of openapi.d.ts file
+ * @returns {Map<string, Map<string, Object>>} Map of paths to methods with parameter info
+ *
+ * @example
+ * ```javascript
+ * const content = readFileSync('openapi.d.ts', 'utf-8');
+ * const paths = extractPaths(content);
+ * // paths.get('/api/kos/device/status') → Map { 'get' => { params: {...} } }
+ * ```
+ */
+function extractPaths(content) {
+  const paths = new Map();
+  const pathsMatch = content.match(/export interface paths \{([\s\S]*?)\n\}/);
+
+  if (!pathsMatch) {
+    return paths;
+  }
+
+  const pathsContent = pathsMatch[1];
+  const lines = pathsContent.split('\n');
+  let currentPath = null;
+  let braceCount = 0;
+  let pathContent = '';
+
+  for (const line of lines) {
+    // Match path property (quoted string at start of line)
+    const pathMatch = line.match(/^\s*"([^"]+)":\s*\{/);
+
+    if (pathMatch && braceCount === 0) {
+      currentPath = pathMatch[1];
+      braceCount = 1;
+      pathContent = line;
+    } else if (currentPath) {
+      pathContent += '\n' + line;
+      braceCount += (line.match(/\{/g) || []).length;
+      braceCount -= (line.match(/\}/g) || []).length;
+
+      if (braceCount === 0) {
+        const methods = extractMethods(pathContent);
+        paths.set(currentPath, methods);
+        currentPath = null;
+        pathContent = '';
+      }
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Extracts HTTP methods and their parameters from a path definition string.
+ *
+ * Parses the TypeScript definition for a single path to identify available
+ * HTTP methods (GET, POST, PUT, DELETE, PATCH) and their query, path, and
+ * body parameters.
+ *
+ * @param {string} pathDef - TypeScript definition string for a single path
+ * @returns {Map<string, Object>} Map of method names to parameter definitions
+ *
+ * @example
+ * ```javascript
+ * const pathDef = `"/api/kos/device/status": {
+ *   get: { parameters: { query: { detailed?: boolean } } }
+ * }`;
+ * const methods = extractMethods(pathDef);
+ * // methods.get('get') → { params: { query: [...], path: [...], body: '...' } }
+ * ```
+ */
+function extractMethods(pathDef) {
+  const methods = new Map();
+  const methodNames = ['get', 'post', 'put', 'delete', 'patch'];
+
+  for (const methodName of methodNames) {
+    // Match method property (unquoted identifier with any indentation)
+    const methodRegex = new RegExp(`^\\s*${methodName}:\\s*\\{`, 'gm');
+    const match = methodRegex.exec(pathDef);
+
+    if (match) {
+      const startIdx = match.index;
+      let braceCount = 1;
+      let endIdx = startIdx + match[0].length;
+
+      for (let i = endIdx; i < pathDef.length; i++) {
+        if (pathDef[i] === '{') braceCount++;
+        if (pathDef[i] === '}') braceCount--;
+        if (braceCount === 0) {
+          endIdx = i + 1;
+          break;
+        }
+      }
+
+      const methodDef = pathDef.substring(startIdx, endIdx);
+
+      const params = {
+        query: extractParameters(methodDef, 'query'),
+        path: extractParameters(methodDef, 'path'),
+        body: extractRequestBody(methodDef)
+      };
+
+      methods.set(methodName, { params });
+    }
+  }
+
+  return methods;
+}
+
+/**
+ * Extracts parameters of a specific type from an HTTP method definition.
+ *
+ * Parses query or path parameters from the TypeScript definition, identifying
+ * parameter names and whether they are required or optional.
+ *
+ * @param {string} methodDef - TypeScript definition for an HTTP method
+ * @param {('query'|'path')} paramType - Type of parameters to extract
+ * @returns {Array<{name: string, required: boolean}>} Array of parameter definitions
+ *
+ * @example
+ * ```javascript
+ * const methodDef = `get: { parameters: { query: { id: string, optional?: string } } }`;
+ * const params = extractParameters(methodDef, 'query');
+ * // Returns: [{ name: 'id', required: true }, { name: 'optional', required: false }]
+ * ```
+ */
+function extractParameters(methodDef, paramType) {
+  const params = [];
+  const paramMatch = methodDef.match(new RegExp(`${paramType}[?]?:\\s*\\{([\\s\\S]*?)\\n\\s*\\}`, 'm'));
+
+  if (paramMatch) {
+    const paramContent = paramMatch[1];
+    const paramRegex = /(\w+)(\?)?:/g;
+    let match;
+
+    while ((match = paramRegex.exec(paramContent)) !== null) {
+      if (match[1] !== 'never' && match[1] !== 'header' && match[1] !== 'cookie') {
+        params.push({
+          name: match[1],
+          required: !match[2]
+        });
+      }
+    }
+  }
+
+  return params;
+}
+
+/**
+ * Checks if an HTTP method definition includes a request body.
+ *
+ * Determines whether the endpoint expects a request body by checking for
+ * the presence of requestBody schema in the TypeScript definition.
+ *
+ * @param {string} methodDef - TypeScript definition for an HTTP method
+ * @returns {('present'|'none')} Whether a request body is expected
+ *
+ * @example
+ * ```javascript
+ * const methodDef = `post: { requestBody: { schema: {...} } }`;
+ * extractRequestBody(methodDef); // Returns: 'present'
+ * ```
+ */
+function extractRequestBody(methodDef) {
+  const bodyMatch = methodDef.match(/requestBody[:\?]\s*\{[\s\S]*?schema:/);
+  return bodyMatch ? 'present' : 'none';
+}
+
+/**
+ * Compares parameters between two API versions to detect changes.
+ *
+ * Identifies added, removed, and modified parameters, classifying changes
+ * as either breaking (removed params, new required params) or safe
+ * (new optional params, optional becoming required).
+ *
+ * @param {Array<{name: string, required: boolean}>} baseParams - Parameters from base version
+ * @param {Array<{name: string, required: boolean}>} targetParams - Parameters from target version
+ * @returns {Array<{type: string, param: string, severity: string}>} Array of parameter changes
+ *
+ * @example
+ * ```javascript
+ * const base = [{ name: 'id', required: true }];
+ * const target = [{ name: 'id', required: false }, { name: 'filter', required: true }];
+ * const changes = compareParameters(base, target);
+ * // Returns changes including:
+ * // - { type: 'changed', param: 'id', change: 'now optional', severity: 'safe' }
+ * // - { type: 'added', param: 'filter', required: true, severity: 'breaking' }
+ * ```
+ */
+function compareParameters(baseParams, targetParams) {
+  const changes = [];
+  const baseNames = new Set(baseParams.map(p => p.name));
+  const targetNames = new Set(targetParams.map(p => p.name));
+
+  // Removed parameters (breaking)
+  for (const param of baseParams) {
+    if (!targetNames.has(param.name)) {
+      changes.push({ type: 'removed', param: param.name, severity: 'breaking' });
+    }
+  }
+
+  // Added parameters
+  for (const param of targetParams) {
+    if (!baseNames.has(param.name)) {
+      const severity = param.required ? 'breaking' : 'safe';
+      changes.push({ type: 'added', param: param.name, required: param.required, severity });
+    }
+  }
+
+  // Changed required status
+  for (const baseParam of baseParams) {
+    const targetParam = targetParams.find(p => p.name === baseParam.name);
+    if (targetParam && baseParam.required !== targetParam.required) {
+      const severity = targetParam.required ? 'breaking' : 'safe';
+      changes.push({
+        type: 'changed',
+        param: baseParam.name,
+        change: targetParam.required ? 'now required' : 'now optional',
+        severity
+      });
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Performs comprehensive comparison of two OpenAPI specifications.
+ *
+ * Analyzes paths, methods, and parameters to generate a detailed compatibility
+ * report including breaking changes, new endpoints, and modifications. The
+ * comparison identifies API evolution and determines backward compatibility.
+ *
+ * @param {Map<string, Map<string, Object>>} basePaths - Parsed paths from base version
+ * @param {Map<string, Map<string, Object>>} targetPaths - Parsed paths from target version
+ * @param {Object} metadata - Version metadata (app, baseVersion, targetVersion)
+ * @returns {Object} Comprehensive comparison results with summary and detailed changes
+ *
+ * @example
+ * ```javascript
+ * const basePaths = extractPaths(baseContent);
+ * const targetPaths = extractPaths(targetContent);
+ * const results = compareSpecs(basePaths, targetPaths, {
+ *   app: 'kos',
+ *   baseVersion: 'v1.8.0',
+ *   targetVersion: 'v1.9.0'
+ * });
+ *
+ * console.log(`Compatible: ${results.summary.compatible}`);
+ * console.log(`Breaking changes: ${results.summary.breakingChanges.length}`);
+ * ```
+ */
+function compareSpecs(basePaths, targetPaths, metadata) {
+  const results = {
+    metadata,
+    summary: {
+      totalPathsBase: basePaths.size,
+      totalPathsTarget: targetPaths.size,
+      addedPaths: [],
+      removedPaths: [],
+      modifiedPaths: [],
+      compatible: true,
+      breakingChanges: []
+    }
+  };
+
+  // Find added paths
+  for (const [path, methods] of targetPaths) {
+    if (!basePaths.has(path)) {
+      results.summary.addedPaths.push({
+        path,
+        methods: Array.from(methods.keys()).map(m => m.toUpperCase())
+      });
+    }
+  }
+
+  // Find removed paths (breaking)
+  for (const [path, methods] of basePaths) {
+    if (!targetPaths.has(path)) {
+      results.summary.removedPaths.push({
+        path,
+        methods: Array.from(methods.keys()).map(m => m.toUpperCase())
+      });
+      results.summary.compatible = false;
+      results.summary.breakingChanges.push({
+        path,
+        change: `${Array.from(methods.keys()).map(m => m.toUpperCase()).join(', ')} removed`
+      });
+    }
+  }
+
+  // Find modified paths
+  for (const [path, baseMethods] of basePaths) {
+    if (!targetPaths.has(path)) continue;
+
+    const targetMethods = targetPaths.get(path);
+    const changes = [];
+
+    // Check for removed methods (breaking)
+    for (const [method, baseMethodDef] of baseMethods) {
+      if (!targetMethods.has(method)) {
+        changes.push(`${method.toUpperCase()} method removed`);
+        results.summary.compatible = false;
+        results.summary.breakingChanges.push({
+          path,
+          change: `${method.toUpperCase()} method removed`
+        });
+      }
+    }
+
+    // Check for added methods (safe)
+    for (const [method] of targetMethods) {
+      if (!baseMethods.has(method)) {
+        changes.push(`Added ${method.toUpperCase()} method`);
+      }
+    }
+
+    // Check for parameter changes
+    for (const [method, baseMethodDef] of baseMethods) {
+      const targetMethodDef = targetMethods.get(method);
+      if (!targetMethodDef) continue;
+
+      // Query parameters
+      const queryChanges = compareParameters(baseMethodDef.params.query, targetMethodDef.params.query);
+      for (const change of queryChanges) {
+        const changeDesc = `${method.toUpperCase()} query parameter "${change.param}" ${change.type}${change.change ? ` (${change.change})` : ''}`;
+
+        if (change.severity === 'breaking') {
+          results.summary.compatible = false;
+          results.summary.breakingChanges.push({ path, change: changeDesc });
+        } else {
+          changes.push(changeDesc);
+        }
+      }
+
+      // Path parameters
+      const pathChanges = compareParameters(baseMethodDef.params.path, targetMethodDef.params.path);
+      for (const change of pathChanges) {
+        const changeDesc = `${method.toUpperCase()} path parameter "${change.param}" ${change.type}${change.change ? ` (${change.change})` : ''}`;
+
+        if (change.severity === 'breaking') {
+          results.summary.compatible = false;
+          results.summary.breakingChanges.push({ path, change: changeDesc });
+        } else {
+          changes.push(changeDesc);
+        }
+      }
+
+      // Request body changes
+      if (baseMethodDef.params.body !== targetMethodDef.params.body) {
+        const changeDesc = targetMethodDef.params.body === 'present' && baseMethodDef.params.body === 'none'
+          ? `${method.toUpperCase()} request body now required`
+          : `${method.toUpperCase()} request body changed`;
+
+        const severity = targetMethodDef.params.body === 'present' && baseMethodDef.params.body === 'none' ? 'breaking' : 'safe';
+
+        if (severity === 'breaking') {
+          results.summary.compatible = false;
+          results.summary.breakingChanges.push({ path, change: changeDesc });
+        } else {
+          changes.push(changeDesc);
+        }
+      }
+    }
+
+    if (changes.length > 0) {
+      results.summary.modifiedPaths.push({ path, changes });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Formats comparison results according to the specified output format.
+ *
+ * Delegates to format-specific functions to generate console, JSON, or
+ * markdown output suitable for different use cases (terminal display,
+ * automation, documentation).
+ *
+ * @param {Array<Object>} results - Array of comparison results (one per app)
+ * @param {('console'|'json'|'markdown')} format - Desired output format
+ * @returns {string} Formatted comparison output
+ *
+ * @example
+ * ```javascript
+ * const results = [{ metadata: {...}, summary: {...} }];
+ * const output = formatResults(results, 'markdown');
+ * writeFileSync('CHANGELOG.md', output);
+ * ```
+ */
+function formatResults(results, format) {
+  switch (format) {
+    case 'json':
+      return formatJson(results);
+    case 'markdown':
+      return formatMarkdown(results);
+    case 'console':
+    default:
+      return formatConsole(results);
+  }
+}
+
+/**
+ * Formats comparison results as JSON for machine-readable output.
+ *
+ * Generates a structured JSON representation suitable for automation,
+ * CI/CD pipelines, and programmatic analysis.
+ *
+ * @param {Array<Object>} results - Array of comparison results
+ * @returns {string} JSON-formatted comparison data
+ *
+ * @example
+ * ```javascript
+ * const json = formatJson(results);
+ * const parsed = JSON.parse(json);
+ * console.log(`Breaking changes: ${parsed[0].summary.breakingChanges.length}`);
+ * ```
+ */
+function formatJson(results) {
+  return JSON.stringify(results, null, 2);
+}
+
+/**
+ * Formats comparison results as Markdown for documentation and release notes.
+ *
+ * Generates well-structured markdown with sections for summary, breaking changes,
+ * new endpoints, removed endpoints, and modifications. Suitable for changelogs,
+ * release notes, and technical documentation.
+ *
+ * @param {Array<Object>} results - Array of comparison results
+ * @returns {string} Markdown-formatted comparison report
+ *
+ * @example
+ * ```javascript
+ * const markdown = formatMarkdown(results);
+ * writeFileSync('CHANGELOG-API.md', markdown);
+ * ```
+ */
+function formatMarkdown(results) {
+  let output = [];
+
+  for (const result of results) {
+    const { metadata, summary } = result;
+
+    output.push(`# API Changes: ${metadata.app} (${metadata.baseVersion} → ${metadata.targetVersion})\n`);
+
+    // Summary
+    output.push(`## Summary\n`);
+    output.push(`- Total endpoints: ${summary.totalPathsBase} → ${summary.totalPathsTarget}`);
+    output.push(`- Added: ${summary.addedPaths.length}`);
+    output.push(`- Removed: ${summary.removedPaths.length}`);
+    output.push(`- Modified: ${summary.modifiedPaths.length}`);
+    output.push(`- Breaking changes: ${summary.breakingChanges.length}`);
+    output.push(`- **Status**: ${summary.compatible ? '✅ Backward compatible' : '❌ Not backward compatible'}\n`);
+
+    // Breaking changes
+    if (summary.breakingChanges.length > 0) {
+      output.push(`## Breaking Changes\n`);
+      for (const change of summary.breakingChanges) {
+        output.push(`- \`${change.path}\` - ${change.change}`);
+      }
+      output.push('');
+    }
+
+    // New endpoints
+    if (summary.addedPaths.length > 0) {
+      output.push(`## New Endpoints\n`);
+      for (const { path, methods } of summary.addedPaths) {
+        output.push(`- \`${path}\` - ${methods.join(', ')}`);
+      }
+      output.push('');
+    }
+
+    // Removed endpoints
+    if (summary.removedPaths.length > 0) {
+      output.push(`## Removed Endpoints\n`);
+      for (const { path, methods } of summary.removedPaths) {
+        output.push(`- \`${path}\` - ${methods.join(', ')}`);
+      }
+      output.push('');
+    }
+
+    // Modified endpoints
+    if (summary.modifiedPaths.length > 0) {
+      output.push(`## Modified Endpoints (Non-Breaking)\n`);
+      for (const { path, changes } of summary.modifiedPaths) {
+        output.push(`- \`${path}\` - ${changes.join(', ')}`);
+      }
+      output.push('');
+    }
+  }
+
+  return output.join('\n');
+}
+
+/**
+ * Formats comparison results with colored terminal output for human readability.
+ *
+ * Generates visually appealing console output with color-coded sections,
+ * compatibility status, and actionable recommendations. Uses chalk for
+ * terminal color support.
+ *
+ * @param {Array<Object>} results - Array of comparison results
+ * @returns {string} Colored terminal output with ASCII decorations
+ *
+ * @example
+ * ```javascript
+ * const output = formatConsole(results);
+ * console.log(output); // Displays colored comparison in terminal
+ * ```
+ */
+function formatConsole(results) {
+  let output = [];
+
+  for (const result of results) {
+    const { metadata, summary } = result;
+
+    // Header
+    output.push(chalk.gray('═'.repeat(63)));
+    output.push(chalk.bold.cyan('API Compatibility Analysis\n'));
+    output.push(chalk.white(`App:            ${metadata.app}`));
+    output.push(chalk.white(`Base Version:   ${metadata.baseVersion}`));
+    output.push(chalk.white(`Target Version: ${metadata.targetVersion}`));
+    output.push(chalk.gray('═'.repeat(63)) + '\n');
+
+    // Compatibility status
+    if (summary.compatible) {
+      output.push(chalk.green.bold('BACKWARD COMPATIBLE\n'));
+    } else {
+      output.push(chalk.red.bold('BREAKING CHANGES DETECTED\n'));
+    }
+
+    output.push(chalk.gray('═'.repeat(63)) + '\n');
+
+    // Summary
+    output.push(chalk.bold('Summary\n'));
+    output.push(chalk.white(`Total Paths in Base:   ${summary.totalPathsBase}`));
+    output.push(chalk.white(`Total Paths in Target: ${summary.totalPathsTarget}`));
+    output.push(chalk.white(`Added Paths:           ${summary.addedPaths.length}`));
+    output.push(chalk.white(`Removed Paths:         ${summary.removedPaths.length}`));
+    output.push(chalk.white(`Modified Paths:        ${summary.modifiedPaths.length}`));
+    output.push(chalk.white(`Breaking Changes:      ${summary.breakingChanges.length}`));
+    output.push('');
+
+    // Breaking changes
+    if (summary.breakingChanges.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.red.bold('BREAKING CHANGES\n'));
+      for (const change of summary.breakingChanges) {
+        output.push(chalk.yellow(`${change.path}`) + chalk.white(` - ${change.change}`));
+      }
+      output.push('');
+    }
+
+    // New endpoints
+    if (summary.addedPaths.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.green.bold('NEW ENDPOINTS\n'));
+      for (const { path, methods } of summary.addedPaths) {
+        output.push(chalk.cyan(path) + chalk.white(` - ${methods.join(', ')}`));
+      }
+      output.push('');
+    }
+
+    // Removed endpoints
+    if (summary.removedPaths.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.red.bold('REMOVED ENDPOINTS\n'));
+      for (const { path, methods } of summary.removedPaths) {
+        output.push(chalk.red(path) + chalk.white(` - ${methods.join(', ')}`));
+      }
+      output.push('');
+    }
+
+    // Modified endpoints
+    if (summary.modifiedPaths.length > 0) {
+      output.push(chalk.gray('═'.repeat(63)) + '\n');
+      output.push(chalk.blue.bold('MODIFIED ENDPOINTS (Non-Breaking)\n'));
+      for (const { path, changes } of summary.modifiedPaths) {
+        output.push(chalk.cyan(path) + chalk.white(` - ${changes.join(', ')}`));
+      }
+      output.push('');
+    }
+
+    output.push(chalk.gray('═'.repeat(63)) + '\n');
+
+    // Recommendations
+    output.push(chalk.bold('Recommendations\n'));
+    if (!summary.compatible) {
+      output.push(chalk.yellow('Migration Required - Breaking changes detected'));
+      output.push(chalk.white('Review all breaking changes before upgrading'));
+    } else if (summary.addedPaths.length > 0) {
+      output.push(chalk.green('Safe to upgrade - No breaking changes'));
+      output.push(chalk.white('New endpoints available to use'));
+    } else {
+      output.push(chalk.green('Versions are identical or fully compatible'));
+    }
+
+    output.push('\n' + chalk.gray('═'.repeat(63)));
+  }
+
+  return output.join('\n');
+}

package/src/lib/generators/workspace/index.mjs

@@ -1,5 +1,5 @@
 // generators/workspace/index.mjs
-import { createWorkspace } from "create-nx-workspace";
+// Note: create-nx-workspace is imported lazily to avoid dependency errors
 import { required } from "../../utils/validators.mjs";
 import registerListModels from "./list-models.mjs";
 import registerListProjects from "./list-projects.mjs";
@@ -15,6 +15,8 @@ export const metadata = {
 };
 export default async function (plop) {
   plop.setActionType("createWorkspace", async function (answers) {
+    // Lazy import to avoid dependency errors when not using workspace generator
+    const { createWorkspace } = await import("create-nx-workspace");
     await createWorkspace("@kosdev-code/kos-nx-plugin", {
       nxCloud: "skip",
       name: answers.workspaceName,

package/src/lib/plopfile.mjs

@@ -13,6 +13,7 @@ import registerComponent from "./generators/component/index.mjs";
 import registerPluginComponent from "./generators/plugin/index.mjs";
 
 import registerApiGenerate from "./generators/api/generate.mjs";
+import registerApiCompare from "./generators/api/compare.mjs";
 import registerCacheGenerators from "./generators/cache/index.mjs";
 import registerDev from "./generators/dev/index.mjs";
 import registerEnv from "./generators/env/index.mjs";
@@ -62,6 +63,7 @@ export default async function (plop) {
   await registerI18n(plop);
   await registerI18nNamespace(plop);
   await registerApiGenerate(plop);
+  await registerApiCompare(plop);
   await registerDev(plop);
   await registerEnv(plop);
   await registerKab(plop);