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

package/src/lib/utils/cli-help-utils.mjs

@@ -0,0 +1,261 @@
+/**
+ * Utility functions for CLI help generation
+ *
+ * Provides intelligent help generation for KOS CLI commands including:
+ * - Example value generation based on argument types and names
+ * - Relevant argument filtering for concise examples
+ * - Command-line example generation with proper formatting
+ * - Named argument documentation display
+ *
+ * @module cli-help-utils
+ */
+
+/**
+ * Generate example values for command-line arguments based on argument names.
+ *
+ * Uses heuristics to determine appropriate example values based on the argument
+ * name and command context. Provides realistic examples for common patterns like
+ * names, projects, and boolean flags.
+ *
+ * @param {string} argName - The argument name (e.g., 'name', 'project', 'singleton')
+ * @param {string} command - The command name for context (e.g., 'model', 'api:generate')
+ * @returns {string|boolean} Example value appropriate for the argument type
+ *
+ * @example
+ * generateExampleValue('name', 'model') // Returns 'MyComponent'
+ * generateExampleValue('singleton', 'model') // Returns true
+ * generateExampleValue('project', 'api:generate') // Returns 'my-ui-lib'
+ */
+export function generateExampleValue(argName, command) {
+  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}`;
+  }
+}
+
+/**
+ * Filter and prioritize arguments for concise help examples.
+ *
+ * Selects the most relevant arguments to display in help examples by prioritizing:
+ * 1. Name-type arguments (name, componentName, modelName, workspaceName)
+ * 2. Project-type arguments (project, componentProject, modelProject)
+ * 3. Other non-boolean arguments (up to 2 additional)
+ *
+ * Boolean flags are excluded from this list and handled separately.
+ *
+ * @param {string[]} args - All available argument names from the generator
+ * @param {string} command - The command name for context
+ * @returns {string[]} Filtered list of most relevant arguments to show (typically 2-4 items)
+ *
+ * @example
+ * getRelevantArgs(['name', 'project', 'singleton', 'dryRun'], 'model')
+ * // Returns ['name', 'project']
+ */
+export function getRelevantArgs(args, command) {
+  const relevantArgs = [];
+
+  const booleanArgs = [
+    "container",
+    "singleton",
+    "parentAware",
+    "dataServices",
+    "dryRun",
+  ];
+
+  // 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;
+}
+
+/**
+ * Generate command-line examples for a generator with proper formatting.
+ *
+ * Creates multiple example commands showing:
+ * - Basic usage with most relevant arguments
+ * - Advanced usage with boolean flags
+ * - Interactive mode invocation (both long and short form)
+ *
+ * Examples are formatted ready for terminal display with proper indentation.
+ *
+ * @param {string} command - The command name (e.g., 'model', 'api:generate')
+ * @param {Object} namedArguments - Mapping of CLI argument names to prompt names
+ * @returns {string[]} Array of formatted example command strings with leading spaces
+ *
+ * @example
+ * generateCommandExamples('api:generate', { project: 'project', host: 'host' })
+ * // Returns:
+ * // [
+ * //   '  kosui api:generate --project my-ui-lib --host http://localhost',
+ * //   '  kosui api:generate --interactive  # Force interactive mode',
+ * //   '  kosui api:generate -i             # Force interactive mode (short form)'
+ * // ]
+ */
+export function generateCommandExamples(command, namedArguments) {
+  if (!namedArguments) {
+    return [`  kosui ${command} [options]`];
+  }
+
+  const args = Object.keys(namedArguments);
+  const examples = [];
+
+  const booleanArgs = [
+    "container",
+    "singleton",
+    "parentAware",
+    "dataServices",
+    "dryRun",
+  ];
+
+  const relevantArgs = getRelevantArgs(args, command);
+
+  // Build basic example with most important arguments
+  const basicArgs = [];
+  relevantArgs.forEach((argName) => {
+    const value = generateExampleValue(argName, command);
+    basicArgs.push(`--${argName} ${value}`);
+  });
+
+  if (basicArgs.length > 0) {
+    examples.push(`  kosui ${command} ${basicArgs.join(" ")}`);
+  }
+
+  // Create advanced example with boolean flags
+  const advancedBooleanArgs = [];
+  booleanArgs.forEach((argName) => {
+    if (args.includes(argName)) {
+      advancedBooleanArgs.push(`--${argName}`);
+    }
+  });
+
+  // Show advanced example with boolean flags if any exist
+  if (basicArgs.length > 0 && advancedBooleanArgs.length > 0) {
+    examples.push(
+      `  kosui ${command} ${basicArgs
+        .slice(0, 2)
+        .join(" ")} ${advancedBooleanArgs.join(" ")}`
+    );
+  }
+
+  // If no basic args, show a minimal example
+  if (basicArgs.length === 0) {
+    examples.push(`  kosui ${command} [options]`);
+  }
+
+  // Always show interactive mode example
+  examples.push(`  kosui ${command} --interactive  # Force interactive mode`);
+  examples.push(
+    `  kosui ${command} -i             # Force interactive mode (short form)`
+  );
+
+  return examples;
+}
+
+/**
+ * Display the named arguments help section to the console.
+ *
+ * Outputs a formatted table showing the mapping between CLI argument names
+ * and their corresponding prompt names in the generator schema. This helps
+ * users understand which CLI arguments map to which interactive prompts.
+ *
+ * @param {Object} namedArguments - Mapping of CLI argument names to prompt names
+ *                                  (e.g., { 'project': 'project', 'host': 'host' })
+ *
+ * @example
+ * displayNamedArguments({ project: 'project', host: 'host' })
+ * // Outputs:
+ * // Named Arguments:
+ * //   --project    Maps to prompt: project
+ * //   --host       Maps to prompt: host
+ */
+export function displayNamedArguments(namedArguments) {
+  if (!namedArguments) return;
+
+  console.log("\nNamed Arguments:");
+  Object.entries(namedArguments).forEach(([cliArg, promptName]) => {
+    console.log(`  --${cliArg}    Maps to prompt: ${promptName}`);
+  });
+}
+
+/**
+ * Display the examples help section to the console.
+ *
+ * Outputs formatted command-line examples showing various ways to invoke the
+ * command, including basic usage, advanced usage with boolean flags, and
+ * interactive mode shortcuts.
+ *
+ * @param {string} command - The command name (e.g., 'model', 'api:generate')
+ * @param {Object} namedArguments - Mapping of CLI argument names to prompt names
+ *
+ * @example
+ * displayExamples('api:generate', { project: 'project', host: 'host' })
+ * // Outputs:
+ * // Examples:
+ * //   kosui api:generate --project my-ui-lib --host http://localhost
+ * //   kosui api:generate --interactive  # Force interactive mode
+ * //   kosui api:generate -i             # Force interactive mode (short form)
+ */
+export function displayExamples(command, namedArguments) {
+  console.log("\nExamples:");
+  const examples = generateCommandExamples(command, namedArguments);
+  examples.forEach((example) => console.log(example));
+}