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

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

@@ -0,0 +1,452 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+import openapiTS, { astToString } from "openapi-typescript";
+import { join } from "path";
+import { getProjectDetails } from "../../../utils/nx-context.mjs";
+
+/**
+ * Generate OpenAPI service types for a project
+ * @param {Object} options - Generation options
+ * @param {string} options.project - Project name
+ * @param {string} [options.host] - API host URL
+ * @param {boolean} [options.studio] - Whether to use Studio API endpoint
+ * @param {string[]} [options.apps] - Apps to include (if not specified, include all)
+ * @param {string} [options.outputPath] - Custom output path relative to sourceRoot
+ * @param {Object.<string, string>} [options.serviceExportAliases] - Custom export aliases
+ * @param {string} [options.defaultVersion] - Default version for exports
+ * @param {Object.<string, string>} [options.appVersions] - Custom versions per app
+ * @param {boolean} [options.excludeCore] - Exclude core SDK services
+ */
+export async function generateApiTypes(options) {
+  const {
+    project: projectName,
+    host: customHost,
+    studio = false,
+    apps: appsToInclude = [],
+    outputPath: customOutputPath,
+    serviceExportAliases: customAliases,
+    defaultVersion: customDefaultVersion,
+    appVersions: customAppVersions,
+    allAppsVersion,
+    excludeCore = false,
+  } = options;
+
+  let projectConfig, host, src, outputPath, serviceExportAliases, defaultVersion, appVersions;
+
+  try {
+    // Read project configuration using existing CLI utility
+    projectConfig = await getProjectDetails(projectName);
+
+    // Merge CLI options with project.json config (CLI takes precedence)
+    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 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
+  const utilsDir = outputPath ? join(src, outputPath) : join(src, "utils");
+  const servicesDir = join(utilsDir, "services");
+  mkdirSync(servicesDir, { recursive: true });
+
+  console.log(`Generating API types for ${projectName} from ${host}`);
+  const path = studio ? "/api/openapi/api" : "/api/kos/openapi/api";
+
+  // Fetch the full OpenAPI spec
+  const openapiUrl = new URL(`${host}${path}`, import.meta.url);
+  const response = await fetch(openapiUrl);
+  const fullSpec = await response.json();
+
+  // Helper function to determine app name from path
+  function getAppFromPath(path) {
+    const segments = path.split("/").filter(Boolean);
+
+    if (segments.length < 2) {
+      return "other";
+    }
+
+    // /api/kos/* → "kos"
+    if (path.startsWith("/api/kos")) {
+      return "kos";
+    }
+
+    // /api/app/{appName}/* → appName
+    if (path.startsWith("/api/app/")) {
+      return segments[2] || "app";
+    }
+
+    // /api/ext/{extName}/* → extName
+    if (path.startsWith("/api/ext/")) {
+      return segments[2] || "ext";
+    }
+
+    // /api/{other}/* → other
+    if (path.startsWith("/api/")) {
+      return segments[1] || "other";
+    }
+
+    return "other";
+  }
+
+  // Group paths by app
+  const appGroups = {};
+  for (const [path, pathItem] of Object.entries(fullSpec.paths || {})) {
+    const appName = getAppFromPath(path);
+
+    if (!appGroups[appName]) {
+      appGroups[appName] = {
+        paths: {},
+        components: new Set(),
+      };
+    }
+
+    appGroups[appName].paths[path] = pathItem;
+
+    // Collect referenced components from this path
+    const pathJson = JSON.stringify(pathItem);
+    const refMatches = pathJson.matchAll(/#\/components\/schemas\/([^"]+)/g);
+    for (const match of refMatches) {
+      appGroups[appName].components.add(match[1]);
+    }
+  }
+
+  // Helper function to recursively collect component dependencies
+  function collectComponentDependencies(componentId, allComponents, collected = new Set()) {
+    if (collected.has(componentId)) {
+      return collected;
+    }
+
+    collected.add(componentId);
+
+    const component = allComponents[componentId];
+    if (!component) {
+      return collected;
+    }
+
+    // Find all schema references in this component
+    const componentJson = JSON.stringify(component);
+    const refMatches = componentJson.matchAll(/#\/components\/schemas\/([^"]+)/g);
+
+    for (const match of refMatches) {
+      const refId = match[1];
+      if (!collected.has(refId)) {
+        collectComponentDependencies(refId, allComponents, collected);
+      }
+    }
+
+    return collected;
+  }
+
+  // Core SDK services that should be excluded in third-party apps
+  const CORE_SDK_SERVICES = ['kos', 'vfs', 'dispense', 'freestyle', 'handle', 'kosdev.ddk'];
+
+  // Filter apps based on command line arguments and core service exclusion
+  let appsToProcess = Object.entries(appGroups);
+
+  // Exclude core services if requested
+  if (excludeCore) {
+    appsToProcess = appsToProcess.filter(([appName]) => !CORE_SDK_SERVICES.includes(appName));
+    console.log(`Excluding core SDK services: ${CORE_SDK_SERVICES.join(', ')}`);
+  }
+
+  // If specific apps are requested, further filter to only those
+  if (appsToInclude.length > 0) {
+    appsToProcess = appsToProcess.filter(([appName]) => appsToInclude.includes(appName));
+    console.log(`Filtering to include only: ${appsToInclude.join(', ')}`);
+  }
+
+  // Generate a separate OpenAPI spec file for each app
+  const generatedFiles = [];
+
+  for (const [appName, appData] of appsToProcess) {
+    // Collect all component dependencies
+    const allComponentIds = new Set();
+    for (const componentId of appData.components) {
+      collectComponentDependencies(componentId, fullSpec.components?.schemas || {}, allComponentIds);
+    }
+
+    // Build filtered components
+    const filteredComponents = {};
+    for (const componentId of allComponentIds) {
+      if (fullSpec.components?.schemas?.[componentId]) {
+        filteredComponents[componentId] = fullSpec.components.schemas[componentId];
+      }
+    }
+
+    // Create app-specific spec
+    const appSpec = {
+      openapi: fullSpec.openapi,
+      info: {
+        ...fullSpec.info,
+        title: `${fullSpec.info.title} - ${appName}`,
+      },
+      paths: appData.paths,
+      components: {
+        schemas: filteredComponents,
+      },
+    };
+
+    // 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);
+    const relativeAppDir = appDir.replace(utilsDir + "/", "");
+
+    console.log(
+      `  - Generating ${relativeAppDir}/ (${
+        Object.keys(appData.paths).length
+      } paths, ${allComponentIds.size} components)`
+    );
+
+    // Generate TypeScript types from the filtered spec
+    const ast = await openapiTS(appSpec);
+    const contents = astToString(ast);
+
+    writeFileSync(outFile, contents);
+
+    // Generate corresponding service file for this app
+    const serviceFile = join(appDir, serviceFilename);
+    const typeModule = "openapi";
+
+    // Special handling for kos-ui-sdk to avoid circular dependency
+    const isKosUiSdk = projectName === "@kosdev-code/kos-ui-sdk";
+    const importStatement = isKosUiSdk
+      ? `import type { KosExecutionContext } from "../../../../../core/core/decorators/kos-execution-context";
+import type {
+  HttpMethod,
+  IKosServiceRequestParams,
+} from "../../../../../core/core/decorators/kos-service-request";
+import { kosServiceRequest as baseKosServiceRequest } from "../../../../../core/core/decorators/kos-service-request";
+import type { ClientResponse } from "../../../../../core/util/kos-service-request";
+import { createClient } from "../../../../../core/util/kos-service-request";
+
+import type { PathsByMethod } from "../../../../../core/util/kos-service-request";`
+      : `import {
+  kosServiceRequest as baseKosServiceRequest,
+  createClient,
+  type ClientResponse,
+  type HttpMethod,
+  type IKosServiceRequestParams,
+  type KosExecutionContext,
+  type PathsByMethod,
+} from "@kosdev-code/kos-ui-sdk"`;
+
+    const serviceContent = `${importStatement}
+import type { paths } from "./${typeModule}";
+
+/**
+ * Type aliases for ${appName} API
+ */
+export type Api = paths;
+export type ApiPath = keyof paths;
+export type ValidPaths = PathsByMethod<paths>;
+
+/**
+ * Get client response type for ${appName} API
+ */
+export type ApiResponse<
+  Path extends ApiPath,
+  Method extends "get" | "post" | "put" | "delete" = "get"
+> = ClientResponse<paths, Path, Method>;
+
+/**
+ * Get execution context type for ${appName} API
+ */
+export type ExecutionContext<
+  Path extends ApiPath = ApiPath,
+  Method extends HttpMethod = "get"
+> = KosExecutionContext<paths, Path, Method>;
+
+/**
+ * Typed decorator factory for @kosServiceRequest with ${appName} API types
+ *
+ * Provides full IntelliSense and type safety for path, query params, and body
+ * based on the ${appName} OpenAPI schema.
+ *
+ * @example
+ * \`\`\`typescript
+ * import { kosServiceRequest } from '../../utils/services/${appDir.replace(
+      servicesDir + "/",
+      ""
+    )}/service';
+ * import { DependencyLifecycle } from '@kosdev-code/kos-ui-sdk';
+ *
+ * @kosServiceRequest({
+ *   path: '/api/...',
+ *   method: 'get',
+ *   lifecycle: DependencyLifecycle.LOAD
+ * })
+ * private onDataLoaded(): void {
+ *   // Fully typed based on ${appName} API
+ * }
+ * \`\`\`
+ */
+export function kosServiceRequest<
+  Path extends ApiPath,
+  Method extends HttpMethod = "get",
+  Response = any,
+  TransformedResponse = Response
+>(
+  params: IKosServiceRequestParams<
+    paths,
+    Path,
+    Method,
+    Response,
+    TransformedResponse
+  >
+) {
+  return baseKosServiceRequest<
+    paths,
+    Path,
+    Method,
+    Response,
+    TransformedResponse
+  >(params);
+}
+
+/**
+ * Create an API client for ${appName}
+ */
+export const api = createClient<paths>();
+
+export default api;
+`;
+
+    writeFileSync(serviceFile, serviceContent);
+
+    // All apps now have version info
+    generatedFiles.push({
+      appName,
+      appDir: appDir.replace(servicesDir + "/", ""),
+      version: version,
+      pathCount: Object.keys(appData.paths).length,
+    });
+  }
+
+  // Read existing index files to preserve manual entries
+  function mergeIndexFile(filePath, newEntries, comment) {
+    let existingContent = "";
+    try {
+      existingContent = readFileSync(filePath, "utf-8");
+    } catch (error) {
+      // File doesn't exist yet, that's ok
+    }
+
+    // Parse existing exports
+    const existingExports = new Map();
+    const manualExports = [];
+    const lines = existingContent.split("\n");
+
+    for (const line of lines) {
+      const match = line.match(/^export \* as (\w+) from ['"](.+)['"]/);
+      if (match) {
+        const [, exportName, path] = match;
+        existingExports.set(exportName, { exportName, path, line });
+      } else if (line.trim() && !line.startsWith("//")) {
+        // Preserve non-export lines (imports, other statements)
+        manualExports.push(line);
+      }
+    }
+
+    // Merge with new entries
+    for (const { exportName, path } of newEntries) {
+      existingExports.set(exportName, {
+        exportName,
+        path,
+        line: `export * as ${exportName} from '${path}';`,
+      });
+    }
+
+    // Build final content
+    const header = comment ? `// ${comment}\n` : "";
+    const exportLines = Array.from(existingExports.values())
+      .sort((a, b) => a.exportName.localeCompare(b.exportName))
+      .map((e) => e.line);
+
+    return (
+      header +
+      exportLines.join("\n") +
+      "\n" +
+      (manualExports.length > 0 ? "\n" + manualExports.join("\n") + "\n" : "")
+    );
+  }
+
+  // Generate index file that exports all apps (merge with existing)
+  const typeIndexEntries = generatedFiles.map(({ appName, appDir }) => ({
+    exportName: appName.replace(/[.-]/g, "_"),
+    path: `./services/${appDir}/openapi`,
+  }));
+
+  const indexFile = join(utilsDir, "openapi-index.ts");
+  const indexContent = mergeIndexFile(
+    indexFile,
+    typeIndexEntries,
+    "Auto-generated type exports - new entries added automatically"
+  );
+  writeFileSync(indexFile, indexContent);
+
+  // Generate service index that re-exports all app services (merge with existing)
+  const serviceIndexEntries = generatedFiles.map(({ appName, appDir, version }) => {
+    const baseAlias = serviceExportAliases[appName] || appName.replace(/[.-]/g, "_").toUpperCase();
+
+    // Check if this version is the default version
+    const isDefaultVersion = defaultVersion && version === defaultVersion;
+
+    // For default version, use base alias. For others, append version suffix
+    const exportName = isDefaultVersion
+      ? baseAlias
+      : `${baseAlias}_${version.replace(/[.-]/g, "_").toUpperCase()}`;
+
+    return {
+      exportName,
+      path: `./services/${appDir}/service`,
+    };
+  });
+
+  const serviceIndexFile = join(utilsDir, "services-index.ts");
+  const serviceIndexContent = mergeIndexFile(
+    serviceIndexFile,
+    serviceIndexEntries,
+    "Auto-generated service exports - new entries added automatically"
+  );
+  writeFileSync(serviceIndexFile, serviceIndexContent);
+
+  console.log(
+    `\nGenerated ${generatedFiles.length} app-specific type and service file pairs:`
+  );
+  generatedFiles.forEach(({ appName, appDir, version, pathCount }) => {
+    const versionStr = version ? ` [${version}]` : "";
+    console.log(`  ✓ ${appDir}/${versionStr} (${appName}: ${pathCount} paths)`);
+  });
+  console.log(`  ✓ openapi-index.ts (aggregated type exports)`);
+  console.log(`  ✓ services-index.ts (aggregated service exports)`);
+
+  return {
+    success: true,
+    filesGenerated: generatedFiles.length * 2 + 2, // type + service files + 2 index files
+    apps: generatedFiles.map(f => f.appName),
+  };
+}

package/src/lib/plopfile.mjs

@@ -12,6 +12,7 @@ import registerKosModel from "./generators/model/model.mjs";
 import registerComponent from "./generators/component/index.mjs";
 import registerPluginComponent from "./generators/plugin/index.mjs";
 
+import registerApiGenerate from "./generators/api/generate.mjs";
 import registerCacheGenerators from "./generators/cache/index.mjs";
 import registerDev from "./generators/dev/index.mjs";
 import registerEnv from "./generators/env/index.mjs";
@@ -60,6 +61,7 @@ export default async function (plop) {
   await registerSplashProject(plop);
   await registerI18n(plop);
   await registerI18nNamespace(plop);
+  await registerApiGenerate(plop);
   await registerDev(plop);
   await registerEnv(plop);
   await registerKab(plop);

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