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

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import fs30 from "fs";
-import path26 from "path";
+import fs35 from "fs";
+import path31 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((resolve3) => {
+  return new Promise((resolve8) => {
     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();
-      resolve3({
+      resolve8({
         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);
-      resolve3({
+      resolve8({
         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((resolve3) => {
+  return new Promise((resolve8) => {
     execFile("fullstack-cli", ["action-plugin", "init"], { cwd: process.cwd(), stdio: "ignore" }, (error) => {
       if (error) {
         debug("action-plugin init \u5931\u8D25: %s", error.message);
       }
-      resolve3();
+      resolve8();
     });
   });
 }
@@ -8236,6 +8236,9 @@ function generateBootstrap(entryPath, plugins) {
   });
   lines.push(
     `globalThis[Symbol.for(${JSON.stringify(STATIC_PLUGIN_REGISTRY_SYMBOL)})] = __staticPluginRegistry;`,
+    `if (process.env.PREVIEW_ARTIFACT_PROBE_REGISTRY_FILE) {`,
+    `  require('node:fs').writeFileSync(process.env.PREVIEW_ARTIFACT_PROBE_REGISTRY_FILE, JSON.stringify(Array.from(__staticPluginRegistry.keys()).sort()));`,
+    `}`,
     `require(${JSON.stringify(entryPath)});`,
     ""
   );
@@ -8619,21 +8622,1093 @@ 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 { 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 MANIFEST_FILE = "manifest.json";
+var PROBE_FILE = "probe.json";
+var SERVER_FILE = "server.bundle.cjs";
+var CLIENT_FILE = "client.zip";
+function parseNodeMajor(nodeVersion) {
+  const match = /^v?(\d+)(?:\.|$)/.exec(nodeVersion.trim());
+  if (!match) {
+    throw new Error(`invalid Node.js version: ${nodeVersion}`);
+  }
+  return Number(match[1]);
+}
+function sha256File(filePath) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs30.readFileSync(filePath));
+  return hash.digest("hex");
+}
+function fileIdentity(generationDir, relativePath) {
+  const filePath = path26.join(generationDir, relativePath);
+  const stat = fs30.lstatSync(filePath);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error(`artifact file must be a regular file: ${relativePath}`);
+  }
+  return {
+    path: relativePath,
+    bytes: stat.size,
+    sha256: sha256File(filePath)
+  };
+}
+function readJson2(filePath) {
+  return JSON.parse(fs30.readFileSync(filePath, "utf8"));
+}
+function writeJsonAtomic(filePath, value) {
+  fs30.mkdirSync(path26.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs30.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
+`, {
+    mode: 384
+  });
+  fs30.renameSync(temporaryPath, filePath);
+}
+function runtimeIdentity(nodeVersion, platform, arch) {
+  return { nodeMajor: parseNodeMajor(nodeVersion), platform, arch };
+}
+function sameRuntime(left, right) {
+  return left.nodeMajor === right.nodeMajor && left.platform === right.platform && left.arch === right.arch;
+}
+function createPreviewArtifactManifest(options) {
+  const generationDir = path26.resolve(options.generationDir);
+  const manifest = {
+    schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
+    generationId: options.generationId,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    runtime: runtimeIdentity(
+      options.nodeVersion,
+      options.platform,
+      options.arch
+    ),
+    files: {
+      server: fileIdentity(generationDir, SERVER_FILE),
+      client: fileIdentity(generationDir, CLIENT_FILE)
+    },
+    actionPlugins: Array.from(new Set(options.actionPlugins ?? [])).sort(),
+    runtimeProbeStatus: "not-run",
+    consumable: false
+  };
+  writeJsonAtomic(path26.join(generationDir, MANIFEST_FILE), manifest);
+  fs30.rmSync(path26.join(generationDir, PROBE_FILE), { force: true });
+  return manifest;
+}
+function recordPreviewArtifactProbe(options) {
+  const generationDir = path26.resolve(options.generationDir);
+  const manifest = readJson2(
+    path26.join(generationDir, MANIFEST_FILE)
+  );
+  const probe = {
+    schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
+    generationId: manifest.generationId,
+    completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    success: options.success,
+    reasons: options.reasons ?? [],
+    runtime: runtimeIdentity(
+      options.nodeVersion,
+      options.platform,
+      options.arch
+    ),
+    serverSha256: sha256File(path26.join(generationDir, SERVER_FILE)),
+    clientSha256: sha256File(path26.join(generationDir, CLIENT_FILE)),
+    coverage: {
+      html: options.coverage.html,
+      businessApi: options.coverage.businessApi,
+      actionPlugins: Array.from(new Set(options.coverage.actionPlugins)).sort()
+    }
+  };
+  writeJsonAtomic(path26.join(generationDir, PROBE_FILE), probe);
+  return probe;
+}
+function promotePreviewArtifactGeneration(generationDirInput) {
+  const generationDir = path26.resolve(generationDirInput);
+  const reasons = [];
+  let manifest;
+  let probe;
+  try {
+    manifest = readJson2(
+      path26.join(generationDir, MANIFEST_FILE)
+    );
+    probe = readJson2(
+      path26.join(generationDir, PROBE_FILE)
+    );
+  } catch (error) {
+    return {
+      promoted: false,
+      reasons: [
+        `probe evidence missing or invalid: ${error instanceof Error ? error.message : String(error)}`
+      ]
+    };
+  }
+  if (manifest.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION || probe.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION) {
+    reasons.push("schema version mismatch");
+  }
+  if (probe.generationId !== manifest.generationId) {
+    reasons.push("probe generation identity mismatch");
+  }
+  if (!probe.success) {
+    reasons.push(`probe failed: ${probe.reasons.join("; ") || "unknown"}`);
+  }
+  if (!sameRuntime(manifest.runtime, probe.runtime)) {
+    reasons.push(
+      "probe runtime identity does not match build runtime identity"
+    );
+  }
+  const currentServerHash = sha256File(path26.join(generationDir, SERVER_FILE));
+  const currentClientHash = sha256File(path26.join(generationDir, CLIENT_FILE));
+  if (currentServerHash !== manifest.files.server.sha256 || currentServerHash !== probe.serverSha256) {
+    reasons.push("server.bundle.cjs hash does not match probe identity");
+  }
+  if (currentClientHash !== manifest.files.client.sha256 || currentClientHash !== probe.clientSha256) {
+    reasons.push("client.zip hash does not match probe identity");
+  }
+  if (!probe.coverage.html) {
+    reasons.push("probe did not verify HTML");
+  }
+  if (!probe.coverage.businessApi) {
+    reasons.push("probe did not verify business API");
+  }
+  const verifiedPlugins = new Set(probe.coverage.actionPlugins);
+  const missingPlugins = manifest.actionPlugins.filter(
+    (plugin) => !verifiedPlugins.has(plugin)
+  );
+  if (missingPlugins.length > 0) {
+    reasons.push(
+      `probe did not verify Action Plugin: ${missingPlugins.join(", ")}`
+    );
+  }
+  if (reasons.length > 0) {
+    return { promoted: false, reasons };
+  }
+  const promotedManifest = {
+    ...manifest,
+    runtimeProbeStatus: "passed",
+    consumable: true
+  };
+  writeJsonAtomic(path26.join(generationDir, MANIFEST_FILE), promotedManifest);
+  return { promoted: true, manifest: promotedManifest };
+}
+
+// src/commands/preview-artifact/probe.ts
+import * as fs31 from "fs";
+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";
+function sleep(ms) {
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
+}
+async function reservePort() {
+  return new Promise((resolve8, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("unable to reserve probe port")));
+        return;
+      }
+      server.close((error) => {
+        if (error) reject(error);
+        else resolve8(address.port);
+      });
+    });
+  });
+}
+function archiveEntries(archivePath) {
+  const listing = spawnSync7("unzip", ["-Z1", archivePath], {
+    encoding: "utf8"
+  });
+  if (listing.status !== 0) {
+    throw new Error(`client archive listing failed: ${listing.stderr.trim()}`);
+  }
+  const entries = listing.stdout.split("\n").filter(Boolean);
+  for (const entry of entries) {
+    const normalized = path27.posix.normalize(entry.replaceAll("\\", "/"));
+    if (path27.posix.isAbsolute(normalized) || normalized === ".." || normalized.startsWith("../")) {
+      throw new Error(`client archive contains unsafe path: ${entry}`);
+    }
+  }
+  return entries;
+}
+function rejectArchivedSymlinks(archivePath) {
+  const listing = spawnSync7("unzip", ["-Z", "-l", archivePath], {
+    encoding: "utf8"
+  });
+  if (listing.status !== 0) {
+    throw new Error(
+      `client archive metadata listing failed: ${listing.stderr.trim()}`
+    );
+  }
+  for (const line of listing.stdout.split("\n")) {
+    if (/^l[rwxstST-]{9}\s/.test(line.trimStart())) {
+      throw new Error("client archive contains symlink");
+    }
+  }
+}
+function rejectSymlinks(root) {
+  const pending = [root];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (!current) continue;
+    for (const entry of fs31.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path27.join(current, entry.name);
+      const stat = fs31.lstatSync(entryPath);
+      if (stat.isSymbolicLink()) {
+        throw new Error(`client archive contains symlink: ${entry.name}`);
+      }
+      if (stat.isDirectory()) pending.push(entryPath);
+    }
+  }
+}
+function extractClientArchive(archivePath, destination) {
+  if (fs31.existsSync(destination)) {
+    throw new Error("client archive destination must not already exist");
+  }
+  archiveEntries(archivePath);
+  rejectArchivedSymlinks(archivePath);
+  fs31.mkdirSync(destination, { recursive: true });
+  try {
+    const extraction = spawnSync7(
+      "unzip",
+      ["-q", archivePath, "-d", destination],
+      { encoding: "utf8" }
+    );
+    if (extraction.status !== 0) {
+      throw new Error(
+        `client archive extraction failed: ${extraction.stderr.trim()}`
+      );
+    }
+    rejectSymlinks(destination);
+  } catch (error) {
+    fs31.rmSync(destination, { recursive: true, force: true });
+    throw error;
+  }
+}
+async function fetchUntil(url, timeoutAt) {
+  while (Date.now() < timeoutAt) {
+    try {
+      return await fetch(url, {
+        redirect: "manual",
+        signal: AbortSignal.timeout(1e3)
+      });
+    } catch {
+      await sleep(50);
+    }
+  }
+  return null;
+}
+function stopProcessGroup(pid) {
+  if (!pid) return;
+  try {
+    process.kill(-pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch {
+      return;
+    }
+  }
+}
+async function runPreviewArtifactProbe(options) {
+  const generationDir = path27.resolve(options.generationDir);
+  const runtimeRoot = fs31.mkdtempSync(
+    path27.join(os4.tmpdir(), "preview-artifact-probe-")
+  );
+  const coverage = {
+    html: false,
+    businessApi: false,
+    actionPlugins: []
+  };
+  const reasons = [];
+  const registryFile = path27.join(runtimeRoot, "plugin-registry.json");
+  let isolatedNodeModulesPresent = false;
+  let child;
+  try {
+    const runtimeBundle = path27.join(runtimeRoot, "server.bundle.cjs");
+    fs31.copyFileSync(
+      path27.join(generationDir, "server.bundle.cjs"),
+      runtimeBundle
+    );
+    extractClientArchive(
+      path27.join(generationDir, "client.zip"),
+      path27.join(runtimeRoot, "dist", "client")
+    );
+    isolatedNodeModulesPresent = fs31.existsSync(
+      path27.join(runtimeRoot, "node_modules")
+    );
+    if (isolatedNodeModulesPresent) {
+      reasons.push("isolated runtime unexpectedly contains node_modules");
+    }
+    const port = await reservePort();
+    const timeoutAt = Date.now() + (options.timeoutMs ?? 12e4);
+    child = spawn2(process.execPath, [runtimeBundle], {
+      cwd: runtimeRoot,
+      detached: true,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        ...options.environment,
+        SERVER_PORT: String(port),
+        PREVIEW_ARTIFACT_PROBE_REGISTRY_FILE: registryFile
+      }
+    });
+    const origin = `http://127.0.0.1:${port}`;
+    const htmlResponse = await fetchUntil(
+      new URL(options.appBasePath, origin).toString(),
+      timeoutAt
+    );
+    coverage.html = htmlResponse?.status === 200;
+    if (!coverage.html) {
+      reasons.push(
+        `HTML probe failed with status ${htmlResponse?.status ?? "unreachable"}`
+      );
+    }
+    const apiResponse = await fetchUntil(
+      new URL(options.businessApiPath, origin).toString(),
+      timeoutAt
+    );
+    coverage.businessApi = Boolean(
+      apiResponse && apiResponse.status !== 404 && apiResponse.status < 500
+    );
+    if (!coverage.businessApi) {
+      reasons.push(
+        `business API returned ${apiResponse?.status ?? "unreachable"}`
+      );
+    }
+    while (!fs31.existsSync(registryFile) && Date.now() < timeoutAt) {
+      await sleep(25);
+    }
+    if (fs31.existsSync(registryFile)) {
+      const parsed = JSON.parse(fs31.readFileSync(registryFile, "utf8"));
+      if (Array.isArray(parsed)) {
+        coverage.actionPlugins = parsed.filter((value) => typeof value === "string").sort();
+      }
+    }
+  } catch (error) {
+    reasons.push(error instanceof Error ? error.message : String(error));
+  } finally {
+    stopProcessGroup(child?.pid);
+  }
+  const probe = recordPreviewArtifactProbe({
+    generationDir,
+    success: reasons.length === 0,
+    reasons,
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch,
+    coverage
+  });
+  fs31.rmSync(runtimeRoot, { recursive: true, force: true });
+  return { ...probe, isolatedNodeModulesPresent };
+}
+
+// src/commands/preview-artifact/store.ts
+import * as fs32 from "fs";
+import * as path28 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")
+    );
+    return pointer.schemaVersion === PREVIEW_ARTIFACT_SCHEMA_VERSION && GENERATION_ID_PATTERN.test(pointer.generationId) ? pointer : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readJson3(filePath) {
+  return JSON.parse(fs32.readFileSync(filePath, "utf8"));
+}
+function writeJsonAtomic2(filePath, value) {
+  fs32.mkdirSync(path28.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs32.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
+`, {
+    mode: 384
+  });
+  fs32.renameSync(temporaryPath, filePath);
+}
+function pruneSupersededGenerations(generationsRoot, retainedGenerationIds) {
+  const retained = new Set(retainedGenerationIds);
+  for (const entry of fs32.readdirSync(generationsRoot, {
+    withFileTypes: true
+  })) {
+    if (retained.has(entry.name)) continue;
+    try {
+      fs32.rmSync(path28.join(generationsRoot, entry.name), {
+        recursive: true,
+        force: true
+      });
+    } catch {
+    }
+  }
+}
+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 validateRegularDirectory(directoryPath, label) {
+  try {
+    const stat = fs32.lstatSync(directoryPath);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      return [`${label} must be a regular directory`];
+    }
+    return [];
+  } catch (error) {
+    return [
+      `${label} is unavailable: ${error instanceof Error ? error.message : String(error)}`
+    ];
+  }
+}
+function validateGeneration(generationDir, runtime) {
+  const reasons = validateRegularDirectory(
+    generationDir,
+    "generation directory"
+  );
+  if (reasons.length > 0) return { reasons };
+  let manifest;
+  let probe;
+  try {
+    manifest = readJson3(
+      path28.join(generationDir, "manifest.json")
+    );
+    probe = readJson3(
+      path28.join(generationDir, "probe.json")
+    );
+  } catch (error) {
+    return {
+      reasons: [
+        `generation metadata is invalid: ${error instanceof Error ? error.message : String(error)}`
+      ]
+    };
+  }
+  if (manifest.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_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) {
+    reasons.push("generation ID is invalid or inconsistent");
+  }
+  if (!manifest.consumable || manifest.runtimeProbeStatus !== "passed") {
+    reasons.push("generation is not consumable");
+  }
+  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");
+  try {
+    if (sha256File(serverPath) !== manifest.files.server.sha256) {
+      reasons.push("server.bundle.cjs hash does not match manifest");
+    }
+    if (sha256File(clientPath) !== manifest.files.client.sha256) {
+      reasons.push("client.zip hash does not match manifest");
+    }
+  } catch (error) {
+    reasons.push(
+      `generation files are unavailable: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (probe.serverSha256 !== manifest.files.server.sha256 || probe.clientSha256 !== manifest.files.client.sha256) {
+    reasons.push("probe file identity does not match manifest");
+  }
+  if (runtime && (runtime.nodeMajor !== manifest.runtime.nodeMajor || runtime.platform !== manifest.runtime.platform || runtime.arch !== manifest.runtime.arch)) {
+    reasons.push("runtime identity is incompatible with generation");
+  }
+  return { manifest, reasons };
+}
+function publishPreviewArtifactGeneration(options) {
+  const storeRoot = path28.resolve(options.storeRoot);
+  const previousPointer = readCurrentPointer(storeRoot);
+  const stagingRoot = path28.join(storeRoot, ".staging");
+  const stagingDir = path28.resolve(options.stagingDir);
+  if (!isPathInside(stagingRoot, stagingDir)) {
+    return {
+      published: false,
+      reasons: [
+        "staging directory must be inside the store .staging directory"
+      ]
+    };
+  }
+  const validation = validateGeneration(stagingDir);
+  if (!validation.manifest || validation.reasons.length > 0) {
+    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)) {
+    return {
+      published: false,
+      reasons: [`generation already exists: ${generationId}`]
+    };
+  }
+  try {
+    fs32.renameSync(stagingDir, generationDir);
+    const pointer = {
+      schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
+      generationId,
+      publishedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeJsonAtomic2(path28.join(storeRoot, "current.json"), pointer);
+    pruneSupersededGenerations(
+      generationsRoot,
+      [generationId, previousPointer?.generationId].filter(
+        (value) => Boolean(value)
+      )
+    );
+    return { published: true, generationId, generationDir };
+  } catch (error) {
+    return {
+      published: false,
+      reasons: [
+        `generation publication failed: ${error instanceof Error ? error.message : String(error)}`
+      ]
+    };
+  }
+}
+function resolveCurrentPreviewArtifact(options) {
+  const storeRoot = path28.resolve(options.storeRoot);
+  let pointer;
+  try {
+    pointer = readJson3(path28.join(storeRoot, "current.json"));
+  } catch (error) {
+    return {
+      resolved: false,
+      reasons: [
+        `current pointer is unavailable: ${error instanceof Error ? error.message : String(error)}`
+      ]
+    };
+  }
+  if (pointer.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION || !GENERATION_ID_PATTERN.test(pointer.generationId)) {
+    return {
+      resolved: false,
+      reasons: ["current generation ID or schema version is invalid"]
+    };
+  }
+  const nodeMajor = parseNodeMajor2(options.nodeVersion);
+  if (nodeMajor == null) {
+    return { resolved: false, reasons: ["runtime Node.js version is invalid"] };
+  }
+  const generationDir = path28.join(
+    storeRoot,
+    "generations",
+    pointer.generationId
+  );
+  const validation = validateGeneration(generationDir, {
+    nodeMajor,
+    platform: options.platform,
+    arch: options.arch
+  });
+  if (!validation.manifest || validation.reasons.length > 0) {
+    return { resolved: false, reasons: validation.reasons };
+  }
+  if (validation.manifest.generationId !== pointer.generationId) {
+    return {
+      resolved: false,
+      reasons: ["current pointer does not match generation manifest"]
+    };
+  }
+  return {
+    resolved: true,
+    generationId: pointer.generationId,
+    generationDir,
+    manifest: validation.manifest
+  };
+}
+
+// src/commands/preview-artifact/producer.ts
+function defaultGenerationId() {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "");
+  return `${timestamp}-${crypto2.randomBytes(5).toString("hex")}`;
+}
+function runBuildCommand(projectRoot, buildCommand, environment) {
+  const result = spawnSync8(buildCommand.command, buildCommand.args, {
+    cwd: projectRoot,
+    env: { ...process.env, ...environment },
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024
+  });
+  if (result.status === 0) return [];
+  return [`production build failed with exit ${result.status ?? "unknown"}`];
+}
+function createClientArchive(clientDir, archivePath) {
+  if (!fs33.existsSync(path29.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 [];
+  return [`client archive failed with exit ${result.status ?? "unknown"}`];
+}
+function readActionPlugins2(metadataFile) {
+  const metadata = JSON.parse(fs33.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 generationId = options.generationId ?? defaultGenerationId();
+  const stagingDir = path29.join(
+    storeRoot,
+    ".staging",
+    `${generationId}.${process.pid}.${Date.now()}`
+  );
+  const failed = (reasons, probe) => ({
+    published: false,
+    generationId,
+    elapsedMs: Date.now() - startedAt,
+    reasons,
+    ...probe ? { probe } : {}
+  });
+  fs33.mkdirSync(stagingDir, { recursive: true });
+  try {
+    const buildReasons = runBuildCommand(
+      projectRoot,
+      options.buildCommand ?? { command: "npm", args: ["run", "build:prod"] },
+      options.environment
+    );
+    if (buildReasons.length > 0) return failed(buildReasons);
+    const serverOutfile = path29.join(stagingDir, "server.bundle.cjs");
+    const serverMetadataFile = path29.join(stagingDir, "server-build.json");
+    const serverResult = await buildPreviewServerArtifact({
+      projectRoot,
+      entry: "dist/main.js",
+      outfile: serverOutfile,
+      metadataFile: serverMetadataFile
+    });
+    if (!serverResult.built) return failed(serverResult.reasons);
+    const archiveReasons = createClientArchive(
+      path29.join(projectRoot, "dist", "client"),
+      path29.join(stagingDir, "client.zip")
+    );
+    if (archiveReasons.length > 0) return failed(archiveReasons);
+    const actionPlugins = readActionPlugins2(serverMetadataFile);
+    fs33.rmSync(serverMetadataFile, { force: true });
+    createPreviewArtifactManifest({
+      generationDir: stagingDir,
+      generationId,
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      actionPlugins
+    });
+    const probe = await runPreviewArtifactProbe({
+      generationDir: stagingDir,
+      appBasePath: options.appBasePath,
+      businessApiPath: options.businessApiPath,
+      environment: options.environment
+    });
+    if (!probe.success) return failed(probe.reasons, probe);
+    const promotion = promotePreviewArtifactGeneration(stagingDir);
+    if (!promotion.promoted) return failed(promotion.reasons, probe);
+    const publication = publishPreviewArtifactGeneration({
+      storeRoot,
+      stagingDir
+    });
+    if (!publication.published) return failed(publication.reasons, probe);
+    return {
+      published: true,
+      generationId,
+      generationDir: publication.generationDir,
+      elapsedMs: Date.now() - startedAt,
+      probe
+    };
+  } catch (error) {
+    return failed([error instanceof Error ? error.message : String(error)]);
+  } finally {
+    fs33.rmSync(stagingDir, { recursive: true, force: true });
+  }
+}
+
+// src/commands/preview-artifact/runtime.ts
+import * as fs34 from "fs";
+import * as net3 from "net";
+import * as path30 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";
+function targetOrigin(target) {
+  return `http://${target.host}:${target.port}`;
+}
+function proxyHttpRequest(target, request2, response) {
+  const upstream = http.request(
+    {
+      host: target.host,
+      port: target.port,
+      method: request2.method,
+      path: request2.url,
+      headers: request2.headers
+    },
+    (upstreamResponse) => {
+      response.writeHead(
+        upstreamResponse.statusCode ?? 502,
+        upstreamResponse.headers
+      );
+      upstreamResponse.pipe(response);
+    }
+  );
+  upstream.on("error", (error) => {
+    if (!response.headersSent) {
+      response.writeHead(502, { "content-type": "application/json" });
+    }
+    response.end(
+      JSON.stringify({
+        ready: false,
+        error: error.code ?? "upstream"
+      })
+    );
+  });
+  request2.pipe(upstream);
+}
+function proxyUpgrade(target, request2, socket, head) {
+  const upstream = net2.connect(target.port, target.host, () => {
+    const headers = Object.entries(request2.headers).flatMap(([name, value]) => {
+      if (Array.isArray(value)) return value.map((item) => `${name}: ${item}`);
+      return value == null ? [] : [`${name}: ${value}`];
+    }).join("\r\n");
+    upstream.write(
+      `${request2.method ?? "GET"} ${request2.url ?? "/"} HTTP/${request2.httpVersion}\r
+${headers}\r
+\r
+`
+    );
+    if (head.length > 0) upstream.write(head);
+    socket.pipe(upstream).pipe(socket);
+  });
+  upstream.on("error", () => socket.destroy());
+  socket.on("error", () => upstream.destroy());
+}
+async function freshTargetReady(target, healthPath) {
+  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;
+  } catch {
+    return false;
+  }
+}
+function createPreviewArtifactSwitcher(options) {
+  const listenHost = options.listenHost ?? "127.0.0.1";
+  const healthPath = options.freshHealthPath ?? "/dev/health";
+  const pollIntervalMs = options.pollIntervalMs ?? 100;
+  let active = "cached";
+  let closed = false;
+  let pollTimer;
+  let settleCutover;
+  const cutover = new Promise((resolve8) => {
+    settleCutover = resolve8;
+  });
+  const currentTarget = () => active === "cached" ? options.cachedTarget : options.freshTarget;
+  const server = http.createServer((request2, response) => {
+    if (request2.url?.split("?")[0] === "/dev/health") {
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(
+        JSON.stringify({
+          ready: true,
+          active,
+          generationId: options.generationId
+        })
+      );
+      return;
+    }
+    proxyHttpRequest(currentTarget(), request2, response);
+  });
+  server.on("upgrade", (request2, socket, head) => {
+    proxyUpgrade(currentTarget(), request2, socket, head);
+  });
+  const schedulePoll = () => {
+    if (closed || active === "fresh") return;
+    pollTimer = setTimeout(async () => {
+      if (await freshTargetReady(options.freshTarget, healthPath)) {
+        active = "fresh";
+        settleCutover?.({
+          switched: true,
+          active,
+          at: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        settleCutover = void 0;
+        return;
+      }
+      schedulePoll();
+    }, pollIntervalMs);
+    pollTimer.unref();
+  };
+  return {
+    get active() {
+      return active;
+    },
+    cutover,
+    start() {
+      return new Promise((resolve8, reject) => {
+        server.once("error", reject);
+        server.listen(options.listenPort, listenHost, () => {
+          const address = server.address();
+          if (!address || typeof address === "string") {
+            reject(new Error("switcher did not expose a TCP address"));
+            return;
+          }
+          schedulePoll();
+          resolve8({
+            host: listenHost,
+            port: address.port,
+            origin: `http://${listenHost}:${address.port}`
+          });
+        });
+      });
+    },
+    close() {
+      closed = true;
+      if (pollTimer) clearTimeout(pollTimer);
+      if (settleCutover) {
+        settleCutover({
+          switched: false,
+          active,
+          at: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        settleCutover = void 0;
+      }
+      return new Promise((resolve8) => {
+        server.close(() => resolve8());
+        server.closeAllConnections?.();
+      });
+    }
+  };
+}
+
+// src/commands/preview-artifact/runtime.ts
+function sleep2(ms) {
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
+}
+async function reservePort2() {
+  return new Promise((resolve8, reject) => {
+    const server = net3.createServer();
+    server.unref();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("unable to reserve runtime port")));
+        return;
+      }
+      server.close((error) => {
+        if (error) reject(error);
+        else resolve8(address.port);
+      });
+    });
+  });
+}
+function stopProcessGroup2(child) {
+  if (!child?.pid) return;
+  try {
+    process.kill(-child.pid, "SIGTERM");
+  } catch {
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      return;
+    }
+  }
+}
+function isPathInside2(parent, candidate) {
+  const relative4 = path30.relative(parent, candidate);
+  return relative4 !== "" && relative4 !== ".." && !relative4.startsWith(`..${path30.sep}`) && !path30.isAbsolute(relative4);
+}
+function ensureRegularRuntimeRoot(runtimeRoot) {
+  fs34.mkdirSync(runtimeRoot, { recursive: true });
+  const stat = fs34.lstatSync(runtimeRoot);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error("runtime root must be a regular directory");
+  }
+}
+function writeMarkerAtomic(markerFile, marker) {
+  fs34.mkdirSync(path30.dirname(markerFile), { recursive: true });
+  const temporaryFile = `${markerFile}.${process.pid}.${Date.now()}.tmp`;
+  fs34.writeFileSync(temporaryFile, `${JSON.stringify(marker, null, 2)}
+`, {
+    mode: 384
+  });
+  fs34.renameSync(temporaryFile, markerFile);
+}
+async function waitForCachedRuntime(origin, appBasePath, timeoutMs, child) {
+  const timeoutAt = Date.now() + timeoutMs;
+  while (Date.now() < timeoutAt) {
+    if (child.exitCode != null || child.signalCode != null) {
+      throw new Error(
+        `cached runtime exited before readiness: ${child.exitCode ?? child.signalCode}`
+      );
+    }
+    try {
+      const response = await fetch(new URL(appBasePath, origin), {
+        redirect: "manual",
+        signal: AbortSignal.timeout(1e3)
+      });
+      if (response.status === 200) return;
+    } catch {
+    }
+    await sleep2(50);
+  }
+  throw new Error("cached runtime readiness timed out");
+}
+async function startPreviewArtifactRuntime(options) {
+  const resolved = resolveCurrentPreviewArtifact({
+    storeRoot: options.storeRoot,
+    nodeVersion: process.version,
+    platform: process.platform,
+    arch: process.arch
+  });
+  if (!resolved.resolved) return { started: false, reasons: resolved.reasons };
+  const runtimeRoot = path30.resolve(options.runtimeRoot);
+  const markerFile = path30.resolve(options.markerFile);
+  let runtimeDir;
+  let cachedRuntime;
+  let switcher;
+  let closed = false;
+  const cleanup = async () => {
+    if (closed) return;
+    closed = true;
+    stopProcessGroup2(cachedRuntime);
+    await switcher?.close();
+    fs34.rmSync(markerFile, { force: true });
+    if (runtimeDir) fs34.rmSync(runtimeDir, { recursive: true, force: true });
+  };
+  try {
+    ensureRegularRuntimeRoot(runtimeRoot);
+    if (!isPathInside2(runtimeRoot, markerFile)) {
+      throw new Error("runtime marker must be inside the runtime root");
+    }
+    runtimeDir = fs34.mkdtempSync(
+      path30.join(runtimeRoot, `${resolved.generationId}-`)
+    );
+    const runtimeBundle = path30.join(runtimeDir, "server.bundle.cjs");
+    fs34.copyFileSync(
+      path30.join(resolved.generationDir, "server.bundle.cjs"),
+      runtimeBundle
+    );
+    extractClientArchive(
+      path30.join(resolved.generationDir, "client.zip"),
+      path30.join(runtimeDir, "dist", "client")
+    );
+    const cachedServerPort = options.cachedServerPort === 0 ? await reservePort2() : options.cachedServerPort;
+    cachedRuntime = spawn3(process.execPath, [runtimeBundle], {
+      cwd: runtimeDir,
+      detached: true,
+      stdio: "ignore",
+      env: {
+        ...process.env,
+        ...options.environment,
+        SERVER_PORT: String(cachedServerPort)
+      }
+    });
+    const cachedOrigin = `http://127.0.0.1:${cachedServerPort}`;
+    await waitForCachedRuntime(
+      cachedOrigin,
+      options.appBasePath,
+      options.startupTimeoutMs ?? 3e4,
+      cachedRuntime
+    );
+    switcher = createPreviewArtifactSwitcher({
+      listenHost: options.listenHost,
+      listenPort: options.listenPort,
+      generationId: resolved.generationId,
+      cachedTarget: { host: "127.0.0.1", port: cachedServerPort },
+      freshTarget: { host: "127.0.0.1", port: options.freshClientPort },
+      pollIntervalMs: options.pollIntervalMs
+    });
+    const address = await switcher.start();
+    const runtimeMarker = {
+      schemaVersion: 1,
+      status: "cached-serving",
+      generationId: resolved.generationId,
+      publicPort: address.port,
+      cachedServerPort,
+      freshServerPort: options.freshServerPort,
+      freshClientPort: options.freshClientPort,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeMarkerAtomic(markerFile, runtimeMarker);
+    const cutover = switcher.cutover.then(async (result) => {
+      if (result.switched) {
+        runtimeMarker.status = "fresh-serving";
+        runtimeMarker.cutoverAt = result.at;
+        writeMarkerAtomic(markerFile, runtimeMarker);
+        await sleep2(options.cachedDrainMs ?? 5e3);
+        stopProcessGroup2(cachedRuntime);
+        cachedRuntime = void 0;
+      }
+      return result;
+    });
+    return {
+      started: true,
+      generationId: resolved.generationId,
+      origin: address.origin,
+      port: address.port,
+      runtimeDir,
+      cutover,
+      close: cleanup
+    };
+  } catch (error) {
+    await cleanup();
+    return {
+      started: false,
+      reasons: [error instanceof Error ? error.message : String(error)]
+    };
+  }
+}
+
 // src/commands/build/index.ts
 var getTokenCommand = {
   name: "get-token",
   description: "Get artifact upload credential (STI token)",
   register(program) {
-    program.command(this.name).description(this.description).requiredOption("--app-id <id>", "Application ID").requiredOption("--scene <scene>", "Build scene (pipeline, static)").option("--commit-id <id>", "Git commit ID (required for pipeline scene)").action(async (options) => {
-      await getToken(options);
-    });
+    program.command(this.name).description(this.description).requiredOption("--app-id <id>", "Application ID").requiredOption("--scene <scene>", "Build scene (pipeline, static)").option("--commit-id <id>", "Git commit ID (required for pipeline scene)").action(
+      async (options) => {
+        await getToken(options);
+      }
+    );
   }
 };
 var uploadStaticCommand = {
   name: "upload-static",
   description: "Upload shared/static files to TOS",
   register(program) {
-    program.command(this.name).description(this.description).requiredOption("--app-id <id>", "Application ID").option("--static-dir <dir>", "Static files directory", UPLOAD_STATIC_DEFAULTS.staticDir).option("--tosutil-path <path>", "Path to tosutil binary", UPLOAD_STATIC_DEFAULTS.tosutilPath).option("--endpoint <endpoint>", "TOS endpoint", UPLOAD_STATIC_DEFAULTS.endpoint).option("--region <region>", "TOS region", UPLOAD_STATIC_DEFAULTS.region).action(async (options) => {
+    program.command(this.name).description(this.description).requiredOption("--app-id <id>", "Application ID").option(
+      "--static-dir <dir>",
+      "Static files directory",
+      UPLOAD_STATIC_DEFAULTS.staticDir
+    ).option(
+      "--tosutil-path <path>",
+      "Path to tosutil binary",
+      UPLOAD_STATIC_DEFAULTS.tosutilPath
+    ).option(
+      "--endpoint <endpoint>",
+      "TOS endpoint",
+      UPLOAD_STATIC_DEFAULTS.endpoint
+    ).option("--region <region>", "TOS region", UPLOAD_STATIC_DEFAULTS.region).action(async (options) => {
       await uploadStatic(options);
     });
   }
@@ -8666,6 +9741,93 @@ var previewServerArtifactCommand = {
     );
   }
 };
+var previewArtifactGenerationCommand = {
+  name: "preview-artifact-generation",
+  description: "Build, probe, promote, and atomically publish a Preview Artifact generation",
+  register(program) {
+    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"
+    ).action(
+      async (options) => {
+        const result = await producePreviewArtifactGeneration(options);
+        console.log(JSON.stringify(result));
+        if (!result.published) process.exitCode = 2;
+      }
+    );
+  }
+};
+function parseTcpPort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`invalid TCP port: ${value}`);
+  }
+  return port;
+}
+var previewArtifactRuntimeCommand = {
+  name: "preview-artifact-runtime",
+  description: "Serve a verified Preview Artifact and switch to the fresh dev service",
+  register(program) {
+    program.command(this.name).description(this.description).requiredOption("--store-root <dir>", "Immutable generation store root").option(
+      "--runtime-root <dir>",
+      "Ephemeral runtime root",
+      "/tmp/preview-artifact"
+    ).option(
+      "--marker-file <file>",
+      "Atomic runtime marker file",
+      "/tmp/preview-artifact/runtime.json"
+    ).option(
+      "--listen-port <port>",
+      "Stable public preview port",
+      parseTcpPort,
+      8001
+    ).option(
+      "--cached-server-port <port>",
+      "Isolated cached Nest server port, 0 selects a free port",
+      parseTcpPort,
+      0
+    ).option(
+      "--fresh-server-port <port>",
+      "Fresh Nest shadow port recorded for dev startup",
+      parseTcpPort,
+      3001
+    ).option(
+      "--fresh-client-port <port>",
+      "Fresh Vite shadow port used as the cutover target",
+      parseTcpPort,
+      8002
+    ).requiredOption(
+      "--app-base-path <path>",
+      "Application HTML readiness path"
+    ).action(
+      async (options) => {
+        const runtime = await startPreviewArtifactRuntime(options);
+        if (!runtime.started) {
+          console.log(JSON.stringify(runtime));
+          process.exitCode = 2;
+          return;
+        }
+        console.log(
+          JSON.stringify({
+            started: true,
+            generationId: runtime.generationId,
+            origin: runtime.origin,
+            runtimeDir: runtime.runtimeDir
+          })
+        );
+        void runtime.cutover.then((result) => {
+          console.log(JSON.stringify({ event: "fresh-cutover", ...result }));
+        });
+        const shutdown = async () => {
+          await runtime.close();
+          process.exit(0);
+        };
+        process.once("SIGTERM", () => void shutdown());
+        process.once("SIGINT", () => void shutdown());
+      }
+    );
+  }
+};
 var buildCommandGroup = {
   name: "build",
   description: "Build related commands",
@@ -8673,7 +9835,9 @@ var buildCommandGroup = {
     getTokenCommand,
     uploadStaticCommand,
     preUploadStaticCommand,
-    previewServerArtifactCommand
+    previewServerArtifactCommand,
+    previewArtifactGenerationCommand,
+    previewArtifactRuntimeCommand
   ]
 };
 
@@ -8691,12 +9855,12 @@ var commands = [
 ];
 
 // src/index.ts
-var envPath = path26.join(process.cwd(), ".env");
-if (fs30.existsSync(envPath)) {
+var envPath = path31.join(process.cwd(), ".env");
+if (fs35.existsSync(envPath)) {
   dotenvConfig({ path: envPath });
 }
-var __dirname = path26.dirname(fileURLToPath5(import.meta.url));
-var pkg = JSON.parse(fs30.readFileSync(path26.join(__dirname, "../package.json"), "utf-8"));
+var __dirname = path31.dirname(fileURLToPath5(import.meta.url));
+var pkg = JSON.parse(fs35.readFileSync(path31.join(__dirname, "../package.json"), "utf-8"));
 var cli = new FullstackCLI(pkg.version);
 cli.useAll(commands);
 cli.run();