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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-ui-cli",
-  "version": "0.1.0-dev.5160",
+  "version": "0.1.0-dev.5162",
   "bin": {
     "kosui": "./src/lib/cli.mjs"
   },
@@ -9,19 +9,21 @@
   ],
   "type": "module",
   "dependencies": {
+    "@nx/devkit": "^18.0.3",
     "chalk": "^5.3.0",
     "prettier": "^2.6.2",
     "rimraf": "^5.0.1",
     "plop": "^3.1.2",
     "inquirer-directory": "^2.2.0",
     "figlet": "^1.6.0",
-    "create-nx-workspace": "18.0.3"
+    "create-nx-workspace": "18.0.3",
+    "openapi-typescript": "^6.7.5"
   },
   "module": "./src/index.js",
   "main": "./src/index.js",
   "kos": {
     "build": {
-      "gitHash": "17ea20fec4bf8c74d5640f015a9fb9459485c27d"
+      "gitHash": "100cee4863c391572c9c06e59c4a54ca6a04a48d"
     }
   },
   "publishConfig": {

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

@@ -0,0 +1,112 @@
+import { generateApiTypes } from "./lib/generate-api.mjs";
+import { getProjects } from "../../utils/nx-context.mjs";
+
+/**
+ * Generator for creating OpenAPI service types
+ */
+export default async function register(plop) {
+  plop.setGenerator("api:generate", {
+    description: "Generate OpenAPI service types for a project",
+    prompts: [
+      {
+        type: "input",
+        name: "project",
+        message: "Project name",
+        validate: (input) => {
+          if (!input || input.trim() === "") {
+            return "Project name is required";
+          }
+          return true;
+        },
+      },
+      {
+        type: "input",
+        name: "host",
+        message: "API host URL",
+        default: "http://127.0.0.1:8081",
+      },
+      {
+        type: "confirm",
+        name: "studio",
+        message: "Use Studio API endpoint?",
+        default: false,
+      },
+      {
+        type: "input",
+        name: "apps",
+        message: "Apps to include (comma-separated, leave empty for all)",
+        default: "",
+        filter: (input) => {
+          if (!input || input.trim() === "") {
+            return [];
+          }
+          return input.split(",").map((s) => s.trim()).filter(Boolean);
+        },
+      },
+      {
+        type: "confirm",
+        name: "excludeCore",
+        message: "Exclude core SDK services (kos, vfs, dispense, freestyle, handle, kosdev.ddk)?",
+        default: false,
+      },
+      {
+        type: "input",
+        name: "outputPath",
+        message: "Output path (relative to sourceRoot, leave empty for default 'utils')",
+        default: "",
+      },
+      {
+        type: "input",
+        name: "defaultVersion",
+        message: "Default version for service exports",
+        default: "daily",
+      },
+    ],
+    actions: function (answers) {
+      return [
+        async function generateApi() {
+          try {
+            const options = {
+              project: answers.project,
+              host: answers.host,
+              studio: answers.studio,
+              apps: answers.apps,
+              excludeCore: answers.excludeCore,
+              outputPath: answers.outputPath || undefined,
+              defaultVersion: answers.defaultVersion,
+              // These can be extended with additional prompts if needed
+              serviceExportAliases: {},
+              appVersions: {},
+            };
+
+            const result = await generateApiTypes(options);
+
+            return `[ok] Generated ${result.filesGenerated} files for ${result.apps.length} apps: ${result.apps.join(", ")}`;
+          } catch (error) {
+            console.error("Error generating API types:", error);
+            throw new Error(`Failed to generate API types: ${error.message}`);
+          }
+        },
+      ];
+    },
+  });
+}
+
+// Export metadata for CLI integration
+export const metadata = {
+  key: "api:generate",
+  name: "Generate OpenAPI service types",
+  description: "Generate typed service helpers from OpenAPI specifications",
+  namedArguments: {
+    project: "project",
+    host: "host",
+    studio: "studio",
+    apps: "apps",
+    "exclude-core": "excludeCore",
+    output: "outputPath",
+    "default-version": "defaultVersion",
+    // Advanced options that can be passed as JSON strings or key=value pairs
+    alias: "serviceExportAliases",
+    "app-version": "appVersions",
+  },
+};

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

@@ -0,0 +1,463 @@
+import devkit from "@nx/devkit";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import openapiTS, { astToString } from "openapi-typescript";
+import { join } from "path";
+
+const { readCachedProjectGraph } = devkit;
+
+/**
+ * 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,
+    excludeCore = false,
+  } = options;
+
+  let graph, project, host, src, outputPath, serviceExportAliases, defaultVersion, appVersions;
+
+  try {
+    graph = readCachedProjectGraph();
+    project = graph.nodes[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;
+  } catch (error) {
+    // Fallback if project graph reading fails
+    console.warn("Warning: Could not read project graph, using defaults");
+    host = customHost || "http://127.0.0.1:8081";
+    src = `libs/${projectName}/src`;
+    serviceExportAliases = customAliases || {};
+    defaultVersion = customDefaultVersion;
+    appVersions = customAppVersions || {};
+  }
+
+  // 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: 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";
+    }
+
+    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);
+
+    // 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;
+
+    generatedFiles.push({
+      appName,
+      appDir: appDir.replace(servicesDir + "/", ""),
+      version: versionInfo,
+      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);