@kosdev-code/kos-ui-cli 2.0.30 → 2.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-ui-cli",
-  "version": "2.0.30",
+  "version": "2.0.31",
   "bin": {
     "kosui": "./src/lib/cli.mjs"
   },
@@ -20,7 +20,7 @@
   "main": "./src/index.js",
   "kos": {
     "build": {
-      "gitHash": "0f92875bc028bb7f4c46e8a12c3be28c1ca3c2ca"
+      "gitHash": "d7b8c63a9bfe61bb6177f4e7628bbb17e3696c2b"
     }
   },
   "publishConfig": {

package/src/lib/cli.mjs

@@ -37,9 +37,22 @@ async function launch() {
 
   if (!command || command === "help") {
     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(
+      "  --interactive, -i   Force interactive mode (ignore provided arguments)"
+    );
+    console.log("  --help          Show this help");
+
     return;
   }
 
@@ -49,13 +62,245 @@ async function launch() {
     console.error(`[kos-cli] Generator "${command}" not found.`);
     process.exit(1);
   }
+
   const meta = await getGeneratorMetadata(command);
+
+  // Show generator-specific help if requested
+  if (parsedArgs.help) {
+    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)`);
+    return;
+  }
+
   if (showBanner) {
     console.log(`--- Running KOS Generator: ${meta?.name || command} ---`);
   }
 
   try {
-    const answers = await generator.runPrompts();
+    // Extract positional arguments for prompt bypass
+    const positionalArgs = parsedArgs._.slice(1); // Remove command from args
+
+    // Get named arguments mapping from generator metadata
+    const namedArgumentsMap = meta?.namedArguments || {};
+
+    // Convert CLI args to answer format using generator's mapping
+    const providedAnswers = {};
+    Object.entries(namedArgumentsMap).forEach(([cliArg, promptName]) => {
+      // Skip 'interactive' - it's handled as a special CLI flag, not a prompt argument
+      if (cliArg === "interactive") {
+        return;
+      }
+
+      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;
+      }
+    });
+
+    // Also handle positional arguments
+    const prompts = generator.prompts || [];
+    positionalArgs.forEach((arg, index) => {
+      if (prompts[index] && !prompts[index].when) {
+        // Only non-conditional prompts
+        const promptName = prompts[index].name;
+        if (providedAnswers[promptName] === undefined) {
+          let value = arg;
+
+          // 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;
+        }
+      }
+    });
+
+    // Check if we have ANY provided answers
+    const hasAnyAnswers = Object.keys(providedAnswers).length > 0;
+
+    let answers;
+
+    // Check if user wants to force interactive mode
+    const forceInteractive = parsedArgs.interactive || parsedArgs.i;
+
+    if (hasAnyAnswers && !forceInteractive) {
+      // Create bypass array for all prompts
+      const bypassArgs = [];
+
+      // Fill bypass array with provided values or defaults
+      for (const prompt of prompts) {
+        if (prompt.when) {
+          // Skip conditional prompts - they can't be bypassed
+          continue;
+        }
+
+        const providedValue = providedAnswers[prompt.name];
+        if (providedValue !== undefined) {
+          bypassArgs.push(providedValue);
+        } else {
+          // Use default value or skip with "_"
+          bypassArgs.push(prompt.default !== undefined ? prompt.default : "_");
+        }
+      }
+
+      // Only bypass if we have all non-conditional prompts
+      const nonConditionalPrompts = prompts.filter((p) => !p.when);
+      if (bypassArgs.length === nonConditionalPrompts.length) {
+        // We can bypass all non-conditional prompts
+        answers = await generator.runPrompts(bypassArgs);
+
+        // Add any conditional prompt values that were provided
+        Object.assign(answers, providedAnswers);
+      } else {
+        // Fall back to interactive mode
+        console.log(
+          "Note: Running interactive mode. Your provided arguments will be applied automatically."
+        );
+        answers = await generator.runPrompts();
+        Object.assign(answers, providedAnswers);
+      }
+    } else {
+      // Run prompts interactively
+      if (forceInteractive) {
+        console.log(
+          "Note: Running in interactive mode. All prompts will be shown."
+        );
+
+        // In interactive mode, ignore provided arguments and run all prompts
+        answers = await generator.runPrompts();
+      } else {
+        answers = await generator.runPrompts();
+      }
+    }
+
     const results = await generator.runActions(answers);
 
     console.log("[kos-cli] Generator completed successfully!");

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

@@ -7,6 +7,12 @@ import { required } from "../../utils/validators.mjs";
 export const metadata = {
   key: "component",
   name: "KOS React Component",
+  namedArguments: {
+    name: "componentName",
+    componentName: "componentName",
+    project: "componentProject",
+    componentProject: "componentProject"
+  }
 };
 
 export default async function (plop) {

package/src/lib/generators/i18n/namespace.mjs

@@ -8,6 +8,11 @@ import { required } from "../../utils/validators.mjs";
 export const metadata = {
   key: "i18n:namespace",
   name: "KOS i18n Project Namespace",
+  namedArguments: {
+    name: "name",
+    locale: "locale",
+    project: "project",
+  },
 };
 
 export default async function (plop) {

package/src/lib/generators/model/companion.mjs

@@ -12,6 +12,19 @@ import { required } from "../../utils/validators.mjs";
 export const metadata = {
   key: "model:companion",
   name: "KOS Companion Model",
+  namedArguments: {
+    name: "modelName",
+    modelName: "modelName",
+    project: "modelProject",
+    modelProject: "modelProject",
+    companionParent: "companionParent",
+    container: "container",
+    parentAware: "parentAware",
+    singleton: "singleton",
+    dataServices: "dataServices",
+    dryRun: "dryRun",
+    interactive: "interactive"
+  }
 };
 
 export default async function (plop) {

package/src/lib/generators/model/container.mjs

@@ -11,6 +11,16 @@ import { DEFAULT_PROMPTS, MODEL_PROMPTS } from "../../utils/prompts.mjs";
 export const metadata = {
   key: "container",
   name: "KOS Container Model",
+  namedArguments: {
+    modelName: "modelName",
+    registrationProject: "registrationProject",
+    container: "container",
+    parentAware: "parentAware",
+    singleton: "singleton",
+    dataServices: "dataServices",
+    dryRun: "dryRun",
+    interactive: "interactive",
+  },
 };
 
 export default async function (plop) {

package/src/lib/generators/model/context.mjs

@@ -5,6 +5,11 @@ import { getAllModels, getAllProjects } from "../../utils/nx-context.mjs";
 export const metadata = {
   key: "context",
   name: "KOS Model React Context",
+  namedArguments: {
+    modelName: "modelName",
+    componentProject: "componentProject",
+    project: "componentProject",
+  },
 };
 
 export default async function (plop) {

package/src/lib/generators/model/hook.mjs

@@ -5,6 +5,11 @@ import { getAllModels, getAllProjects } from "../../utils/nx-context.mjs";
 export const metadata = {
   key: "hook",
   name: "KOS Model React Hook",
+  namedArguments: {
+    modelName: "modelName",
+    componentProject: "componentProject",
+    project: "componentProject"
+  }
 };
 
 export default async function (plop) {

package/src/lib/generators/model/model.mjs

@@ -13,6 +13,18 @@ export const metadata = {
   key: "model",
   name: "KOS Model",
   invalidateCache: true,
+  namedArguments: {
+    name: "modelName",
+    modelName: "modelName",
+    project: "modelProject", 
+    modelProject: "modelProject",
+    container: "container",
+    parentAware: "parentAware",
+    singleton: "singleton",
+    dataServices: "dataServices",
+    dryRun: "dryRun",
+    interactive: "interactive"
+  }
 };
 
 export default async function (plop) {

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

@@ -4,13 +4,78 @@ import { execute } from "../../utils/exec.mjs";
 import { getAllProjects } from "../../utils/nx-context.mjs";
 import { required } from "../../utils/validators.mjs";
 export const metadata = [
-  { key: "pluginComponent", name: "KOS UI Plugin Component" },
-  { key: "plugin:cui", name: "KOS UI Plugin CUI Configuration" },
-  { key: "plugin:setup", name: "KOS UI Plugin Setup Step" },
-  { key: "plugin:utility", name: "KOS UI Plugin Utility" },
-  { key: "plugin:setting", name: "KOS UI Plugin Setting" },
-  { key: "plugin:nav", name: "KOS UI Plugin Navigation View" },
-  { key: "plugin:cp", name: "KOS UI Plugin Control Pour" },
+  { 
+    key: "pluginComponent", 
+    name: "KOS UI Plugin Component",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject",
+      extensionPoint: "extensionPoint"
+    }
+  },
+  { 
+    key: "plugin:cui", 
+    name: "KOS UI Plugin CUI Configuration",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject"
+    }
+  },
+  { 
+    key: "plugin:setup", 
+    name: "KOS UI Plugin Setup Step",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject"
+    }
+  },
+  { 
+    key: "plugin:utility", 
+    name: "KOS UI Plugin Utility",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject"
+    }
+  },
+  { 
+    key: "plugin:setting", 
+    name: "KOS UI Plugin Setting",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject",
+      group: "group"
+    }
+  },
+  { 
+    key: "plugin:nav", 
+    name: "KOS UI Plugin Navigation View",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject"
+    }
+  },
+  { 
+    key: "plugin:cp", 
+    name: "KOS UI Plugin Control Pour",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject"
+    }
+  },
 ];
 
 export default async function (plop) {

package/src/lib/generators/project/app.mjs

@@ -7,6 +7,7 @@ export const metadata = {
   key: "project",
   name: "KOS UI App Project",
   invalidateCache: true,
+  namedArguments: { name: "name" },
 };
 export default async function (plop) {
   plop.setActionType("createUiProject", async function (answers) {

package/src/lib/generators/project/i18n.mjs

@@ -6,6 +6,7 @@ export const metadata = {
   key: "i18n",
   name: "KOS Localization Project",
   invalidateCache: true,
+  namedArguments: { name: "name" },
 };
 export default async function (plop) {
   plop.setActionType("createI18nProject", async function (answers) {

package/src/lib/generators/project/plugin.mjs

@@ -6,6 +6,7 @@ export const metadata = {
   key: "plugin",
   name: "KOS Plugin Project",
   invalidateCache: true,
+  namedArguments: { name: "name" },
 };
 export default async function (plop) {
   plop.setActionType("createPluginProject", async function (answers) {

package/src/lib/generators/project/splash.mjs

@@ -7,6 +7,7 @@ export const metadata = {
   key: "project:splash",
   name: "KOS Splash Screen Project",
   invalidateCache: true,
+  namedArguments: { name: "name" },
 };
 export default async function (plop) {
   plop.setActionType("createSplashProject", async function (answers) {

package/src/lib/generators/project/theme.mjs

@@ -6,6 +6,7 @@ export const metadata = {
   key: "theme",
   name: "KOS Theme Project",
   invalidateCache: true,
+  namedArguments: { name: "name" },
 };
 export default async function (plop) {
   plop.setActionType("createThemeProject", async function (answers) {

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

@@ -5,6 +5,10 @@ import { required } from "../../utils/validators.mjs";
 export const metadata = {
   key: "workspace",
   name: "Create a new KOS UI Workspace",
+  namedArguments: {
+    name: "workspaceName",
+    workspaceName: "workspaceName"
+  }
 };
 export default async function (plop) {
   plop.setActionType("createWorkspace", async function (answers) {

package/src/lib/utils/prompts.mjs

@@ -29,7 +29,6 @@ export const MODEL_PROMPTS = [
     name: "parentAware",
     message: "Aware of parent container?",
     default: false,
-    when: (answers) => !!answers.container,
   },
   {
     type: "confirm",