@lark-apaas/fullstack-cli 1.1.59-alpha.2 → 1.1.59-alpha.20260717162925

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import fs29 from "fs";
-import path25 from "path";
+import fs30 from "fs";
+import path26 from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 import { config as dotenvConfig } from "dotenv";
 
@@ -4921,7 +4921,7 @@ var PROMPT_PATTERNS = [
   { pattern: /proceed\?/i, answer: "y\n" }
 ];
 async function executeShadcnAdd(registryItemPath) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     let output = "";
     const args = ["--yes", "shadcn@3.8.2", "add", registryItemPath];
     const ptyProcess = pty.spawn("npx", args, {
@@ -4947,7 +4947,7 @@ async function executeShadcnAdd(registryItemPath) {
     });
     const timeoutId = setTimeout(() => {
       ptyProcess.kill();
-      resolve2({
+      resolve3({
         success: false,
         files: [],
         error: "\u6267\u884C\u8D85\u65F6"
@@ -4958,7 +4958,7 @@ async function executeShadcnAdd(registryItemPath) {
       const success = exitCode === 0;
       const filePaths = parseOutput(output);
       const files = filePaths.map(toFileInfo);
-      resolve2({
+      resolve3({
         success,
         files,
         error: success ? void 0 : output || `Process exited with code ${exitCode}`
@@ -4969,12 +4969,12 @@ async function executeShadcnAdd(registryItemPath) {
 
 // src/commands/component/add.handler.ts
 function runActionPluginInit() {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     execFile("fullstack-cli", ["action-plugin", "init"], { cwd: process.cwd(), stdio: "ignore" }, (error) => {
       if (error) {
         debug("action-plugin init \u5931\u8D25: %s", error.message);
       }
-      resolve2();
+      resolve3();
     });
   });
 }
@@ -8098,6 +8098,527 @@ async function preUploadStatic(options) {
   }
 }
 
+// src/commands/build/preview-server-artifact.handler.ts
+import * as fs29 from "fs";
+import * as os3 from "os";
+import * as path25 from "path";
+import { builtinModules, createRequire as createRequire3 } from "module";
+import { build } from "esbuild";
+import { parse as parse2 } from "acorn";
+import { simple as walkSimple } from "acorn-walk";
+var STATIC_PLUGIN_REGISTRY_SYMBOL = "@lark-apaas/nestjs-capability/static-plugin-registry";
+var STATIC_PLUGIN_REGISTRY_PROTOCOL_VERSION = 1;
+var OPTIONAL_DEPENDENCY_STUBS = [
+  "@nestjs/microservices",
+  "@nestjs/microservices/microservices-module",
+  "@nestjs/websockets/socket-module",
+  "fsevents"
+];
+var BUILTIN_MODULES = /* @__PURE__ */ new Set([
+  ...builtinModules,
+  ...builtinModules.map((moduleName) => `node:${moduleName}`)
+]);
+function toAbsolutePath(projectRoot, candidate) {
+  return path25.isAbsolute(candidate) ? candidate : path25.resolve(projectRoot, candidate);
+}
+function readJson(filePath) {
+  return JSON.parse(fs29.readFileSync(filePath, "utf8"));
+}
+function findPackageRoot(entryPath) {
+  let current = path25.dirname(entryPath);
+  const filesystemRoot = path25.parse(current).root;
+  while (current !== filesystemRoot) {
+    if (fs29.existsSync(path25.join(current, "package.json"))) {
+      return current;
+    }
+    current = path25.dirname(current);
+  }
+  return null;
+}
+function findNativeAddons(root) {
+  const nativeAddons = [];
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current) {
+      continue;
+    }
+    for (const entry of fs29.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path25.join(current, entry.name);
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        pending.push(entryPath);
+      } else if (entry.isFile() && entry.name.endsWith(".node")) {
+        nativeAddons.push(entryPath);
+      }
+    }
+  }
+  return nativeAddons.sort();
+}
+function resolveActionPlugins(projectRoot, packageJson) {
+  const configuredPlugins = packageJson.actionPlugins;
+  if (!configuredPlugins || typeof configuredPlugins !== "object") {
+    return { plugins: [], reasons: [] };
+  }
+  const projectRequire = createRequire3(path25.join(projectRoot, "package.json"));
+  const plugins = [];
+  const reasons = [];
+  for (const name of Object.keys(configuredPlugins).sort()) {
+    let entryPath;
+    try {
+      entryPath = projectRequire.resolve(name);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      reasons.push(`Action Plugin ${name} \u65E0\u6CD5\u89E3\u6790: ${message}`);
+      continue;
+    }
+    const packageRoot = findPackageRoot(entryPath);
+    if (!packageRoot) {
+      reasons.push(`Action Plugin ${name} \u65E0\u6CD5\u5B9A\u4F4D package.json: ${entryPath}`);
+      continue;
+    }
+    const nativeAddons = findNativeAddons(packageRoot);
+    if (nativeAddons.length > 0) {
+      const relativeAddons = nativeAddons.map(
+        (filePath) => path25.relative(packageRoot, filePath)
+      );
+      reasons.push(
+        `Action Plugin ${name} \u5305\u542B\u539F\u751F\u6269\u5C55\uFF0C\u4E0D\u80FD\u751F\u6210\u8DE8\u6C99\u7BB1\u5355 bundle: ${relativeAddons.join(", ")}`
+      );
+      continue;
+    }
+    const manifestPath = path25.join(packageRoot, "manifest.json");
+    let manifest;
+    if (fs29.existsSync(manifestPath)) {
+      try {
+        manifest = readJson(manifestPath);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        reasons.push(
+          `Action Plugin ${name} \u7684 manifest.json \u65E0\u6CD5\u89E3\u6790: ${message}`
+        );
+        continue;
+      }
+    }
+    plugins.push({ name, entryPath, manifest });
+  }
+  if (reasons.length === 0 && plugins.length > 0) {
+    try {
+      const capabilityRuntime = projectRequire(
+        "@lark-apaas/nestjs-capability"
+      );
+      if (capabilityRuntime.STATIC_PLUGIN_REGISTRY_PROTOCOL_VERSION !== STATIC_PLUGIN_REGISTRY_PROTOCOL_VERSION) {
+        reasons.push(
+          `@lark-apaas/nestjs-capability \u672A\u63D0\u4F9B\u517C\u5BB9\u7684 STATIC_PLUGIN_REGISTRY_PROTOCOL_VERSION=${STATIC_PLUGIN_REGISTRY_PROTOCOL_VERSION}`
+        );
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      reasons.push(
+        `@lark-apaas/nestjs-capability \u65E0\u6CD5\u52A0\u8F7D\uFF0C\u7F3A\u5C11 STATIC_PLUGIN_REGISTRY_PROTOCOL_VERSION=${STATIC_PLUGIN_REGISTRY_PROTOCOL_VERSION}: ${message}`
+      );
+    }
+  }
+  return { plugins, reasons };
+}
+function generateBootstrap(entryPath, plugins) {
+  const lines = [`'use strict';`, `const __staticPluginRegistry = new Map();`];
+  plugins.forEach((plugin, index) => {
+    const moduleVariable = `__staticPlugin${index}`;
+    lines.push(
+      `const ${moduleVariable} = require(${JSON.stringify(plugin.entryPath)});`
+    );
+    lines.push(
+      `__staticPluginRegistry.set(${JSON.stringify(plugin.name)}, { module: ${moduleVariable}, manifest: ${JSON.stringify(plugin.manifest ?? null)} });`
+    );
+  });
+  lines.push(
+    `globalThis[Symbol.for(${JSON.stringify(STATIC_PLUGIN_REGISTRY_SYMBOL)})] = __staticPluginRegistry;`,
+    `require(${JSON.stringify(entryPath)});`,
+    ""
+  );
+  return lines.join("\n");
+}
+function classTransformerStorageResolver(projectRoot) {
+  const projectRequire = createRequire3(path25.join(projectRoot, "package.json"));
+  return {
+    name: "class-transformer-storage-resolver",
+    setup(esbuild) {
+      esbuild.onResolve({ filter: /^class-transformer\/storage$/ }, () => {
+        try {
+          return {
+            path: projectRequire.resolve("class-transformer/cjs/storage.js")
+          };
+        } catch {
+          return void 0;
+        }
+      });
+    }
+  };
+}
+function optionalDependencyStubPlugin() {
+  const stubbedDependencies = /* @__PURE__ */ new Set();
+  const escapedNames = OPTIONAL_DEPENDENCY_STUBS.map(
+    (name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  );
+  const filter = new RegExp(`^(?:${escapedNames.join("|")})$`);
+  return {
+    stubbedDependencies,
+    plugin: {
+      name: "preview-optional-dependency-stubs",
+      setup(esbuild) {
+        esbuild.onResolve({ filter }, (args) => {
+          stubbedDependencies.add(args.path);
+          return {
+            path: args.path,
+            namespace: "preview-optional-dependency"
+          };
+        });
+        esbuild.onLoad(
+          { filter: /.*/, namespace: "preview-optional-dependency" },
+          (args) => ({
+            contents: `
+              const error = new Error(${JSON.stringify(
+              `Optional dependency is unavailable in Preview Artifact: ${args.path}`
+            )});
+              error.code = 'MODULE_NOT_FOUND';
+              throw error;
+            `,
+            loader: "js"
+          })
+        );
+      }
+    }
+  };
+}
+function isStaticString(node) {
+  if (!node) {
+    return false;
+  }
+  if (node.type === "Literal") {
+    return typeof node.value === "string";
+  }
+  return node.type === "TemplateLiteral" && node.expressions.length === 0;
+}
+function staticPropertyName(node) {
+  if (node.type !== "MemberExpression") {
+    return void 0;
+  }
+  if (!node.computed && node.property.type === "Identifier") {
+    return node.property.name;
+  }
+  if (node.computed && node.property.type === "Literal" && typeof node.property.value === "string") {
+    return node.property.value;
+  }
+  return void 0;
+}
+function auditBundleClosure(outfile, stubbedDependencies) {
+  const ast = parse2(fs29.readFileSync(outfile, "utf8"), {
+    ecmaVersion: "latest",
+    sourceType: "script",
+    allowHashBang: true
+  });
+  let dynamicRequireCount = 0;
+  let dynamicImportCount = 0;
+  let createRequireCount = 0;
+  let requireResolveCount = 0;
+  let runtimeFileReadCount = 0;
+  const runtimeFileReads = /* @__PURE__ */ new Set([
+    "access",
+    "accessSync",
+    "createReadStream",
+    "open",
+    "openSync",
+    "readFile",
+    "readFileSync",
+    "readdir",
+    "readdirSync",
+    "stat",
+    "statSync"
+  ]);
+  walkSimple(ast, {
+    CallExpression(node) {
+      if (node.callee.type === "Identifier" && node.callee.name === "require" && !isStaticString(node.arguments[0])) {
+        dynamicRequireCount += 1;
+      }
+      if (node.callee.type === "Identifier" && node.callee.name === "createRequire" || staticPropertyName(node.callee) === "createRequire") {
+        createRequireCount += 1;
+      }
+      const propertyName = staticPropertyName(node.callee);
+      if (propertyName === "resolve" && node.callee.type === "MemberExpression" && node.callee.object.type === "Identifier" && node.callee.object.name === "require") {
+        requireResolveCount += 1;
+      }
+      if (propertyName && runtimeFileReads.has(propertyName)) {
+        runtimeFileReadCount += 1;
+      }
+    },
+    ImportExpression(node) {
+      if (!isStaticString(node.source)) {
+        dynamicImportCount += 1;
+      }
+    }
+  });
+  const risks = [];
+  if (dynamicRequireCount > 0) {
+    risks.push(`bundle retains ${dynamicRequireCount} dynamic require call(s)`);
+  }
+  if (dynamicImportCount > 0) {
+    risks.push(`bundle retains ${dynamicImportCount} dynamic import call(s)`);
+  }
+  if (createRequireCount > 0 || requireResolveCount > 0) {
+    risks.push(
+      `bundle retains runtime module resolution (createRequire=${createRequireCount}, require.resolve=${requireResolveCount})`
+    );
+  }
+  if (runtimeFileReadCount > 0) {
+    risks.push(
+      `bundle retains ${runtimeFileReadCount} runtime filesystem read call(s)`
+    );
+  }
+  if (stubbedDependencies.length > 0) {
+    risks.push(
+      `bundle stubs optional dependencies: ${stubbedDependencies.join(", ")}`
+    );
+  }
+  return risks;
+}
+function collectExternalImports(metafile, outfile) {
+  const normalizedOutfile = path25.resolve(outfile);
+  const output = Object.entries(metafile.outputs).find(
+    ([outputPath]) => path25.resolve(outputPath) === normalizedOutfile
+  )?.[1];
+  if (!output) {
+    return [];
+  }
+  return Array.from(
+    new Set(
+      output.imports.filter((importRecord) => importRecord.external).map((importRecord) => importRecord.path).filter(
+        (importPath) => !BUILTIN_MODULES.has(importPath) && !importPath.startsWith("node:")
+      )
+    )
+  ).sort();
+}
+function formatBuildError(error) {
+  if (!error || typeof error !== "object" || !("errors" in error)) {
+    return [error instanceof Error ? error.message : String(error)];
+  }
+  const errors = error.errors;
+  if (!errors || errors.length === 0) {
+    return [error instanceof Error ? error.message : String(error)];
+  }
+  return errors.map((item) => {
+    const location = item.location?.file ? `${item.location.file}${item.location.line ? `:${item.location.line}` : ""}: ` : "";
+    return `${location}${item.text ?? "unknown esbuild error"}`;
+  });
+}
+function removePublishedArtifact(outfile, metadataFile) {
+  fs29.rmSync(outfile, { force: true });
+  fs29.rmSync(metadataFile, { force: true });
+}
+function bestEffortRemove(targetPath, options = {}) {
+  if (!targetPath) {
+    return;
+  }
+  try {
+    fs29.rmSync(targetPath, { force: true, recursive: options.recursive });
+  } catch {
+  }
+}
+function outputPathConflicts(entryPath, packageJsonPath, outfile, metadataFile) {
+  const reasons = [];
+  if (outfile === metadataFile) {
+    reasons.push("bundle \u4E0E metadata \u8F93\u51FA\u8DEF\u5F84\u4E0D\u80FD\u76F8\u540C");
+  }
+  const protectedInputs = /* @__PURE__ */ new Map([
+    [entryPath, "Nest \u7F16\u8BD1\u5165\u53E3"],
+    [packageJsonPath, "package.json"]
+  ]);
+  for (const [outputPath, outputName] of [
+    [outfile, "bundle"],
+    [metadataFile, "metadata"]
+  ]) {
+    const protectedName = protectedInputs.get(outputPath);
+    if (protectedName) {
+      reasons.push(
+        `${outputName} \u8F93\u51FA\u8DEF\u5F84\u4E0D\u80FD\u8986\u76D6 ${protectedName}: ${outputPath}`
+      );
+    }
+  }
+  return reasons;
+}
+async function buildPreviewServerArtifact(options) {
+  const startedAt = Date.now();
+  const projectRoot = path25.resolve(options.projectRoot);
+  const entryPath = toAbsolutePath(
+    projectRoot,
+    options.entry ?? "dist/main.js"
+  );
+  const outfile = toAbsolutePath(
+    projectRoot,
+    options.outfile ?? ".preview-artifact/server.bundle.cjs"
+  );
+  const metadataFile = toAbsolutePath(
+    projectRoot,
+    options.metadataFile ?? `${outfile}.meta.json`
+  );
+  const packageJsonPath = path25.join(projectRoot, "package.json");
+  let pluginCount = 0;
+  let outputCleared = false;
+  let phase = "\u6821\u9A8C\u8F93\u5165";
+  let tempRoot;
+  let tempOutputRoot;
+  let tempMetadataFile;
+  const failed = (reasons) => ({
+    built: false,
+    elapsedMs: Date.now() - startedAt,
+    pluginCount,
+    reasons
+  });
+  const pathConflicts = outputPathConflicts(
+    entryPath,
+    packageJsonPath,
+    outfile,
+    metadataFile
+  );
+  if (pathConflicts.length > 0) {
+    return failed(pathConflicts);
+  }
+  if (!fs29.existsSync(entryPath)) {
+    return failed([`Nest \u7F16\u8BD1\u5165\u53E3\u4E0D\u5B58\u5728: ${entryPath}`]);
+  }
+  if (!fs29.existsSync(packageJsonPath)) {
+    return failed([`package.json \u4E0D\u5B58\u5728: ${packageJsonPath}`]);
+  }
+  try {
+    phase = `\u89E3\u6790 ${packageJsonPath}`;
+    const packageJson = readJson(packageJsonPath);
+    phase = "\u89E3\u6790 Action Plugin";
+    const { plugins, reasons } = resolveActionPlugins(projectRoot, packageJson);
+    pluginCount = plugins.length;
+    phase = "\u6E05\u7406\u65E7 Preview Artifact";
+    removePublishedArtifact(outfile, metadataFile);
+    outputCleared = true;
+    if (reasons.length > 0) {
+      return failed(reasons);
+    }
+    phase = "\u521B\u5EFA Preview Artifact \u4E34\u65F6\u76EE\u5F55";
+    fs29.mkdirSync(path25.dirname(outfile), { recursive: true });
+    fs29.mkdirSync(path25.dirname(metadataFile), { recursive: true });
+    tempRoot = fs29.mkdtempSync(
+      path25.join(os3.tmpdir(), "preview-server-artifact-")
+    );
+    tempOutputRoot = fs29.mkdtempSync(
+      path25.join(path25.dirname(outfile), ".preview-server-artifact-")
+    );
+    const bootstrapPath = path25.join(tempRoot, "bootstrap.cjs");
+    const tempOutfile = path25.join(tempOutputRoot, path25.basename(outfile));
+    tempMetadataFile = path25.join(
+      path25.dirname(metadataFile),
+      `.${path25.basename(metadataFile)}.${process.pid}.${Date.now()}.tmp`
+    );
+    fs29.writeFileSync(bootstrapPath, generateBootstrap(entryPath, plugins));
+    const optionalDependencies = optionalDependencyStubPlugin();
+    const buildOptions = {
+      absWorkingDir: projectRoot,
+      entryPoints: [bootstrapPath],
+      outfile: tempOutfile,
+      bundle: true,
+      platform: "node",
+      format: "cjs",
+      target: "node22",
+      treeShaking: true,
+      keepNames: true,
+      legalComments: "none",
+      sourcemap: false,
+      metafile: true,
+      logLevel: "silent",
+      plugins: [
+        classTransformerStorageResolver(projectRoot),
+        optionalDependencies.plugin
+      ]
+    };
+    phase = "\u6267\u884C esbuild";
+    const buildResult2 = await build(buildOptions);
+    if (!buildResult2.metafile) {
+      throw new Error("esbuild \u672A\u8FD4\u56DE metafile");
+    }
+    const externalImports = collectExternalImports(
+      buildResult2.metafile,
+      tempOutfile
+    );
+    if (externalImports.length > 0) {
+      return failed([`bundle \u6B8B\u7559\u8FD0\u884C\u65F6\u4F9D\u8D56: ${externalImports.join(", ")}`]);
+    }
+    phase = "\u5BA1\u8BA1 bundle \u8FD0\u884C\u65F6\u95ED\u5305";
+    const stubbedOptionalDependencies = Array.from(
+      optionalDependencies.stubbedDependencies
+    ).sort();
+    const closureRisks = auditBundleClosure(
+      tempOutfile,
+      stubbedOptionalDependencies
+    );
+    const closureStatus = closureRisks.length === 0 ? "static-audit-clean" : "runtime-validation-required";
+    const metadata = {
+      version: 1,
+      entry: entryPath,
+      outfile,
+      bundleBytes: fs29.statSync(tempOutfile).size,
+      inputFiles: Object.keys(buildResult2.metafile.inputs).length,
+      externalImports,
+      actionPlugins: plugins.map((plugin) => plugin.name),
+      closureStatus,
+      closureRisks,
+      stubbedOptionalDependencies,
+      runtimeProbeStatus: "not-run",
+      consumable: false,
+      elapsedMs: Date.now() - startedAt
+    };
+    phase = "\u53D1\u5E03 bundle \u4E0E metadata";
+    fs29.writeFileSync(
+      tempMetadataFile,
+      `${JSON.stringify(metadata, null, 2)}
+`
+    );
+    fs29.renameSync(tempOutfile, outfile);
+    fs29.renameSync(tempMetadataFile, metadataFile);
+    return {
+      built: true,
+      outfile,
+      metadataFile,
+      bundleBytes: metadata.bundleBytes,
+      inputFiles: metadata.inputFiles,
+      externalImports,
+      pluginCount,
+      closureStatus,
+      closureRisks,
+      stubbedOptionalDependencies,
+      runtimeProbeStatus: "not-run",
+      consumable: false,
+      elapsedMs: metadata.elapsedMs
+    };
+  } catch (error) {
+    const reasons = formatBuildError(error).map(
+      (reason) => `${phase}: ${reason}`
+    );
+    if (outputCleared) {
+      try {
+        removePublishedArtifact(outfile, metadataFile);
+      } catch (cleanupError) {
+        reasons.push(
+          `\u6E05\u7406\u5931\u8D25\u4EA7\u7269: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`
+        );
+      }
+    }
+    return failed(reasons);
+  } finally {
+    bestEffortRemove(tempRoot, { recursive: true });
+    bestEffortRemove(tempOutputRoot, { recursive: true });
+    bestEffortRemove(tempMetadataFile);
+  }
+}
+
 // src/commands/build/index.ts
 var getTokenCommand = {
   name: "get-token",
@@ -8126,10 +8647,34 @@ var preUploadStaticCommand = {
     });
   }
 };
+var previewServerArtifactCommand = {
+  name: "preview-server-artifact",
+  description: "Build and audit a single-file Nest preview server artifact",
+  register(program) {
+    program.command(this.name).description(this.description).option("--project-root <dir>", "Application project root", process.cwd()).option("--entry <file>", "Compiled Nest entry", "dist/main.js").option(
+      "--outfile <file>",
+      "Output bundle",
+      ".preview-artifact/server.bundle.cjs"
+    ).option("--metadata-file <file>", "Output build metadata file").action(
+      async (options) => {
+        const result = await buildPreviewServerArtifact(options);
+        console.log(JSON.stringify(result));
+        if (!result.built) {
+          process.exitCode = 2;
+        }
+      }
+    );
+  }
+};
 var buildCommandGroup = {
   name: "build",
   description: "Build related commands",
-  commands: [getTokenCommand, uploadStaticCommand, preUploadStaticCommand]
+  commands: [
+    getTokenCommand,
+    uploadStaticCommand,
+    preUploadStaticCommand,
+    previewServerArtifactCommand
+  ]
 };
 
 // src/commands/index.ts
@@ -8146,12 +8691,12 @@ var commands = [
 ];
 
 // src/index.ts
-var envPath = path25.join(process.cwd(), ".env");
-if (fs29.existsSync(envPath)) {
+var envPath = path26.join(process.cwd(), ".env");
+if (fs30.existsSync(envPath)) {
   dotenvConfig({ path: envPath });
 }
-var __dirname = path25.dirname(fileURLToPath5(import.meta.url));
-var pkg = JSON.parse(fs29.readFileSync(path25.join(__dirname, "../package.json"), "utf-8"));
+var __dirname = path26.dirname(fileURLToPath5(import.meta.url));
+var pkg = JSON.parse(fs30.readFileSync(path26.join(__dirname, "../package.json"), "utf-8"));
 var cli = new FullstackCLI(pkg.version);
 cli.useAll(commands);
 cli.run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "1.1.59-alpha.2",
+  "version": "1.1.59-alpha.20260717162925",
   "description": "CLI tool for fullstack template management",
   "type": "module",
   "main": "dist/index.js",
@@ -34,12 +34,15 @@
     "@lark-apaas/http-client": "^0.1.7",
     "@lydell/node-pty": "1.1.0",
     "@vercel/nft": "^0.30.3",
+    "acorn": "^8.16.0",
+    "acorn-walk": "^8.3.5",
     "commander": "^13.0.0",
     "debug": "^4.4.3",
     "dotenv": "^16.0.0",
     "drizzle-kit": "0.31.5",
     "drizzle-orm": "0.44.6",
     "es-toolkit": "^1.44.0",
+    "esbuild": "^0.27.0",
     "inflection": "^3.0.2",
     "pinyin-pro": "^3.27.0",
     "postgres": "^3.4.3",

package/templates/nest-cli.json

@@ -21,5 +21,9 @@
         }
       }
     ]
+  },
+  "x-miaoda-preview": {
+    "compiler": "swc",
+    "typeCheck": "deferred"
   }
-}
+}

package/templates/scripts/dev.js

@@ -3,10 +3,15 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawn, execSync } = require('child_process');
+const { spawn, execFileSync, execSync } = require('child_process');
 const readline = require('readline');
 const {
+  buildListeningPortLookupArgs,
+  createDeferredTypecheckGate,
   createPreviewPhaseReporter,
+  normalizeTcpPort,
+  parseTscWatchSummary,
+  resolvePreviewServerCommand,
   waitForTcpReady,
 } = require('./preview-startup-timing.cjs');
 
@@ -40,8 +45,12 @@ const MAX_RESTART_COUNT = process.env.MAX_RESTART_COUNT != null && process.env.M
   : Infinity;
 const RESTART_DELAY = parseInt(process.env.RESTART_DELAY, 10) || 2;
 const MAX_DELAY = 8;
-const SERVER_PORT = process.env.SERVER_PORT || '3000';
-const CLIENT_DEV_PORT = process.env.CLIENT_DEV_PORT || '8080';
+const SERVER_PORT = normalizeTcpPort(process.env.SERVER_PORT, 3000, 'SERVER_PORT');
+const CLIENT_DEV_PORT = normalizeTcpPort(
+  process.env.CLIENT_DEV_PORT,
+  8080,
+  'CLIENT_DEV_PORT'
+);
 
 fs.mkdirSync(LOG_DIR, { recursive: true });
 
@@ -102,16 +111,38 @@ function killProcessGroup(pid, signal) {
 
 function killOrphansByPort(port) {
   try {
-    const pids = execSync(`lsof -ti :${port}`, { encoding: 'utf8', timeout: 5000 }).trim();
-    if (pids) {
-      const pidList = pids.split('\n').filter(Boolean);
-      for (const p of pidList) {
-        try { process.kill(parseInt(p, 10), 'SIGKILL'); } catch {}
+    const output = execFileSync('lsof', buildListeningPortLookupArgs(port), {
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
+    const killedPids = [];
+    const failures = [];
+    if (output) {
+      for (const pidText of output.split('\n').filter(Boolean)) {
+        const pid = Number(pidText);
+        try {
+          process.kill(pid, 'SIGKILL');
+          killedPids.push(pidText);
+        } catch (error) {
+          if (error?.code !== 'ESRCH') {
+            failures.push(
+              `${pidText}: ${error instanceof Error ? error.message : String(error)}`
+            );
+          }
+        }
       }
-      return pidList;
     }
-  } catch {}
-  return [];
+    return {
+      pids: killedPids,
+      error: failures.length > 0 ? failures.join('; ') : null,
+    };
+  } catch (error) {
+    if (error?.status === 1) return { pids: [], error: null };
+    return {
+      pids: [],
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
 }
 
 // ── Process supervision ───────────────────────────────────────────────────────
@@ -126,7 +157,7 @@ function sleep(ms) {
  * Start and supervise a process with auto-restart and log piping.
  * Returns a promise that resolves when the process loop ends.
  */
-function startProcess({ name, command, args, cleanupPort }) {
+function startProcess({ name, command, args, cleanupPort, phaseDetail = {}, onReady, onOutputLine }) {
   const logFilePath = path.join(LOG_DIR, `${name}.std.log`);
   const logFd = fs.openSync(logFilePath, 'a');
 
@@ -136,6 +167,30 @@ function startProcess({ name, command, args, cleanupPort }) {
   const run = async () => {
     let restartCount = 0;
 
+    if (cleanupPort) {
+      const portCleanup = killOrphansByPort(cleanupPort);
+      const stalePids = portCleanup.pids;
+      logEvent(
+        portCleanup.error ? 'ERROR' : stalePids.length > 0 ? 'WARN' : 'INFO',
+        name,
+        portCleanup.error
+          ? `Port ${cleanupPort} preflight failed: ${portCleanup.error}`
+          : stalePids.length > 0
+          ? `Killed stale processes on port ${cleanupPort} before first spawn: ${stalePids.join(' ')}`
+          : `Port ${cleanupPort} is clear before first spawn`
+      );
+      previewPhaseReporter.emit(
+        name === 'server' ? 'backend_port_preflight' : 'client_port_preflight',
+        portCleanup.error ? 'error' : 'success',
+        {
+          exact: true,
+          cleanup_count: stalePids.length,
+          ...(portCleanup.error ? { error: portCleanup.error } : {}),
+        }
+      );
+      if (stalePids.length > 0) await sleep(500);
+    }
+
     while (!stopping) {
       const child = spawn(command, args, {
         detached: true,
@@ -151,11 +206,17 @@ function startProcess({ name, command, args, cleanupPort }) {
       const startTime = Date.now();
       const attempt = restartCount + 1;
       logEvent('INFO', name, `Process started (PGID: ${child.pid}): ${command} ${args.join(' ')}`);
-      const processPhase = name === 'server' ? 'backend_process_spawn' : 'client_process_spawn';
+      const processPhase =
+        name === 'server'
+          ? 'backend_process_spawn'
+          : name === 'server-typecheck'
+            ? 'backend_typecheck_process_spawn'
+            : 'client_process_spawn';
       previewPhaseReporter.emit(processPhase, 'success', {
         at_ms: startTime,
         attempt,
         exact: true,
+        ...phaseDetail,
       });
       if (name === 'server') {
         void waitForTcpReady({
@@ -164,29 +225,60 @@ function startProcess({ name, command, args, cleanupPort }) {
           interval_ms: 50,
           timeout_ms: 120000,
           should_continue: () => entry.child === child && !stopping,
-        }).then((result) => {
-          if (result.cancelled) return;
-          previewPhaseReporter.emit(
-            'backend_tcp_ready',
-            result.ready ? 'success' : 'error',
-            { ...result, attempt, exact: false }
-          );
-        }).catch((error) => {
-          if (entry.child !== child || stopping) return;
-          previewPhaseReporter.emit('backend_tcp_ready', 'error', {
-            duration_ms: Date.now() - startTime,
-            attempt,
-            exact: false,
-            precision_ms: 50,
-            error: error instanceof Error ? error.message : String(error),
+        })
+          .then(result => {
+            if (result.cancelled) return;
+            previewPhaseReporter.emit(
+              'backend_tcp_ready',
+              result.ready ? 'success' : 'error',
+              { ...result, attempt, exact: false }
+            );
+            if (result.ready && onReady) {
+              try {
+                onReady(result);
+              } catch (error) {
+                logEvent(
+                  'ERROR',
+                  name,
+                  `Backend ready callback failed: ${error instanceof Error ? error.message : String(error)}`
+                );
+              }
+            }
+          })
+          .catch(error => {
+            if (entry.child !== child || stopping) return;
+            previewPhaseReporter.emit('backend_tcp_ready', 'error', {
+              duration_ms: Date.now() - startTime,
+              attempt,
+              exact: false,
+              precision_ms: 50,
+              error: error instanceof Error ? error.message : String(error),
+            });
           });
-        });
       }
 
       // Pipe stdout and stderr through readline for timestamped logging
+      let typecheckSummaryReported = false;
       const pipeLines = (stream) => {
         const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
         rl.on('line', (line) => {
+          if (onOutputLine) onOutputLine(line);
+          if (name === 'server-typecheck' && !typecheckSummaryReported) {
+            const summary = parseTscWatchSummary(line);
+            if (summary) {
+              typecheckSummaryReported = true;
+              previewPhaseReporter.emit(
+                'backend_typecheck_ready',
+                summary.passed ? 'success' : 'error',
+                {
+                  duration_ms: Date.now() - startTime,
+                  attempt,
+                  exact: true,
+                  ...summary,
+                }
+              );
+            }
+          }
           const msg = `[${timestamp()}] [${name}] ${line}\n`;
           try { fs.writeSync(logFd, msg); } catch {}
           writeOutput(msg);
@@ -215,7 +307,15 @@ function startProcess({ name, command, args, cleanupPort }) {
 
       // Port cleanup fallback
       if (cleanupPort) {
-        const orphans = killOrphansByPort(cleanupPort);
+        const portCleanup = killOrphansByPort(cleanupPort);
+        const orphans = portCleanup.pids;
+        if (portCleanup.error) {
+          logEvent(
+            'ERROR',
+            name,
+            `Port ${cleanupPort} cleanup failed: ${portCleanup.error}`
+          );
+        }
         if (orphans.length > 0) {
           logEvent('WARN', name, `Killed orphan processes on port ${cleanupPort}: ${orphans.join(' ')}`);
           await sleep(500);
@@ -277,8 +377,12 @@ async function cleanup() {
   }
 
   // Port cleanup fallback
-  killOrphansByPort(SERVER_PORT);
-  killOrphansByPort(CLIENT_DEV_PORT);
+  for (const port of [SERVER_PORT, CLIENT_DEV_PORT]) {
+    const portCleanup = killOrphansByPort(port);
+    if (portCleanup.error) {
+      logEvent('ERROR', 'main', `Port ${port} cleanup failed: ${portCleanup.error}`);
+    }
+  }
 
   logEvent('INFO', 'main', 'All processes stopped');
 
@@ -332,11 +436,101 @@ async function main() {
   }
 
   // Start server and client
+  const serverCommand = resolvePreviewServerCommand({
+    project_root: PROJECT_ROOT,
+  });
+  logEvent(
+    'INFO',
+    'server',
+    `Selected ${serverCommand.compiler} compiler (${serverCommand.reason})`
+  );
+  previewPhaseReporter.emit('backend_compiler_selected', 'success', {
+    exact: true,
+    compiler: serverCommand.compiler,
+    type_check: serverCommand.type_check,
+    type_check_mode: serverCommand.type_check_mode,
+    reason: serverCommand.reason,
+    missing_modules: serverCommand.missing_modules,
+  });
+  const typecheckGate = createDeferredTypecheckGate();
+  let serverTypecheckStarted = false;
+  const startServerTypecheck = trigger => {
+    if (serverTypecheckStarted || !serverCommand.type_check_command) return;
+    try {
+      logEvent(
+        'INFO',
+        'server-typecheck',
+        `Starting deferred server type checker after ${trigger}`
+      );
+      previewPhaseReporter.emit('backend_typecheck_deferred_start', 'success', {
+        exact: true,
+        type_check_mode: serverCommand.type_check_mode,
+        trigger,
+      });
+      const typecheckPromise = startProcess({
+        name: 'server-typecheck',
+        command: serverCommand.type_check_command.command,
+        args: serverCommand.type_check_command.args,
+        phaseDetail: { type_check_mode: serverCommand.type_check_mode },
+      });
+      serverTypecheckStarted = true;
+      void typecheckPromise.catch(error => {
+        logEvent(
+          'ERROR',
+          'server-typecheck',
+          `Deferred server type checker failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      });
+    } catch (error) {
+      previewPhaseReporter.emit('backend_typecheck_deferred_start', 'error', {
+        exact: true,
+        type_check_mode: serverCommand.type_check_mode,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      logEvent(
+        'ERROR',
+        'server-typecheck',
+        `Failed to start deferred server type checker: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  };
+  const handleBackendReady = () => {
+    if (!serverCommand.type_check_command) return;
+    const decision = typecheckGate.onBackendReady();
+    if (decision.should_start) {
+      startServerTypecheck(decision.reason);
+      return;
+    }
+    logEvent(
+      'INFO',
+      'server-typecheck',
+      'Skipped type checking during initial preview startup'
+    );
+    previewPhaseReporter.emit('backend_typecheck_skipped', 'success', {
+      exact: true,
+      type_check_mode: serverCommand.type_check_mode,
+      reason: decision.reason,
+      next_trigger: 'source_change_or_backend_restart',
+    });
+  };
+  const handleServerOutput = line => {
+    if (!serverCommand.type_check_command || serverTypecheckStarted) return;
+    const decision = typecheckGate.onCompilerOutput(line);
+    if (decision?.should_start) startServerTypecheck(decision.reason);
+  };
   const serverPromise = startProcess({
     name: 'server',
-    command: 'npm',
-    args: ['run', 'dev:server'],
+    command: serverCommand.command,
+    args: serverCommand.args,
     cleanupPort: SERVER_PORT,
+    phaseDetail: {
+      compiler: serverCommand.compiler,
+      type_check: serverCommand.type_check,
+      type_check_mode: serverCommand.type_check_mode,
+      compiler_selection_reason: serverCommand.reason,
+    },
+    onReady: handleBackendReady,
+    onOutputLine: handleServerOutput,
   });
 
   const clientPromise = startProcess({

package/templates/scripts/preview-startup-timing.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
+const fs = require('fs');
 const net = require('net');
+const path = require('path');
 
 const PREFIX = '[MiaodaPreviewPhase] ';
 const RUN_ID_PATTERN = /^prv_[A-Za-z0-9_-]{1,128}$/;
@@ -37,6 +39,277 @@ function createPreviewPhaseReporter(options = {}) {
   return { emit };
 }
 
+function createTscServerCommand(reason, missingModules = []) {
+  return {
+    command: 'npm',
+    args: ['run', 'dev:server', '--', '--builder', 'tsc'],
+    compiler: 'tsc',
+    type_check: true,
+    type_check_mode: 'compiler_integrated',
+    type_check_command: null,
+    reason,
+    missing_modules: missingModules,
+  };
+}
+
+function normalizeTcpPort(value, fallback, name = 'TCP port') {
+  const candidate = value == null || value === '' ? fallback : value;
+  const serialized = String(candidate);
+  if (!/^\d+$/.test(serialized)) {
+    throw new Error(`${name} must be a valid TCP port`);
+  }
+  const port = Number(serialized);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`${name} must be a valid TCP port`);
+  }
+  return port;
+}
+
+function buildListeningPortLookupArgs(port) {
+  const validatedPort = normalizeTcpPort(port, 0);
+  return [`-tiTCP:${validatedPort}`, '-sTCP:LISTEN'];
+}
+
+function hasRuntimeCompilerPluginConsumer(projectRoot, sourceRoot) {
+  const root = path.resolve(projectRoot, sourceRoot || 'src');
+  const stack = [root];
+  let scannedFiles = 0;
+  let scannedBytes = 0;
+  const maxFiles = 2000;
+  const maxBytes = 16 * 1024 * 1024;
+  const consumerPatterns = [
+    /\bSwaggerModule\s*\.\s*(?:createDocument|loadPluginMetadata)\b/,
+    /\bcreateDocument\s*\(/,
+    /\bloadPluginMetadata\s*\(/,
+    /\bDevTools(?:V2)?Module\s*\.\s*mount\b/,
+  ];
+
+  if (!fs.existsSync(root)) return true;
+
+  try {
+    while (stack.length > 0) {
+      const current = stack.pop();
+      for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          if (!['node_modules', 'dist', '.git'].includes(entry.name)) {
+            stack.push(path.join(current, entry.name));
+          }
+          continue;
+        }
+        if (!entry.isFile() || !/\.(?:[cm]?js|tsx?)$/.test(entry.name)) {
+          continue;
+        }
+        scannedFiles += 1;
+        const filePath = path.join(current, entry.name);
+        const stat = fs.statSync(filePath);
+        scannedBytes += stat.size;
+        if (scannedFiles > maxFiles || scannedBytes > maxBytes) return true;
+        const source = fs.readFileSync(filePath, 'utf8');
+        if (consumerPatterns.some(pattern => pattern.test(source))) return true;
+      }
+    }
+  } catch {
+    // If we cannot prove the compiler plugin is unobservable at runtime, keep TSC.
+    return true;
+  }
+  return false;
+}
+
+function resolvePreviewServerCommand(options = {}) {
+  const projectRoot = options.project_root || path.resolve(__dirname, '..');
+  let packageJson = options.package_json;
+  if (!packageJson) {
+    try {
+      packageJson = JSON.parse(
+        fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8')
+      );
+    } catch {
+      packageJson = {};
+    }
+  }
+
+  let nestCliConfig = options.nest_cli_config;
+  if (!nestCliConfig) {
+    try {
+      nestCliConfig = JSON.parse(
+        fs.readFileSync(path.join(projectRoot, 'nest-cli.json'), 'utf8')
+      );
+    } catch {
+      nestCliConfig = {};
+    }
+  }
+
+  const serverScript = packageJson?.scripts?.['dev:server'] || '';
+  const normalizedServerScript = serverScript
+    .trim()
+    .replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*/, '')
+    .replace(/\s+/g, ' ');
+  const isNestWatchScript = normalizedServerScript === 'nest start --watch';
+  if (!isNestWatchScript) {
+    return {
+      command: 'npm',
+      args: ['run', 'dev:server'],
+      compiler: 'configured',
+      type_check: false,
+      type_check_mode: 'configured',
+      type_check_command: null,
+      reason: 'custom_server_script',
+      missing_modules: [],
+    };
+  }
+
+  const configuredBuilder = nestCliConfig?.compilerOptions?.builder;
+  if (configuredBuilder && configuredBuilder !== 'tsc') {
+    return {
+      command: 'npm',
+      args: ['run', 'dev:server'],
+      compiler: 'configured',
+      type_check: false,
+      type_check_mode: 'configured',
+      type_check_command: null,
+      reason: 'custom_nest_builder',
+      missing_modules: [],
+    };
+  }
+
+  const serverTypecheckScript =
+    packageJson?.scripts?.['type:check:server'] || '';
+  const normalizedTypecheckScript = serverTypecheckScript
+    .trim()
+    .replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*/, '')
+    .replace(/\s+/g, ' ');
+  const isNonEmittingTscScript =
+    /^(?:npx )?tsc --noEmit --project [A-Za-z0-9_./-]+$/.test(
+      normalizedTypecheckScript
+    );
+  if (!isNonEmittingTscScript) {
+    return createTscServerCommand('server_typecheck_script_unavailable');
+  }
+
+  const previewCapability = nestCliConfig?.['x-miaoda-preview'];
+  if (
+    previewCapability?.compiler !== 'swc' ||
+    previewCapability?.typeCheck !== 'deferred'
+  ) {
+    return createTscServerCommand('preview_swc_capability_not_declared');
+  }
+
+  const compilerPlugins = Array.isArray(nestCliConfig?.compilerOptions?.plugins)
+    ? nestCliConfig.compilerOptions.plugins
+    : [];
+  const compilerPluginNames = compilerPlugins.map(plugin =>
+    typeof plugin === 'string' ? plugin : plugin?.name || ''
+  );
+  if (
+    compilerPluginNames.some(pluginName => pluginName !== '@nestjs/swagger')
+  ) {
+    return createTscServerCommand('unsupported_nest_compiler_plugins');
+  }
+  if (compilerPluginNames.includes('@nestjs/swagger')) {
+    const runtimeConsumer =
+      typeof options.has_runtime_compiler_plugin_consumer === 'boolean'
+        ? options.has_runtime_compiler_plugin_consumer
+        : hasRuntimeCompilerPluginConsumer(
+            projectRoot,
+            nestCliConfig?.sourceRoot || 'src'
+          );
+    if (runtimeConsumer) {
+      return createTscServerCommand(
+        'runtime_compiler_plugin_consumer_detected'
+      );
+    }
+  }
+
+  const resolveModule =
+    options.resolve_module ||
+    (moduleName => {
+      const resolved = require.resolve(moduleName, { paths: [projectRoot] });
+      if (moduleName === '@swc/core') {
+        const swc = require(resolved);
+        if (typeof swc.transformSync !== 'function') {
+          throw new Error('@swc/core native binding is unavailable');
+        }
+      }
+      return resolved;
+    });
+  const requiredModules = ['@swc/cli', '@swc/core'];
+  const missingModules = requiredModules.filter(moduleName => {
+    try {
+      resolveModule(moduleName);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+
+  if (missingModules.length > 0) {
+    return createTscServerCommand('swc_dependencies_missing', missingModules);
+  }
+
+  return {
+    command: 'npm',
+    args: ['run', 'dev:server', '--', '--builder', 'swc'],
+    compiler: 'swc',
+    type_check: true,
+    type_check_mode: 'deferred_tsc_watch',
+    type_check_command: {
+      command: 'npm',
+      args: [
+        'run',
+        'type:check:server',
+        '--',
+        '--watch',
+        '--preserveWatchOutput',
+        '--locale',
+        'en',
+      ],
+    },
+    reason: 'swc_dependencies_ready',
+    missing_modules: [],
+  };
+}
+
+function createDeferredTypecheckGate() {
+  let initialBackendReadySeen = false;
+
+  return {
+    onBackendReady() {
+      if (!initialBackendReadySeen) {
+        initialBackendReadySeen = true;
+        return {
+          should_start: false,
+          reason: 'initial_preview_startup',
+        };
+      }
+      return {
+        should_start: true,
+        reason: 'backend_restart',
+      };
+    },
+    onCompilerOutput(line) {
+      if (
+        !initialBackendReadySeen ||
+        !/Successfully compiled:\s+\d+\s+files?\s+with\s+swc\b/i.test(line)
+      ) {
+        return null;
+      }
+      return {
+        should_start: true,
+        reason: 'source_change',
+      };
+    },
+  };
+}
+
+function parseTscWatchSummary(line) {
+  const match = /Found\s+(\d+)\s+errors?\.\s+Watching for file changes\./i.exec(
+    line
+  );
+  if (!match) return null;
+  const errorCount = Number(match[1]);
+  return { error_count: errorCount, passed: errorCount === 0 };
+}
+
 function connectTcpOnce({ host, port, timeout_ms }) {
   return new Promise(resolve => {
     const socket = net.createConnection({ host, port });
@@ -127,6 +400,11 @@ async function waitForTcpReady(options) {
 }
 
 module.exports = {
+  buildListeningPortLookupArgs,
+  createDeferredTypecheckGate,
   createPreviewPhaseReporter,
+  normalizeTcpPort,
+  parseTscWatchSummary,
+  resolvePreviewServerCommand,
   waitForTcpReady,
 };