@kosdev-code/kos-ui-cli 2.0.43 → 2.0.45

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/generate.mjs

@@ -0,0 +1,105 @@
+import { generateApiTypes } from "./lib/generate-api.mjs";
+
+/**
+ * Generator for creating OpenAPI service types
+ */
+export default async function register(plop) {
+  plop.setGenerator("api:generate", {
+    description: "Generate OpenAPI service types for a project",
+    prompts: [
+      {
+        type: "input",
+        name: "project",
+        message: "Project name",
+        validate: (input) => {
+          if (!input || input.trim() === "") {
+            return "Project name is required";
+          }
+          return true;
+        },
+      },
+      {
+        type: "input",
+        name: "host",
+        message: "API host URL (or 'inherit' to use project.json)",
+        default: "inherit",
+      },
+      {
+        type: "input",
+        name: "apps",
+        message: "Apps to include (comma-separated, leave empty for all)",
+        default: "",
+        filter: (input) => {
+          if (!input || input.trim() === "") {
+            return [];
+          }
+          return input.split(",").map((s) => s.trim()).filter(Boolean);
+        },
+      },
+      {
+        type: "input",
+        name: "outputPath",
+        message: "Output path (or 'inherit' to use project.json)",
+        default: "inherit",
+      },
+      {
+        type: "input",
+        name: "defaultVersion",
+        message: "Default version (or 'inherit' to use project.json)",
+        default: "inherit",
+      },
+      {
+        type: "input",
+        name: "allAppsVersion",
+        message: "Override all apps to specific version (leave empty to use individual versions)",
+        default: "",
+      },
+    ],
+    actions: function (answers) {
+      return [
+        async function generateApi() {
+          try {
+            const options = {
+              project: answers.project,
+              host: answers.host === "inherit" ? undefined : answers.host,
+              studio: false, // Third-party projects don't use Studio endpoints
+              apps: answers.apps,
+              excludeCore: true, // Always exclude core services (already in published SDKs)
+              outputPath: answers.outputPath === "inherit" ? undefined : (answers.outputPath || undefined),
+              defaultVersion: answers.defaultVersion === "inherit" ? undefined : answers.defaultVersion,
+              allAppsVersion: answers.allAppsVersion || undefined,
+              // Pass CLI overrides if provided (they'll be merged with project.json in generate-api.mjs)
+              appVersions: answers.appVersions,
+              serviceExportAliases: answers.serviceExportAliases,
+            };
+
+            const result = await generateApiTypes(options);
+
+            return `[ok] Generated ${result.filesGenerated} files for ${result.apps.length} apps: ${result.apps.join(", ")}`;
+          } catch (error) {
+            console.error("Error generating API types:", error);
+            throw new Error(`Failed to generate API types: ${error.message}`);
+          }
+        },
+      ];
+    },
+  });
+}
+
+// Export metadata for CLI integration
+export const metadata = {
+  key: "api:generate",
+  name: "Generate OpenAPI service types",
+  description: "Generate typed service helpers from OpenAPI specifications",
+  namedArguments: {
+    project: "project",
+    host: "host",
+    apps: "apps",
+    output: "outputPath",
+    "default-version": "defaultVersion",
+    "all-apps-version": "allAppsVersion",
+    // Advanced options that can be passed as JSON strings or key=value pairs
+    alias: "serviceExportAliases",
+    "app-version": "appVersions",
+  },
+};