@lark-apaas/fullstack-cli 1.1.59-alpha.20260718151739 → 1.1.59-alpha.20260719084243

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import fs35 from "fs";
-import path31 from "path";
+import fs37 from "fs";
+import path33 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((resolve8) => {
+  return new Promise((resolve9) => {
     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();
-      resolve8({
+      resolve9({
         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);
-      resolve8({
+      resolve9({
         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((resolve8) => {
+  return new Promise((resolve9) => {
     execFile("fullstack-cli", ["action-plugin", "init"], { cwd: process.cwd(), stdio: "ignore" }, (error) => {
       if (error) {
         debug("action-plugin init \u5931\u8D25: %s", error.message);
       }
-      resolve8();
+      resolve9();
     });
   });
 }
@@ -8624,19 +8624,58 @@ async function buildPreviewServerArtifact(options) {
 
 // src/commands/preview-artifact/producer.ts
 import * as crypto2 from "crypto";
-import * as fs33 from "fs";
-import * as path29 from "path";
+import * as fs34 from "fs";
+import * as path30 from "path";
 import { spawnSync as spawnSync8 } from "child_process";
 
 // src/commands/preview-artifact/generation.ts
 import * as crypto from "crypto";
 import * as fs30 from "fs";
 import * as path26 from "path";
-var PREVIEW_ARTIFACT_SCHEMA_VERSION = 1;
+var PREVIEW_ARTIFACT_SCHEMA_VERSION = 2;
+var PREVIEW_ARTIFACT_PROTOCOL_VERSION = 2;
 var MANIFEST_FILE = "manifest.json";
 var PROBE_FILE = "probe.json";
 var SERVER_FILE = "server.bundle.cjs";
 var CLIENT_FILE = "client.zip";
+var RUNTIME_ONLY_ENVIRONMENT_KEYS = /* @__PURE__ */ new Set([
+  "CLIENT_DEV_HOST",
+  "CLIENT_DEV_PORT",
+  "FORCE_AUTHN_ACCESS_KEY",
+  "FORCE_AUTHN_ACCESS_SECRET",
+  "FORCE_AUTHN_PREVIEW_SESSION_ID",
+  "MIAODA_HMR_WS_TOKEN",
+  "MIAODA_PREVIEW_RUN_ID",
+  "PREVIEW_RUN_ID",
+  "SANDBOX_COOKIE",
+  "SANDBOX_ID",
+  "SERVER_PORT",
+  "preview_run_id"
+]);
+var RUNTIME_ONLY_ENVIRONMENT_PREFIXES = ["PREVIEW_ARTIFACT_"];
+function previewArtifactBuildEnvironment(environment, appBasePath) {
+  const buildEnvironment = {};
+  for (const [key, value] of Object.entries(environment ?? {})) {
+    if (typeof value === "string" && !RUNTIME_ONLY_ENVIRONMENT_KEYS.has(key) && !RUNTIME_ONLY_ENVIRONMENT_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+      buildEnvironment[key] = value;
+    }
+  }
+  buildEnvironment.CLIENT_BASE_PATH = appBasePath;
+  buildEnvironment.NODE_ENV = environment?.NODE_ENV ?? "production";
+  return buildEnvironment;
+}
+function previewArtifactBuildEnvironmentHash(environment, appBasePath) {
+  const buildEnvironment = previewArtifactBuildEnvironment(
+    environment,
+    appBasePath
+  );
+  const canonical = Object.fromEntries(
+    Object.entries(buildEnvironment).sort(
+      ([left], [right]) => left.localeCompare(right)
+    )
+  );
+  return crypto.createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
 function parseNodeMajor(nodeVersion) {
   const match = /^v?(\d+)(?:\.|$)/.exec(nodeVersion.trim());
   if (!match) {
@@ -8683,8 +8722,10 @@ function createPreviewArtifactManifest(options) {
   const generationDir = path26.resolve(options.generationDir);
   const manifest = {
     schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
+    protocolVersion: PREVIEW_ARTIFACT_PROTOCOL_VERSION,
     generationId: options.generationId,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    buildEnvironmentSha256: options.buildEnvironmentSha256,
     runtime: runtimeIdentity(
       options.nodeVersion,
       options.platform,
@@ -8723,6 +8764,7 @@ function recordPreviewArtifactProbe(options) {
     coverage: {
       html: options.coverage.html,
       businessApi: options.coverage.businessApi,
+      clientAssets: Array.from(new Set(options.coverage.clientAssets)).sort(),
       actionPlugins: Array.from(new Set(options.coverage.actionPlugins)).sort()
     }
   };
@@ -8777,6 +8819,9 @@ function promotePreviewArtifactGeneration(generationDirInput) {
   if (!probe.coverage.businessApi) {
     reasons.push("probe did not verify business API");
   }
+  if (!Array.isArray(probe.coverage.clientAssets) || probe.coverage.clientAssets.length === 0) {
+    reasons.push("probe did not verify client entry assets");
+  }
   const verifiedPlugins = new Set(probe.coverage.actionPlugins);
   const missingPlugins = manifest.actionPlugins.filter(
     (plugin) => !verifiedPlugins.has(plugin)
@@ -8804,11 +8849,18 @@ import * as net from "net";
 import * as os4 from "os";
 import * as path27 from "path";
 import { spawn as spawn2, spawnSync as spawnSync7 } from "child_process";
+
+// src/commands/preview-artifact/readiness.ts
+function isPreviewBusinessResponseReady(response) {
+  return response.status !== 404 && response.status < 500 && !response.headers.get("content-type")?.includes("text/html");
+}
+
+// src/commands/preview-artifact/probe.ts
 function sleep(ms) {
-  return new Promise((resolve8) => setTimeout(resolve8, ms));
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
 }
 async function reservePort() {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const server = net.createServer();
     server.unref();
     server.once("error", reject);
@@ -8820,7 +8872,7 @@ async function reservePort() {
       }
       server.close((error) => {
         if (error) reject(error);
-        else resolve8(address.port);
+        else resolve9(address.port);
       });
     });
   });
@@ -8871,6 +8923,77 @@ function rejectSymlinks(root) {
     }
   }
 }
+function isPathInside(parent, candidate) {
+  const relative5 = path27.relative(parent, candidate);
+  return relative5 !== "" && relative5 !== ".." && !relative5.startsWith(`..${path27.sep}`) && !path27.isAbsolute(relative5);
+}
+function clientEntryAssetReferences(html, appBasePath) {
+  const local = /* @__PURE__ */ new Set();
+  const localExecutable = /* @__PURE__ */ new Set();
+  const unsupportedExternal = /* @__PURE__ */ new Set();
+  const tags = /<(script|link)\b[^>]*>/gi;
+  const readAttribute = (tag, name) => new RegExp(`\\b${name}=["']([^"']+)["']`, "i").exec(tag)?.[1];
+  const base = new URL(appBasePath, "http://preview.local");
+  for (const match of html.matchAll(tags)) {
+    const tagName = match[1]?.toLowerCase();
+    const tag = match[0];
+    let linkRel = [];
+    if (tagName === "link") {
+      linkRel = readAttribute(tag, "rel")?.toLowerCase().split(/\s+/) ?? [];
+      if (!linkRel.some(
+        (value2) => [
+          "stylesheet",
+          "modulepreload",
+          "preload",
+          "icon",
+          "manifest"
+        ].includes(value2)
+      )) {
+        continue;
+      }
+    }
+    const value = readAttribute(
+      tag,
+      tagName === "script" ? "src" : "href"
+    )?.trim();
+    if (!value || value.startsWith("data:") || value.startsWith("#")) continue;
+    const resolved = new URL(value, base);
+    if (resolved.origin !== base.origin) {
+      if (tagName === "script" || linkRel.some(
+        (value2) => ["stylesheet", "modulepreload", "preload"].includes(value2)
+      )) {
+        unsupportedExternal.add(resolved.toString());
+      }
+      continue;
+    }
+    local.add(resolved.pathname);
+    if (tagName === "script") localExecutable.add(resolved.pathname);
+  }
+  return {
+    local: Array.from(local).sort(),
+    localExecutable: Array.from(localExecutable).sort(),
+    unsupportedExternal: Array.from(unsupportedExternal).sort()
+  };
+}
+function resolveClientEntryAsset(clientRoot, appBasePath, requestPath) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(requestPath);
+  } catch {
+    return void 0;
+  }
+  const normalizedBase = appBasePath.endsWith("/") ? appBasePath : `${appBasePath}/`;
+  const relative5 = decoded.startsWith(normalizedBase) ? decoded.slice(normalizedBase.length) : decoded.replace(/^\/+/, "");
+  if (!relative5 || relative5 === "index.html") return void 0;
+  const candidate = path27.resolve(clientRoot, relative5);
+  if (!isPathInside(clientRoot, candidate)) return void 0;
+  try {
+    const stat = fs31.lstatSync(candidate);
+    return stat.isFile() && !stat.isSymbolicLink() ? candidate : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function extractClientArchive(archivePath, destination) {
   if (fs31.existsSync(destination)) {
     throw new Error("client archive destination must not already exist");
@@ -8928,6 +9051,7 @@ async function runPreviewArtifactProbe(options) {
   const coverage = {
     html: false,
     businessApi: false,
+    clientAssets: [],
     actionPlugins: []
   };
   const reasons = [];
@@ -8940,10 +9064,8 @@ async function runPreviewArtifactProbe(options) {
       path27.join(generationDir, "server.bundle.cjs"),
       runtimeBundle
     );
-    extractClientArchive(
-      path27.join(generationDir, "client.zip"),
-      path27.join(runtimeRoot, "dist", "client")
-    );
+    const clientRoot = path27.join(runtimeRoot, "dist", "client");
+    extractClientArchive(path27.join(generationDir, "client.zip"), clientRoot);
     isolatedNodeModulesPresent = fs31.existsSync(
       path27.join(runtimeRoot, "node_modules")
     );
@@ -8974,12 +9096,34 @@ async function runPreviewArtifactProbe(options) {
         `HTML probe failed with status ${htmlResponse?.status ?? "unreachable"}`
       );
     }
+    if (coverage.html && htmlResponse) {
+      const html = await htmlResponse.text();
+      const entryReferences = clientEntryAssetReferences(
+        html,
+        options.appBasePath
+      );
+      const entryAssets = entryReferences.local;
+      coverage.clientAssets = entryReferences.localExecutable;
+      if (entryReferences.localExecutable.length === 0) {
+        reasons.push("client HTML has no local executable entry asset");
+      }
+      for (const externalAsset of entryReferences.unsupportedExternal) {
+        reasons.push(
+          `external client entry asset is unsupported: ${externalAsset}`
+        );
+      }
+      for (const entryAsset of entryAssets) {
+        if (!resolveClientEntryAsset(clientRoot, options.appBasePath, entryAsset)) {
+          reasons.push(`client entry asset is unavailable: ${entryAsset}`);
+        }
+      }
+    }
     const apiResponse = await fetchUntil(
       new URL(options.businessApiPath, origin).toString(),
       timeoutAt
     );
     coverage.businessApi = Boolean(
-      apiResponse && apiResponse.status !== 404 && apiResponse.status < 500
+      apiResponse && isPreviewBusinessResponseReady(apiResponse)
     );
     if (!coverage.businessApi) {
       reasons.push(
@@ -8990,10 +9134,16 @@ async function runPreviewArtifactProbe(options) {
       await sleep(25);
     }
     if (fs31.existsSync(registryFile)) {
-      const parsed = JSON.parse(fs31.readFileSync(registryFile, "utf8"));
-      if (Array.isArray(parsed)) {
+      const parsed = JSON.parse(
+        fs31.readFileSync(registryFile, "utf8")
+      );
+      if (Array.isArray(parsed) && parsed.every((value) => typeof value === "string")) {
         coverage.actionPlugins = parsed.filter((value) => typeof value === "string").sort();
+      } else {
+        reasons.push("Action Plugin registry evidence is invalid");
       }
+    } else {
+      reasons.push("Action Plugin registry evidence is unavailable");
     }
   } catch (error) {
     reasons.push(error instanceof Error ? error.message : String(error));
@@ -9013,14 +9163,44 @@ async function runPreviewArtifactProbe(options) {
   return { ...probe, isolatedNodeModulesPresent };
 }
 
-// src/commands/preview-artifact/store.ts
+// src/commands/preview-artifact/environment.ts
 import * as fs32 from "fs";
 import * as path28 from "path";
+var ENVIRONMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function readPreviewArtifactEnvironmentFile(filePath) {
+  const resolved = path28.resolve(filePath);
+  const parsed = JSON.parse(fs32.readFileSync(resolved, "utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("preview artifact environment file must contain an object");
+  }
+  const environment = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!ENVIRONMENT_NAME.test(key) || typeof value !== "string") {
+      throw new Error(`invalid environment variable in ${resolved}: ${key}`);
+    }
+    environment[key] = value;
+  }
+  return environment;
+}
+function previewArtifactRuntimeEnvironment(environment) {
+  return {
+    ...environment,
+    NODE_ENV: environment?.NODE_ENV ?? "production",
+    // Probe and switcher connect through 127.0.0.1. Linux may resolve
+    // `localhost` to IPv6-only ::1, so the isolated Nest process must bind to
+    // the same explicit private endpoint instead of inheriting app defaults.
+    SERVER_HOST: "127.0.0.1"
+  };
+}
+
+// src/commands/preview-artifact/store.ts
+import * as fs33 from "fs";
+import * as path29 from "path";
 var GENERATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 function readCurrentPointer(storeRoot) {
   try {
     const pointer = readJson3(
-      path28.join(storeRoot, "current.json")
+      path29.join(storeRoot, "current.json")
     );
     return pointer.schemaVersion === PREVIEW_ARTIFACT_SCHEMA_VERSION && GENERATION_ID_PATTERN.test(pointer.generationId) ? pointer : void 0;
   } catch {
@@ -9028,25 +9208,25 @@ function readCurrentPointer(storeRoot) {
   }
 }
 function readJson3(filePath) {
-  return JSON.parse(fs32.readFileSync(filePath, "utf8"));
+  return JSON.parse(fs33.readFileSync(filePath, "utf8"));
 }
 function writeJsonAtomic2(filePath, value) {
-  fs32.mkdirSync(path28.dirname(filePath), { recursive: true });
+  fs33.mkdirSync(path29.dirname(filePath), { recursive: true });
   const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  fs32.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
+  fs33.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
 `, {
     mode: 384
   });
-  fs32.renameSync(temporaryPath, filePath);
+  fs33.renameSync(temporaryPath, filePath);
 }
 function pruneSupersededGenerations(generationsRoot, retainedGenerationIds) {
   const retained = new Set(retainedGenerationIds);
-  for (const entry of fs32.readdirSync(generationsRoot, {
+  for (const entry of fs33.readdirSync(generationsRoot, {
     withFileTypes: true
   })) {
     if (retained.has(entry.name)) continue;
     try {
-      fs32.rmSync(path28.join(generationsRoot, entry.name), {
+      fs33.rmSync(path29.join(generationsRoot, entry.name), {
         recursive: true,
         force: true
       });
@@ -9058,13 +9238,13 @@ function parseNodeMajor2(nodeVersion) {
   const match = /^v?(\d+)(?:\.|$)/.exec(nodeVersion.trim());
   return match ? Number(match[1]) : null;
 }
-function isPathInside(parent, candidate) {
-  const relative4 = path28.relative(parent, candidate);
-  return relative4 !== "" && !relative4.startsWith(`..${path28.sep}`) && relative4 !== ".." && !path28.isAbsolute(relative4);
+function isPathInside2(parent, candidate) {
+  const relative5 = path29.relative(parent, candidate);
+  return relative5 !== "" && !relative5.startsWith(`..${path29.sep}`) && relative5 !== ".." && !path29.isAbsolute(relative5);
 }
 function validateRegularDirectory(directoryPath, label) {
   try {
-    const stat = fs32.lstatSync(directoryPath);
+    const stat = fs33.lstatSync(directoryPath);
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
       return [`${label} must be a regular directory`];
     }
@@ -9085,10 +9265,10 @@ function validateGeneration(generationDir, runtime) {
   let probe;
   try {
     manifest = readJson3(
-      path28.join(generationDir, "manifest.json")
+      path29.join(generationDir, "manifest.json")
     );
     probe = readJson3(
-      path28.join(generationDir, "probe.json")
+      path29.join(generationDir, "probe.json")
     );
   } catch (error) {
     return {
@@ -9097,7 +9277,7 @@ function validateGeneration(generationDir, runtime) {
       ]
     };
   }
-  if (manifest.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION || probe.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION) {
+  if (manifest.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION || manifest.protocolVersion !== PREVIEW_ARTIFACT_PROTOCOL_VERSION || probe.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION) {
     reasons.push("generation schema version is incompatible");
   }
   if (!GENERATION_ID_PATTERN.test(manifest.generationId) || probe.generationId !== manifest.generationId) {
@@ -9109,8 +9289,14 @@ function validateGeneration(generationDir, runtime) {
   if (!probe.success) {
     reasons.push("generation runtime probe did not pass");
   }
-  const serverPath = path28.join(generationDir, "server.bundle.cjs");
-  const clientPath = path28.join(generationDir, "client.zip");
+  if (!Array.isArray(probe.coverage?.clientAssets) || probe.coverage.clientAssets.length === 0) {
+    reasons.push("generation client asset evidence is invalid");
+  }
+  if (!/^[a-f0-9]{64}$/.test(manifest.buildEnvironmentSha256)) {
+    reasons.push("build environment identity is invalid");
+  }
+  const serverPath = path29.join(generationDir, "server.bundle.cjs");
+  const clientPath = path29.join(generationDir, "client.zip");
   try {
     if (sha256File(serverPath) !== manifest.files.server.sha256) {
       reasons.push("server.bundle.cjs hash does not match manifest");
@@ -9132,11 +9318,11 @@ function validateGeneration(generationDir, runtime) {
   return { manifest, reasons };
 }
 function publishPreviewArtifactGeneration(options) {
-  const storeRoot = path28.resolve(options.storeRoot);
+  const storeRoot = path29.resolve(options.storeRoot);
   const previousPointer = readCurrentPointer(storeRoot);
-  const stagingRoot = path28.join(storeRoot, ".staging");
-  const stagingDir = path28.resolve(options.stagingDir);
-  if (!isPathInside(stagingRoot, stagingDir)) {
+  const stagingRoot = path29.join(storeRoot, ".staging");
+  const stagingDir = path29.resolve(options.stagingDir);
+  if (!isPathInside2(stagingRoot, stagingDir)) {
     return {
       published: false,
       reasons: [
@@ -9149,23 +9335,23 @@ function publishPreviewArtifactGeneration(options) {
     return { published: false, reasons: validation.reasons };
   }
   const generationId = validation.manifest.generationId;
-  const generationsRoot = path28.join(storeRoot, "generations");
-  const generationDir = path28.join(generationsRoot, generationId);
-  fs32.mkdirSync(generationsRoot, { recursive: true });
-  if (fs32.existsSync(generationDir)) {
+  const generationsRoot = path29.join(storeRoot, "generations");
+  const generationDir = path29.join(generationsRoot, generationId);
+  fs33.mkdirSync(generationsRoot, { recursive: true });
+  if (fs33.existsSync(generationDir)) {
     return {
       published: false,
       reasons: [`generation already exists: ${generationId}`]
     };
   }
   try {
-    fs32.renameSync(stagingDir, generationDir);
+    fs33.renameSync(stagingDir, generationDir);
     const pointer = {
       schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
       generationId,
       publishedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    writeJsonAtomic2(path28.join(storeRoot, "current.json"), pointer);
+    writeJsonAtomic2(path29.join(storeRoot, "current.json"), pointer);
     pruneSupersededGenerations(
       generationsRoot,
       [generationId, previousPointer?.generationId].filter(
@@ -9183,10 +9369,10 @@ function publishPreviewArtifactGeneration(options) {
   }
 }
 function resolveCurrentPreviewArtifact(options) {
-  const storeRoot = path28.resolve(options.storeRoot);
+  const storeRoot = path29.resolve(options.storeRoot);
   let pointer;
   try {
-    pointer = readJson3(path28.join(storeRoot, "current.json"));
+    pointer = readJson3(path29.join(storeRoot, "current.json"));
   } catch (error) {
     return {
       resolved: false,
@@ -9205,7 +9391,7 @@ function resolveCurrentPreviewArtifact(options) {
   if (nodeMajor == null) {
     return { resolved: false, reasons: ["runtime Node.js version is invalid"] };
   }
-  const generationDir = path28.join(
+  const generationDir = path29.join(
     storeRoot,
     "generations",
     pointer.generationId
@@ -9224,6 +9410,12 @@ function resolveCurrentPreviewArtifact(options) {
       reasons: ["current pointer does not match generation manifest"]
     };
   }
+  if (validation.manifest.buildEnvironmentSha256 !== options.buildEnvironmentSha256) {
+    return {
+      resolved: false,
+      reasons: ["build environment is incompatible with generation"]
+    };
+  }
   return {
     resolved: true,
     generationId: pointer.generationId,
@@ -9248,27 +9440,27 @@ function runBuildCommand(projectRoot, buildCommand, environment) {
   return [`production build failed with exit ${result.status ?? "unknown"}`];
 }
 function createClientArchive(clientDir, archivePath) {
-  if (!fs33.existsSync(path29.join(clientDir, "index.html"))) {
+  if (!fs34.existsSync(path30.join(clientDir, "index.html"))) {
     return [`client build output is missing: ${clientDir}`];
   }
   const result = spawnSync8("zip", ["-qry", archivePath, "."], {
     cwd: clientDir,
     encoding: "utf8"
   });
-  if (result.status === 0 && fs33.existsSync(archivePath)) return [];
+  if (result.status === 0 && fs34.existsSync(archivePath)) return [];
   return [`client archive failed with exit ${result.status ?? "unknown"}`];
 }
 function readActionPlugins2(metadataFile) {
-  const metadata = JSON.parse(fs33.readFileSync(metadataFile, "utf8"));
+  const metadata = JSON.parse(fs34.readFileSync(metadataFile, "utf8"));
   if (!Array.isArray(metadata.actionPlugins)) return [];
   return metadata.actionPlugins.filter((value) => typeof value === "string").sort();
 }
 async function producePreviewArtifactGeneration(options) {
   const startedAt = Date.now();
-  const projectRoot = path29.resolve(options.projectRoot);
-  const storeRoot = path29.resolve(options.storeRoot);
+  const projectRoot = path30.resolve(options.projectRoot);
+  const storeRoot = path30.resolve(options.storeRoot);
   const generationId = options.generationId ?? defaultGenerationId();
-  const stagingDir = path29.join(
+  const stagingDir = path30.join(
     storeRoot,
     ".staging",
     `${generationId}.${process.pid}.${Date.now()}`
@@ -9280,16 +9472,20 @@ async function producePreviewArtifactGeneration(options) {
     reasons,
     ...probe ? { probe } : {}
   });
-  fs33.mkdirSync(stagingDir, { recursive: true });
+  fs34.mkdirSync(stagingDir, { recursive: true });
   try {
+    const buildEnvironment = previewArtifactBuildEnvironment(
+      options.environment,
+      options.appBasePath
+    );
     const buildReasons = runBuildCommand(
       projectRoot,
       options.buildCommand ?? { command: "npm", args: ["run", "build:prod"] },
-      options.environment
+      buildEnvironment
     );
     if (buildReasons.length > 0) return failed(buildReasons);
-    const serverOutfile = path29.join(stagingDir, "server.bundle.cjs");
-    const serverMetadataFile = path29.join(stagingDir, "server-build.json");
+    const serverOutfile = path30.join(stagingDir, "server.bundle.cjs");
+    const serverMetadataFile = path30.join(stagingDir, "server-build.json");
     const serverResult = await buildPreviewServerArtifact({
       projectRoot,
       entry: "dist/main.js",
@@ -9298,25 +9494,29 @@ async function producePreviewArtifactGeneration(options) {
     });
     if (!serverResult.built) return failed(serverResult.reasons);
     const archiveReasons = createClientArchive(
-      path29.join(projectRoot, "dist", "client"),
-      path29.join(stagingDir, "client.zip")
+      path30.join(projectRoot, "dist", "client"),
+      path30.join(stagingDir, "client.zip")
     );
     if (archiveReasons.length > 0) return failed(archiveReasons);
     const actionPlugins = readActionPlugins2(serverMetadataFile);
-    fs33.rmSync(serverMetadataFile, { force: true });
+    fs34.rmSync(serverMetadataFile, { force: true });
     createPreviewArtifactManifest({
       generationDir: stagingDir,
       generationId,
       nodeVersion: process.version,
       platform: process.platform,
       arch: process.arch,
+      buildEnvironmentSha256: previewArtifactBuildEnvironmentHash(
+        options.environment,
+        options.appBasePath
+      ),
       actionPlugins
     });
     const probe = await runPreviewArtifactProbe({
       generationDir: stagingDir,
       appBasePath: options.appBasePath,
       businessApiPath: options.businessApiPath,
-      environment: options.environment
+      environment: previewArtifactRuntimeEnvironment(options.environment)
     });
     if (!probe.success) return failed(probe.reasons, probe);
     const promotion = promotePreviewArtifactGeneration(stagingDir);
@@ -9336,23 +9536,25 @@ async function producePreviewArtifactGeneration(options) {
   } catch (error) {
     return failed([error instanceof Error ? error.message : String(error)]);
   } finally {
-    fs33.rmSync(stagingDir, { recursive: true, force: true });
+    fs34.rmSync(stagingDir, { recursive: true, force: true });
   }
 }
 
 // src/commands/preview-artifact/runtime.ts
-import * as fs34 from "fs";
+import * as fs36 from "fs";
 import * as net3 from "net";
-import * as path30 from "path";
+import * as path32 from "path";
 import { spawn as spawn3 } from "child_process";
 
 // src/commands/preview-artifact/switcher.ts
 import * as http from "http";
 import * as net2 from "net";
+import * as fs35 from "fs";
+import * as path31 from "path";
 function targetOrigin(target) {
   return `http://${target.host}:${target.port}`;
 }
-function proxyHttpRequest(target, request2, response) {
+function proxyHttpRequest(target, request2, response, fallback) {
   const upstream = http.request(
     {
       host: target.host,
@@ -9362,6 +9564,13 @@ function proxyHttpRequest(target, request2, response) {
       headers: request2.headers
     },
     (upstreamResponse) => {
+      const upstreamContentType = upstreamResponse.headers["content-type"];
+      const isHtmlFallback = typeof upstreamContentType === "string" && upstreamContentType.toLowerCase().includes("text/html");
+      if (fallback && (upstreamResponse.statusCode === 404 || isHtmlFallback)) {
+        upstreamResponse.resume();
+        fallback();
+        return;
+      }
       response.writeHead(
         upstreamResponse.statusCode ?? 502,
         upstreamResponse.headers
@@ -9382,6 +9591,72 @@ function proxyHttpRequest(target, request2, response) {
   });
   request2.pipe(upstream);
 }
+function cachedAssetFile(request2, cachedAssetFiles) {
+  if (request2.method !== "GET" && request2.method !== "HEAD") return void 0;
+  if (!cachedAssetFiles) return void 0;
+  const pathname = new URL(request2.url ?? "/", "http://preview.local").pathname;
+  return cachedAssetFiles.get(pathname);
+}
+function contentType(filePath) {
+  switch (path31.extname(filePath).toLowerCase()) {
+    case ".js":
+    case ".mjs":
+      return "text/javascript; charset=utf-8";
+    case ".css":
+      return "text/css; charset=utf-8";
+    case ".json":
+    case ".map":
+      return "application/json; charset=utf-8";
+    case ".svg":
+      return "image/svg+xml";
+    case ".png":
+      return "image/png";
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".gif":
+      return "image/gif";
+    case ".webp":
+      return "image/webp";
+    case ".ico":
+      return "image/x-icon";
+    case ".woff":
+      return "font/woff";
+    case ".woff2":
+      return "font/woff2";
+    case ".ttf":
+      return "font/ttf";
+    case ".wasm":
+      return "application/wasm";
+    default:
+      return "application/octet-stream";
+  }
+}
+function serveCachedAsset(request2, response, filePath) {
+  let stat;
+  try {
+    stat = fs35.lstatSync(filePath);
+  } catch {
+    response.writeHead(404).end();
+    return;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    response.writeHead(404).end();
+    return;
+  }
+  response.writeHead(200, {
+    "content-type": contentType(filePath),
+    "content-length": stat.size,
+    "cache-control": "no-store"
+  });
+  if (request2.method === "HEAD") {
+    response.end();
+    return;
+  }
+  const stream = fs35.createReadStream(filePath);
+  stream.on("error", () => response.destroy());
+  stream.pipe(response);
+}
 function proxyUpgrade(target, request2, socket, head) {
   const upstream = net2.connect(target.port, target.host, () => {
     const headers = Object.entries(request2.headers).flatMap(([name, value]) => {
@@ -9400,14 +9675,19 @@ ${headers}\r
   upstream.on("error", () => socket.destroy());
   socket.on("error", () => upstream.destroy());
 }
-async function freshTargetReady(target, healthPath) {
+async function freshTargetReady(target, healthPath, businessPath) {
   try {
     const response = await fetch(new URL(healthPath, targetOrigin(target)), {
       signal: AbortSignal.timeout(1e3)
     });
     if (response.status !== 200) return false;
     const body = await response.json();
-    return body.ready === true;
+    if (body.ready !== true) return false;
+    const businessResponse = await fetch(
+      new URL(businessPath, targetOrigin(target)),
+      { signal: AbortSignal.timeout(1e3), redirect: "manual" }
+    );
+    return isPreviewBusinessResponseReady(businessResponse);
   } catch {
     return false;
   }
@@ -9420,8 +9700,8 @@ function createPreviewArtifactSwitcher(options) {
   let closed = false;
   let pollTimer;
   let settleCutover;
-  const cutover = new Promise((resolve8) => {
-    settleCutover = resolve8;
+  const cutover = new Promise((resolve9) => {
+    settleCutover = resolve9;
   });
   const currentTarget = () => active === "cached" ? options.cachedTarget : options.freshTarget;
   const server = http.createServer((request2, response) => {
@@ -9436,7 +9716,14 @@ function createPreviewArtifactSwitcher(options) {
       );
       return;
     }
-    proxyHttpRequest(currentTarget(), request2, response);
+    const assetFile = cachedAssetFile(request2, options.cachedAssetFiles);
+    if (active === "cached" && assetFile) {
+      serveCachedAsset(request2, response, assetFile);
+      return;
+    }
+    const target = currentTarget();
+    const fallback = active === "fresh" && assetFile ? () => serveCachedAsset(request2, response, assetFile) : void 0;
+    proxyHttpRequest(target, request2, response, fallback);
   });
   server.on("upgrade", (request2, socket, head) => {
     proxyUpgrade(currentTarget(), request2, socket, head);
@@ -9444,7 +9731,11 @@ function createPreviewArtifactSwitcher(options) {
   const schedulePoll = () => {
     if (closed || active === "fresh") return;
     pollTimer = setTimeout(async () => {
-      if (await freshTargetReady(options.freshTarget, healthPath)) {
+      if (await freshTargetReady(
+        options.freshTarget,
+        healthPath,
+        options.freshBusinessPath
+      )) {
         active = "fresh";
         settleCutover?.({
           switched: true,
@@ -9464,7 +9755,7 @@ function createPreviewArtifactSwitcher(options) {
     },
     cutover,
     start() {
-      return new Promise((resolve8, reject) => {
+      return new Promise((resolve9, reject) => {
         server.once("error", reject);
         server.listen(options.listenPort, listenHost, () => {
           const address = server.address();
@@ -9473,7 +9764,7 @@ function createPreviewArtifactSwitcher(options) {
             return;
           }
           schedulePoll();
-          resolve8({
+          resolve9({
             host: listenHost,
             port: address.port,
             origin: `http://${listenHost}:${address.port}`
@@ -9492,8 +9783,8 @@ function createPreviewArtifactSwitcher(options) {
         });
         settleCutover = void 0;
       }
-      return new Promise((resolve8) => {
-        server.close(() => resolve8());
+      return new Promise((resolve9) => {
+        server.close(() => resolve9());
         server.closeAllConnections?.();
       });
     }
@@ -9502,10 +9793,10 @@ function createPreviewArtifactSwitcher(options) {
 
 // src/commands/preview-artifact/runtime.ts
 function sleep2(ms) {
-  return new Promise((resolve8) => setTimeout(resolve8, ms));
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
 }
 async function reservePort2() {
-  return new Promise((resolve8, reject) => {
+  return new Promise((resolve9, reject) => {
     const server = net3.createServer();
     server.unref();
     server.once("error", reject);
@@ -9517,7 +9808,7 @@ async function reservePort2() {
       }
       server.close((error) => {
         if (error) reject(error);
-        else resolve8(address.port);
+        else resolve9(address.port);
       });
     });
   });
@@ -9534,27 +9825,53 @@ function stopProcessGroup2(child) {
     }
   }
 }
-function isPathInside2(parent, candidate) {
-  const relative4 = path30.relative(parent, candidate);
-  return relative4 !== "" && relative4 !== ".." && !relative4.startsWith(`..${path30.sep}`) && !path30.isAbsolute(relative4);
+function isPathInside3(parent, candidate) {
+  const relative5 = path32.relative(parent, candidate);
+  return relative5 !== "" && relative5 !== ".." && !relative5.startsWith(`..${path32.sep}`) && !path32.isAbsolute(relative5);
 }
 function ensureRegularRuntimeRoot(runtimeRoot) {
-  fs34.mkdirSync(runtimeRoot, { recursive: true });
-  const stat = fs34.lstatSync(runtimeRoot);
+  fs36.mkdirSync(runtimeRoot, { recursive: true });
+  const stat = fs36.lstatSync(runtimeRoot);
   if (!stat.isDirectory() || stat.isSymbolicLink()) {
     throw new Error("runtime root must be a regular directory");
   }
 }
+function collectCachedAssetFiles(clientRoot, appBasePath) {
+  const files = /* @__PURE__ */ new Map();
+  const basePath = appBasePath.endsWith("/") ? appBasePath : `${appBasePath}/`;
+  const visit = (directory) => {
+    for (const entry of fs36.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path32.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        visit(absolute);
+        continue;
+      }
+      if (!entry.isFile() || entry.isSymbolicLink()) continue;
+      const relative5 = path32.relative(clientRoot, absolute).split(path32.sep).join("/");
+      if (relative5 === "index.html") continue;
+      files.set(
+        new URL(`/${relative5}`, "http://preview.local").pathname,
+        absolute
+      );
+      files.set(
+        new URL(relative5, `http://preview.local${basePath}`).pathname,
+        absolute
+      );
+    }
+  };
+  visit(clientRoot);
+  return files;
+}
 function writeMarkerAtomic(markerFile, marker) {
-  fs34.mkdirSync(path30.dirname(markerFile), { recursive: true });
+  fs36.mkdirSync(path32.dirname(markerFile), { recursive: true });
   const temporaryFile = `${markerFile}.${process.pid}.${Date.now()}.tmp`;
-  fs34.writeFileSync(temporaryFile, `${JSON.stringify(marker, null, 2)}
+  fs36.writeFileSync(temporaryFile, `${JSON.stringify(marker, null, 2)}
 `, {
     mode: 384
   });
-  fs34.renameSync(temporaryFile, markerFile);
+  fs36.renameSync(temporaryFile, markerFile);
 }
-async function waitForCachedRuntime(origin, appBasePath, timeoutMs, child) {
+async function waitForCachedRuntime(origin, appBasePath, businessApiPath, timeoutMs, child) {
   const timeoutAt = Date.now() + timeoutMs;
   while (Date.now() < timeoutAt) {
     if (child.exitCode != null || child.signalCode != null) {
@@ -9567,7 +9884,15 @@ async function waitForCachedRuntime(origin, appBasePath, timeoutMs, child) {
         redirect: "manual",
         signal: AbortSignal.timeout(1e3)
       });
-      if (response.status === 200) return;
+      if (response.status === 200) {
+        const businessResponse = await fetch(new URL(businessApiPath, origin), {
+          redirect: "manual",
+          signal: AbortSignal.timeout(1e3)
+        });
+        if (isPreviewBusinessResponseReady(businessResponse)) {
+          return;
+        }
+      }
     } catch {
     }
     await sleep2(50);
@@ -9579,11 +9904,15 @@ async function startPreviewArtifactRuntime(options) {
     storeRoot: options.storeRoot,
     nodeVersion: process.version,
     platform: process.platform,
-    arch: process.arch
+    arch: process.arch,
+    buildEnvironmentSha256: previewArtifactBuildEnvironmentHash(
+      options.environment,
+      options.appBasePath
+    )
   });
   if (!resolved.resolved) return { started: false, reasons: resolved.reasons };
-  const runtimeRoot = path30.resolve(options.runtimeRoot);
-  const markerFile = path30.resolve(options.markerFile);
+  const runtimeRoot = path32.resolve(options.runtimeRoot);
+  const markerFile = path32.resolve(options.markerFile);
   let runtimeDir;
   let cachedRuntime;
   let switcher;
@@ -9593,25 +9922,26 @@ async function startPreviewArtifactRuntime(options) {
     closed = true;
     stopProcessGroup2(cachedRuntime);
     await switcher?.close();
-    fs34.rmSync(markerFile, { force: true });
-    if (runtimeDir) fs34.rmSync(runtimeDir, { recursive: true, force: true });
+    fs36.rmSync(markerFile, { force: true });
+    if (runtimeDir) fs36.rmSync(runtimeDir, { recursive: true, force: true });
   };
   try {
     ensureRegularRuntimeRoot(runtimeRoot);
-    if (!isPathInside2(runtimeRoot, markerFile)) {
+    if (!isPathInside3(runtimeRoot, markerFile)) {
       throw new Error("runtime marker must be inside the runtime root");
     }
-    runtimeDir = fs34.mkdtempSync(
-      path30.join(runtimeRoot, `${resolved.generationId}-`)
+    runtimeDir = fs36.mkdtempSync(
+      path32.join(runtimeRoot, `${resolved.generationId}-`)
     );
-    const runtimeBundle = path30.join(runtimeDir, "server.bundle.cjs");
-    fs34.copyFileSync(
-      path30.join(resolved.generationDir, "server.bundle.cjs"),
+    const runtimeBundle = path32.join(runtimeDir, "server.bundle.cjs");
+    fs36.copyFileSync(
+      path32.join(resolved.generationDir, "server.bundle.cjs"),
       runtimeBundle
     );
+    const clientRoot = path32.join(runtimeDir, "dist", "client");
     extractClientArchive(
-      path30.join(resolved.generationDir, "client.zip"),
-      path30.join(runtimeDir, "dist", "client")
+      path32.join(resolved.generationDir, "client.zip"),
+      clientRoot
     );
     const cachedServerPort = options.cachedServerPort === 0 ? await reservePort2() : options.cachedServerPort;
     cachedRuntime = spawn3(process.execPath, [runtimeBundle], {
@@ -9620,7 +9950,7 @@ async function startPreviewArtifactRuntime(options) {
       stdio: "ignore",
       env: {
         ...process.env,
-        ...options.environment,
+        ...previewArtifactRuntimeEnvironment(options.environment),
         SERVER_PORT: String(cachedServerPort)
       }
     });
@@ -9628,6 +9958,7 @@ async function startPreviewArtifactRuntime(options) {
     await waitForCachedRuntime(
       cachedOrigin,
       options.appBasePath,
+      options.businessApiPath,
       options.startupTimeoutMs ?? 3e4,
       cachedRuntime
     );
@@ -9637,6 +9968,11 @@ async function startPreviewArtifactRuntime(options) {
       generationId: resolved.generationId,
       cachedTarget: { host: "127.0.0.1", port: cachedServerPort },
       freshTarget: { host: "127.0.0.1", port: options.freshClientPort },
+      freshBusinessPath: options.businessApiPath,
+      cachedAssetFiles: collectCachedAssetFiles(
+        clientRoot,
+        options.appBasePath
+      ),
       pollIntervalMs: options.pollIntervalMs
     });
     const address = await switcher.start();
@@ -9656,9 +9992,6 @@ async function startPreviewArtifactRuntime(options) {
         runtimeMarker.status = "fresh-serving";
         runtimeMarker.cutoverAt = result.at;
         writeMarkerAtomic(markerFile, runtimeMarker);
-        await sleep2(options.cachedDrainMs ?? 5e3);
-        stopProcessGroup2(cachedRuntime);
-        cachedRuntime = void 0;
       }
       return result;
     });
@@ -9748,9 +10081,17 @@ var previewArtifactGenerationCommand = {
     program.command(this.name).description(this.description).option("--project-root <dir>", "Application project root", process.cwd()).requiredOption("--store-root <dir>", "Immutable generation store root").option("--generation-id <id>", "Explicit immutable generation ID").requiredOption("--app-base-path <path>", "Application HTML probe path").requiredOption(
       "--business-api-path <path>",
       "Business API probe path that must not return 404/5xx"
+    ).requiredOption(
+      "--environment-file <file>",
+      "JSON application environment passed only to build/probe children"
     ).action(
       async (options) => {
-        const result = await producePreviewArtifactGeneration(options);
+        const result = await producePreviewArtifactGeneration({
+          ...options,
+          environment: readPreviewArtifactEnvironmentFile(
+            options.environmentFile
+          )
+        });
         console.log(JSON.stringify(result));
         if (!result.published) process.exitCode = 2;
       }
@@ -9799,9 +10140,20 @@ var previewArtifactRuntimeCommand = {
     ).requiredOption(
       "--app-base-path <path>",
       "Application HTML readiness path"
+    ).requiredOption(
+      "--business-api-path <path>",
+      "Business API path revalidated with the current runtime environment"
+    ).requiredOption(
+      "--environment-file <file>",
+      "JSON application environment passed only to cached application child"
     ).action(
       async (options) => {
-        const runtime = await startPreviewArtifactRuntime(options);
+        const runtime = await startPreviewArtifactRuntime({
+          ...options,
+          environment: readPreviewArtifactEnvironmentFile(
+            options.environmentFile
+          )
+        });
         if (!runtime.started) {
           console.log(JSON.stringify(runtime));
           process.exitCode = 2;
@@ -9855,12 +10207,12 @@ var commands = [
 ];
 
 // src/index.ts
-var envPath = path31.join(process.cwd(), ".env");
-if (fs35.existsSync(envPath)) {
+var envPath = path33.join(process.cwd(), ".env");
+if (fs37.existsSync(envPath)) {
   dotenvConfig({ path: envPath });
 }
-var __dirname = path31.dirname(fileURLToPath5(import.meta.url));
-var pkg = JSON.parse(fs35.readFileSync(path31.join(__dirname, "../package.json"), "utf-8"));
+var __dirname = path33.dirname(fileURLToPath5(import.meta.url));
+var pkg = JSON.parse(fs37.readFileSync(path33.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.20260718151739",
+  "version": "1.1.59-alpha.20260719084243",
   "description": "CLI tool for fullstack template management",
   "type": "module",
   "main": "dist/index.js",