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

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

@@ -1,182 +0,0 @@
-// generators/version/index.mjs
-import { execSync } from "child_process";
-import { existsSync, readFileSync } from "fs";
-import path from "path";
-import { detectWorkspace } from "../../utils/nx-context.mjs";
-
-export const metadata = {
-  key: "version",
-  name: "Display CLI and SDK Version Information",
-  namedArguments: { interactive: "interactive" },
-};
-
-function getPackageVersion(packagePath) {
-  try {
-    const packageJsonPath = path.join(packagePath, "package.json");
-    if (existsSync(packageJsonPath)) {
-      const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
-      return packageJson.version || "unknown";
-    }
-  } catch (error) {
-    // Package not found
-  }
-  return null;
-}
-
-function findWorkspaceRoot(startDir = process.cwd()) {
-  let dir = startDir;
-  while (dir !== path.dirname(dir)) {
-    if (existsSync(path.join(dir, "nx.json"))) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-  return null;
-}
-
-function getCliVersion() {
-  let version = null;
-
-  // Option 1: Check workspace root package.json for installed CLI
-  const workspaceRoot = findWorkspaceRoot();
-  if (workspaceRoot) {
-    try {
-      const output = execSync(
-        "npm list @kosdev-code/kos-ui-cli --depth=0 --json",
-        {
-          cwd: workspaceRoot,
-          encoding: "utf-8",
-          stdio: ["pipe", "pipe", "ignore"],
-        }
-      );
-      const data = JSON.parse(output);
-      version = data?.dependencies?.["@kosdev-code/kos-ui-cli"]?.version;
-    } catch (error) {
-      // Not in workspace dependencies
-    }
-  }
-
-  // Option 2: Check global installation
-  if (!version) {
-    try {
-      const output = execSync(
-        "npm list -g @kosdev-code/kos-ui-cli --depth=0 --json",
-        {
-          encoding: "utf-8",
-          stdio: ["pipe", "pipe", "ignore"],
-        }
-      );
-      const data = JSON.parse(output);
-      version = data?.dependencies?.["@kosdev-code/kos-ui-cli"]?.version;
-    } catch (error) {
-      // Not installed globally
-    }
-  }
-
-  return version || "unknown";
-}
-
-export default async function (plop) {
-  plop.setActionType("showVersions", async function () {
-    console.log("[kos-cli] Discovering version information...\n");
-
-    const isWorkspace = await detectWorkspace();
-    const workspaceRoot = findWorkspaceRoot();
-
-    const versions = {};
-
-    // Get CLI version
-    versions.cli = getCliVersion();
-
-    if (isWorkspace && workspaceRoot) {
-      // Get SDK versions from workspace dependencies
-      const sdkPackages = {
-        sdk: ["@kosdev-code/kos-ui-sdk", "@kosdev-code/kos-dispense-sdk"],
-        ddk: [
-          "@kosdev-code/kos-ddk-components",
-          "@kosdev-code/kos-ddk-model-components",
-        ],
-      };
-
-      for (const [type, packages] of Object.entries(sdkPackages)) {
-        for (const pkgName of packages) {
-          try {
-            const output = execSync(`npm list ${pkgName} --depth=0 --json`, {
-              cwd: workspaceRoot,
-              encoding: "utf-8",
-              stdio: ["pipe", "pipe", "ignore"],
-            });
-            const data = JSON.parse(output);
-            const version = data?.dependencies?.[pkgName]?.version;
-            if (version) {
-              // Store with short name (without @kosdev-code/ prefix)
-              const shortName = pkgName.replace("@kosdev-code/", "");
-              versions[shortName] = version;
-            }
-          } catch (error) {
-            // Package not installed in workspace
-          }
-        }
-      }
-    }
-
-    // Display results
-    console.log("Version Information:");
-    console.log("===================\n");
-
-    if (versions.cli) {
-      console.log(`kos-ui-cli: ${versions.cli}`);
-    } else {
-      console.log("kos-ui-cli: unknown");
-    }
-
-    if (isWorkspace) {
-      console.log("");
-      console.log("SDK Packages:");
-      console.log("-------------");
-
-      if (versions["kos-ui-sdk"]) {
-        console.log(`kos-ui-sdk: ${versions["kos-ui-sdk"]}`);
-      }
-
-      if (versions["kos-dispense-sdk"]) {
-        console.log(`kos-dispense-sdk: ${versions["kos-dispense-sdk"]}`);
-      }
-
-      console.log("");
-      console.log("DDK Packages:");
-      console.log("-------------");
-
-      if (versions["kos-ddk-components"]) {
-        console.log(`kos-ddk-components: ${versions["kos-ddk-components"]}`);
-      }
-
-      if (versions["kos-ddk-model-components"]) {
-        console.log(
-          `kos-ddk-model-components: ${versions["kos-ddk-model-components"]}`
-        );
-      }
-
-      if (!versions["kos-ui-sdk"] && !versions["kos-dispense-sdk"]) {
-        console.log("(No SDK packages found in workspace)");
-      }
-
-      if (
-        !versions["kos-ddk-components"] &&
-        !versions["kos-ddk-model-components"]
-      ) {
-        console.log("(No DDK packages found in workspace)");
-      }
-    } else {
-      console.log("\n(Not in workspace - SDK versions unavailable)");
-    }
-
-    return "\n";
-  });
-
-  plop.setGenerator("version", {
-    description: "Display CLI and SDK version information",
-    prompts: [],
-    actions: () => [{ type: "showVersions" }],
-  });
-}

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

@@ -1,84 +0,0 @@
-/**
- * CLI help display utilities
- *
- * High-level help display functions for the KOS CLI. Coordinates the display
- * of generator-specific help and general CLI help using utilities from
- * cli-help-utils.mjs.
- *
- * @module cli-help-display
- */
-import { displayExamples, displayNamedArguments } from "./cli-help-utils.mjs";
-
-/**
- * Display comprehensive help information for a specific generator.
- *
- * Shows the generator's name, description, named arguments mapping, and
- * usage examples. This provides users with all the information needed to
- * use a specific CLI command effectively.
- *
- * @param {string} command - The command name (e.g., 'model', 'api:generate')
- * @param {Object} meta - Generator metadata from the generator's export
- * @param {string} meta.name - Display name for the generator
- * @param {string} meta.description - Brief description of what the generator does
- * @param {Object} meta.namedArguments - Mapping of CLI args to prompt names
- * @param {Object} [generator=null] - Optional plop generator object (fallback for metadata)
- *
- * @example
- * displayGeneratorHelp('api:generate', {
- *   name: 'Generate OpenAPI service types',
- *   description: 'Generate typed service helpers from OpenAPI specifications',
- *   namedArguments: { project: 'project', host: 'host' }
- * })
- */
-export function displayGeneratorHelp(command, meta, generator = null) {
-  console.log(`--- ${meta?.name || command} Help ---`);
-  console.log(
-    meta?.description || generator?.description || "No description available"
-  );
-
-  displayNamedArguments(meta?.namedArguments);
-  displayExamples(command, meta?.namedArguments);
-}
-
-/**
- * Display general CLI help showing all available generators and global options.
- *
- * Outputs a comprehensive overview of the KOS CLI including:
- * - List of all available generators with descriptions
- * - General usage pattern
- * - Global options that apply to all commands
- * - Help invocation instructions
- *
- * This is displayed when users run `kosui --help` or `kosui` with no command.
- *
- * @param {Object} plop - The plop instance containing registered generators
- *
- * @example
- * displayGeneralHelp(plopInstance)
- * // Outputs:
- * // --- KOS CLI Help ---
- * //
- * // Available Generators:
- * // - model: Generate KOS models
- * // - api:generate: Generate OpenAPI service types
- * // ...
- */
-export function displayGeneralHelp(plop) {
-  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");
-}

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

@@ -1,261 +0,0 @@
-/**
- * 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

@@ -1,94 +0,0 @@
-/**
- * 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);
-}