@kosdev-code/kos-ui-cli 0.1.0-dev.5162 → 0.1.0-dev.5164

package/src/lib/generators/api/lib/generate-api.mjs

@@ -1,9 +1,7 @@
-import devkit from "@nx/devkit";
-import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
 import openapiTS, { astToString } from "openapi-typescript";
 import { join } from "path";
-
-const { readCachedProjectGraph } = devkit;
+import { getProjectDetails } from "../../../utils/nx-context.mjs";
 
 /**
  * Generate OpenAPI service types for a project
@@ -28,30 +26,39 @@ export async function generateApiTypes(options) {
     serviceExportAliases: customAliases,
     defaultVersion: customDefaultVersion,
     appVersions: customAppVersions,
+    allAppsVersion,
     excludeCore = false,
   } = options;
 
-  let graph, project, host, src, outputPath, serviceExportAliases, defaultVersion, appVersions;
+  let projectConfig, host, src, outputPath, serviceExportAliases, defaultVersion, appVersions;
 
   try {
-    graph = readCachedProjectGraph();
-    project = graph.nodes[projectName];
+    // Read project configuration using existing CLI utility
+    projectConfig = await getProjectDetails(projectName);
 
     // Merge CLI options with project.json config (CLI takes precedence)
-    host = customHost || project.data.targets.api?.options?.host || "http://127.0.0.1:8081";
-    outputPath = customOutputPath || project.data.targets.api?.options?.outputPath;
-    serviceExportAliases = customAliases || project.data.targets.api?.options?.serviceExportAliases || {};
-    defaultVersion = customDefaultVersion || project.data.targets.api?.options?.defaultVersion;
-    appVersions = customAppVersions || project.data.targets.api?.options?.appVersions || {};
-    src = project.data.sourceRoot || project.data.root;
+    host = customHost || projectConfig.targets?.api?.options?.host || "http://127.0.0.1:8081";
+    outputPath = customOutputPath || projectConfig.targets?.api?.options?.outputPath;
+    serviceExportAliases = {
+      ...(projectConfig.targets?.api?.options?.serviceExportAliases || {}),
+      ...(customAliases || {})
+    };
+    defaultVersion = customDefaultVersion || projectConfig.targets?.api?.options?.defaultVersion;
+    appVersions = {
+      ...(projectConfig.targets?.api?.options?.appVersions || {}),
+      ...(customAppVersions || {})
+    };
+    src = projectConfig.sourceRoot || projectConfig.root;
   } catch (error) {
-    // Fallback if project graph reading fails
-    console.warn("Warning: Could not read project graph, using defaults");
+    // Fallback if project reading fails
+    console.warn("Warning: Could not read project configuration, using defaults");
+    console.warn(`Error: ${error.message}`);
     host = customHost || "http://127.0.0.1:8081";
     src = `libs/${projectName}/src`;
     serviceExportAliases = customAliases || {};
     defaultVersion = customDefaultVersion;
     appVersions = customAppVersions || {};
+    outputPath = customOutputPath;
   }
 
   // Use custom output path if specified, otherwise default to src/utils
@@ -196,26 +203,13 @@ export async function generateApiTypes(options) {
       },
     };
 
-    // Determine version: use custom app version if provided, otherwise use OpenAPI spec version
-    const version = appVersions[appName] || fullSpec.info.version || "v1";
-    let appDir, filename, serviceFilename;
-
-    if (["kos", "ext"].includes(appName) || !appName.includes(".")) {
-      // For kos, ext, and simple names: utils/services/{appName}/{version}/
-      appDir = join(servicesDir, appName, version);
-      filename = "openapi.d.ts";
-      serviceFilename = "service.ts";
-    } else {
-      // For app names with dots: utils/services/{appName}/
-      // If custom version specified, use versioned folder structure
-      if (appVersions[appName]) {
-        appDir = join(servicesDir, appName, version);
-      } else {
-        appDir = join(servicesDir, appName);
-      }
-      filename = "openapi.d.ts";
-      serviceFilename = "service.ts";
-    }
+    // Determine version: priority order is allAppsVersion (CLI override), appVersions (per-app config), OpenAPI spec, fallback
+    const version = allAppsVersion || appVersions[appName] || fullSpec.info.version || "v1";
+
+    // All apps now use versioned folder structure: utils/services/{appName}/{version}/
+    const appDir = join(servicesDir, appName, version);
+    const filename = "openapi.d.ts";
+    const serviceFilename = "service.ts";
 
     mkdirSync(appDir, { recursive: true });
     const outFile = join(appDir, filename);
@@ -343,16 +337,11 @@ export default api;
 
     writeFileSync(serviceFile, serviceContent);
 
-    // Store version info if it's a core service (kos, ext) or has a custom version specified
-    const versionInfo =
-      ["kos", "ext"].includes(appName) || !appName.includes(".") || appVersions[appName]
-        ? version
-        : null;
-
+    // All apps now have version info
     generatedFiles.push({
       appName,
       appDir: appDir.replace(servicesDir + "/", ""),
-      version: versionInfo,
+      version: version,
       pathCount: Object.keys(appData.paths).length,
     });
   }

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

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

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