virrun 2.31.1 → 2.32.0

package/dist/{createVirrun-C8zMQHAQ.js → createVirrun-CirfmuYa.js}

@@ -1,8 +1,9 @@
 import { createRequire } from "node:module";
-import { constants, tmpdir } from "node:os";
 import { execFileSync, spawn } from "node:child_process";
-import { mkdtempSync } from "node:fs";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { constants, homedir, tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { createHash } from "node:crypto";
 import process$1 from "node:process";
 import { runInThisContext } from "node:vm";
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
@@ -16,14 +17,6 @@ const parseCliCommand = (argv) => {
 	return separatorIndex === -1 ? [...argv] : argv.slice(separatorIndex + 1);
 };
 //#endregion
-//#region src/models/source/SourceType.ts
-let SourceType = /* @__PURE__ */ function(SourceType) {
-	SourceType["Dir"] = "dir";
-	SourceType["Files"] = "files";
-	SourceType["Git"] = "git";
-	return SourceType;
-}({});
-//#endregion
 //#region src/models/virrun/BackendType.ts
 let BackendType = /* @__PURE__ */ function(BackendType) {
 	BackendType["Auto"] = "auto";
@@ -33,73 +26,6 @@ let BackendType = /* @__PURE__ */ function(BackendType) {
 	return BackendType;
 }({});
 //#endregion
-//#region src/services/exec/toExitCode.ts
-const toExitCode = (code, signal) => code ?? (signal ? 128 + constants.signals[signal] : 0);
-//#endregion
-//#region src/services/exec/createNativeBackend.ts
-const createNativeBackend = () => ({
-	exec: (command, options) => new Promise((resolve, reject) => {
-		const [file, ...args] = Array.isArray(command) ? command : [command];
-		const child = spawn(file, args, {
-			cwd: options.cwd === "" ? void 0 : options.cwd,
-			shell: !Array.isArray(command),
-			stdio: options.stdio
-		});
-		let stdout = "";
-		let stderr = "";
-		child.stdout?.on("data", (chunk) => {
-			stdout += chunk.toString();
-		});
-		child.stderr?.on("data", (chunk) => {
-			stderr += chunk.toString();
-		});
-		child.on("error", reject);
-		child.on("close", (code, signal) => {
-			resolve({
-				exitCode: toExitCode(code, signal),
-				stderr,
-				stdout
-			});
-		});
-	}),
-	name: "native"
-});
-//#endregion
-//#region src/services/exec/buildBwrapArgs.ts
-const buildBwrapArgs = (command, cwd, { network = false, overlayDirs = [] } = {}) => {
-	const dir = cwd === "" ? process.cwd() : cwd;
-	const commandArgs = Array.isArray(command) ? [...command] : [
-		"/bin/sh",
-		"-c",
-		command
-	];
-	const overlays = [dir, ...overlayDirs].flatMap((overlayDir) => [
-		"--overlay-src",
-		overlayDir,
-		"--tmp-overlay",
-		overlayDir
-	]);
-	return [
-		"--unshare-all",
-		...network ? ["--share-net"] : [],
-		"--die-with-parent",
-		"--ro-bind",
-		"/",
-		"/",
-		"--dev",
-		"/dev",
-		"--proc",
-		"/proc",
-		"--tmpfs",
-		"/tmp",
-		...overlays,
-		"--chdir",
-		dir,
-		"--",
-		...commandArgs
-	];
-};
-//#endregion
 //#region ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/core/core.js
 var _a$1;
 function $constructor(name, initializer, params) {
@@ -18686,20 +18612,241 @@ const exhaustiveGuard = (value) => {
 	throw new InvalidOperationError("Read", exhaustiveGuard.name, JSON.stringify(value));
 };
 //#endregion
-//#region src/services/exec/isOsBackendSupported.ts
+//#region src/services/exec/bwrap/buildBwrapArgs.ts
+const buildBwrapArgs = (command, cwd, { bindDirs = [], isNetworkEnabled = false } = {}, { lowerDirs = [], upperDir, workDir } = {}) => {
+	if (upperDir === void 0 !== (workDir === void 0)) throw new InvalidOperationError(Operation.Create, buildBwrapArgs.name, "a persistent overlay needs both upperDir and workDir");
+	const dir = cwd === "" ? process.cwd() : cwd;
+	const commandArgs = Array.isArray(command) ? [...command] : [
+		"/bin/sh",
+		"-c",
+		command
+	];
+	const topOverlay = upperDir !== void 0 && workDir !== void 0 ? [
+		"--overlay",
+		upperDir,
+		workDir,
+		dir
+	] : ["--tmp-overlay", dir];
+	return [
+		"--unshare-all",
+		...isNetworkEnabled ? ["--share-net"] : [],
+		"--die-with-parent",
+		"--ro-bind",
+		"/",
+		"/",
+		"--dev",
+		"/dev",
+		"--proc",
+		"/proc",
+		"--tmpfs",
+		"/tmp",
+		"--overlay-src",
+		dir,
+		...lowerDirs.flatMap((lowerDir) => ["--overlay-src", lowerDir]),
+		...topOverlay,
+		...bindDirs.flatMap((bindDir) => [
+			"--bind",
+			bindDir,
+			bindDir
+		]),
+		"--chdir",
+		dir,
+		"--",
+		...commandArgs
+	];
+};
+//#endregion
+//#region src/services/exec/util/constants.ts
+const GITIGNORE_FILENAME = ".gitignore";
+const VIRRUN_CACHE_DIRECTORY_NAME = ".virrun";
+const VIRRUN_GITIGNORE_ENTRY = `/${VIRRUN_CACHE_DIRECTORY_NAME}/`;
+const VIRRUN_STORE_DIRECTORY_NAME = "store";
+const VIRRUN_PNPM_STORE_DIRECTORY_NAME = "pnpm";
+const VIRRUN_COREPACK_STORE_DIRECTORY_NAME = "corepack";
+const VIRRUN_SNAPSHOTS_DIRECTORY_NAME = "snapshots";
+const VIRRUN_SNAPSHOT_UPPER_DIRECTORY_NAME = "upper";
+const VIRRUN_SNAPSHOT_WORK_DIRECTORY_NAME = "work";
+const PNPM_LOCKFILE_FILENAME = "pnpm-lock.yaml";
+const VIRRUN_CONFIGURATION_FILENAME = "virrun.config.json";
+const VIRRUN_ENV_KEY = "VIRRUN";
+const COREPACK_HOME_KEY = "COREPACK_HOME";
+const VIRRUN_CACHE_HOME_KEY = "VIRRUN_CACHE_HOME";
+const PNPM_CONFIG_PACKAGE_IMPORT_METHOD_KEY = "PNPM_CONFIG_PACKAGE_IMPORT_METHOD";
+const PNPM_CONFIG_PACKAGE_IMPORT_METHOD_VALUE = "copy";
+const PNPM_CONFIG_STORE_DIR_KEY = "PNPM_CONFIG_STORE_DIR";
+const VIRRUN_TEMP_DIR_PREFIX = "virrun-temp-";
+//#endregion
+//#region src/services/exec/os/isOsBackendSupported.ts
 let isSupported;
 const isOsBackendSupported = () => {
 	if (isSupported !== void 0) return isSupported;
-	if (process.platform !== "linux") {
-		isSupported = false;
-		return isSupported;
-	}
-	const dir = mkdtempSync(join(tmpdir(), "os-support-"));
-	isSupported = getResult(() => execFileSync("bwrap", buildBwrapArgs("true", dir), { stdio: "pipe" })).match(() => true, () => false);
+	else if (process.platform === "linux") {
+		const dir = mkdtempSync(join(tmpdir(), VIRRUN_TEMP_DIR_PREFIX));
+		isSupported = getResult(() => withFinalizer(() => execFileSync("bwrap", buildBwrapArgs("true", dir), { stdio: "pipe" }), () => {
+			rmSync(dir, {
+				force: true,
+				recursive: true
+			});
+		})).match(() => true, () => false);
+	} else if (process.platform === "win32") isSupported = getResult(() => execFileSync("wsl.exe", [
+		"--exec",
+		"mktemp",
+		"-d"
+	], { stdio: "pipe" })).map((stdout) => stdout.toString().trim()).andThen((wslDir) => getResult(() => withFinalizer(() => execFileSync("wsl.exe", [
+		"--exec",
+		"bwrap",
+		...buildBwrapArgs("true", wslDir)
+	], { stdio: "pipe" }), () => {
+		getResult(() => execFileSync("wsl.exe", [
+			"--exec",
+			"rm",
+			"-rf",
+			wslDir
+		], { stdio: "pipe" })).unwrapOr(void 0);
+	}))).match(() => true, () => false);
+	else isSupported = false;
 	return isSupported;
 };
 //#endregion
-//#region src/services/exec/parseBwrapExitCode.ts
+//#region src/services/configuration/resolveBackend.ts
+const resolveBackend = (configuration) => {
+	if (configuration === void 0) return "auto";
+	if (configuration.backend === "os" && !isOsBackendSupported()) return configuration.fallback;
+	return configuration.backend;
+};
+//#endregion
+//#region src/services/configuration/parseVirrunConfiguration.ts
+const isBackendType = (value) => typeof value === "string" && Object.values(BackendType).includes(value);
+const toBackendType = (value, field) => {
+	if (isBackendType(value)) return value;
+	throw new InvalidOperationError(Operation.Read, parseVirrunConfiguration.name, `\`${field}\` must be one of: ${Object.values(BackendType).join(", ")}`);
+};
+const parseVirrunConfiguration = (content) => {
+	const result = getResult(() => JSON.parse(content));
+	if (result.isErr()) throw new InvalidOperationError(Operation.Read, parseVirrunConfiguration.name, `not valid JSON: ${result.error.message}`);
+	const value = result.value;
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new InvalidOperationError(Operation.Read, parseVirrunConfiguration.name, "must be a JSON object");
+	const allowedKeys = [
+		"$schema",
+		"backend",
+		"fallback"
+	];
+	const unknownKeys = Object.keys(value).filter((key) => !allowedKeys.includes(key));
+	if (unknownKeys.length > 0) throw new InvalidOperationError(Operation.Read, parseVirrunConfiguration.name, `unknown ${unknownKeys.length === 1 ? "key" : "keys"}: ${unknownKeys.join(", ")} (allowed: ${allowedKeys.join(", ")})`);
+	const { backend = "auto", fallback = "native" } = value;
+	return {
+		backend: toBackendType(backend, "backend"),
+		fallback: toBackendType(fallback, "fallback")
+	};
+};
+//#endregion
+//#region src/services/exec/util/resolveCwd.ts
+const resolveCwd = (cwd) => cwd === "" ? process.cwd() : cwd;
+//#endregion
+//#region ../../node_modules/.pnpm/empathic@2.0.1/node_modules/empathic/resolve.mjs
+/**
+* Resolve an absolute path from {@link root}, but only
+* if {@link input} isn't already absolute.
+*
+* @param input The path to resolve.
+* @param root The base path; default = process.cwd()
+* @returns The resolved absolute path.
+*/
+function absolute(input, root) {
+	return isAbsolute(input) ? input : resolve(root || ".", input);
+}
+//#endregion
+//#region ../../node_modules/.pnpm/empathic@2.0.1/node_modules/empathic/walk.mjs
+/**
+* Get all parent directories of {@link base}.
+* Stops after {@link Options['last']} is processed.
+*
+* @returns An array of absolute paths of all parent directories.
+*/
+function up(base, options) {
+	let { last, cwd } = options || {};
+	let tmp = absolute(base, cwd);
+	let root = absolute(last || "/", cwd);
+	let prev, arr = [];
+	while (prev !== root) {
+		arr.push(tmp);
+		tmp = dirname(prev = tmp);
+		if (tmp === prev) break;
+	}
+	return arr;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/empathic@2.0.1/node_modules/empathic/find.mjs
+/**
+* Find a file by name, walking parent directories until found.
+*
+* > [NOTE]
+* > This function only returns a value for file matches.
+* > A directory match with the same name will be ignored.
+*
+* @param name The file name to find.
+* @returns The absolute path to the file, if found.
+*/
+function file(name, options) {
+	let dir, tmp;
+	for (dir of up(options && options.cwd || "", options)) try {
+		tmp = join(dir, name);
+		if (statSync(tmp).isFile()) return tmp;
+	} catch {}
+}
+//#endregion
+//#region src/services/configuration/resolveVirrunConfiguration.ts
+const resolveVirrunConfiguration = (cwd) => {
+	const configurationFile = file(VIRRUN_CONFIGURATION_FILENAME, { cwd: resolveCwd(cwd) });
+	if (configurationFile === void 0) return void 0;
+	return parseVirrunConfiguration(readFileSync(configurationFile, "utf8"));
+};
+//#endregion
+//#region src/models/source/SourceType.ts
+let SourceType = /* @__PURE__ */ function(SourceType) {
+	SourceType["Dir"] = "dir";
+	SourceType["Files"] = "files";
+	SourceType["Git"] = "git";
+	return SourceType;
+}({});
+//#endregion
+//#region src/services/exec/util/toExitCode.ts
+const toExitCode = (code, signal) => code ?? (signal ? 128 + constants.signals[signal] : 0);
+//#endregion
+//#region src/services/exec/native/createNativeBackend.ts
+const createNativeBackend = () => ({
+	exec: (command, options) => new Promise((resolve, reject) => {
+		const [file, ...args] = Array.isArray(command) ? command : [command];
+		const child = spawn(file, args, {
+			cwd: options.cwd === "" ? void 0 : options.cwd,
+			env: {
+				...process.env,
+				...options.env
+			},
+			shell: !Array.isArray(command),
+			stdio: options.stdio
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", reject);
+		child.on("close", (code, signal) => {
+			resolve({
+				exitCode: toExitCode(code, signal),
+				stderr,
+				stdout
+			});
+		});
+	}),
+	name: "native"
+});
+//#endregion
+//#region src/services/exec/bwrap/parseBwrapExitCode.ts
 const parseBwrapExitCode = (status) => {
 	for (const line of status.split("\n")) {
 		const result = getResult(() => JSON.parse(line));
@@ -18707,53 +18854,258 @@ const parseBwrapExitCode = (status) => {
 	}
 };
 //#endregion
-//#region src/services/exec/createOsBackend.ts
-const createOsBackend = () => {
-	if (!isOsBackendSupported()) throw new InvalidOperationError(Operation.Create, createOsBackend.name, "requires Linux + bubblewrap");
+//#region src/services/exec/bwrap/constants.ts
+const WSL_BWRAP_STATUS_BEGIN = "\n__VIRRUN_BWRAP_STATUS_BEGIN__\n";
+const WSL_BWRAP_STATUS_END = "\n__VIRRUN_BWRAP_STATUS_END__\n";
+//#endregion
+//#region src/services/exec/bwrap/parseBwrapStderrStatus.ts
+const parseBwrapStderrStatus = (stderr) => {
+	const beginIndex = stderr.lastIndexOf(WSL_BWRAP_STATUS_BEGIN);
+	const endIndex = stderr.lastIndexOf(WSL_BWRAP_STATUS_END);
+	if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) return {
+		status: "",
+		stderr
+	};
+	const statusStartIndex = beginIndex + 31;
 	return {
-		exec: (command, options) => new Promise((resolve, reject) => {
-			const stdio = [
-				options.stdio,
-				options.stdio,
-				options.stdio,
-				"pipe"
-			];
-			const child = spawn("bwrap", [
-				"--json-status-fd",
-				"3",
-				...buildBwrapArgs(command, options.cwd, options)
-			], {
-				shell: false,
-				stdio
-			});
-			let stdout = "";
-			let stderr = "";
-			let status = "";
-			child.stdout?.on("data", (chunk) => {
-				stdout += chunk.toString();
-			});
-			child.stderr?.on("data", (chunk) => {
-				stderr += chunk.toString();
-			});
-			child.stdio[3]?.on("data", (chunk) => {
-				status += chunk.toString();
-			});
-			child.on("error", reject);
-			child.on("close", () => {
-				const exitCode = parseBwrapExitCode(status);
-				if (exitCode === void 0) reject(new InvalidOperationError(Operation.Create, createOsBackend.name, "bubblewrap failed to set up the sandbox"));
-				else resolve({
-					exitCode,
-					stderr,
-					stdout
-				});
+		status: stderr.slice(statusStartIndex, endIndex),
+		stderr: `${stderr.slice(0, beginIndex)}${stderr.slice(endIndex + 29)}`
+	};
+};
+//#endregion
+//#region src/services/exec/bwrap/createBwrapBackend.ts
+const createBwrapBackend = (createBwrapArgs, createBwrapCommand, errorName) => ({
+	exec: (command, options) => new Promise((resolve, reject) => {
+		const bwrapCommand = createBwrapCommand(createBwrapArgs(command, options.cwd, options), options);
+		const [file, ...args] = bwrapCommand.command;
+		const stdio = bwrapCommand.statusSource === "fd" ? [
+			options.stdio,
+			options.stdio,
+			options.stdio,
+			"pipe"
+		] : [
+			options.stdio,
+			options.stdio,
+			"pipe"
+		];
+		const child = spawn(file, args, {
+			env: {
+				...process.env,
+				...options.env
+			},
+			shell: false,
+			stdio
+		});
+		let stdout = "";
+		let stderr = "";
+		let status = "";
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.stdio[3]?.on("data", (chunk) => {
+			status += chunk.toString();
+		});
+		child.on("error", reject);
+		child.on("close", () => {
+			const bwrapStderr = bwrapCommand.statusSource === "stderr" ? parseBwrapStderrStatus(stderr) : {
+				status,
+				stderr
+			};
+			const exitCode = parseBwrapExitCode(bwrapStderr.status);
+			if (exitCode === void 0) reject(new InvalidOperationError(Operation.Create, errorName, "bubblewrap failed to set up the sandbox"));
+			else resolve({
+				exitCode,
+				stderr: bwrapStderr.stderr,
+				stdout
 			});
-		}),
-		name: "os"
+		});
+	}),
+	name: "os"
+});
+//#endregion
+//#region src/services/exec/bwrap/createLinuxOsBackend.ts
+const createLinuxOsBackend = (errorName) => createBwrapBackend((command, cwd, options) => buildBwrapArgs(command, cwd, options, options.overlayLayers), (bwrapArgs) => ({
+	command: [
+		"bwrap",
+		"--json-status-fd",
+		"3",
+		...bwrapArgs
+	],
+	statusSource: "fd"
+}), errorName);
+//#endregion
+//#region src/services/exec/wsl/readWslPath.ts
+const wslPaths = /* @__PURE__ */ new Map();
+const readWslPath = (path) => {
+	const wslPath = wslPaths.get(path);
+	if (wslPath) return wslPath;
+	const newWslPath = execFileSync("wsl.exe", [
+		"--exec",
+		"wslpath",
+		"-a",
+		path
+	], {
+		encoding: "utf8",
+		stdio: "pipe"
+	}).trim();
+	wslPaths.set(path, newWslPath);
+	return newWslPath;
+};
+//#endregion
+//#region src/services/exec/wsl/createWslBwrapArgs.ts
+const readWslOverlayLayers = ({ lowerDirs, upperDir, workDir }) => ({
+	lowerDirs: lowerDirs?.map((lowerDir) => readWslPath(lowerDir)),
+	upperDir: upperDir === void 0 ? void 0 : readWslPath(upperDir),
+	workDir: workDir === void 0 ? void 0 : readWslPath(workDir)
+});
+const createWslBwrapArgs = (command, cwd, { bindDirs = [], isNetworkEnabled = false, overlayLayers } = {}) => {
+	return buildBwrapArgs(command, readWslPath(resolveCwd(cwd)), {
+		bindDirs: bindDirs.map((bindDir) => readWslPath(bindDir)),
+		isNetworkEnabled
+	}, overlayLayers === void 0 ? void 0 : readWslOverlayLayers(overlayLayers));
+};
+//#endregion
+//#region src/services/exec/wsl/createWslEnvArgs.ts
+const WSL_PATH_ENV_KEYS = /* @__PURE__ */ new Set([COREPACK_HOME_KEY, PNPM_CONFIG_STORE_DIR_KEY]);
+const createWslEnvArgs = ({ env = {} }) => Object.entries(env).map(([key, value]) => `${key}=${WSL_PATH_ENV_KEYS.has(key) ? readWslPath(value) : value}`);
+//#endregion
+//#region src/services/exec/wsl/createWslOsBackend.ts
+const createWslOsBackend = (errorName) => createBwrapBackend(createWslBwrapArgs, (bwrapArgs, options) => ({
+	command: [
+		"wsl.exe",
+		"--exec",
+		"env",
+		...createWslEnvArgs(options),
+		"sh",
+		"-c",
+		[
+			`status="$(mktemp)"`,
+			`bwrap --json-status-fd 3 "$@" 3>"$status"`,
+			`bwrapExitCode=$?`,
+			`printf '${WSL_BWRAP_STATUS_BEGIN.replaceAll("\n", String.raw`\n`)}' >&2`,
+			`cat "$status" >&2`,
+			`printf '${WSL_BWRAP_STATUS_END.replaceAll("\n", String.raw`\n`)}' >&2`,
+			`rm -f "$status"`,
+			`exit "$bwrapExitCode"`
+		].join("; "),
+		"virrun-bwrap",
+		...bwrapArgs
+	],
+	statusSource: "stderr"
+}), errorName);
+//#endregion
+//#region src/services/exec/os/createOsBackend.ts
+const createOsBackend = () => {
+	if (!isOsBackendSupported()) throw new InvalidOperationError(Operation.Create, createOsBackend.name, "requires Linux/WSL + bubblewrap");
+	if (process.platform === "linux") return createLinuxOsBackend(createOsBackend.name);
+	else if (process.platform === "win32") return createWslOsBackend(createOsBackend.name);
+	throw new InvalidOperationError(Operation.Create, createOsBackend.name, "requires Linux/WSL + bubblewrap");
+};
+//#endregion
+//#region src/services/exec/snapshot/removeSnapshotLocation.ts
+const makeTraversable = (dir) => {
+	chmodSync(dir, 448);
+	for (const entry of readdirSync(dir, { withFileTypes: true })) if (entry.isDirectory()) makeTraversable(join(dir, entry.name));
+};
+const removeSnapshotLocation = ({ dir }) => {
+	if (existsSync(dir)) makeTraversable(dir);
+	rmSync(dir, {
+		force: true,
+		recursive: true
+	});
+};
+//#endregion
+//#region src/services/exec/snapshot/computeLockfileHash.ts
+const computeLockfileHash = (cwd) => {
+	const dir = resolveCwd(cwd);
+	const lockfile = join(dir, PNPM_LOCKFILE_FILENAME);
+	if (!existsSync(lockfile)) throw new InvalidOperationError(Operation.Read, computeLockfileHash.name, `no ${PNPM_LOCKFILE_FILENAME} in ${dir}`);
+	return createHash("sha256").update(readFileSync(lockfile)).digest("hex");
+};
+//#endregion
+//#region src/services/exec/util/getGlobalCacheDirectory.ts
+const getGlobalCacheDirectory = () => process.env["VIRRUN_CACHE_HOME"] || join(homedir(), ".virrun");
+//#endregion
+//#region src/services/exec/snapshot/resolveSnapshotLocation.ts
+const resolveSnapshotLocation = (cwd) => {
+	const hash = computeLockfileHash(cwd);
+	const snapshotDir = join(getGlobalCacheDirectory(), VIRRUN_SNAPSHOTS_DIRECTORY_NAME, hash);
+	const upperDir = join(snapshotDir, VIRRUN_SNAPSHOT_UPPER_DIRECTORY_NAME);
+	return {
+		dir: snapshotDir,
+		exists: existsSync(upperDir),
+		hash,
+		upperDir,
+		workDir: join(snapshotDir, VIRRUN_SNAPSHOT_WORK_DIRECTORY_NAME)
+	};
+};
+//#endregion
+//#region src/services/exec/snapshot/createSnapshot.ts
+const createSnapshot = (backend, command, options) => {
+	const location = resolveSnapshotLocation(options.cwd);
+	const { upperDir, workDir } = location;
+	return getResultAsync(async () => {
+		mkdirSync(upperDir, { recursive: true });
+		mkdirSync(workDir, { recursive: true });
+		const result = await backend.exec(command, {
+			...options,
+			overlayLayers: {
+				upperDir,
+				workDir
+			}
+		});
+		if (result.exitCode !== 0) throw new InvalidOperationError(Operation.Create, createSnapshot.name, `snapshot setup command exited with ${result.exitCode}: ${result.stderr}`);
+		return {
+			location: {
+				...location,
+				exists: true
+			},
+			result
+		};
+	}).match((value) => value, (error) => {
+		removeSnapshotLocation(location);
+		throw error;
+	});
+};
+//#endregion
+//#region src/services/exec/snapshot/forkSnapshot.ts
+const forkSnapshot = (backend, command, options) => {
+	const { exists, upperDir } = resolveSnapshotLocation(options.cwd);
+	if (!exists) throw new InvalidOperationError(Operation.Read, forkSnapshot.name, "no captured snapshot to fork; run createSnapshot first");
+	return backend.exec(command, {
+		...options,
+		overlayLayers: { lowerDirs: [upperDir] }
+	});
+};
+//#endregion
+//#region src/services/exec/util/getRepoCacheDirectory.ts
+const getRepoCacheDirectory = (cwd) => join(resolveCwd(cwd), VIRRUN_CACHE_DIRECTORY_NAME);
+//#endregion
+//#region src/services/exec/store/createSharedPackageStoreOptions.ts
+const ensureGitIgnoreEntry = (cwd) => {
+	const gitignore = join(cwd, GITIGNORE_FILENAME);
+	const gitignoreContent = existsSync(gitignore) ? readFileSync(gitignore, "utf8") : "";
+	if (gitignoreContent.split(/\r?\n/u).includes(VIRRUN_GITIGNORE_ENTRY)) return;
+	appendFileSync(gitignore, `${gitignoreContent.endsWith("\n") || gitignoreContent === "" ? "" : "\n"}${VIRRUN_GITIGNORE_ENTRY}\n`);
+};
+const createSharedPackageStoreOptions = (cwd) => {
+	const dir = resolveCwd(cwd);
+	const storeDir = join(getRepoCacheDirectory(dir), VIRRUN_STORE_DIRECTORY_NAME, VIRRUN_PNPM_STORE_DIRECTORY_NAME);
+	mkdirSync(storeDir, { recursive: true });
+	ensureGitIgnoreEntry(dir);
+	return {
+		bindDirs: [storeDir],
+		env: {
+			[PNPM_CONFIG_PACKAGE_IMPORT_METHOD_KEY]: PNPM_CONFIG_PACKAGE_IMPORT_METHOD_VALUE,
+			[PNPM_CONFIG_STORE_DIR_KEY]: storeDir
+		}
 	};
 };
 //#endregion
-//#region src/services/exec/tokenizeShellCommand.ts
+//#region src/services/exec/vfs/tokenizeShellCommand.ts
 const SHELL_OPERATORS = /* @__PURE__ */ new Set([
 	"$",
 	"&",
@@ -18798,7 +19150,7 @@ const tokenizeShellCommand = (input) => {
 	return tokens;
 };
 //#endregion
-//#region src/services/exec/parseNodeInvocation.ts
+//#region src/services/exec/vfs/parseNodeInvocation.ts
 const parseNodeInvocation = (command) => {
 	const tokens = typeof command === "string" ? tokenizeShellCommand(command) : [...command];
 	if (!tokens) return void 0;
@@ -22793,10 +23145,10 @@ var import_vfs = (/* @__PURE__ */ __commonJSMin$1(((exports, module) => {
 		SqliteProvider
 	};
 })))();
-const createPlatformaticFsProvider = ({ overlay = false } = {}) => {
+const createPlatformaticFsProvider = ({ isOverlayEnabled = false } = {}) => {
 	const vfs = (0, import_vfs.create)({
 		moduleHooks: true,
-		overlay
+		overlay: isOverlayEnabled
 	});
 	return {
 		dispose: () => {
@@ -22820,7 +23172,7 @@ const createPlatformaticFsProvider = ({ overlay = false } = {}) => {
 	};
 };
 //#endregion
-//#region src/services/exec/runNodeInProcess.ts
+//#region src/services/exec/vfs/runNodeInProcess.ts
 const runNodeInProcess = ({ code, file }, { cwd, stdio }) => {
 	const originalStdoutWrite = process$1.stdout.write.bind(process$1.stdout);
 	const originalStderrWrite = process$1.stderr.write.bind(process$1.stderr);
@@ -22829,7 +23181,7 @@ const runNodeInProcess = ({ code, file }, { cwd, stdio }) => {
 	const originalRequire = globalThis.require;
 	const originalCwd = cwd === "" ? "" : process$1.cwd();
 	const baseDir = cwd === "" ? process$1.cwd() : cwd;
-	const fs = createPlatformaticFsProvider({ overlay: true });
+	const fs = createPlatformaticFsProvider({ isOverlayEnabled: true });
 	const isPipe = stdio === "pipe";
 	const require = createRequire(resolve(baseDir, "[eval].js"));
 	const cachedBefore = new Set(Object.keys(require.cache));
@@ -22874,7 +23226,7 @@ const runNodeInProcess = ({ code, file }, { cwd, stdio }) => {
 	});
 };
 //#endregion
-//#region src/services/exec/createVfsBackend.ts
+//#region src/services/exec/vfs/createVfsBackend.ts
 const createVfsBackend = () => {
 	const native = createNativeBackend();
 	return {
@@ -22896,7 +23248,7 @@ const loadDirSource = (source) => Promise.resolve({
 //#endregion
 //#region src/services/source/loadFilesSource.ts
 const loadFilesSource = async (source) => {
-	const cwd = await mkdtemp(join(tmpdir(), "sandbox-"));
+	const cwd = await mkdtemp(join(tmpdir(), VIRRUN_TEMP_DIR_PREFIX));
 	const dispose = () => rm(cwd, {
 		force: true,
 		recursive: true
@@ -22974,21 +23326,32 @@ const backendFactories = {
 	["os"]: createOsBackend,
 	["vfs"]: createVfsBackend
 };
-const createVirrun = async (options = {}) => {
-	const { backend = "auto", source = {
-		dir: "",
-		type: "dir"
-	} } = options;
+const createVirrun = async ({ backend = "auto", source = {
+	dir: "",
+	type: "dir"
+} } = {}) => {
 	const execBackend = backendFactories[backend]();
 	const { cwd, dispose } = await loadSource(source);
+	const sharedPackageStoreOptions = execBackend.name === "os" ? createSharedPackageStoreOptions(cwd) : {};
+	const toOptions = (stdio) => ({
+		...sharedPackageStoreOptions,
+		cwd,
+		env: {
+			...sharedPackageStoreOptions.env,
+			[VIRRUN_ENV_KEY]: "true"
+		},
+		stdio
+	});
 	return {
 		backend: execBackend.name,
 		dispose,
-		exec: (command, stdio = "pipe") => execBackend.exec(command, {
-			cwd,
-			stdio
-		})
+		exec: (command, stdio = "pipe") => execBackend.exec(command, toOptions(stdio)),
+		fork: async (command, stdio = "pipe") => {
+			if (execBackend.name !== "os") return execBackend.exec(command, toOptions(stdio));
+			if (!resolveSnapshotLocation(cwd).exists) return (await createSnapshot(execBackend, command, toOptions(stdio))).result;
+			return forkSnapshot(execBackend, command, toOptions(stdio));
+		}
 	};
 };
 //#endregion
-export { createNativeBackend as _, loadDirSource as a, SourceType as b, createPlatformaticFsProvider as c, tokenizeShellCommand as d, createOsBackend as f, buildBwrapArgs as g, withFinalizerAsync as h, loadFilesSource as i, ExitSignalError as l, isOsBackendSupported as m, loadSource as n, createVfsBackend as o, parseBwrapExitCode as p, loadGitSource as r, runNodeInProcess as s, createVirrun as t, parseNodeInvocation as u, toExitCode as v, parseCliCommand as x, BackendType as y };
+export { VIRRUN_SNAPSHOT_UPPER_DIRECTORY_NAME as $, parseBwrapExitCode as A, GITIGNORE_FILENAME as B, createWslBwrapArgs as C, parseBwrapStderrStatus as D, createBwrapBackend as E, resolveCwd as F, VIRRUN_CACHE_DIRECTORY_NAME as G, PNPM_CONFIG_PACKAGE_IMPORT_METHOD_VALUE as H, parseVirrunConfiguration as I, VIRRUN_COREPACK_STORE_DIRECTORY_NAME as J, VIRRUN_CACHE_HOME_KEY as K, resolveBackend as L, toExitCode as M, SourceType as N, WSL_BWRAP_STATUS_BEGIN as O, resolveVirrunConfiguration as P, VIRRUN_SNAPSHOTS_DIRECTORY_NAME as Q, isOsBackendSupported as R, createWslEnvArgs as S, createLinuxOsBackend as T, PNPM_CONFIG_STORE_DIR_KEY as U, PNPM_CONFIG_PACKAGE_IMPORT_METHOD_KEY as V, PNPM_LOCKFILE_FILENAME as W, VIRRUN_GITIGNORE_ENTRY as X, VIRRUN_ENV_KEY as Y, VIRRUN_PNPM_STORE_DIRECTORY_NAME as Z, getGlobalCacheDirectory as _, loadDirSource as a, BackendType as at, createOsBackend as b, createPlatformaticFsProvider as c, tokenizeShellCommand as d, VIRRUN_SNAPSHOT_WORK_DIRECTORY_NAME as et, createSharedPackageStoreOptions as f, resolveSnapshotLocation as g, createSnapshot as h, loadFilesSource as i, withFinalizerAsync as it, createNativeBackend as j, WSL_BWRAP_STATUS_END as k, ExitSignalError as l, forkSnapshot as m, loadSource as n, VIRRUN_TEMP_DIR_PREFIX as nt, createVfsBackend as o, parseCliCommand as ot, getRepoCacheDirectory as p, VIRRUN_CONFIGURATION_FILENAME as q, loadGitSource as r, buildBwrapArgs as rt, runNodeInProcess as s, createVirrun as t, VIRRUN_STORE_DIRECTORY_NAME as tt, parseNodeInvocation as u, computeLockfileHash as v, readWslPath as w, createWslOsBackend as x, removeSnapshotLocation as y, COREPACK_HOME_KEY as z };