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

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));
+}

package/src/lib/utils/command-builder.mjs

@@ -0,0 +1,94 @@
+/**
+ * Builds a non-interactive command string from interactive session answers
+ * This helps users understand how to run the same command without prompts
+ */
+
+/**
+ * Converts interactive prompt answers back to CLI command arguments
+ * @param {string} command - The generator command name
+ * @param {Object} answers - The answers collected from prompts
+ * @param {Object} meta - Generator metadata including namedArguments mapping
+ * @returns {string|null} The equivalent CLI command string, or null if cannot be built
+ */
+export function buildNonInteractiveCommand(command, answers, meta) {
+  if (!meta?.namedArguments) {
+    return null;
+  }
+
+  const args = [`kosui ${command}`];
+  const reverseMap = {};
+
+  // Create reverse mapping from prompt names to CLI arguments
+  Object.entries(meta.namedArguments).forEach(([cliArg, promptName]) => {
+    // Skip special flags that don't map to prompts
+    if (cliArg !== "interactive" && cliArg !== "dryRun") {
+      reverseMap[promptName] = cliArg;
+    }
+  });
+
+  // Build command arguments from answers
+  Object.entries(answers).forEach(([promptName, value]) => {
+    const cliArg = reverseMap[promptName];
+    if (cliArg && value !== undefined && value !== null && value !== "") {
+      args.push(formatArgument(cliArg, value));
+    }
+  });
+
+  // Add dryRun if it was provided
+  if (answers.dryRun) {
+    args.push("--dryRun");
+  }
+
+  return args.join(" ");
+}
+
+/**
+ * Formats a single CLI argument based on its value type
+ * @param {string} argName - The CLI argument name
+ * @param {any} value - The value for the argument
+ * @returns {string} The formatted CLI argument string
+ */
+function formatArgument(argName, value) {
+  // Handle boolean values
+  if (typeof value === "boolean") {
+    if (value) {
+      return `--${argName}`;
+    } else {
+      // For false booleans, explicitly set to false
+      // This ensures the command can be replicated exactly
+      return `--${argName}=false`;
+    }
+  }
+
+  // Handle string/number values
+  const stringValue = String(value);
+
+  // Check if value needs escaping
+  if (needsEscaping(stringValue)) {
+    // Use double quotes and escape internal quotes
+    return `--${argName}="${stringValue.replace(/"/g, '\\"')}"`;
+  }
+
+  return `--${argName}=${stringValue}`;
+}
+
+/**
+ * Determines if a string value needs shell escaping
+ * @param {string} value - The value to check
+ * @returns {boolean} True if the value needs escaping
+ */
+function needsEscaping(value) {
+  // Check for characters that need escaping in shell
+  return /[\s'"$`\\!]/.test(value);
+}
+
+/**
+ * Determines if the CLI is running in interactive mode
+ * @param {Object} parsedArgs - Parsed command line arguments
+ * @param {boolean} hasAnyAnswers - Whether any answers were provided via CLI
+ * @returns {boolean} True if running in interactive mode
+ */
+export function isRunningInteractively(parsedArgs, hasAnyAnswers) {
+  const forceInteractive = parsedArgs.interactive || parsedArgs.i;
+  return forceInteractive || (!hasAnyAnswers && !parsedArgs.help);
+}

package/src/lib/utils/dev-config.mjs

@@ -0,0 +1,150 @@
+// utils/dev-config.mjs
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+
+/**
+ * Read the development configuration from root .kos.json
+ *
+ * @returns {Object|null} Development config or null if not found
+ */
+export function getDevConfig() {
+  const workspaceRoot = process.cwd();
+  const kosJsonPath = path.join(workspaceRoot, '.kos.json');
+
+  if (!existsSync(kosJsonPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(kosJsonPath, 'utf-8');
+    const config = JSON.parse(content);
+
+    if (config.type !== 'root') {
+      return null;
+    }
+
+    if (!config.development || !config.development.hosts) {
+      return null;
+    }
+
+    return config.development;
+  } catch (error) {
+    console.error(`[kos-cli] Error reading .kos.json: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Find a host configuration by name
+ *
+ * @param {string} hostName - Name of the host to find
+ * @returns {Object|null} Host config or null if not found
+ */
+export function getHost(hostName) {
+  const devConfig = getDevConfig();
+
+  if (!devConfig) {
+    return null;
+  }
+
+  return devConfig.hosts.find(h => h.name === hostName) || null;
+}
+
+/**
+ * Get all available hosts
+ *
+ * @returns {Array} Array of host configurations
+ */
+export function getAllHosts() {
+  const devConfig = getDevConfig();
+
+  if (!devConfig) {
+    return [];
+  }
+
+  return devConfig.hosts || [];
+}
+
+/**
+ * Filter plugins based on options
+ *
+ * @param {Array} hostPlugins - Array of plugin configs from host
+ * @param {Object} options - Filter options
+ * @param {Array} options.plugins - Specific plugin aliases to include
+ * @param {Array} options.disable - Plugin aliases to exclude
+ * @returns {Array} Filtered array of plugin configurations
+ */
+export function filterPlugins(hostPlugins, options = {}) {
+  let plugins = hostPlugins.filter(p => p.enabled);
+
+  // If specific plugins requested, override enabled flag
+  if (options.plugins && options.plugins.length > 0) {
+    plugins = hostPlugins.filter(p => options.plugins.includes(p.alias));
+  }
+
+  // Apply disable list
+  if (options.disable && options.disable.length > 0) {
+    plugins = plugins.filter(p => !options.disable.includes(p.alias));
+  }
+
+  return plugins;
+}
+
+/**
+ * Check if a project exists in the workspace
+ *
+ * @param {string} projectName - Name of the project
+ * @returns {boolean} True if project exists
+ */
+export function checkProjectExists(projectName) {
+  const workspaceRoot = process.cwd();
+
+  // Check common project locations
+  const appPath = path.join(workspaceRoot, 'apps', projectName, 'project.json');
+  const libPath = path.join(workspaceRoot, 'libs', projectName, 'project.json');
+  const pluginPath = path.join(workspaceRoot, 'plugins', projectName, 'project.json');
+  const packagesPath = path.join(workspaceRoot, 'packages', projectName, 'project.json');
+
+  return existsSync(appPath) ||
+         existsSync(libPath) ||
+         existsSync(pluginPath) ||
+         existsSync(packagesPath);
+}
+
+/**
+ * Validate development configuration
+ *
+ * @returns {Object} Validation result with isValid and errors
+ */
+export function validateDevConfig() {
+  const devConfig = getDevConfig();
+  const errors = [];
+
+  if (!devConfig) {
+    errors.push('.kos.json missing or does not contain development configuration');
+    return { isValid: false, errors };
+  }
+
+  if (!Array.isArray(devConfig.hosts) || devConfig.hosts.length === 0) {
+    errors.push('No hosts defined in development configuration');
+    return { isValid: false, errors };
+  }
+
+  // Validate each host
+  devConfig.hosts.forEach((host, idx) => {
+    if (!host.name) {
+      errors.push(`Host at index ${idx} missing required 'name' field`);
+    }
+    if (!host.project) {
+      errors.push(`Host at index ${idx} missing required 'project' field`);
+    }
+    if (!host.port) {
+      errors.push(`Host at index ${idx} missing required 'port' field`);
+    }
+    if (!Array.isArray(host.plugins)) {
+      errors.push(`Host '${host.name}' missing 'plugins' array`);
+    }
+  });
+
+  return { isValid: errors.length === 0, errors };
+}