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

package/src/lib/cli.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { clearCache } from "./utils/cache.mjs";
 import { buildNonInteractiveCommand, isRunningInteractively } from "./utils/command-builder.mjs";
 import { getGeneratorMetadata } from "./utils/generator-loader.mjs";
+import { displayGeneralHelp, displayGeneratorHelp } from "./utils/cli-help-display.mjs";
 
 const originalArgs = process.argv.slice(2);
 const parsedArgs = minimist(originalArgs);
@@ -37,6 +38,47 @@ const configPath = path.join(__dirname, "plopfile.mjs");
 const showBanner =
   command !== "help" && process.env.DISABLE_CLI_BANNER !== "true";
 
+/**
+ * Parse CLI argument values, handling booleans, JSON, key=value pairs, and repeated arguments
+ * @param {*} value - The raw argument value from minimist
+ * @returns {*} - The parsed value (boolean, object, or original value)
+ */
+function parseArgumentValue(value) {
+  // Convert string boolean values to actual booleans
+  if (value === "true" || value === "y" || value === "yes") {
+    return true;
+  } else if (value === "false" || value === "n" || value === "no") {
+    return false;
+  } else if (typeof value === "string" && (value.startsWith("{") || value.startsWith("["))) {
+    // Try to parse JSON for complex arguments like --app-version='{"ice-app":"v2"}'
+    try {
+      return JSON.parse(value);
+    } catch (e) {
+      // If JSON parsing fails, keep as string
+      return value;
+    }
+  } else if (Array.isArray(value)) {
+    // Handle repeated arguments like --app-version ice-app=v2 --app-version apc=v3
+    // Minimist stores repeated args as arrays
+    const parsedObject = {};
+    value.forEach(item => {
+      if (typeof item === 'string' && item.includes('=')) {
+        const [key, val] = item.split('=');
+        parsedObject[key.trim()] = val.trim();
+      }
+    });
+    return Object.keys(parsedObject).length > 0 ? parsedObject : value;
+  } else if (typeof value === "string" && value.includes("=")) {
+    // Handle single key=value format like --app-version ice-app=v2
+    const parsedObject = {};
+    const [key, val] = value.split('=');
+    parsedObject[key.trim()] = val.trim();
+    return parsedObject;
+  }
+
+  return value;
+}
+
 async function launch() {
   // Check for help modes before initializing plop to avoid expensive model parsing
   const shouldShowHelp = parsedArgs.help;
@@ -44,25 +86,7 @@ async function launch() {
   if (!command || command === "help") {
     // For general help, we still need plop to list generators
     const plop = await nodePlop(configPath);
-
-    console.warn("--- KOS CLI Help ---");
-    console.log("\nAvailable Generators:");
-    plop.getGeneratorList().forEach((g) => {
-      console.log(`- ${g.name}: ${g.description}`);
-    });
-
-    console.log("\nUsage:");
-    console.log("  kosui <generator> [options]");
-    console.log("  kosui <generator> --help  # Show generator-specific help");
-    console.log("\nGlobal Options:");
-    console.log("  --no-cache      Disable cache");
-    console.log("  --refresh       Clear cache and refresh");
-    console.log("  --quiet         Suppress banner and debug output");
-    console.log(
-      "  --interactive, -i   Force interactive mode (ignore provided arguments)"
-    );
-    console.log("  --help          Show this help");
-
+    displayGeneralHelp(plop);
     return;
   }
 
@@ -71,151 +95,7 @@ async function launch() {
     const earlyMeta = await getGeneratorMetadata(command);
 
     if (earlyMeta && Object.keys(earlyMeta).length > 0) {
-      // Show help immediately for --help flag
-      console.log(`--- ${earlyMeta?.name || command} Help ---`);
-      console.log(earlyMeta.description || "No description available");
-
-      if (earlyMeta?.namedArguments) {
-        console.log("\nNamed Arguments:");
-        Object.entries(earlyMeta.namedArguments).forEach(
-          ([cliArg, promptName]) => {
-            console.log(`  --${cliArg}    Maps to prompt: ${promptName}`);
-          }
-        );
-      }
-
-      console.log("\nExamples:");
-
-      // Generate examples dynamically from the generator's named arguments
-      if (earlyMeta?.namedArguments) {
-        const args = Object.keys(earlyMeta.namedArguments);
-
-        // Generate example values based on argument names
-        const generateExampleValue = (argName) => {
-          switch (argName) {
-            case "name":
-            case "componentName":
-              return command.includes("plugin") ? "MyPlugin" : "MyComponent";
-            case "modelName":
-              return "my-model";
-            case "workspaceName":
-              return "my-workspace";
-            case "project":
-            case "componentProject":
-            case "modelProject":
-              return "my-ui-lib";
-            case "registrationProject":
-              return "my-lib";
-            case "companionParent":
-              return "parent-model";
-            case "extensionPoint":
-              return "utility";
-            case "group":
-              return "appearance";
-            case "locale":
-              return "en";
-            case "container":
-            case "singleton":
-            case "parentAware":
-            case "dataServices":
-              return true;
-            case "dryRun":
-              return true;
-            default:
-              return `my-${argName}`;
-          }
-        };
-
-        // Create basic example with most important arguments
-        const basicArgs = [];
-        const booleanArgs = [
-          "container",
-          "singleton",
-          "parentAware",
-          "dataServices",
-          "dryRun",
-        ];
-
-        // Pick the most relevant arguments for each generator type
-        const getRelevantArgs = (args, command) => {
-          const relevantArgs = [];
-
-          // Always prefer name-type arguments first
-          const nameArgs = [
-            "name",
-            "componentName",
-            "modelName",
-            "workspaceName",
-          ].filter((arg) => args.includes(arg));
-          if (nameArgs.length > 0) {
-            relevantArgs.push(nameArgs[0]); // Take the first name argument
-          }
-
-          // Then add project-type arguments
-          const projectArgs = [
-            "project",
-            "componentProject",
-            "modelProject",
-            "registrationProject",
-          ].filter((arg) => args.includes(arg));
-          if (projectArgs.length > 0) {
-            relevantArgs.push(projectArgs[0]); // Take the first project argument
-          }
-
-          // Add other specific arguments
-          const otherArgs = args.filter(
-            (arg) =>
-              !nameArgs.includes(arg) &&
-              !projectArgs.includes(arg) &&
-              !booleanArgs.includes(arg) &&
-              arg !== "interactive"
-          );
-
-          // Add up to 2 more relevant arguments
-          relevantArgs.push(...otherArgs.slice(0, 2));
-
-          return relevantArgs;
-        };
-
-        const relevantArgs = getRelevantArgs(args, command);
-
-        relevantArgs.forEach((argName) => {
-          const value = generateExampleValue(argName);
-          basicArgs.push(`--${argName} ${value}`);
-        });
-
-        // Create advanced example with boolean flags
-        const advancedBooleanArgs = [];
-        booleanArgs.forEach((argName) => {
-          if (args.includes(argName)) {
-            advancedBooleanArgs.push(`--${argName}`);
-          }
-        });
-
-        // Show basic example
-        if (basicArgs.length > 0) {
-          console.log(`  kosui ${command} ${basicArgs.join(" ")}`);
-        }
-
-        // Show advanced example with boolean flags if any exist
-        if (basicArgs.length > 0 && advancedBooleanArgs.length > 0) {
-          console.log(
-            `  kosui ${command} ${basicArgs
-              .slice(0, 2)
-              .join(" ")} ${advancedBooleanArgs.join(" ")}`
-          );
-        }
-
-        // If no basic args, show a minimal example
-        if (basicArgs.length === 0) {
-          console.log(`  kosui ${command} [options]`);
-        }
-      }
-
-      console.log(`  kosui ${command} --interactive  # Force interactive mode`);
-      console.log(
-        `  kosui ${command} -i             # Force interactive mode (short form)`
-      );
+      displayGeneratorHelp(command, earlyMeta);
       return;
     }
   }
@@ -228,13 +108,7 @@ async function launch() {
     Object.entries(namedArgumentsMap).forEach(([cliArg, promptName]) => {
       if (cliArg === "interactive") return;
       if (parsedArgs[cliArg] !== undefined) {
-        let value = parsedArgs[cliArg];
-        if (value === "true" || value === "y" || value === "yes") {
-          value = true;
-        } else if (value === "false" || value === "n" || value === "no") {
-          value = false;
-        }
-        providedAnswers[promptName] = value;
+        providedAnswers[promptName] = parseArgumentValue(parsedArgs[cliArg]);
       }
     });
     const hasAnyAnswers = Object.keys(providedAnswers).length > 0;
@@ -242,150 +116,7 @@ async function launch() {
 
     // Show help for no-arguments case
     if (!hasAnyAnswers && !forceInteractive) {
-      console.log(`--- ${earlyMeta?.name || command} Help ---`);
-      console.log(earlyMeta.description || "No description available");
-
-      if (earlyMeta?.namedArguments) {
-        console.log("\nNamed Arguments:");
-        Object.entries(earlyMeta.namedArguments).forEach(
-          ([cliArg, promptName]) => {
-            console.log(`  --${cliArg}    Maps to prompt: ${promptName}`);
-          }
-        );
-      }
-
-      console.log("\nExamples:");
-
-      // Generate examples dynamically from the generator's named arguments
-      if (earlyMeta?.namedArguments) {
-        const args = Object.keys(earlyMeta.namedArguments);
-
-        // Generate example values based on argument names
-        const generateExampleValue = (argName) => {
-          switch (argName) {
-            case "name":
-            case "componentName":
-              return command.includes("plugin") ? "MyPlugin" : "MyComponent";
-            case "modelName":
-              return "my-model";
-            case "workspaceName":
-              return "my-workspace";
-            case "project":
-            case "componentProject":
-            case "modelProject":
-              return "my-ui-lib";
-            case "registrationProject":
-              return "my-lib";
-            case "companionParent":
-              return "parent-model";
-            case "extensionPoint":
-              return "utility";
-            case "group":
-              return "appearance";
-            case "locale":
-              return "en";
-            case "container":
-            case "singleton":
-            case "parentAware":
-            case "dataServices":
-              return true;
-            case "dryRun":
-              return true;
-            default:
-              return `my-${argName}`;
-          }
-        };
-
-        // Create basic example with most important arguments
-        const basicArgs = [];
-        const booleanArgs = [
-          "container",
-          "singleton",
-          "parentAware",
-          "dataServices",
-          "dryRun",
-        ];
-
-        // Pick the most relevant arguments for each generator type
-        const getRelevantArgs = (args, command) => {
-          const relevantArgs = [];
-
-          // Always prefer name-type arguments first
-          const nameArgs = [
-            "name",
-            "componentName",
-            "modelName",
-            "workspaceName",
-          ].filter((arg) => args.includes(arg));
-          if (nameArgs.length > 0) {
-            relevantArgs.push(nameArgs[0]); // Take the first name argument
-          }
-
-          // Then add project-type arguments
-          const projectArgs = [
-            "project",
-            "componentProject",
-            "modelProject",
-            "registrationProject",
-          ].filter((arg) => args.includes(arg));
-          if (projectArgs.length > 0) {
-            relevantArgs.push(projectArgs[0]); // Take the first project argument
-          }
-
-          // Add other specific arguments
-          const otherArgs = args.filter(
-            (arg) =>
-              !nameArgs.includes(arg) &&
-              !projectArgs.includes(arg) &&
-              !booleanArgs.includes(arg) &&
-              arg !== "interactive"
-          );
-
-          // Add up to 2 more relevant arguments
-          relevantArgs.push(...otherArgs.slice(0, 2));
-
-          return relevantArgs;
-        };
-
-        const relevantArgs = getRelevantArgs(args, command);
-
-        relevantArgs.forEach((argName) => {
-          const value = generateExampleValue(argName);
-          basicArgs.push(`--${argName} ${value}`);
-        });
-
-        // Create advanced example with boolean flags
-        const advancedBooleanArgs = [];
-        booleanArgs.forEach((argName) => {
-          if (args.includes(argName)) {
-            advancedBooleanArgs.push(`--${argName}`);
-          }
-        });
-
-        // Show basic example
-        if (basicArgs.length > 0) {
-          console.log(`  kosui ${command} ${basicArgs.join(" ")}`);
-        }
-
-        // Show advanced example with boolean flags if any exist
-        if (basicArgs.length > 0 && advancedBooleanArgs.length > 0) {
-          console.log(
-            `  kosui ${command} ${basicArgs
-              .slice(0, 2)
-              .join(" ")} ${advancedBooleanArgs.join(" ")}`
-          );
-        }
-
-        // If no basic args, show a minimal example
-        if (basicArgs.length === 0) {
-          console.log(`  kosui ${command} [options]`);
-        }
-      }
-
-      console.log(`  kosui ${command} --interactive  # Force interactive mode`);
-      console.log(
-        `  kosui ${command} -i             # Force interactive mode (short form)`
-      );
+      displayGeneratorHelp(command, earlyMeta);
       return;
     }
   }
@@ -434,16 +165,7 @@ async function launch() {
       }
 
       if (parsedArgs[cliArg] !== undefined) {
-        let value = parsedArgs[cliArg];
-
-        // Convert string boolean values to actual booleans
-        if (value === "true" || value === "y" || value === "yes") {
-          value = true;
-        } else if (value === "false" || value === "n" || value === "no") {
-          value = false;
-        }
-
-        providedAnswers[promptName] = value;
+        providedAnswers[promptName] = parseArgumentValue(parsedArgs[cliArg]);
       }
     });
 
@@ -478,148 +200,7 @@ async function launch() {
 
     // If no arguments provided and no interactive flag, show help
     if (!hasAnyAnswers && !forceInteractive) {
-      console.log(`--- ${meta?.name || command} Help ---`);
-      console.log(generator.description || "No description available");
-
-      if (meta?.namedArguments) {
-        console.log("\nNamed Arguments:");
-        Object.entries(meta.namedArguments).forEach(([cliArg, promptName]) => {
-          console.log(`  --${cliArg}    Maps to prompt: ${promptName}`);
-        });
-      }
-
-      console.log("\nExamples:");
-
-      // Generate examples dynamically from the generator's named arguments
-      if (meta?.namedArguments) {
-        const args = Object.keys(meta.namedArguments);
-
-        // Generate example values based on argument names
-        const generateExampleValue = (argName) => {
-          switch (argName) {
-            case "name":
-            case "componentName":
-              return command.includes("plugin") ? "MyPlugin" : "MyComponent";
-            case "modelName":
-              return "my-model";
-            case "workspaceName":
-              return "my-workspace";
-            case "project":
-            case "componentProject":
-            case "modelProject":
-              return "my-ui-lib";
-            case "registrationProject":
-              return "my-lib";
-            case "companionParent":
-              return "parent-model";
-            case "extensionPoint":
-              return "utility";
-            case "group":
-              return "appearance";
-            case "locale":
-              return "en";
-            case "container":
-            case "singleton":
-            case "parentAware":
-            case "dataServices":
-              return true;
-            case "dryRun":
-              return true;
-            default:
-              return `my-${argName}`;
-          }
-        };
-
-        // Create basic example with most important arguments
-        const basicArgs = [];
-        const booleanArgs = [
-          "container",
-          "singleton",
-          "parentAware",
-          "dataServices",
-          "dryRun",
-        ];
-
-        // Pick the most relevant arguments for each generator type
-        const getRelevantArgs = (args, command) => {
-          const relevantArgs = [];
-
-          // Always prefer name-type arguments first
-          const nameArgs = [
-            "name",
-            "componentName",
-            "modelName",
-            "workspaceName",
-          ].filter((arg) => args.includes(arg));
-          if (nameArgs.length > 0) {
-            relevantArgs.push(nameArgs[0]); // Take the first name argument
-          }
-
-          // Then add project-type arguments
-          const projectArgs = [
-            "project",
-            "componentProject",
-            "modelProject",
-            "registrationProject",
-          ].filter((arg) => args.includes(arg));
-          if (projectArgs.length > 0) {
-            relevantArgs.push(projectArgs[0]); // Take the first project argument
-          }
-
-          // Add other specific arguments
-          const otherArgs = args.filter(
-            (arg) =>
-              !nameArgs.includes(arg) &&
-              !projectArgs.includes(arg) &&
-              !booleanArgs.includes(arg) &&
-              arg !== "interactive"
-          );
-
-          // Add up to 2 more relevant arguments
-          relevantArgs.push(...otherArgs.slice(0, 2));
-
-          return relevantArgs;
-        };
-
-        const relevantArgs = getRelevantArgs(args, command);
-
-        relevantArgs.forEach((argName) => {
-          const value = generateExampleValue(argName);
-          basicArgs.push(`--${argName} ${value}`);
-        });
-
-        // Create advanced example with boolean flags
-        const advancedBooleanArgs = [];
-        booleanArgs.forEach((argName) => {
-          if (args.includes(argName)) {
-            advancedBooleanArgs.push(`--${argName}`);
-          }
-        });
-
-        // Show basic example
-        if (basicArgs.length > 0) {
-          console.log(`  kosui ${command} ${basicArgs.join(" ")}`);
-        }
-
-        // Show advanced example with boolean flags if any exist
-        if (basicArgs.length > 0 && advancedBooleanArgs.length > 0) {
-          console.log(
-            `  kosui ${command} ${basicArgs
-              .slice(0, 2)
-              .join(" ")} ${advancedBooleanArgs.join(" ")}`
-          );
-        }
-
-        // If no basic args, show a minimal example
-        if (basicArgs.length === 0) {
-          console.log(`  kosui ${command} [options]`);
-        }
-      }
-
-      console.log(`  kosui ${command} --interactive  # Force interactive mode`);
-      console.log(
-        `  kosui ${command} -i             # Force interactive mode (short form)`
-      );
+      displayGeneratorHelp(command, meta, generator);
       return;
     }
 

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",
+  },
+};