@ldsg/cli 0.3.43 → 0.3.44

package/src/cli.ts

@@ -1,39 +1,9 @@
 #!/usr/bin/env node
 import { readFileSync } from "fs";
 import { join } from "path";
-import { AppData } from "@ldsg/types";
-import {
-  extendAppData,
-  ExtendAppDataParams,
-  loadAppResourceRecords,
-  prepare,
-  ZipAppDataLayout,
-} from "@ldsg/utils";
 import { Command } from "commander";
-import { DEFAULT_OUTPUT_PATH, DEFAULT_SOURCE_FILE, DEFAULT_SOURCE_PATH } from "./constants";
-import { getExtendAppDataParamsUsingNpmLdsgModule } from "./utils/get-extend-app-data-params-using-npm-ldsg-module";
-import { getExtendAppDataParamsUsingWorkspaceLdsgModule } from "./utils/get-extend-app-data-params-using-workspace-ldsg-module";
-import { resolveSource, isStdinSource, getSourceDescription } from "./utils/source-resolver";
-import {
-  formatSuccess,
-  formatError,
-  formatJson,
-  formatPrettyList,
-  formatPrettyTree,
-  formatPrettyDiff,
-} from "./utils/formatter";
-import { createResource } from "./commands/resource/create";
-import { updateResource } from "./commands/resource/update";
-import { deleteResource } from "./commands/resource/delete";
-import { listResources, getTree } from "./commands/resource/list";
-import { getResource } from "./commands/resource/get";
-import { diffResource } from "./commands/resource/diff";
-import {
-  mutateRecordsDirect,
-  mutateResources,
-  pullRemoteResourceRecords,
-  purifyResourceRecord,
-} from "./commands/resource/mutate";
+import { registerGenerateCommand } from "./commands/generate";
+import { registerResourceCommand } from "./commands/resource";
 
 const { version } = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 
@@ -41,483 +11,7 @@ const program = new Command();
 
 program.name("ldsg").description("LDSG CLI tools").version(version);
 
-program
-  .command("generate")
-  .aliases(["g", "gen"])
-  .description("Generate standalone application from resource records")
-  .option("--app-data-uri <uri>", "runtime app data URI")
-  .option(
-    "--app-data-expression <expression>",
-    "runtime app data expression (jsonata), used to convert source data to standard ldsg resource records",
-  )
-  .option("--using-workspace-ldsg-module", "use workspace ldsg module mode")
-  .option(
-    "--layout <layout>",
-    `app layout: nested or flat (default: flat for workspace mode, nested otherwise)`,
-  )
-  .option("--app-package-name <name>", "app package name (default: @ldsg/app)")
-  .option(
-    "-o, --output <path>",
-    `output directory for prepared app code (default: ${DEFAULT_OUTPUT_PATH})`,
-  )
-  .action(async (options) => {
-    const outputPath = options.output || DEFAULT_OUTPUT_PATH;
-
-    const usingWorkspaceLdsgModule = options.usingWorkspaceLdsgModule ?? false;
-
-    const layout =
-      options.layout === "nested"
-        ? ZipAppDataLayout.NESTED
-        : options.layout === "flat"
-          ? ZipAppDataLayout.FLAT
-          : undefined;
-    if (options.layout && layout === undefined) {
-      throw new Error(`invalid layout: ${options.layout} (expected nested or flat)`);
-    }
-
-    const { resourceRecords } = await loadAppResourceRecords({
-      appDataUri: options.appDataUri,
-      appDataExpression: options.appDataExpression,
-    });
-
-    const appData: AppData = { resourceRecords };
-
-    let extendAppDataParams: ExtendAppDataParams;
-
-    if (usingWorkspaceLdsgModule) {
-      extendAppDataParams = await getExtendAppDataParamsUsingWorkspaceLdsgModule({
-        appData,
-        ...(layout ? { layout } : {}),
-        ...(options.appPackageName ? { appPackageName: options.appPackageName } : {}),
-        outputPath,
-      });
-    } else {
-      extendAppDataParams = await getExtendAppDataParamsUsingNpmLdsgModule({ appData });
-    }
-
-    const extendAppDataRes = extendAppData(extendAppDataParams);
-
-    await prepare({
-      ...extendAppDataRes,
-      outputPath,
-      ...(layout ? { layout } : usingWorkspaceLdsgModule ? { layout: ZipAppDataLayout.FLAT } : {}),
-    });
-  });
-
-const resource = program.command("resource").aliases(["r"]).description("Manage resource records");
-
-resource
-  .command("list")
-  .description("List resource records by filter")
-  .option("--source <path>", `data source (default: ${DEFAULT_SOURCE_PATH})`)
-  .option("--kind <kind>", "filter by resource kind")
-  .option("--parent-id <id>", "filter by parent id")
-  .option("--root-id <id>", "filter by root resource id")
-  .option("--pretty", "human-readable output")
-  .action(async (options) => {
-    try {
-      const sourceDesc = getSourceDescription(options.source);
-      const sourceData = await resolveSource(options.source);
-      const { total, resources } = await listResources(sourceData.resourceRecords, {
-        kind: options.kind,
-        parentId: options.parentId,
-        rootId: options.rootId,
-      });
-
-      if (options.pretty) {
-        console.log(
-          formatPrettyList(
-            resources.map((r) => ({
-              id: r.id,
-              kind: r.kind,
-              parentId: r.parentId,
-              title: (r.settings as Record<string, unknown>)?.title as string | undefined,
-            })),
-          ),
-        );
-      } else {
-        console.log(formatJson(formatSuccess({ source: sourceDesc, total, resources })));
-      }
-    } catch (error) {
-      console.error(formatJson(formatError("LIST_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-resource
-  .command("get <id>")
-  .description("Get a resource record by id")
-  .option("--source <path>", `data source (default: ${DEFAULT_SOURCE_PATH})`)
-  .option("--children", "include direct children")
-  .option("--tree", "include full subtree")
-  .option("--pretty", "human-readable output")
-  .action(async (id, options) => {
-    try {
-      const sourceDesc = getSourceDescription(options.source);
-      const sourceData = await resolveSource(options.source);
-      const record = await getResource(sourceData.resourceRecords, id, {
-        children: options.children,
-        tree: options.tree,
-      });
-
-      if (!record) {
-        console.error(formatJson(formatError("NOT_FOUND", `Resource with id "${id}" not found`)));
-        process.exit(1);
-      }
-
-      if (options.pretty) {
-        console.log(formatJson(record));
-      } else {
-        console.log(formatJson(formatSuccess({ source: sourceDesc, record })));
-      }
-    } catch (error) {
-      console.error(formatJson(formatError("GET_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-resource
-  .command("tree [root-id]")
-  .description("Display resource tree")
-  .option("--source <path>", `data source (default: ${DEFAULT_SOURCE_PATH})`)
-  .option("--show-kind", "show resource kind prefix")
-  .option("--pretty", "human-readable output")
-  .action(async (rootId, options) => {
-    try {
-      const sourceDesc = getSourceDescription(options.source);
-      const sourceData = await resolveSource(options.source);
-      const result = await getTree(sourceData.resourceRecords, rootId, options.showKind);
-
-      if (options.pretty) {
-        console.log(formatPrettyTree(result.tree as never, options.showKind ?? false));
-      } else {
-        console.log(formatJson(formatSuccess({ source: sourceDesc, ...result })));
-      }
-    } catch (error) {
-      console.error(formatJson(formatError("TREE_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-resource
-  .command("create")
-  .description("Create a new resource record")
-  .option("--source <path>", `data source (default: ${DEFAULT_SOURCE_PATH})`)
-  .option("--kind <kind>", "resource kind")
-  .option("--parent-id <id>", "parent resource id")
-  .option("--settings <json>", "resource settings as JSON string")
-  .option("--from-file <path>", "read full resource record from JSON file")
-  .option("--from-stdin", "read full resource record from stdin")
-  .option("--dry-run", "preview without writing")
-  .action(async (options) => {
-    try {
-      if (isStdinSource(options.source)) {
-        console.error(
-          formatJson(
-            formatError("STDIN_NOT_WRITABLE", "stdin source does not support write operations"),
-          ),
-        );
-        process.exit(1);
-      }
-
-      const sourceData = await resolveSource(options.source);
-
-      let fromFileRecord: Record<string, unknown> | undefined;
-
-      if (options.fromFile) {
-        const fs = await import("fs-extra");
-        fromFileRecord = await fs.readJson(options.fromFile);
-      } else if (options.fromStdin) {
-        const chunks: Buffer[] = [];
-        process.stdin.setEncoding("utf-8");
-        for await (const chunk of process.stdin) {
-          chunks.push(Buffer.from(chunk));
-        }
-        const raw = Buffer.concat(chunks).toString("utf-8");
-        fromFileRecord = JSON.parse(raw);
-      }
-
-      let settings: Record<string, unknown> | undefined;
-      if (options.settings) {
-        settings = JSON.parse(options.settings);
-      }
-
-      const { record } = await createResource({
-        sourceData,
-        kind: options.kind,
-        parentId: options.parentId,
-        settings,
-        fromFileRecord: fromFileRecord as never,
-        dryRun: options.dryRun,
-      });
-
-      console.log(formatJson(formatSuccess({ record, dryRun: options.dryRun ?? false })));
-    } catch (error) {
-      console.error(formatJson(formatError("CREATE_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-resource
-  .command("update <id>")
-  .description("Update a resource record")
-  .option("--source <path>", `data source (default: ${DEFAULT_SOURCE_PATH})`)
-  .option("--settings <json>", "resource settings to merge (JSON string, required)")
-  .option("--dry-run", "preview without writing")
-  .action(async (id, options) => {
-    try {
-      if (isStdinSource(options.source)) {
-        console.error(
-          formatJson(
-            formatError("STDIN_NOT_WRITABLE", "stdin source does not support write operations"),
-          ),
-        );
-        process.exit(1);
-      }
-
-      const sourceData = await resolveSource(options.source);
-
-      if (!options.settings) {
-        console.error(
-          formatJson(formatError("MISSING_SETTINGS", "Required option: --settings <json>")),
-        );
-        process.exit(1);
-      }
-
-      const settings = JSON.parse(options.settings);
-      const { record } = await updateResource({
-        sourceData,
-        id,
-        settings,
-        dryRun: options.dryRun,
-      });
-
-      console.log(formatJson(formatSuccess({ record, dryRun: options.dryRun ?? false })));
-    } catch (error) {
-      console.error(formatJson(formatError("UPDATE_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-resource
-  .command("delete <id>")
-  .description("Delete a resource record and its children")
-  .option("--source <path>", `data source (default: ${DEFAULT_SOURCE_PATH})`)
-  .option("--dry-run", "preview deletion scope without writing")
-  .action(async (id, options) => {
-    try {
-      if (isStdinSource(options.source)) {
-        console.error(
-          formatJson(
-            formatError("STDIN_NOT_WRITABLE", "stdin source does not support write operations"),
-          ),
-        );
-        process.exit(1);
-      }
-
-      const sourceData = await resolveSource(options.source);
-      const { removed } = await deleteResource({
-        sourceData,
-        id,
-        dryRun: options.dryRun,
-      });
-
-      console.log(
-        formatJson(
-          formatSuccess({
-            dryRun: options.dryRun ?? false,
-            removedCount: removed.length,
-            removed: removed.map((r) => ({ id: r.id, kind: r.kind })),
-          }),
-        ),
-      );
-    } catch (error) {
-      console.error(formatJson(formatError("DELETE_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-resource
-  .command("diff <id>")
-  .description("Diff a resource between two sources")
-  .option("--source-a <path>", "first source file (required)")
-  .option("--source-b <path>", "second source file (required)")
-  .option("--pretty", "human-readable output")
-  .action(async (id, options) => {
-    try {
-      if (!options.sourceA || !options.sourceB) {
-        console.error(
-          formatJson(formatError("MISSING_ARGS", "Required options: --source-a, --source-b")),
-        );
-        process.exit(1);
-      }
-
-      const sourceDataA = await resolveSource(options.sourceA);
-      const sourceDataB = await resolveSource(options.sourceB);
-
-      const result = await diffResource({
-        sourceA: getSourceDescription(options.sourceA),
-        sourceB: getSourceDescription(options.sourceB),
-        id,
-        recordsA: sourceDataA.resourceRecords,
-        recordsB: sourceDataB.resourceRecords,
-      });
-
-      if (options.pretty) {
-        console.log(formatPrettyDiff(result));
-      } else {
-        console.log(formatJson(formatSuccess(result)));
-      }
-    } catch (error) {
-      console.error(formatJson(formatError("DIFF_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-resource
-  .command("pull")
-  .description("Pull resource records from RRM to a local file (read-only)")
-  .option("--endpoint <url>", "RRM GraphQL endpoint")
-  .option("--path <regex>", "scope remote records to a path regex (e.g. application id)")
-  .option("-o, --output <path>", `output file (default: ${DEFAULT_SOURCE_PATH})`)
-  .action(async (options) => {
-    try {
-      const result = await pullRemoteResourceRecords({
-        endpoint: options.endpoint,
-        path: options.path,
-        output: options.output,
-      });
-
-      console.log(formatJson(formatSuccess(result)));
-    } catch (error) {
-      console.error(formatJson(formatError("PULL_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
-
-async function parseExplicitRecords(
-  value?: string,
-  file?: string,
-): Promise<
-  | { id: string; kind: string; parentId: string | null; settings: Record<string, unknown> }[]
-  | undefined
-> {
-  if (value && file) {
-    throw new Error("Cannot use both an inline value and a file for the same record list");
-  }
-
-  let data: unknown;
-
-  if (file) {
-    const fs = await import("fs-extra");
-    data = await fs.readJson(file);
-  } else if (value) {
-    data = JSON.parse(value);
-  } else {
-    return undefined;
-  }
-
-  const list = Array.isArray(data) ? data : [data];
-  return list.map((record) => purifyResourceRecord(record as never));
-}
-
-resource
-  .command("mutate")
-  .description("Mutate local resource records on RRM via mutateResourceRecords")
-  .option("--source <path>", `data source (default: ${DEFAULT_SOURCE_PATH})`)
-  .option("--endpoint <url>", "RRM GraphQL endpoint")
-  .option("--token <token>", "RRM Bearer token (or RRM_ACCESS_TOKEN env)")
-  .option(
-    "--path <regex>",
-    "scope remote records to a path regex (e.g. application id) before splitting",
-  )
-  .option(
-    "--no-delete-missing",
-    "do not soft-delete remote-only records (default: soft-delete like console)",
-  )
-  .option("--no-write-back", "do not write server-assigned ids back to the local source file")
-  .option("--yes", "confirm soft-deletion without prompting")
-  .option("--dry-run", "preview the plan without sending")
-  .option("--create <json>", "explicit create records as JSON (skip auto split)")
-  .option("--update <json>", "explicit update records as JSON (skip auto split)")
-  .option("--create-file <path>", "explicit create records from JSON file (skip auto split)")
-  .option("--update-file <path>", "explicit update records from JSON file (skip auto split)")
-  .action(async (options) => {
-    try {
-      const explicitCreate = await parseExplicitRecords(options.create, options.createFile);
-      const explicitUpdate = await parseExplicitRecords(options.update, options.updateFile);
-
-      if (explicitCreate !== undefined || explicitUpdate !== undefined) {
-        const result = await mutateRecordsDirect({
-          endpoint: options.endpoint,
-          token: options.token,
-          createResourceRecords: explicitCreate ?? [],
-          updateResourceRecords: explicitUpdate ?? [],
-          dryRun: options.dryRun,
-        });
-
-        console.log(
-          formatJson(
-            formatSuccess({
-              mode: "explicit",
-              dryRun: result.dryRun,
-              createCount: result.createCount,
-              updateCount: result.updateCount,
-              createdResourceRecords: result.createdResourceRecords,
-              updatedResourceRecords: result.updatedResourceRecords,
-            }),
-          ),
-        );
-        return;
-      }
-
-      if (isStdinSource(options.source)) {
-        console.error(
-          formatJson(
-            formatError(
-              "STDIN_NOT_SUPPORTED",
-              "stdin source is not supported for mutate; use a local JSON file",
-            ),
-          ),
-        );
-        process.exit(1);
-      }
-
-      const sourceData = await resolveSource(options.source);
-
-      const result = await mutateResources({
-        sourceData,
-        endpoint: options.endpoint,
-        token: options.token,
-        path: options.path,
-        deleteMissing: options.deleteMissing,
-        writeBack: options.writeBack,
-        yes: options.yes,
-        dryRun: options.dryRun,
-      });
-
-      const { plan } = result;
-
-      console.log(
-        formatJson(
-          formatSuccess({
-            mode: "auto",
-            dryRun: result.dryRun,
-            source: getSourceDescription(options.source),
-            remoteCount: plan.remoteCount,
-            localCount: plan.localCount,
-            createCount: plan.createResourceRecords.length,
-            updateCount: plan.updateResourceRecords.length,
-            deleteCount: plan.deleteResourceRecords.length,
-            idMap: result.idMap,
-            writeBackPath: result.writeBackPath,
-          }),
-        ),
-      );
-    } catch (error) {
-      console.error(formatJson(formatError("MUTATE_ERROR", (error as Error).message)));
-      process.exit(1);
-    }
-  });
+registerGenerateCommand(program);
+registerResourceCommand(program);
 
 program.parse(process.argv);

package/src/commands/generate/index.ts

@@ -0,0 +1,54 @@
+import { loadData } from "@ldsg/utils";
+import { Command } from "commander";
+import { DEFAULT_OUTPUT_PATH } from "../../constants";
+import { parseExtraOptions } from "./utils/parse-extra-options";
+import { GenerateParams } from "@ldsg/types";
+import { generateApplication } from "./utils/generate-application";
+
+/**
+ * 注册 generate 命令
+ *
+ * 从 ldsg 数据源生成独立应用：三阶段构建（bootstrap generator → application generator → buildApp）
+ */
+export function registerGenerateCommand(program: Command): void {
+  program
+    .command("generate")
+    .aliases(["g", "gen"])
+    .description("Generate standalone application from ldsg data source")
+    // output 为位置参数（放在命令最后），声明在 usage 中用于帮助信息展示；
+    // 实际取值由 parseExtraOptions 从 command.args 中解析（未知选项会导致 commander 位置参数错位）
+    .usage(
+      `[options] [output]\n\n  output: output directory for prepared source code, or zip file path when --zip (default: ${DEFAULT_OUTPUT_PATH})`,
+    )
+    .option("--data-uri <uri>", "ldsg source data URI")
+    .option(
+      "--data-expression <expression>",
+      "ldsg data expression (jsonata), used to convert source data to ldsg data",
+    )
+    .option("-z, --zip", "write the prepared source code as a zip file")
+    .allowUnknownOption(true)
+    .action(async (options, command) => {
+      const { dataUri, dataExpression, zip: isZip = false } = options;
+
+      // 解析额外未知选项与位置参数（最后一个位置参数为输出目录）
+      const { options: extraOptions, positionals } = parseExtraOptions(command.args);
+      const outputPath = positionals[positionals.length - 1] ?? DEFAULT_OUTPUT_PATH;
+
+      const data = await loadData({
+        dataUri,
+        dataExpression,
+      });
+
+      /**
+       * 生成器选项
+       */
+      const generateParams: GenerateParams = {
+        data,
+        outputPath,
+        isZip,
+        extraOptions,
+      };
+
+      await generateApplication(generateParams);
+    });
+}

package/src/commands/generate/utils/generate-application/index.ts

@@ -0,0 +1,50 @@
+import { extractZipToFolder } from "@ldsg/utils";
+import fs from "fs-extra";
+import path from "node:path";
+import type { GenerateParams } from "@ldsg/types";
+import { buildAppGenerator, buildMetaGenerator, generateApp } from "./utils";
+
+interface GenerateApplicationParams extends GenerateParams {}
+
+type GenerateApplication = (params: GenerateApplicationParams) => Promise<void>;
+
+/**
+ * 生成应用
+ * 1. 基于资源记录，使用此应用（@ldsg/cli）内置能力构建（含生成、依赖安装、构建）元生成器（Meta Generator）；
+ * 2. 基于资源记录，使用元生成器（Meta Generator）能力构建（含生成、依赖安装、构建）应用生成器（App Generator）；
+ * 3. 基于资源记录，使用应用生成器（App Generator）能力生成（仅含生成，不含依赖安装、构建）生成应用（App）压缩包；
+ * 4. 输出压缩包或解压至目标输出路径。
+ */
+export const generateApplication: GenerateApplication = async (params) => {
+  const { outputPath, isZip } = params;
+
+  /**
+   * 1. 基于资源记录，使用此应用（@ldsg/cli）内置能力构建（含生成、依赖安装、构建）元生成器（Meta Generator）；
+   */
+  const { metaGenerator } = await buildMetaGenerator(params);
+
+  /**
+   * 2. 基于资源记录，使用元生成器（Meta Generator）能力构建（含生成、依赖安装、构建）应用生成器（App Generator）；
+   */
+  const { appGenerator } = await buildAppGenerator({ metaGenerator, ...params });
+
+  /**
+   * 3. 基于资源记录，使用应用生成器（App Generator）能力生成（仅含生成，不含依赖安装、构建）生成应用（App）压缩包；
+   */
+  const generateAppRes = await generateApp({ appGenerator, ...params });
+
+  /**
+   * 4. 输出压缩包或解压至目标输出路径。
+   */
+  {
+    const { archive } = generateAppRes;
+
+    if (isZip) {
+      const zipOutputPath = path.join(outputPath, "app.zip");
+
+      await fs.outputFile(zipOutputPath, archive);
+    } else {
+      extractZipToFolder({ archive, outputPath });
+    }
+  }
+};

package/src/commands/generate/utils/generate-application/utils/build-app-generator/index.ts

@@ -0,0 +1,39 @@
+import { GenerateParams, Generator } from "@ldsg/types";
+import path from "node:path";
+import os from "node:os";
+import { extractZipToFolder } from "@ldsg/utils";
+
+export interface BuildAppGeneratorParams extends GenerateParams {
+  metaGenerator: Generator;
+}
+
+export interface BuildAppGeneratorRes {
+  appGenerator: Generator;
+}
+
+export type BuildAppGenerator = (params: BuildAppGeneratorParams) => Promise<BuildAppGeneratorRes>;
+
+export const buildAppGenerator: BuildAppGenerator = async (params) => {
+  const { metaGenerator, ...restParams } = params;
+
+  const { archive } = await metaGenerator.generate(restParams);
+
+  const outputPath = path.join(os.homedir(), ".ldsg", "app-generator");
+
+  extractZipToFolder({
+    archive,
+    outputPath,
+  });
+
+  const res: BuildAppGeneratorRes = {
+    appGenerator: {
+      generate: async () => {
+        return {
+          archive,
+        };
+      },
+    },
+  };
+
+  return res;
+};