@lark-apaas/fullstack-cli 1.1.59-alpha.20260724074215 → 1.1.59-alpha.20260802184501

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
-import fs37 from "fs";
-import path33 from "path";
+import fs38 from "fs";
+import path34 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((resolve9) => {
+  return new Promise((resolve10) => {
     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();
-      resolve9({
+      resolve10({
         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);
-      resolve9({
+      resolve10({
         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((resolve9) => {
+  return new Promise((resolve10) => {
     execFile("fullstack-cli", ["action-plugin", "init"], { cwd: process.cwd(), stdio: "ignore" }, (error) => {
       if (error) {
         debug("action-plugin init \u5931\u8D25: %s", error.message);
       }
-      resolve9();
+      resolve10();
     });
   });
 }
@@ -8677,16 +8677,270 @@ async function buildPreviewServerArtifact(options) {
 }
 
 // src/commands/preview-artifact/producer.ts
-import * as crypto3 from "crypto";
-import * as fs34 from "fs";
-import * as path30 from "path";
-import { spawnSync as spawnSync8 } from "child_process";
+import * as crypto4 from "crypto";
+import * as fs35 from "fs";
+import * as path31 from "path";
+import { spawnSync as spawnSync9 } from "child_process";
 
 // src/commands/preview-artifact/generation.ts
+import * as crypto2 from "crypto";
+import * as fs31 from "fs";
+import * as path27 from "path";
+
+// src/commands/preview-artifact/workspace-identity.ts
 import * as crypto from "crypto";
+import { spawnSync as spawnSync7 } from "child_process";
 import * as fs30 from "fs";
+import * as os4 from "os";
 import * as path26 from "path";
-var PREVIEW_ARTIFACT_SCHEMA_VERSION = 3;
+var PREVIEW_ARTIFACT_WORKSPACE_MANIFEST_SCHEMA_VERSION = 1;
+var WORKSPACE_IDENTITY_DOMAIN = "workspace-content:v1\n";
+var WORKSPACE_BACKUP_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var GIT_OBJECT_ID_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+var SOURCE_TREE_ID_PATTERN = /^git-tree-(sha1|sha256):([a-f0-9]{40}|[a-f0-9]{64})$/;
+var WORKSPACE_VERSION_PATTERN = /^sha256:[a-f0-9]{64}$/;
+function normalizeSourceTreeIncludePaths(values) {
+  if (!values || values.length === 0) return [];
+  const normalized = /* @__PURE__ */ new Set();
+  for (const rawValue of values) {
+    if (typeof rawValue !== "string" || rawValue.includes("\0") || rawValue.includes("\n") || rawValue.includes("\r") || rawValue.includes("\\")) {
+      throw new Error(`invalid source tree include path: ${String(rawValue)}`);
+    }
+    const value = path26.posix.normalize(rawValue.trim());
+    if (!value || value === ".." || value.startsWith("../") || path26.posix.isAbsolute(value)) {
+      throw new Error(`invalid source tree include path: ${rawValue}`);
+    }
+    if (value === ".") return [];
+    normalized.add(value.replace(/\/$/, ""));
+  }
+  return [...normalized].sort((left, right) => left.localeCompare(right));
+}
+function createPreviewArtifactSourceTreeValidation(enabled, includePaths) {
+  return enabled ? {
+    enabled: true,
+    includePaths: normalizeSourceTreeIncludePaths(includePaths)
+  } : { enabled: false, includePaths: [] };
+}
+function previewArtifactSourceTreeValidation(identity) {
+  if (identity.sourceTreeValidation == null) {
+    return identity.sourceTreeId != null || identity.workspaceVersion != null ? { enabled: true, includePaths: [] } : { enabled: false, includePaths: [] };
+  }
+  return identity.sourceTreeValidation;
+}
+function samePreviewArtifactSourceTreeValidation(left, right) {
+  return left.enabled === right.enabled && left.includePaths.length === right.includePaths.length && left.includePaths.every(
+    (value, index) => value === right.includePaths[index]
+  );
+}
+function runGit(projectRoot, args, environment, allowFailure = false) {
+  const result = spawnSync7("git", args, {
+    cwd: projectRoot,
+    env: { ...process.env, ...environment },
+    encoding: "utf8",
+    maxBuffer: 10 * 1024 * 1024
+  });
+  if (result.status === 0) return result.stdout.trim();
+  if (allowFailure) return void 0;
+  const diagnostic = `${result.stderr ?? ""}
+${result.stdout ?? ""}`.trim().slice(-8 * 1024);
+  throw new Error(
+    `git ${args.join(" ")} failed with exit ${result.status ?? "unknown"}${diagnostic ? `: ${diagnostic}` : ""}`
+  );
+}
+function resolveGitPath(projectRoot, relativePath) {
+  return path26.isAbsolute(relativePath) ? relativePath : path26.resolve(projectRoot, relativePath);
+}
+function writeJsonAtomic(filePath, value) {
+  fs30.mkdirSync(path26.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs30.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
+`, {
+      mode: 384
+    });
+    fs30.renameSync(temporaryPath, filePath);
+  } finally {
+    fs30.rmSync(temporaryPath, { force: true });
+  }
+}
+function gitObjectFormat(projectRoot, treeId) {
+  const reported = runGit(
+    projectRoot,
+    ["rev-parse", "--show-object-format"],
+    void 0,
+    true
+  );
+  if (reported === "sha1" || reported === "sha256") return reported;
+  if (treeId.length === 40) return "sha1";
+  if (treeId.length === 64) return "sha256";
+  throw new Error(`unsupported Git tree object ID: ${treeId}`);
+}
+function workspaceVersionForSourceTreeId(sourceTreeId) {
+  if (!SOURCE_TREE_ID_PATTERN.test(sourceTreeId)) {
+    throw new Error(`invalid sourceTreeId: ${sourceTreeId}`);
+  }
+  return `sha256:${crypto.createHash("sha256").update(`${WORKSPACE_IDENTITY_DOMAIN}${sourceTreeId}`).digest("hex")}`;
+}
+function validatePreviewArtifactWorkspaceManifest(manifest) {
+  const reasons = [];
+  if (manifest.schemaVersion !== PREVIEW_ARTIFACT_WORKSPACE_MANIFEST_SCHEMA_VERSION) {
+    reasons.push("workspace manifest schema version is incompatible");
+  }
+  reasons.push(...validatePreviewArtifactWorkspaceIdentity(manifest));
+  if (typeof manifest.appId !== "string" || manifest.appId.length === 0 || manifest.appId.length > 256) {
+    reasons.push("workspace application ID is invalid");
+  }
+  if (typeof manifest.createdAt !== "string" || !Number.isFinite(Date.parse(manifest.createdAt))) {
+    reasons.push("workspace manifest creation time is invalid");
+  }
+  return reasons;
+}
+function validatePreviewArtifactWorkspaceIdentity(identity) {
+  const reasons = [];
+  if (!WORKSPACE_BACKUP_ID_PATTERN.test(identity.workspaceBackupId)) {
+    reasons.push("workspace backup ID is invalid");
+  }
+  if (identity.commitId !== "UNBORN" && !GIT_OBJECT_ID_PATTERN.test(identity.commitId)) {
+    reasons.push("workspace commit ID is invalid");
+  }
+  const validation = previewArtifactSourceTreeValidation(identity);
+  let normalizedIncludePaths;
+  try {
+    normalizedIncludePaths = normalizeSourceTreeIncludePaths(
+      validation.includePaths
+    );
+  } catch {
+    reasons.push("workspace source tree include paths are invalid");
+  }
+  if (typeof validation.enabled !== "boolean" || !Array.isArray(validation.includePaths) || !normalizedIncludePaths || normalizedIncludePaths.length !== validation.includePaths.length || normalizedIncludePaths.some(
+    (value, index) => value !== validation.includePaths[index]
+  )) {
+    reasons.push("workspace source tree validation policy is invalid");
+  }
+  if (!validation.enabled) {
+    if (identity.sourceTreeId != null || identity.workspaceVersion != null) {
+      reasons.push(
+        "disabled source tree validation must not persist an identity"
+      );
+    }
+    return reasons;
+  }
+  if (typeof identity.sourceTreeId !== "string" || !SOURCE_TREE_ID_PATTERN.test(identity.sourceTreeId)) {
+    reasons.push("workspace source tree ID is invalid");
+  }
+  if (typeof identity.workspaceVersion !== "string" || !WORKSPACE_VERSION_PATTERN.test(identity.workspaceVersion)) {
+    reasons.push("workspace version is invalid");
+  } else if (typeof identity.sourceTreeId === "string") {
+    try {
+      if (workspaceVersionForSourceTreeId(identity.sourceTreeId) !== identity.workspaceVersion) {
+        reasons.push("workspace version does not match source tree ID");
+      }
+    } catch {
+    }
+  }
+  return reasons;
+}
+function readPreviewArtifactWorkspaceManifest(manifestFile) {
+  const manifest = JSON.parse(
+    fs30.readFileSync(path26.resolve(manifestFile), "utf8")
+  );
+  const reasons = validatePreviewArtifactWorkspaceManifest(manifest);
+  if (reasons.length > 0) {
+    throw new Error(reasons.join("; "));
+  }
+  return manifest;
+}
+function createPreviewArtifactWorkspaceManifest(options) {
+  if (!WORKSPACE_BACKUP_ID_PATTERN.test(options.workspaceBackupId)) {
+    throw new Error(
+      `invalid workspace backup ID: ${options.workspaceBackupId}`
+    );
+  }
+  if (!options.appId || options.appId.length > 256) {
+    throw new Error(`invalid application ID: ${options.appId}`);
+  }
+  const projectRoot = fs30.realpathSync(path26.resolve(options.projectRoot));
+  const repositoryRoot = runGit(projectRoot, ["rev-parse", "--show-toplevel"]);
+  if (!repositoryRoot || fs30.realpathSync(repositoryRoot) !== projectRoot) {
+    throw new Error("project root must be the Git repository root");
+  }
+  const sourceTreeValidation = createPreviewArtifactSourceTreeValidation(
+    options.validateSourceTree,
+    options.sourceTreeIncludePaths
+  );
+  let sourceTreeId;
+  let workspaceVersion;
+  if (sourceTreeValidation.enabled) {
+    const temporaryRoot = fs30.mkdtempSync(
+      path26.join(os4.tmpdir(), "preview-workspace-identity-")
+    );
+    try {
+      const temporaryIndex = path26.join(temporaryRoot, "index");
+      const temporaryObjects = path26.join(temporaryRoot, "objects");
+      fs30.mkdirSync(temporaryObjects, { recursive: true });
+      const gitObjectsPath = resolveGitPath(
+        projectRoot,
+        runGit(projectRoot, ["rev-parse", "--git-path", "objects"])
+      );
+      const isolatedGitEnvironment = {
+        GIT_INDEX_FILE: temporaryIndex,
+        GIT_OBJECT_DIRECTORY: temporaryObjects,
+        GIT_ALTERNATE_OBJECT_DIRECTORIES: gitObjectsPath,
+        GIT_OPTIONAL_LOCKS: "0"
+      };
+      runGit(projectRoot, ["read-tree", "--empty"], isolatedGitEnvironment);
+      const includedPaths = sourceTreeValidation.includePaths.length === 0 ? ["."] : sourceTreeValidation.includePaths.filter(
+        (includedPath) => fs30.existsSync(path26.join(projectRoot, includedPath))
+      );
+      if (includedPaths.length > 0) {
+        runGit(
+          projectRoot,
+          [
+            "add",
+            "-A",
+            "--",
+            ...includedPaths.map(
+              (includedPath) => includedPath === "." ? "." : `:(top,literal)${includedPath}`
+            )
+          ],
+          isolatedGitEnvironment
+        );
+      }
+      const treeId = runGit(
+        projectRoot,
+        ["write-tree"],
+        isolatedGitEnvironment
+      );
+      if (!treeId || !GIT_OBJECT_ID_PATTERN.test(treeId)) {
+        throw new Error(
+          `git write-tree returned an invalid object ID: ${treeId}`
+        );
+      }
+      sourceTreeId = `git-tree-${gitObjectFormat(
+        projectRoot,
+        treeId
+      )}:${treeId}`;
+      workspaceVersion = workspaceVersionForSourceTreeId(sourceTreeId);
+    } finally {
+      fs30.rmSync(temporaryRoot, { recursive: true, force: true });
+    }
+  }
+  const manifest = {
+    schemaVersion: PREVIEW_ARTIFACT_WORKSPACE_MANIFEST_SCHEMA_VERSION,
+    workspaceBackupId: options.workspaceBackupId,
+    appId: options.appId,
+    commitId: runGit(projectRoot, ["rev-parse", "HEAD"], void 0, true) ?? "UNBORN",
+    sourceTreeValidation,
+    ...sourceTreeId == null ? {} : { sourceTreeId },
+    ...workspaceVersion == null ? {} : { workspaceVersion },
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeJsonAtomic(path26.resolve(options.manifestFile), manifest);
+  return manifest;
+}
+
+// src/commands/preview-artifact/generation.ts
+var PREVIEW_ARTIFACT_SCHEMA_VERSION = 4;
 var PREVIEW_ARTIFACT_PROTOCOL_VERSION = 3;
 var MANIFEST_FILE = "manifest.json";
 var PROBE_FILE = "probe.json";
@@ -8733,7 +8987,7 @@ function previewArtifactBuildEnvironmentHash(environment, appBasePath) {
       ([left], [right]) => left.localeCompare(right)
     )
   );
-  return crypto.createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+  return crypto2.createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
 }
 function parseNodeMajor(nodeVersion) {
   const match = /^v?(\d+)(?:\.|$)/.exec(nodeVersion.trim());
@@ -8743,13 +8997,13 @@ function parseNodeMajor(nodeVersion) {
   return Number(match[1]);
 }
 function sha256File(filePath) {
-  const hash = crypto.createHash("sha256");
-  hash.update(fs30.readFileSync(filePath));
+  const hash = crypto2.createHash("sha256");
+  hash.update(fs31.readFileSync(filePath));
   return hash.digest("hex");
 }
 function fileIdentity(generationDir, relativePath) {
-  const filePath = path26.join(generationDir, relativePath);
-  const stat = fs30.lstatSync(filePath);
+  const filePath = path27.join(generationDir, relativePath);
+  const stat = fs31.lstatSync(filePath);
   if (!stat.isFile() || stat.isSymbolicLink()) {
     throw new Error(`artifact file must be a regular file: ${relativePath}`);
   }
@@ -8760,16 +9014,16 @@ function fileIdentity(generationDir, relativePath) {
   };
 }
 function readJson2(filePath) {
-  return JSON.parse(fs30.readFileSync(filePath, "utf8"));
+  return JSON.parse(fs31.readFileSync(filePath, "utf8"));
 }
-function writeJsonAtomic(filePath, value) {
-  fs30.mkdirSync(path26.dirname(filePath), { recursive: true });
+function writeJsonAtomic2(filePath, value) {
+  fs31.mkdirSync(path27.dirname(filePath), { recursive: true });
   const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  fs30.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
+  fs31.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
 `, {
     mode: 384
   });
-  fs30.renameSync(temporaryPath, filePath);
+  fs31.renameSync(temporaryPath, filePath);
 }
 function runtimeIdentity(nodeVersion, platform, arch) {
   return { nodeMajor: parseNodeMajor(nodeVersion), platform, arch };
@@ -8778,12 +9032,23 @@ 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 generationDir = path27.resolve(options.generationDir);
+  const workspaceIdentityReasons = validatePreviewArtifactWorkspaceIdentity(
+    options.workspaceManifest
+  );
+  if (workspaceIdentityReasons.length > 0) {
+    throw new Error(workspaceIdentityReasons.join("; "));
+  }
   const manifest = {
     schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
     protocolVersion: PREVIEW_ARTIFACT_PROTOCOL_VERSION,
     generationId: options.generationId,
     createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    workspaceBackupId: options.workspaceManifest.workspaceBackupId,
+    commitId: options.workspaceManifest.commitId,
+    sourceTreeValidation: options.workspaceManifest.sourceTreeValidation,
+    ...options.workspaceManifest.sourceTreeId == null ? {} : { sourceTreeId: options.workspaceManifest.sourceTreeId },
+    ...options.workspaceManifest.workspaceVersion == null ? {} : { workspaceVersion: options.workspaceManifest.workspaceVersion },
     buildEnvironmentSha256: options.buildEnvironmentSha256,
     runtime: runtimeIdentity(
       options.nodeVersion,
@@ -8798,14 +9063,14 @@ function createPreviewArtifactManifest(options) {
     runtimeProbeStatus: "not-run",
     consumable: false
   };
-  writeJsonAtomic(path26.join(generationDir, MANIFEST_FILE), manifest);
-  fs30.rmSync(path26.join(generationDir, PROBE_FILE), { force: true });
+  writeJsonAtomic2(path27.join(generationDir, MANIFEST_FILE), manifest);
+  fs31.rmSync(path27.join(generationDir, PROBE_FILE), { force: true });
   return manifest;
 }
 function recordPreviewArtifactProbe(options) {
-  const generationDir = path26.resolve(options.generationDir);
+  const generationDir = path27.resolve(options.generationDir);
   const manifest = readJson2(
-    path26.join(generationDir, MANIFEST_FILE)
+    path27.join(generationDir, MANIFEST_FILE)
   );
   const probe = {
     schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
@@ -8818,8 +9083,8 @@ function recordPreviewArtifactProbe(options) {
       options.platform,
       options.arch
     ),
-    serverSha256: sha256File(path26.join(generationDir, SERVER_FILE)),
-    clientSha256: sha256File(path26.join(generationDir, CLIENT_FILE)),
+    serverSha256: sha256File(path27.join(generationDir, SERVER_FILE)),
+    clientSha256: sha256File(path27.join(generationDir, CLIENT_FILE)),
     coverage: {
       html: options.coverage.html,
       businessApi: options.coverage.businessApi,
@@ -8827,20 +9092,20 @@ function recordPreviewArtifactProbe(options) {
       actionPlugins: Array.from(new Set(options.coverage.actionPlugins)).sort()
     }
   };
-  writeJsonAtomic(path26.join(generationDir, PROBE_FILE), probe);
+  writeJsonAtomic2(path27.join(generationDir, PROBE_FILE), probe);
   return probe;
 }
 function promotePreviewArtifactGeneration(generationDirInput) {
-  const generationDir = path26.resolve(generationDirInput);
+  const generationDir = path27.resolve(generationDirInput);
   const reasons = [];
   let manifest;
   let probe;
   try {
     manifest = readJson2(
-      path26.join(generationDir, MANIFEST_FILE)
+      path27.join(generationDir, MANIFEST_FILE)
     );
     probe = readJson2(
-      path26.join(generationDir, PROBE_FILE)
+      path27.join(generationDir, PROBE_FILE)
     );
   } catch (error) {
     return {
@@ -8864,8 +9129,8 @@ function promotePreviewArtifactGeneration(generationDirInput) {
       "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));
+  const currentServerHash = sha256File(path27.join(generationDir, SERVER_FILE));
+  const currentClientHash = sha256File(path27.join(generationDir, CLIENT_FILE));
   if (currentServerHash !== manifest.files.server.sha256 || currentServerHash !== probe.serverSha256) {
     reasons.push("server.bundle.cjs hash does not match probe identity");
   }
@@ -8898,16 +9163,16 @@ function promotePreviewArtifactGeneration(generationDirInput) {
     runtimeProbeStatus: "passed",
     consumable: true
   };
-  writeJsonAtomic(path26.join(generationDir, MANIFEST_FILE), promotedManifest);
+  writeJsonAtomic2(path27.join(generationDir, MANIFEST_FILE), promotedManifest);
   return { promoted: true, manifest: promotedManifest };
 }
 
 // src/commands/preview-artifact/probe.ts
-import * as fs31 from "fs";
+import * as fs32 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";
+import * as os5 from "os";
+import * as path28 from "path";
+import { spawn as spawn2, spawnSync as spawnSync8 } from "child_process";
 
 // src/commands/preview-artifact/readiness.ts
 function isPreviewBusinessResponseReady(response) {
@@ -8917,10 +9182,10 @@ function isPreviewBusinessResponseReady(response) {
 
 // src/commands/preview-artifact/probe.ts
 function sleep(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 async function reservePort() {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const server = net.createServer();
     server.unref();
     server.once("error", reject);
@@ -8932,13 +9197,13 @@ async function reservePort() {
       }
       server.close((error) => {
         if (error) reject(error);
-        else resolve9(address.port);
+        else resolve10(address.port);
       });
     });
   });
 }
 function archiveEntries(archivePath) {
-  const listing = spawnSync7("unzip", ["-Z1", archivePath], {
+  const listing = spawnSync8("unzip", ["-Z1", archivePath], {
     encoding: "utf8"
   });
   if (listing.status !== 0) {
@@ -8946,15 +9211,15 @@ function archiveEntries(archivePath) {
   }
   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("../")) {
+    const normalized = path28.posix.normalize(entry.replaceAll("\\", "/"));
+    if (path28.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], {
+  const listing = spawnSync8("unzip", ["-Z", "-l", archivePath], {
     encoding: "utf8"
   });
   if (listing.status !== 0) {
@@ -8973,9 +9238,9 @@ function rejectSymlinks(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);
+    for (const entry of fs32.readdirSync(current, { withFileTypes: true })) {
+      const entryPath = path28.join(current, entry.name);
+      const stat = fs32.lstatSync(entryPath);
       if (stat.isSymbolicLink()) {
         throw new Error(`client archive contains symlink: ${entry.name}`);
       }
@@ -8988,8 +9253,8 @@ function inspectClientArchive(archivePath) {
   rejectArchivedSymlinks(archivePath);
 }
 function isPathInside(parent, candidate) {
-  const relative5 = path27.relative(parent, candidate);
-  return relative5 !== "" && relative5 !== ".." && !relative5.startsWith(`..${path27.sep}`) && !path27.isAbsolute(relative5);
+  const relative5 = path28.relative(parent, candidate);
+  return relative5 !== "" && relative5 !== ".." && !relative5.startsWith(`..${path28.sep}`) && !path28.isAbsolute(relative5);
 }
 function clientEntryAssetReferences(html, appBasePath) {
   const local = /* @__PURE__ */ new Set();
@@ -9049,23 +9314,23 @@ function resolveClientEntryAsset(clientRoot, appBasePath, requestPath) {
   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);
+  const candidate = path28.resolve(clientRoot, relative5);
   if (!isPathInside(clientRoot, candidate)) return void 0;
   try {
-    const stat = fs31.lstatSync(candidate);
+    const stat = fs32.lstatSync(candidate);
     return stat.isFile() && !stat.isSymbolicLink() ? candidate : void 0;
   } catch {
     return void 0;
   }
 }
 function extractClientArchive(archivePath, destination) {
-  if (fs31.existsSync(destination)) {
+  if (fs32.existsSync(destination)) {
     throw new Error("client archive destination must not already exist");
   }
   inspectClientArchive(archivePath);
-  fs31.mkdirSync(destination, { recursive: true });
+  fs32.mkdirSync(destination, { recursive: true });
   try {
-    const extraction = spawnSync7(
+    const extraction = spawnSync8(
       "unzip",
       ["-q", archivePath, "-d", destination],
       { encoding: "utf8" }
@@ -9077,17 +9342,17 @@ function extractClientArchive(archivePath, destination) {
     }
     rejectSymlinks(destination);
   } catch (error) {
-    fs31.rmSync(destination, { recursive: true, force: true });
+    fs32.rmSync(destination, { recursive: true, force: true });
     throw error;
   }
 }
 async function extractInspectedClientArchive(archivePath, destination) {
-  if (fs31.existsSync(destination)) {
+  if (fs32.existsSync(destination)) {
     throw new Error("client archive destination must not already exist");
   }
-  fs31.mkdirSync(destination, { recursive: true });
+  fs32.mkdirSync(destination, { recursive: true });
   try {
-    await new Promise((resolve9, reject) => {
+    await new Promise((resolve10, reject) => {
       const extraction = spawn2(
         "unzip",
         ["-q", archivePath, "-d", destination],
@@ -9100,7 +9365,7 @@ async function extractInspectedClientArchive(archivePath, destination) {
       });
       extraction.once("error", reject);
       extraction.once("close", (code) => {
-        if (code === 0) resolve9();
+        if (code === 0) resolve10();
         else
           reject(
             new Error(
@@ -9111,7 +9376,7 @@ async function extractInspectedClientArchive(archivePath, destination) {
     });
     rejectSymlinks(destination);
   } catch (error) {
-    fs31.rmSync(destination, { recursive: true, force: true });
+    fs32.rmSync(destination, { recursive: true, force: true });
     throw error;
   }
 }
@@ -9141,9 +9406,9 @@ function stopProcessGroup(pid) {
   }
 }
 async function runPreviewArtifactProbe(options) {
-  const generationDir = path27.resolve(options.generationDir);
-  const runtimeRoot = fs31.mkdtempSync(
-    path27.join(os4.tmpdir(), "preview-artifact-probe-")
+  const generationDir = path28.resolve(options.generationDir);
+  const runtimeRoot = fs32.mkdtempSync(
+    path28.join(os5.tmpdir(), "preview-artifact-probe-")
   );
   const coverage = {
     html: false,
@@ -9152,19 +9417,19 @@ async function runPreviewArtifactProbe(options) {
     actionPlugins: []
   };
   const reasons = [];
-  const registryFile = path27.join(runtimeRoot, "plugin-registry.json");
+  const registryFile = path28.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"),
+    const runtimeBundle = path28.join(runtimeRoot, "server.bundle.cjs");
+    fs32.copyFileSync(
+      path28.join(generationDir, "server.bundle.cjs"),
       runtimeBundle
     );
-    const clientRoot = path27.join(runtimeRoot, "dist", "client");
-    extractClientArchive(path27.join(generationDir, "client.zip"), clientRoot);
-    isolatedNodeModulesPresent = fs31.existsSync(
-      path27.join(runtimeRoot, "node_modules")
+    const clientRoot = path28.join(runtimeRoot, "dist", "client");
+    extractClientArchive(path28.join(generationDir, "client.zip"), clientRoot);
+    isolatedNodeModulesPresent = fs32.existsSync(
+      path28.join(runtimeRoot, "node_modules")
     );
     if (isolatedNodeModulesPresent) {
       reasons.push("isolated runtime unexpectedly contains node_modules");
@@ -9227,12 +9492,12 @@ async function runPreviewArtifactProbe(options) {
         `business API returned ${apiResponse?.status ?? "unreachable"}`
       );
     }
-    while (!fs31.existsSync(registryFile) && Date.now() < timeoutAt) {
+    while (!fs32.existsSync(registryFile) && Date.now() < timeoutAt) {
       await sleep(25);
     }
-    if (fs31.existsSync(registryFile)) {
+    if (fs32.existsSync(registryFile)) {
       const parsed = JSON.parse(
-        fs31.readFileSync(registryFile, "utf8")
+        fs32.readFileSync(registryFile, "utf8")
       );
       if (Array.isArray(parsed) && parsed.every((value) => typeof value === "string")) {
         coverage.actionPlugins = parsed.filter((value) => typeof value === "string").sort();
@@ -9256,17 +9521,17 @@ async function runPreviewArtifactProbe(options) {
     arch: process.arch,
     coverage
   });
-  fs31.rmSync(runtimeRoot, { recursive: true, force: true });
+  fs32.rmSync(runtimeRoot, { recursive: true, force: true });
   return { ...probe, isolatedNodeModulesPresent };
 }
 
 // src/commands/preview-artifact/environment.ts
-import * as fs32 from "fs";
-import * as path28 from "path";
+import * as fs33 from "fs";
+import * as path29 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"));
+  const resolved = path29.resolve(filePath);
+  const parsed = JSON.parse(fs33.readFileSync(resolved, "utf8"));
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error("preview artifact environment file must contain an object");
   }
@@ -9291,40 +9556,42 @@ function previewArtifactRuntimeEnvironment(environment) {
 }
 
 // src/commands/preview-artifact/store.ts
-import * as crypto2 from "crypto";
-import * as fs33 from "fs";
-import * as path29 from "path";
+import * as crypto3 from "crypto";
+import * as fs34 from "fs";
+import * as path30 from "path";
 var GENERATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var WORKSPACE_BACKUP_ID_PATTERN2 = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var WORKSPACE_VERSION_PATTERN2 = /^sha256:[a-f0-9]{64}$/;
 function readCurrentPointer(storeRoot) {
   try {
     const pointer = readJson3(
-      path29.join(storeRoot, "current.json")
+      path30.join(storeRoot, "current.json")
     );
-    return pointer.schemaVersion === PREVIEW_ARTIFACT_SCHEMA_VERSION && GENERATION_ID_PATTERN.test(pointer.generationId) ? pointer : void 0;
+    return pointer.schemaVersion === PREVIEW_ARTIFACT_SCHEMA_VERSION && GENERATION_ID_PATTERN.test(pointer.generationId) && WORKSPACE_BACKUP_ID_PATTERN2.test(pointer.workspaceBackupId) && (pointer.workspaceVersion == null || WORKSPACE_VERSION_PATTERN2.test(pointer.workspaceVersion)) ? pointer : void 0;
   } catch {
     return void 0;
   }
 }
 function readJson3(filePath) {
-  return JSON.parse(fs33.readFileSync(filePath, "utf8"));
+  return JSON.parse(fs34.readFileSync(filePath, "utf8"));
 }
-function writeJsonAtomic2(filePath, value) {
-  fs33.mkdirSync(path29.dirname(filePath), { recursive: true });
+function writeJsonAtomic3(filePath, value) {
+  fs34.mkdirSync(path30.dirname(filePath), { recursive: true });
   const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  fs33.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
+  fs34.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}
 `, {
     mode: 384
   });
-  fs33.renameSync(temporaryPath, filePath);
+  fs34.renameSync(temporaryPath, filePath);
 }
 function pruneSupersededGenerations(generationsRoot, retainedGenerationIds) {
   const retained = new Set(retainedGenerationIds);
-  for (const entry of fs33.readdirSync(generationsRoot, {
+  for (const entry of fs34.readdirSync(generationsRoot, {
     withFileTypes: true
   })) {
     if (retained.has(entry.name)) continue;
     try {
-      fs33.rmSync(path29.join(generationsRoot, entry.name), {
+      fs34.rmSync(path30.join(generationsRoot, entry.name), {
         recursive: true,
         force: true
       });
@@ -9337,12 +9604,12 @@ function parseNodeMajor2(nodeVersion) {
   return match ? Number(match[1]) : null;
 }
 function isPathInside2(parent, candidate) {
-  const relative5 = path29.relative(parent, candidate);
-  return relative5 !== "" && !relative5.startsWith(`..${path29.sep}`) && relative5 !== ".." && !path29.isAbsolute(relative5);
+  const relative5 = path30.relative(parent, candidate);
+  return relative5 !== "" && !relative5.startsWith(`..${path30.sep}`) && relative5 !== ".." && !path30.isAbsolute(relative5);
 }
 function validateRegularDirectory(directoryPath, label) {
   try {
-    const stat = fs33.lstatSync(directoryPath);
+    const stat = fs34.lstatSync(directoryPath);
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
       return [`${label} must be a regular directory`];
     }
@@ -9363,10 +9630,10 @@ function validateGeneration(generationDir, runtime, verifyPayloads = true) {
   let probe;
   try {
     manifest = readJson3(
-      path29.join(generationDir, "manifest.json")
+      path30.join(generationDir, "manifest.json")
     );
     probe = readJson3(
-      path29.join(generationDir, "probe.json")
+      path30.join(generationDir, "probe.json")
     );
   } catch (error) {
     return {
@@ -9393,6 +9660,7 @@ function validateGeneration(generationDir, runtime, verifyPayloads = true) {
   if (!/^[a-f0-9]{64}$/.test(manifest.buildEnvironmentSha256)) {
     reasons.push("build environment identity is invalid");
   }
+  reasons.push(...validatePreviewArtifactWorkspaceIdentity(manifest));
   for (const [label, identity, expectedPath] of [
     ["server", manifest.files?.server, "server.bundle.cjs"],
     ["client", manifest.files?.client, "client.zip"]
@@ -9402,8 +9670,8 @@ function validateGeneration(generationDir, runtime, verifyPayloads = true) {
     }
   }
   if (verifyPayloads && manifest.files?.server && manifest.files?.client) {
-    const serverPath = path29.join(generationDir, "server.bundle.cjs");
-    const clientPath = path29.join(generationDir, "client.zip");
+    const serverPath = path30.join(generationDir, "server.bundle.cjs");
+    const clientPath = path30.join(generationDir, "client.zip");
     try {
       if (sha256File(serverPath) !== manifest.files.server.sha256) {
         reasons.push("server.bundle.cjs hash does not match manifest");
@@ -9426,10 +9694,10 @@ function validateGeneration(generationDir, runtime, verifyPayloads = true) {
   return { manifest, reasons };
 }
 function publishPreviewArtifactGeneration(options) {
-  const storeRoot = path29.resolve(options.storeRoot);
+  const storeRoot = path30.resolve(options.storeRoot);
   const previousPointer = readCurrentPointer(storeRoot);
-  const stagingRoot = path29.join(storeRoot, ".staging");
-  const stagingDir = path29.resolve(options.stagingDir);
+  const stagingRoot = path30.join(storeRoot, ".staging");
+  const stagingDir = path30.resolve(options.stagingDir);
   if (!isPathInside2(stagingRoot, stagingDir)) {
     return {
       published: false,
@@ -9443,23 +9711,25 @@ function publishPreviewArtifactGeneration(options) {
     return { published: false, reasons: validation.reasons };
   }
   const generationId = validation.manifest.generationId;
-  const generationsRoot = path29.join(storeRoot, "generations");
-  const generationDir = path29.join(generationsRoot, generationId);
-  fs33.mkdirSync(generationsRoot, { recursive: true });
-  if (fs33.existsSync(generationDir)) {
+  const generationsRoot = path30.join(storeRoot, "generations");
+  const generationDir = path30.join(generationsRoot, generationId);
+  fs34.mkdirSync(generationsRoot, { recursive: true });
+  if (fs34.existsSync(generationDir)) {
     return {
       published: false,
       reasons: [`generation already exists: ${generationId}`]
     };
   }
   try {
-    fs33.renameSync(stagingDir, generationDir);
+    fs34.renameSync(stagingDir, generationDir);
     const pointer = {
       schemaVersion: PREVIEW_ARTIFACT_SCHEMA_VERSION,
       generationId,
+      workspaceBackupId: validation.manifest.workspaceBackupId,
+      ...validation.manifest.workspaceVersion == null ? {} : { workspaceVersion: validation.manifest.workspaceVersion },
       publishedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
-    writeJsonAtomic2(path29.join(storeRoot, "current.json"), pointer);
+    writeJsonAtomic3(path30.join(storeRoot, "current.json"), pointer);
     pruneSupersededGenerations(
       generationsRoot,
       [generationId, previousPointer?.generationId].filter(
@@ -9477,10 +9747,37 @@ function publishPreviewArtifactGeneration(options) {
   }
 }
 function resolveCurrentPreviewArtifactMetadata(options) {
-  const storeRoot = path29.resolve(options.storeRoot);
+  if (!options.workspaceManifest) {
+    return {
+      resolved: false,
+      reasons: ["workspace manifest is unavailable"]
+    };
+  }
+  const workspaceManifestReasons = validatePreviewArtifactWorkspaceManifest(
+    options.workspaceManifest
+  );
+  if (workspaceManifestReasons.length > 0) {
+    return {
+      resolved: false,
+      reasons: workspaceManifestReasons
+    };
+  }
+  let requestedSourceTreeValidation;
+  try {
+    requestedSourceTreeValidation = createPreviewArtifactSourceTreeValidation(
+      options.sourceTreeValidation?.enabled,
+      options.sourceTreeValidation?.includePaths
+    );
+  } catch {
+    return {
+      resolved: false,
+      reasons: ["requested source tree validation policy is invalid"]
+    };
+  }
+  const storeRoot = path30.resolve(options.storeRoot);
   let pointer;
   try {
-    pointer = readJson3(path29.join(storeRoot, "current.json"));
+    pointer = readJson3(path30.join(storeRoot, "current.json"));
   } catch (error) {
     return {
       resolved: false,
@@ -9489,17 +9786,19 @@ function resolveCurrentPreviewArtifactMetadata(options) {
       ]
     };
   }
-  if (pointer.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION || !GENERATION_ID_PATTERN.test(pointer.generationId)) {
+  if (pointer.schemaVersion !== PREVIEW_ARTIFACT_SCHEMA_VERSION || !GENERATION_ID_PATTERN.test(pointer.generationId) || !WORKSPACE_BACKUP_ID_PATTERN2.test(pointer.workspaceBackupId) || pointer.workspaceVersion != null && !WORKSPACE_VERSION_PATTERN2.test(pointer.workspaceVersion)) {
     return {
       resolved: false,
-      reasons: ["current generation ID or schema version is invalid"]
+      reasons: [
+        "current generation ID, workspace identity, 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 = path29.join(
+  const generationDir = path30.join(
     storeRoot,
     "generations",
     pointer.generationId
@@ -9516,12 +9815,38 @@ function resolveCurrentPreviewArtifactMetadata(options) {
   if (!validation.manifest || validation.reasons.length > 0) {
     return { resolved: false, reasons: validation.reasons };
   }
-  if (validation.manifest.generationId !== pointer.generationId) {
+  if (validation.manifest.generationId !== pointer.generationId || validation.manifest.workspaceBackupId !== pointer.workspaceBackupId || validation.manifest.workspaceVersion !== pointer.workspaceVersion) {
     return {
       resolved: false,
       reasons: ["current pointer does not match generation manifest"]
     };
   }
+  if (requestedSourceTreeValidation.enabled) {
+    const generationSourceTreeValidation = previewArtifactSourceTreeValidation(
+      validation.manifest
+    );
+    const workspaceSourceTreeValidation = previewArtifactSourceTreeValidation(
+      options.workspaceManifest
+    );
+    if (!samePreviewArtifactSourceTreeValidation(
+      requestedSourceTreeValidation,
+      generationSourceTreeValidation
+    ) || !samePreviewArtifactSourceTreeValidation(
+      requestedSourceTreeValidation,
+      workspaceSourceTreeValidation
+    )) {
+      return {
+        resolved: false,
+        reasons: ["workspace source tree validation policy mismatch"]
+      };
+    }
+    if (options.workspaceManifest.workspaceVersion !== validation.manifest.workspaceVersion) {
+      return {
+        resolved: false,
+        reasons: ["workspace version mismatch"]
+      };
+    }
+  }
   if (validation.manifest.buildEnvironmentSha256 !== options.buildEnvironmentSha256) {
     return {
       resolved: false,
@@ -9536,33 +9861,33 @@ function resolveCurrentPreviewArtifactMetadata(options) {
   };
 }
 async function materializeVerifiedPreviewArtifactFile(options) {
-  const source = path29.resolve(options.source);
-  const destination = path29.resolve(options.destination);
+  const source = path30.resolve(options.source);
+  const destination = path30.resolve(options.destination);
   const temporary = `${destination}.${process.pid}.${Date.now()}.tmp`;
-  fs33.mkdirSync(path29.dirname(destination), { recursive: true });
-  if (fs33.existsSync(destination)) {
+  fs34.mkdirSync(path30.dirname(destination), { recursive: true });
+  if (fs34.existsSync(destination)) {
     throw new Error(
       `materialization destination already exists: ${destination}`
     );
   }
-  const noFollow = fs33.constants.O_NOFOLLOW ?? 0;
+  const noFollow = fs34.constants.O_NOFOLLOW ?? 0;
   let sourceHandle;
   let destinationHandle;
   try {
-    sourceHandle = await fs33.promises.open(
+    sourceHandle = await fs34.promises.open(
       source,
-      fs33.constants.O_RDONLY | noFollow
+      fs34.constants.O_RDONLY | noFollow
     );
     const sourceStat = await sourceHandle.stat();
     if (!sourceStat.isFile()) {
       throw new Error(`${options.identity.path} is not a regular file`);
     }
-    destinationHandle = await fs33.promises.open(
+    destinationHandle = await fs34.promises.open(
       temporary,
-      fs33.constants.O_WRONLY | fs33.constants.O_CREAT | fs33.constants.O_EXCL,
+      fs34.constants.O_WRONLY | fs34.constants.O_CREAT | fs34.constants.O_EXCL,
       384
     );
-    const hash = crypto2.createHash("sha256");
+    const hash = crypto3.createHash("sha256");
     const buffer = Buffer.allocUnsafe(256 * 1024);
     let totalBytes = 0;
     for (; ; ) {
@@ -9601,24 +9926,24 @@ async function materializeVerifiedPreviewArtifactFile(options) {
     await destinationHandle.sync();
     await destinationHandle.close();
     destinationHandle = void 0;
-    await fs33.promises.rename(temporary, destination);
+    await fs34.promises.rename(temporary, destination);
     return { bytes: totalBytes, sha256 };
   } finally {
     await destinationHandle?.close().catch(() => void 0);
     await sourceHandle?.close().catch(() => void 0);
-    await fs33.promises.rm(temporary, { force: true }).catch(() => void 0);
+    await fs34.promises.rm(temporary, { force: true }).catch(() => void 0);
   }
 }
 
 // src/commands/preview-artifact/producer.ts
 function defaultGenerationId() {
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:.TZ]/g, "");
-  return `${timestamp}-${crypto3.randomBytes(5).toString("hex")}`;
+  return `${timestamp}-${crypto4.randomBytes(5).toString("hex")}`;
 }
 function defaultPreviewBundleBuildCommands(projectRootInput) {
-  const projectRoot = path30.resolve(projectRootInput);
+  const projectRoot = path31.resolve(projectRootInput);
   const executableSuffix = process.platform === "win32" ? ".cmd" : "";
-  const localBinary = (name) => path30.join(
+  const localBinary = (name) => path31.join(
     projectRoot,
     "node_modules",
     ".bin",
@@ -9638,7 +9963,7 @@ function defaultPreviewBundleBuildCommands(projectRootInput) {
 }
 function runBuildCommands(projectRoot, buildCommands, environment) {
   for (const buildCommand of buildCommands) {
-    const result = spawnSync8(buildCommand.command, buildCommand.args, {
+    const result = spawnSync9(buildCommand.command, buildCommand.args, {
       cwd: projectRoot,
       env: { ...process.env, ...environment },
       encoding: "utf8",
@@ -9656,27 +9981,27 @@ ${diagnostic}` : ""}`
   return [];
 }
 function createClientArchive(clientDir, archivePath) {
-  if (!fs34.existsSync(path30.join(clientDir, "index.html"))) {
+  if (!fs35.existsSync(path31.join(clientDir, "index.html"))) {
     return [`client build output is missing: ${clientDir}`];
   }
-  const result = spawnSync8("zip", ["-qry", archivePath, "."], {
+  const result = spawnSync9("zip", ["-qry", archivePath, "."], {
     cwd: clientDir,
     encoding: "utf8"
   });
-  if (result.status === 0 && fs34.existsSync(archivePath)) return [];
+  if (result.status === 0 && fs35.existsSync(archivePath)) return [];
   return [`client archive failed with exit ${result.status ?? "unknown"}`];
 }
 function readActionPlugins2(metadataFile) {
-  const metadata = JSON.parse(fs34.readFileSync(metadataFile, "utf8"));
+  const metadata = JSON.parse(fs35.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 = path30.resolve(options.projectRoot);
-  const storeRoot = path30.resolve(options.storeRoot);
+  const projectRoot = path31.resolve(options.projectRoot);
+  const storeRoot = path31.resolve(options.storeRoot);
   const generationId = options.generationId ?? defaultGenerationId();
-  const stagingDir = path30.join(
+  const stagingDir = path31.join(
     storeRoot,
     ".staging",
     `${generationId}.${process.pid}.${Date.now()}`
@@ -9688,7 +10013,7 @@ async function producePreviewArtifactGeneration(options) {
     reasons,
     ...probe ? { probe } : {}
   });
-  fs34.mkdirSync(stagingDir, { recursive: true });
+  fs35.mkdirSync(stagingDir, { recursive: true });
   try {
     const buildEnvironment = previewArtifactBuildEnvironment(
       options.environment,
@@ -9701,8 +10026,8 @@ async function producePreviewArtifactGeneration(options) {
       buildEnvironment
     );
     if (buildReasons.length > 0) return failed(buildReasons);
-    const serverOutfile = path30.join(stagingDir, "server.bundle.cjs");
-    const serverMetadataFile = path30.join(stagingDir, "server-build.json");
+    const serverOutfile = path31.join(stagingDir, "server.bundle.cjs");
+    const serverMetadataFile = path31.join(stagingDir, "server-build.json");
     const serverResult = await buildPreviewServerArtifact({
       projectRoot,
       entry: "dist/main.js",
@@ -9711,12 +10036,12 @@ async function producePreviewArtifactGeneration(options) {
     });
     if (!serverResult.built) return failed(serverResult.reasons);
     const archiveReasons = createClientArchive(
-      path30.join(projectRoot, "dist", "client"),
-      path30.join(stagingDir, "client.zip")
+      path31.join(projectRoot, "dist", "client"),
+      path31.join(stagingDir, "client.zip")
     );
     if (archiveReasons.length > 0) return failed(archiveReasons);
     const actionPlugins = readActionPlugins2(serverMetadataFile);
-    fs34.rmSync(serverMetadataFile, { force: true });
+    fs35.rmSync(serverMetadataFile, { force: true });
     createPreviewArtifactManifest({
       generationDir: stagingDir,
       generationId,
@@ -9727,6 +10052,7 @@ async function producePreviewArtifactGeneration(options) {
         options.environment,
         options.appBasePath
       ),
+      workspaceManifest: options.workspaceManifest,
       actionPlugins
     });
     const probe = await runPreviewArtifactProbe({
@@ -9753,21 +10079,21 @@ async function producePreviewArtifactGeneration(options) {
   } catch (error) {
     return failed([error instanceof Error ? error.message : String(error)]);
   } finally {
-    fs34.rmSync(stagingDir, { recursive: true, force: true });
+    fs35.rmSync(stagingDir, { recursive: true, force: true });
   }
 }
 
 // src/commands/preview-artifact/runtime.ts
-import * as fs36 from "fs";
+import * as fs37 from "fs";
 import * as net3 from "net";
-import * as path32 from "path";
+import * as path33 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";
+import * as fs36 from "fs";
+import * as path32 from "path";
 function targetOrigin(target) {
   return `http://${target.host}:${target.port}`;
 }
@@ -9815,7 +10141,7 @@ function cachedAssetFile(request2, cachedAssetFiles) {
   return cachedAssetFiles.get(pathname);
 }
 function contentType(filePath) {
-  switch (path31.extname(filePath).toLowerCase()) {
+  switch (path32.extname(filePath).toLowerCase()) {
     case ".js":
     case ".mjs":
       return "text/javascript; charset=utf-8";
@@ -9852,7 +10178,7 @@ function contentType(filePath) {
 function serveCachedAsset(request2, response, filePath) {
   let stat;
   try {
-    stat = fs35.lstatSync(filePath);
+    stat = fs36.lstatSync(filePath);
   } catch {
     response.writeHead(404).end();
     return;
@@ -9870,7 +10196,7 @@ function serveCachedAsset(request2, response, filePath) {
     response.end();
     return;
   }
-  const stream = fs35.createReadStream(filePath);
+  const stream = fs36.createReadStream(filePath);
   stream.on("error", () => response.destroy());
   stream.pipe(response);
 }
@@ -9917,8 +10243,8 @@ function createPreviewArtifactSwitcher(options) {
   let closed = false;
   let pollTimer;
   let settleCutover;
-  const cutover = new Promise((resolve9) => {
-    settleCutover = resolve9;
+  const cutover = new Promise((resolve10) => {
+    settleCutover = resolve10;
   });
   const currentTarget = () => active === "cached" ? options.cachedTarget : options.freshTarget;
   const server = http.createServer((request2, response) => {
@@ -9972,7 +10298,7 @@ function createPreviewArtifactSwitcher(options) {
     },
     cutover,
     start() {
-      return new Promise((resolve9, reject) => {
+      return new Promise((resolve10, reject) => {
         server.once("error", reject);
         server.listen(options.listenPort, listenHost, () => {
           const address = server.address();
@@ -9981,7 +10307,7 @@ function createPreviewArtifactSwitcher(options) {
             return;
           }
           schedulePoll();
-          resolve9({
+          resolve10({
             host: listenHost,
             port: address.port,
             origin: `http://${listenHost}:${address.port}`
@@ -10000,8 +10326,8 @@ function createPreviewArtifactSwitcher(options) {
         });
         settleCutover = void 0;
       }
-      return new Promise((resolve9) => {
-        server.close(() => resolve9());
+      return new Promise((resolve10) => {
+        server.close(() => resolve10());
         server.closeAllConnections?.();
       });
     }
@@ -10026,10 +10352,10 @@ async function measureAsync(timings, phase, operation, detail) {
   }
 }
 function sleep2(ms) {
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 async function reservePort2() {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const server = net3.createServer();
     server.unref();
     server.once("error", reject);
@@ -10041,7 +10367,7 @@ async function reservePort2() {
       }
       server.close((error) => {
         if (error) reject(error);
-        else resolve9(address.port);
+        else resolve10(address.port);
       });
     });
   });
@@ -10059,12 +10385,12 @@ function stopProcessGroup2(child) {
   }
 }
 function isPathInside3(parent, candidate) {
-  const relative5 = path32.relative(parent, candidate);
-  return relative5 !== "" && relative5 !== ".." && !relative5.startsWith(`..${path32.sep}`) && !path32.isAbsolute(relative5);
+  const relative5 = path33.relative(parent, candidate);
+  return relative5 !== "" && relative5 !== ".." && !relative5.startsWith(`..${path33.sep}`) && !path33.isAbsolute(relative5);
 }
 function ensureRegularRuntimeRoot(runtimeRoot) {
-  fs36.mkdirSync(runtimeRoot, { recursive: true });
-  const stat = fs36.lstatSync(runtimeRoot);
+  fs37.mkdirSync(runtimeRoot, { recursive: true });
+  const stat = fs37.lstatSync(runtimeRoot);
   if (!stat.isDirectory() || stat.isSymbolicLink()) {
     throw new Error("runtime root must be a regular directory");
   }
@@ -10073,14 +10399,14 @@ 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);
+    for (const entry of fs37.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path33.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("/");
+      const relative5 = path33.relative(clientRoot, absolute).split(path33.sep).join("/");
       if (relative5 === "index.html") continue;
       files.set(
         new URL(`/${relative5}`, "http://preview.local").pathname,
@@ -10096,13 +10422,13 @@ function collectCachedAssetFiles(clientRoot, appBasePath) {
   return files;
 }
 function writeMarkerAtomic(markerFile, marker) {
-  fs36.mkdirSync(path32.dirname(markerFile), { recursive: true });
+  fs37.mkdirSync(path33.dirname(markerFile), { recursive: true });
   const temporaryFile = `${markerFile}.${process.pid}.${Date.now()}.tmp`;
-  fs36.writeFileSync(temporaryFile, `${JSON.stringify(marker, null, 2)}
+  fs37.writeFileSync(temporaryFile, `${JSON.stringify(marker, null, 2)}
 `, {
     mode: 384
   });
-  fs36.renameSync(temporaryFile, markerFile);
+  fs37.renameSync(temporaryFile, markerFile);
 }
 async function waitForCachedRuntime(origin, appBasePath, businessApiPath, timeoutMs, child) {
   const timeoutAt = Date.now() + timeoutMs;
@@ -10145,12 +10471,14 @@ async function startPreviewArtifactRuntime(options) {
       buildEnvironmentSha256: previewArtifactBuildEnvironmentHash(
         options.environment,
         options.appBasePath
-      )
+      ),
+      sourceTreeValidation: options.sourceTreeValidation,
+      workspaceManifest: options.workspaceManifest
     })
   );
   if (!resolved.resolved) return { started: false, reasons: resolved.reasons };
-  const runtimeRoot = path32.resolve(options.runtimeRoot);
-  const markerFile = path32.resolve(options.markerFile);
+  const runtimeRoot = path33.resolve(options.runtimeRoot);
+  const markerFile = path33.resolve(options.markerFile);
   let runtimeDir;
   let cachedRuntime;
   let switcher;
@@ -10160,58 +10488,22 @@ async function startPreviewArtifactRuntime(options) {
     closed = true;
     stopProcessGroup2(cachedRuntime);
     await switcher?.close();
-    fs36.rmSync(markerFile, { force: true });
-    if (runtimeDir) fs36.rmSync(runtimeDir, { recursive: true, force: true });
+    fs37.rmSync(markerFile, { force: true });
+    if (runtimeDir) fs37.rmSync(runtimeDir, { recursive: true, force: true });
   };
   try {
     ensureRegularRuntimeRoot(runtimeRoot);
     if (!isPathInside3(runtimeRoot, markerFile)) {
       throw new Error("runtime marker must be inside the runtime root");
     }
-    runtimeDir = fs36.mkdtempSync(
-      path32.join(runtimeRoot, `${resolved.generationId}-`)
+    runtimeDir = fs37.mkdtempSync(
+      path33.join(runtimeRoot, `${resolved.generationId}-`)
     );
-    const runtimeBundle = path32.join(runtimeDir, "server.bundle.cjs");
-    const serverSource = path32.join(resolved.generationDir, "server.bundle.cjs");
-    const clientArchive = path32.join(runtimeDir, "client.zip");
-    const clientSource = path32.join(resolved.generationDir, "client.zip");
-    const clientRoot = path32.join(runtimeDir, "dist", "client");
-    const backendReady = (async () => {
-      await measureAsync(
-        timings,
-        "server_materialize",
-        () => materializeVerifiedPreviewArtifactFile({
-          source: serverSource,
-          destination: runtimeBundle,
-          identity: resolved.manifest.files.server
-        }),
-        { bytes: resolved.manifest.files.server.bytes }
-      );
-      const cachedServerPort2 = options.cachedServerPort === 0 ? await reservePort2() : options.cachedServerPort;
-      cachedRuntime = spawn3(process.execPath, [runtimeBundle], {
-        cwd: runtimeDir,
-        detached: true,
-        stdio: "ignore",
-        env: {
-          ...process.env,
-          ...previewArtifactRuntimeEnvironment(options.environment),
-          SERVER_PORT: String(cachedServerPort2)
-        }
-      });
-      const cachedOrigin = `http://127.0.0.1:${cachedServerPort2}`;
-      await measureAsync(
-        timings,
-        "backend_spawn_to_business_ready",
-        () => waitForCachedRuntime(
-          cachedOrigin,
-          options.appBasePath,
-          options.businessApiPath,
-          options.startupTimeoutMs ?? 3e4,
-          cachedRuntime
-        )
-      );
-      return cachedServerPort2;
-    })();
+    const runtimeBundle = path33.join(runtimeDir, "server.bundle.cjs");
+    const serverSource = path33.join(resolved.generationDir, "server.bundle.cjs");
+    const clientArchive = path33.join(runtimeDir, "client.zip");
+    const clientSource = path33.join(resolved.generationDir, "client.zip");
+    const clientRoot = path33.join(runtimeDir, "dist", "client");
     const assetsReady = (async () => {
       await measureAsync(
         timings,
@@ -10241,9 +10533,48 @@ async function startPreviewArtifactRuntime(options) {
       timings[timings.length - 1].fileCount = new Set(
         cachedAssetFiles2.values()
       ).size;
-      fs36.rmSync(clientArchive, { force: true });
+      fs37.rmSync(clientArchive, { force: true });
       return cachedAssetFiles2;
     })();
+    const backendReady = (async () => {
+      await measureAsync(
+        timings,
+        "server_materialize",
+        () => materializeVerifiedPreviewArtifactFile({
+          source: serverSource,
+          destination: runtimeBundle,
+          identity: resolved.manifest.files.server
+        }),
+        { bytes: resolved.manifest.files.server.bytes }
+      );
+      const cachedServerPort2 = options.cachedServerPort === 0 ? await reservePort2() : options.cachedServerPort;
+      cachedRuntime = spawn3(process.execPath, [runtimeBundle], {
+        cwd: runtimeDir,
+        detached: true,
+        stdio: "ignore",
+        env: {
+          ...process.env,
+          ...previewArtifactRuntimeEnvironment(options.environment),
+          SERVER_PORT: String(cachedServerPort2)
+        }
+      });
+      const cachedOrigin = `http://127.0.0.1:${cachedServerPort2}`;
+      await measureAsync(
+        timings,
+        "backend_spawn_to_business_ready",
+        async () => {
+          await assetsReady;
+          await waitForCachedRuntime(
+            cachedOrigin,
+            options.appBasePath,
+            options.businessApiPath,
+            options.startupTimeoutMs ?? 3e4,
+            cachedRuntime
+          );
+        }
+      );
+      return cachedServerPort2;
+    })();
     const [backendResult, assetsResult] = await Promise.allSettled([
       backendReady,
       assetsReady
@@ -10371,6 +10702,35 @@ var previewServerArtifactCommand = {
     );
   }
 };
+var previewArtifactWorkspaceManifestCommand = {
+  name: "preview-artifact-workspace-manifest",
+  description: "Snapshot the Git-visible Workspace content identity for backup and cache validation",
+  register(program) {
+    program.command(this.name).description(this.description).option("--project-root <dir>", "Application project root", process.cwd()).requiredOption(
+      "--manifest-file <file>",
+      "Workspace Manifest sidecar output file"
+    ).requiredOption(
+      "--workspace-backup-id <id>",
+      "Physical Workspace backup identity"
+    ).requiredOption("--app-id <id>", "Application ID").option(
+      "--validate-source-tree",
+      "Calculate a sourceTreeId and bind cache consumption to it"
+    ).option(
+      "--source-tree-include <path>",
+      "Repository-relative file or directory included in sourceTreeId; repeatable",
+      (value, previous) => [...previous, value],
+      []
+    ).action(
+      (options) => {
+        const manifest = createPreviewArtifactWorkspaceManifest({
+          ...options,
+          sourceTreeIncludePaths: options.sourceTreeInclude
+        });
+        console.log(JSON.stringify(manifest));
+      }
+    );
+  }
+};
 var previewArtifactGenerationCommand = {
   name: "preview-artifact-generation",
   description: "Build, probe, promote, and atomically publish a Preview Artifact generation",
@@ -10381,12 +10741,18 @@ var previewArtifactGenerationCommand = {
     ).requiredOption(
       "--environment-file <file>",
       "JSON application environment passed only to build/probe children"
+    ).requiredOption(
+      "--workspace-manifest-file <file>",
+      "Workspace Manifest sidecar created at backup start"
     ).action(
       async (options) => {
         const result = await producePreviewArtifactGeneration({
           ...options,
           environment: readPreviewArtifactEnvironmentFile(
             options.environmentFile
+          ),
+          workspaceManifest: readPreviewArtifactWorkspaceManifest(
+            options.workspaceManifestFile
           )
         });
         console.log(JSON.stringify(result));
@@ -10443,6 +10809,17 @@ var previewArtifactRuntimeCommand = {
     ).requiredOption(
       "--environment-file <file>",
       "JSON application environment passed only to cached application child"
+    ).requiredOption(
+      "--workspace-manifest-file <file>",
+      "Workspace Manifest sidecar restored with this backup"
+    ).option(
+      "--validate-source-tree",
+      "Reject cache when its sourceTreeId does not match the Workspace backup"
+    ).option(
+      "--source-tree-include <path>",
+      "Repository-relative sourceTreeId scope; repeatable",
+      (value, previous) => [...previous, value],
+      []
     ).action(
       async (options) => {
         const environmentLoadStartedAt = Date.now();
@@ -10450,9 +10827,18 @@ var previewArtifactRuntimeCommand = {
           options.environmentFile
         );
         const environmentLoadDurationMs = Date.now() - environmentLoadStartedAt;
+        const workspaceManifest = readPreviewArtifactWorkspaceManifest(
+          options.workspaceManifestFile
+        );
+        const sourceTreeValidation = createPreviewArtifactSourceTreeValidation(
+          options.validateSourceTree,
+          options.sourceTreeInclude
+        );
         const runtime = await startPreviewArtifactRuntime({
           ...options,
           environment,
+          workspaceManifest,
+          sourceTreeValidation,
           initialTimings: [
             {
               phase: "cli_bootstrap",
@@ -10498,6 +10884,7 @@ var buildCommandGroup = {
     uploadStaticCommand,
     preUploadStaticCommand,
     previewServerArtifactCommand,
+    previewArtifactWorkspaceManifestCommand,
     previewArtifactGenerationCommand,
     previewArtifactRuntimeCommand
   ]
@@ -10517,12 +10904,12 @@ var commands = [
 ];
 
 // src/index.ts
-var envPath = path33.join(process.cwd(), ".env");
-if (fs37.existsSync(envPath)) {
+var envPath = path34.join(process.cwd(), ".env");
+if (fs38.existsSync(envPath)) {
   dotenvConfig({ path: envPath });
 }
-var __dirname = path33.dirname(fileURLToPath5(import.meta.url));
-var pkg = JSON.parse(fs37.readFileSync(path33.join(__dirname, "../package.json"), "utf-8"));
+var __dirname = path34.dirname(fileURLToPath5(import.meta.url));
+var pkg = JSON.parse(fs38.readFileSync(path34.join(__dirname, "../package.json"), "utf-8"));
 var cli = new FullstackCLI(pkg.version);
 cli.useAll(commands);
 cli.run();