spawnfile 0.1.17 → 0.1.18

package/dist/compiler/workspaceBundleFiles.js

@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { listCommittedTree, listIndex, readStableSnapshot, readStatus, readStatusAgainstHead, resolveGitLocation, resolveCommit, resolveHead, streamBlobs } from "./workspaceBundleGit.js";
+import { BundleTarWriter, normalizeBundleMode, WORKSPACE_BUNDLE_MAX_BYTES, WORKSPACE_BUNDLE_MAX_ENTRIES } from "./workspaceBundleTar.js";
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+const SYMLINK = 0o120000, GITLINK = 0o160000;
+const escapeRegExp = (value) => value.replace(/[.+^${}()|[\]\\]/gu, "\\$&");
+/**
+ * Exclude patterns match the path relative to the bundle root: `*` and `?`
+ * stay inside one segment, `**` crosses segments, and a pattern that matches
+ * a directory excludes everything beneath it.
+ */
+export const compileExcludePatterns = (patterns = []) => {
+    const expressions = patterns.map((pattern) => {
+        const trimmed = pattern.replace(/^\.\//u, "").replace(/\/+$/u, "");
+        if (!trimmed || trimmed.startsWith("/") || trimmed.split("/").some((segment) => segment === ".." || segment === ".")) {
+            fail(`Workspace bundle exclude pattern must be a relative path glob: ${pattern}`);
+        }
+        let source = "";
+        for (let index = 0; index < trimmed.length;) {
+            if (trimmed.startsWith("**/", index)) {
+                source += "(?:.*/)?";
+                index += 3;
+            }
+            else if (trimmed.startsWith("**", index)) {
+                source += ".*";
+                index += 2;
+            }
+            else if (trimmed[index] === "*") {
+                source += "[^/]*";
+                index += 1;
+            }
+            else if (trimmed[index] === "?") {
+                source += "[^/]";
+                index += 1;
+            }
+            else {
+                source += escapeRegExp(trimmed[index]);
+                index += 1;
+            }
+        }
+        return new RegExp(`^${source}$`, "u");
+    });
+    return (relativePath) => {
+        if (expressions.length === 0)
+            return false;
+        const segments = relativePath.split("/");
+        for (let length = 1; length <= segments.length; length += 1) {
+            const candidate = segments.slice(0, length).join("/");
+            if (expressions.some((expression) => expression.test(candidate)))
+                return true;
+        }
+        return false;
+    };
+};
+const validEntryPath = (relativePath) => {
+    if (!relativePath || relativePath.includes("\\") || relativePath.split("/").some((part) => !part || part === "." || part === "..")) {
+        fail(`Workspace bundle input path cannot be archived safely: ${relativePath}`);
+    }
+    return relativePath;
+};
+const refuseLinks = (relativePath, mode) => {
+    if (mode === SYMLINK)
+        fail(`Workspace bundle input is a symlink; exclude it or replace it with a file: ${relativePath}`);
+    if (mode === GITLINK)
+        fail(`Workspace bundle input is a git submodule; exclude it or declare it as its own resource: ${relativePath}`);
+};
+const relativeTo = (status, prefix) => status.map((entry) => ({ ...entry, path: entry.path.startsWith(prefix) ? entry.path.slice(prefix.length) : entry.path }));
+const sortEntries = (entries) => entries.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+export const resolveBundleRoot = async (directory) => {
+    const info = await lstat(directory).catch(() => fail(`Workspace bundle root does not exist: ${directory}`));
+    if (!info.isDirectory())
+        fail(`Workspace bundle root must be a real directory, not a file or symlink: ${directory}`);
+    return realpath(directory);
+};
+/**
+ * Release identity: the root must be clean against HEAD (ignoring excluded
+ * paths), and the identity is the committed tree's blob ids and modes. No
+ * input file is read.
+ */
+export const resolveReleaseFiles = async (directory, exclude = []) => {
+    const excluded = compileExcludePatterns(exclude);
+    const [{ prefix }, status] = await Promise.all([resolveGitLocation(directory), readStatusAgainstHead(directory)]);
+    if (!status.head)
+        fail(`Release workspace bundle requires a commit; the repository has none: ${directory}`);
+    const dirty = status.changed.map((changed) => changed.startsWith(prefix) ? changed.slice(prefix.length) : changed).filter((changed) => !excluded(changed));
+    if (dirty.length > 0) {
+        fail(`Release workspace bundle requires a clean commit; ${dirty.length} uncommitted change(s) under ${directory}, first: ${dirty[0]}`);
+    }
+    // The tree of exactly the commit status verified clean against; bytes come from its objects, so later edits cannot leak in.
+    // Status reads HEAD twice internally; if HEAD has moved since, it may have compared against a different commit.
+    const [tree, headNow] = await Promise.all([listCommittedTree(directory, status.head), resolveHead(directory)]);
+    if (headNow !== status.head)
+        fail(`Release workspace bundle HEAD moved while it was checked; retry: ${directory}`);
+    return { directory, entries: treeEntries(tree, excluded), mode: "release" };
+};
+const treeEntries = (tree, excluded) => {
+    const entries = [];
+    for (const entry of tree) {
+        if (excluded(entry.path))
+            continue;
+        refuseLinks(entry.path, entry.mode);
+        if (entry.type !== "blob")
+            fail(`Workspace bundle input has unsupported git type ${entry.type}: ${entry.path}`);
+        entries.push({ identity: `git:${entry.objectId}`, mode: normalizeBundleMode(entry.mode), objectId: entry.objectId, path: validEntryPath(entry.path) });
+    }
+    return sortEntries(entries);
+};
+/**
+ * Release rule for recipe inputs that are named files rather than a tree:
+ * each must be tracked at HEAD with no staged, unstaged or untracked change.
+ */
+export const assertCommittedInputs = async (directory, names) => {
+    const [{ prefix }, status] = await Promise.all([resolveGitLocation(directory), readStatusAgainstHead(directory)]);
+    if (!status.head)
+        fail(`Release workspace bundle requires a commit; the repository has none: ${directory}`);
+    const wanted = new Set(names.map((name) => `${prefix}${name}`));
+    const dirty = status.changed.find((changed) => wanted.has(changed));
+    if (dirty)
+        fail(`Release workspace bundle requires a clean commit; ${dirty} has uncommitted changes`);
+    const committed = new Set((await listCommittedTree(directory, status.head)).map((entry) => entry.path));
+    const missing = names.find((name) => !committed.has(name));
+    if (missing)
+        fail(`Release workspace bundle input ${missing} is not committed in ${directory}`);
+    if (await resolveHead(directory) !== status.head)
+        fail(`Release workspace bundle HEAD moved while it was checked; retry: ${directory}`);
+};
+/**
+ * A pinned revision: identity and bytes come from the tree of `ref` (resolved
+ * to a commit once), so the work tree's state is irrelevant and no clean
+ * checkout is needed. The same in dev and release compiles.
+ */
+export const resolveCommittedFiles = async (directory, ref, exclude = []) => {
+    const commit = await resolveCommit(directory, ref);
+    if (!commit)
+        fail(`Workspace bundle ref ${ref} does not name a commit in ${directory}; fetch it first`);
+    return { directory, entries: treeEntries(await listCommittedTree(directory, commit), compileExcludePatterns(exclude)), mode: "release" };
+};
+const HASH_CONCURRENCY = 8;
+const hashFile = async (filePath, spend) => {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        spend(chunk.length);
+        hash.update(chunk);
+    }
+    return `sha256:${hash.digest("hex")}`;
+};
+/**
+ * Dev identity: the working tree as it is now. Files git reports as unchanged
+ * keep their index blob id; modified and untracked (not ignored) files are
+ * hashed from disk, so an uncommitted edit or a new file always moves the key.
+ */
+export const resolveDevFiles = async (directory, exclude = []) => {
+    const excluded = compileExcludePatterns(exclude), location = await resolveGitLocation(directory), { prefix } = location;
+    const [index, rawStatus] = await readStableSnapshot(location, () => Promise.all([listIndex(directory), readStatus(directory)]));
+    const status = relativeTo(rawStatus, prefix);
+    const untracked = status.filter((entry) => entry.index === "?").map((entry) => entry.path);
+    const changed = new Set(status.filter((entry) => entry.worktree !== " " && entry.worktree !== "?").map((entry) => entry.path));
+    const conflicted = new Set(index.filter((entry) => entry.stage !== 0).map((entry) => entry.path));
+    const entries = new Map(), toHash = [];
+    for (const entry of index) {
+        if (excluded(entry.path) || entries.has(entry.path))
+            continue;
+        if (changed.has(entry.path) || conflicted.has(entry.path)) {
+            toHash.push(entry.path);
+            continue;
+        }
+        refuseLinks(entry.path, entry.mode);
+        entries.set(entry.path, { identity: `git:${entry.objectId}`, mode: normalizeBundleMode(entry.mode), objectId: entry.objectId, path: validEntryPath(entry.path) });
+    }
+    for (const relativePath of untracked) {
+        if (excluded(relativePath.replace(/\/$/u, "")))
+            continue;
+        if (relativePath.endsWith("/"))
+            fail(`Workspace bundle input contains a nested git repository; exclude it: ${relativePath}`);
+        toHash.push(relativePath);
+    }
+    const pending = [...new Set(toHash)];
+    let hashedBytes = 0;
+    // Bounded: at most HASH_CONCURRENCY files open, and the byte budget is spent before a file is read.
+    const hashNext = async () => {
+        for (let relativePath = pending.pop(); relativePath !== undefined; relativePath = pending.pop()) {
+            const filePath = path.join(directory, relativePath);
+            const info = await lstat(filePath).catch(() => undefined);
+            if (!info)
+                continue; // deleted in the work tree: not an input any more
+            if (info.isSymbolicLink())
+                refuseLinks(relativePath, SYMLINK);
+            if (!info.isFile())
+                fail(`Workspace bundle input is not a regular file: ${relativePath}`);
+            entries.set(relativePath, { identity: await hashFile(filePath, spend), mode: normalizeBundleMode(info.mode), path: validEntryPath(relativePath) });
+        }
+    };
+    // Budget the bytes actually streamed, so a file that grows after lstat cannot overrun it.
+    const spend = (bytes) => { hashedBytes += bytes; if (hashedBytes > WORKSPACE_BUNDLE_MAX_BYTES)
+        fail("Workspace bundle exceeds the maximum archive size"); };
+    await Promise.all(Array.from({ length: HASH_CONCURRENCY }, hashNext));
+    if (entries.size > WORKSPACE_BUNDLE_MAX_ENTRIES)
+        fail("Workspace bundle exceeds the maximum entry count");
+    return { directory, entries: sortEntries([...entries.values()]), mode: "dev" };
+};
+/**
+ * Writes the archive for a resolved input set. Every `git:` entry is read from
+ * the object store, so its bytes are exactly the blob its identity names;
+ * every `sha256:` entry is read from disk and re-checked against its digest.
+ * The archive is therefore a pure function of the cache key.
+ */
+export const writeBundleFiles = async (input, outputPath) => {
+    const writer = await BundleTarWriter.create(outputPath);
+    const objects = input.entries.filter((entry) => entry.objectId !== undefined);
+    const disk = input.entries.filter((entry) => entry.objectId === undefined);
+    let next = 0;
+    const writeDiskBefore = async (limit) => {
+        for (; next < disk.length && (limit === undefined || disk[next].path < limit); next += 1) {
+            const entry = disk[next], filePath = path.join(input.directory, entry.path);
+            if ((await stat(filePath)).size > WORKSPACE_BUNDLE_MAX_BYTES)
+                fail("Workspace bundle exceeds the maximum archive size");
+            const bytes = await readFile(filePath);
+            if (`sha256:${createHash("sha256").update(bytes).digest("hex")}` !== entry.identity) {
+                fail(`Workspace bundle input changed while the bundle was built: ${entry.path}`);
+            }
+            await writer.begin(entry.path, bytes.length, entry.mode);
+            await writer.data(bytes);
+            await writer.end();
+        }
+    };
+    try {
+        if (objects.length > 0) {
+            await streamBlobs(input.directory, objects.map((entry) => entry.objectId), {
+                begin: async (index, size) => {
+                    const entry = objects[index];
+                    await writeDiskBefore(entry.path);
+                    await writer.begin(entry.path, size, entry.mode);
+                },
+                data: (chunk) => writer.data(chunk),
+                end: () => writer.end()
+            });
+        }
+        await writeDiskBefore();
+        return await writer.finish();
+    }
+    catch (error) {
+        await writer.abort();
+        throw error;
+    }
+};

package/dist/compiler/workspaceBundleGenerated.d.ts

@@ -0,0 +1,25 @@
+import type { WorkspaceBundleBuild } from "../manifest/index.js";
+import { type BundleFilesInput } from "./workspaceBundleFiles.js";
+import { type BundleBuildContext, type BundleBuildPlan } from "./workspaceBundleKey.js";
+type FilesSpec = NonNullable<WorkspaceBundleBuild["files"]>;
+type GeneratedSpec = NonNullable<WorkspaceBundleBuild["generated"]>;
+export declare const GENERATED_OUTPUT_PLACEHOLDER = "${output}";
+/** Git identity for one declared file input: a pinned ref, a clean commit (release) or the work tree (dev). */
+export declare const resolveFilesInput: (spec: FilesSpec, context: BundleBuildContext) => Promise<BundleFilesInput>;
+export declare const planFilesBundle: (spec: FilesSpec, context: BundleBuildContext) => Promise<BundleBuildPlan>;
+/**
+ * `generated`: a declared command writes an output directory from declared
+ * inputs. The key is the recipe above plus the target platform; the command
+ * runs only on a cache miss. After it runs the recipe is computed again and
+ * the build fails if any input or tool changed meanwhile, so output is never
+ * cached under a key that does not describe what it was built from.
+ * Undeclared inputs and host environment are not part of the key, so declare
+ * everything the command reads. Inputs come from the work tree the command
+ * reads, so `ref` is refused; with `image`, only `cwd` is mounted, so every
+ * input must live inside it. `captureTools: false` keys tools by argv only and
+ * runs nothing (used for pins).
+ */
+export declare const planGeneratedBundle: (spec: GeneratedSpec, context: BundleBuildContext, options?: {
+    captureTools?: boolean;
+}) => Promise<BundleBuildPlan>;
+export {};

package/dist/compiler/workspaceBundleGenerated.js

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { resolveBundleRoot, resolveCommittedFiles, resolveDevFiles, resolveReleaseFiles, writeBundleFiles } from "./workspaceBundleFiles.js";
+import { computeRecipeBundleKey, computeWorkspaceBundleKey, filesIdentity } from "./workspaceBundleKey.js";
+import { bundleContainerName, runBundleCommand, runContainerStep } from "./workspaceBundleRun.js";
+import { walkBuiltTree } from "./workspaceBundleTree.js";
+const DEFAULT_TIMEOUT_SECONDS = 600;
+const TOOL_TIMEOUT_MS = 120_000;
+const CONTAINER_WORKDIR = "/spawnfile/work", CONTAINER_OUTPUT = "/spawnfile/output";
+export const GENERATED_OUTPUT_PLACEHOLDER = "${output}";
+/** The compile output is never an input, even when an input root contains it. */
+const withOutputExcluded = (root, exclude, outputReal) => {
+    const inside = path.relative(root, outputReal);
+    return inside && !inside.startsWith("..") && !path.isAbsolute(inside) ? [...(exclude ?? []), inside.split(path.sep).join("/")] : exclude;
+};
+/** Git identity for one declared file input: a pinned ref, a clean commit (release) or the work tree (dev). */
+export const resolveFilesInput = async (spec, context) => {
+    const root = await resolveBundleRoot(spec.root), exclude = withOutputExcluded(root, spec.exclude, context.outputReal);
+    if (spec.ref !== undefined)
+        return resolveCommittedFiles(root, spec.ref, exclude);
+    return context.identity === "release" ? resolveReleaseFiles(root, exclude) : resolveDevFiles(root, exclude);
+};
+export const planFilesBundle = async (spec, context) => {
+    const input = await resolveFilesInput(spec, context);
+    return { input: "files", key: computeWorkspaceBundleKey(input, context.platform), write: (temporaryTar) => writeBundleFiles(input, temporaryTar) };
+};
+const inside = (root, candidate) => {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+};
+/**
+ * The recipe a generated bundle is keyed by: every input's git identity, the
+ * command, `cwd`, the image, and each tool command with its exact captured
+ * stdout (or, without capture, just its argv). Captured output is hashed as
+ * bytes, so whitespace changes count.
+ */
+const generatedRecipe = async (spec, cwd, context, captureTools) => {
+    const inputs = await Promise.all(spec.inputs.map((input) => resolveFilesInput(input, context)));
+    const tools = await Promise.all((spec.tools ?? []).map(async (tool) => ({
+        argv: tool,
+        output: captureTools ? createHash("sha256").update(spec.image
+            ? await runContainerStep({ argv: tool, dockerCommand: context.dockerCommand, image: spec.image, mounts: [[cwd, CONTAINER_WORKDIR]], name: bundleContainerName(), platform: context.platform, workdir: CONTAINER_WORKDIR }, TOOL_TIMEOUT_MS, `Generated bundle tool ${tool.join(" ")}`, cwd)
+            : await runBundleCommand({ argv: tool, cwd, timeoutMs: TOOL_TIMEOUT_MS }, `Generated bundle tool ${tool.join(" ")}`)).digest("hex") : null
+    })));
+    return {
+        command: spec.command, cwd, image: spec.image ?? null,
+        inputs: inputs.map((input) => ({ entries: filesIdentity(input), root: input.directory })),
+        tools
+    };
+};
+/**
+ * `generated`: a declared command writes an output directory from declared
+ * inputs. The key is the recipe above plus the target platform; the command
+ * runs only on a cache miss. After it runs the recipe is computed again and
+ * the build fails if any input or tool changed meanwhile, so output is never
+ * cached under a key that does not describe what it was built from.
+ * Undeclared inputs and host environment are not part of the key, so declare
+ * everything the command reads. Inputs come from the work tree the command
+ * reads, so `ref` is refused; with `image`, only `cwd` is mounted, so every
+ * input must live inside it. `captureTools: false` keys tools by argv only and
+ * runs nothing (used for pins).
+ */
+export const planGeneratedBundle = async (spec, context, options = {}) => {
+    if (spec.inputs.some((input) => input.ref !== undefined)) {
+        throw new SpawnfileError("validation_error", "Generated bundle inputs cannot pin a ref: the command reads the work tree");
+    }
+    const cwd = await resolveBundleRoot(spec.cwd), captureTools = options.captureTools ?? true;
+    if (spec.image && (await Promise.all(spec.inputs.map((input) => resolveBundleRoot(input.root)))).some((root) => !inside(cwd, root))) {
+        throw new SpawnfileError("validation_error", "Generated bundle inputs must live inside cwd when the command runs in an image: only cwd is mounted");
+    }
+    const recipe = await generatedRecipe(spec, cwd, context, captureTools);
+    return {
+        input: "generated",
+        key: computeRecipeBundleKey("generated", recipe, context.platform),
+        write: async (temporaryTar) => {
+            await mkdir(context.workRoot, { mode: 0o700, recursive: true });
+            const output = await mkdtemp(path.join(context.workRoot, "generated-"));
+            try {
+                const target = spec.image ? CONTAINER_OUTPUT : output;
+                const argv = spec.command.map((part) => part.split(GENERATED_OUTPUT_PLACEHOLDER).join(target));
+                const label = `Generated bundle command ${spec.command.join(" ")}`, timeoutMs = (spec.timeout_seconds ?? DEFAULT_TIMEOUT_SECONDS) * 1_000;
+                if (spec.image) {
+                    await runContainerStep({
+                        argv, dockerCommand: context.dockerCommand, env: { SPAWNFILE_BUNDLE_OUTPUT: target }, image: spec.image,
+                        mounts: [[cwd, CONTAINER_WORKDIR], [output, CONTAINER_OUTPUT]], name: bundleContainerName(), platform: context.platform, workdir: CONTAINER_WORKDIR
+                    }, timeoutMs, label, cwd);
+                }
+                else {
+                    await runBundleCommand({ argv, cwd, env: { ...process.env, SPAWNFILE_BUNDLE_OUTPUT: target }, timeoutMs }, label);
+                }
+                if (JSON.stringify(await generatedRecipe(spec, cwd, context, captureTools)) !== JSON.stringify(recipe)) {
+                    throw new SpawnfileError("validation_error", `${label}: inputs or tools changed while it ran; nothing was cached, retry`);
+                }
+                return await writeBundleFiles(await walkBuiltTree(output), temporaryTar);
+            }
+            finally {
+                await rm(output, { force: true, recursive: true });
+            }
+        }
+    };
+};

package/dist/compiler/workspaceBundleGit.d.ts

@@ -0,0 +1,64 @@
+export interface GitTreeEntry {
+    mode: number;
+    objectId: string;
+    path: string;
+    type: string;
+}
+export interface GitIndexEntry {
+    mode: number;
+    objectId: string;
+    path: string;
+    stage: number;
+}
+export interface GitLocation {
+    indexPath: string;
+    prefix: string;
+    topLevel: string;
+}
+/** The repository top level, this directory's path prefix inside it ("" at the top), and the index file. */
+export declare const resolveGitLocation: (directory: string) => Promise<GitLocation>;
+/**
+ * Runs `read` against one consistent index: the index file must be identical
+ * before and after, else a concurrent `git add` could pair an old index
+ * listing with a new status. Retries a few times, then fails.
+ */
+export declare const readStableSnapshot: <T>(location: GitLocation, read: () => Promise<T>) => Promise<T>;
+/** Committed tree under `directory`: blob ids and modes from the tree objects alone, no blob or file reads. */
+export declare const listCommittedTree: (directory: string, commit?: string) => Promise<GitTreeEntry[]>;
+/** Index entries under `directory` (paths relative to it). */
+export declare const listIndex: (directory: string) => Promise<GitIndexEntry[]>;
+export interface GitStatusEntry {
+    index: string;
+    path: string;
+    worktree: string;
+}
+/**
+ * `git status` under `directory`, paths relative to the repository top level
+ * (strip the location prefix). Untracked, not-ignored files appear
+ * individually as `??`; a nested repository appears once with a trailing "/".
+ * Ignored paths never appear.
+ */
+export declare const readStatus: (directory: string) => Promise<GitStatusEntry[]>;
+/** The commit a revision names, or "" when it names none. */
+export declare const resolveCommit: (directory: string, revision: string) => Promise<string>;
+/** The HEAD commit id, or "" when the repository has none. */
+export declare const resolveHead: (directory: string) => Promise<string>;
+/**
+ * The commit `git status` compared against and every changed path under
+ * `directory` (repository-relative), from one porcelain v2 run. Pairing the
+ * two in one process means a concurrent commit can never split them.
+ */
+export declare const readStatusAgainstHead: (directory: string) => Promise<{
+    changed: string[];
+    head: string;
+}>;
+/**
+ * Streams blob contents for `objectIds`, in order, through `onBlob`. One
+ * `git cat-file --batch` process serves the whole tree; content never touches
+ * the work tree, so the result is a pure function of the committed objects.
+ */
+export declare const streamBlobs: (directory: string, objectIds: string[], handlers: {
+    begin: (index: number, size: number) => Promise<void>;
+    data: (chunk: Buffer) => Promise<void>;
+    end: () => Promise<void>;
+}) => Promise<void>;

package/dist/compiler/workspaceBundleGit.js

@@ -0,0 +1,154 @@
+import { execFile, spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const run = promisify(execFile);
+const MAX_BUFFER = 268_435_456;
+// Never take git's optional index lock: a compile reads the repository, it does not maintain it.
+// Never honour replacement refs: the cache key names object ids, so their bytes must be the objects'.
+const gitEnv = () => ({ ...process.env, GIT_NO_REPLACE_OBJECTS: "1", GIT_OPTIONAL_LOCKS: "0" });
+const git = async (cwd, args) => {
+    try {
+        const { stdout } = await run("git", args, { cwd, encoding: "buffer", env: gitEnv(), maxBuffer: MAX_BUFFER });
+        return stdout;
+    }
+    catch (error) {
+        const stderr = error.stderr?.toString("utf8").trim();
+        throw new SpawnfileError("validation_error", `Workspace bundle git query failed in ${cwd}: git ${args[0]}${stderr ? `: ${stderr}` : ""}`);
+    }
+};
+const records = (output) => output.toString("utf8").split("\0").filter(Boolean);
+/** The repository top level, this directory's path prefix inside it ("" at the top), and the index file. */
+export const resolveGitLocation = async (directory) => {
+    const [topLevel, prefix = "", indexPath = ""] = (await git(directory, ["rev-parse", "--show-toplevel", "--show-prefix", "--git-path", "index"])).toString("utf8").split("\n");
+    if (!topLevel || !indexPath)
+        throw new SpawnfileError("validation_error", `Workspace bundle root is not inside a git work tree: ${directory}`);
+    return { indexPath: path.resolve(directory, indexPath), prefix, topLevel };
+};
+const indexStamp = async (location) => {
+    const index = await stat(location.indexPath).catch(() => undefined);
+    return JSON.stringify([index?.ino, index?.size, index?.mtimeMs]);
+};
+/**
+ * Runs `read` against one consistent index: the index file must be identical
+ * before and after, else a concurrent `git add` could pair an old index
+ * listing with a new status. Retries a few times, then fails.
+ */
+export const readStableSnapshot = async (location, read) => {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const before = await indexStamp(location);
+        const value = await read();
+        if (before === await indexStamp(location))
+            return value;
+    }
+    throw new SpawnfileError("validation_error", `Workspace bundle inputs kept changing while they were read: ${location.topLevel}`);
+};
+/** Committed tree under `directory`: blob ids and modes from the tree objects alone, no blob or file reads. */
+export const listCommittedTree = async (directory, commit = "HEAD") => records(await git(directory, ["ls-tree", "-r", "-z", commit, "--", "."])).map((record) => {
+    const tab = record.indexOf("\t");
+    const [mode, type, objectId] = record.slice(0, tab).split(" ");
+    return { mode: Number.parseInt(mode, 8), objectId: objectId, path: record.slice(tab + 1), type: type };
+});
+/** Index entries under `directory` (paths relative to it). */
+export const listIndex = async (directory) => records(await git(directory, ["ls-files", "-s", "-z", "--", "."])).map((record) => {
+    const tab = record.indexOf("\t");
+    const [mode, objectId, stage] = record.slice(0, tab).split(" ");
+    return { mode: Number.parseInt(mode, 8), objectId: objectId, path: record.slice(tab + 1), stage: Number(stage) };
+});
+/**
+ * `git status` under `directory`, paths relative to the repository top level
+ * (strip the location prefix). Untracked, not-ignored files appear
+ * individually as `??`; a nested repository appears once with a trailing "/".
+ * Ignored paths never appear.
+ */
+export const readStatus = async (directory) => records(await git(directory, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--no-renames", "--", "."])).map((record) => ({ index: record[0], path: record.slice(3), worktree: record[1] }));
+/** The commit a revision names, or "" when it names none. */
+export const resolveCommit = async (directory, revision) => revision.startsWith("-") ? "" : git(directory, ["rev-parse", "-q", "--verify", "--end-of-options", `${revision}^{commit}`]).then((output) => output.toString("utf8").trim(), () => "");
+/** The HEAD commit id, or "" when the repository has none. */
+export const resolveHead = async (directory) => resolveCommit(directory, "HEAD");
+/**
+ * The commit `git status` compared against and every changed path under
+ * `directory` (repository-relative), from one porcelain v2 run. Pairing the
+ * two in one process means a concurrent commit can never split them.
+ */
+export const readStatusAgainstHead = async (directory) => {
+    let head = "";
+    const changed = [];
+    for (const record of records(await git(directory, ["status", "--porcelain=v2", "--branch", "-z", "--untracked-files=all", "--no-renames", "--", "."]))) {
+        if (record.startsWith("# branch.oid ")) {
+            const oid = record.slice(13);
+            head = /^[a-f0-9]{40,64}$/u.test(oid) ? oid : "";
+            continue;
+        }
+        if (record.startsWith("#"))
+            continue;
+        const fields = record.split(" "), skip = record[0] === "1" ? 8 : record[0] === "u" ? 10 : 1;
+        changed.push(fields.slice(skip).join(" "));
+    }
+    return { changed, head };
+};
+/**
+ * Streams blob contents for `objectIds`, in order, through `onBlob`. One
+ * `git cat-file --batch` process serves the whole tree; content never touches
+ * the work tree, so the result is a pure function of the committed objects.
+ */
+export const streamBlobs = async (directory, objectIds, handlers) => {
+    const child = spawn("git", ["cat-file", "--batch"], { cwd: directory, env: gitEnv(), stdio: ["pipe", "pipe", "pipe"] });
+    const exited = new Promise((resolve, reject) => { child.once("error", reject); child.once("close", resolve); });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(objectIds.map((id) => `${id}\n`).join(""));
+    let index = 0, remaining = -1, trailer = false, header = Buffer.alloc(0);
+    try {
+        for await (const raw of child.stdout) {
+            let chunk = raw;
+            while (chunk.length > 0) {
+                if (trailer) {
+                    if (chunk[0] !== 0x0a)
+                        throw new SpawnfileError("validation_error", "Workspace bundle blob stream is malformed");
+                    chunk = chunk.subarray(1);
+                    trailer = false;
+                    await handlers.end();
+                    index += 1;
+                    continue;
+                }
+                if (remaining < 0) {
+                    const newline = chunk.indexOf(0x0a);
+                    if (newline < 0) {
+                        header = Buffer.concat([header, chunk]);
+                        break;
+                    }
+                    const line = Buffer.concat([header, chunk.subarray(0, newline)]).toString("utf8");
+                    header = Buffer.alloc(0);
+                    chunk = chunk.subarray(newline + 1);
+                    const [objectId, type, size] = line.split(" ");
+                    if (index >= objectIds.length || objectId !== objectIds[index] || type !== "blob" || !/^\d+$/u.test(size ?? "")) {
+                        throw new SpawnfileError("validation_error", `Workspace bundle blob ${objectIds[index] ?? "?"} is not readable: ${line}`);
+                    }
+                    remaining = Number(size);
+                    await handlers.begin(index, remaining);
+                }
+                const take = Math.min(remaining, chunk.length);
+                if (take > 0)
+                    await handlers.data(chunk.subarray(0, take));
+                chunk = chunk.subarray(take);
+                remaining -= take;
+                if (remaining === 0) {
+                    remaining = -1;
+                    trailer = true;
+                }
+            }
+        }
+    }
+    catch (error) {
+        child.kill();
+        await exited.catch(() => undefined);
+        throw error;
+    }
+    const code = await exited;
+    if (code !== 0 || index !== objectIds.length || remaining !== -1 || trailer) {
+        throw new SpawnfileError("validation_error", `Workspace bundle blob stream ended early${stderr ? `: ${stderr.trim()}` : ""}`);
+    }
+};

package/dist/compiler/workspaceBundleKey.d.ts

@@ -0,0 +1,34 @@
+import type { BundleFilesInput, BundleIdentityMode } from "./workspaceBundleFiles.js";
+import { type BundleTarSummary } from "./workspaceBundleTar.js";
+export type BundleInputKind = "dependencies" | "files" | "generated";
+/** Everything a build step needs that is not part of one bundle's declaration. */
+export interface BundleBuildContext {
+    dockerCommand: string;
+    identity: BundleIdentityMode;
+    /** Real path of this compile's output directory, excluded from every input root that contains it. */
+    outputReal: string;
+    /** `linux/<arch>` of the target container. */
+    platform: string;
+    /** Private scratch space for installs and generated output. */
+    workRoot: string;
+}
+/** A bundle whose key is known; `write` builds its archive only on a cache miss. */
+export interface BundleBuildPlan {
+    input: BundleInputKind;
+    key: string;
+    write: (temporaryTar: string) => Promise<BundleTarSummary>;
+}
+/** The identity of a file input set: every entry's path, mode and content identity. */
+export declare const filesIdentity: (input: Pick<BundleFilesInput, "entries">) => Array<[string, number, string]>;
+/**
+ * The cache key of a `files` bundle: every input file's path, mode and
+ * content identity, the archive writer that turns them into bytes, and the
+ * target platform.
+ */
+export declare const computeWorkspaceBundleKey: (input: Pick<BundleFilesInput, "entries">, platform: string) => string;
+/**
+ * The cache key of a recipe bundle: its kind, the full recipe (input
+ * identities, commands, pinned images, captured tool versions), the archive
+ * writer and the target platform. Callers build `recipe` with a fixed key order.
+ */
+export declare const computeRecipeBundleKey: (input: Exclude<BundleInputKind, "files">, recipe: unknown, platform: string) => string;

package/dist/compiler/workspaceBundleKey.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+import { WORKSPACE_BUNDLE_TAR_WRITER } from "./workspaceBundleTar.js";
+const KEY_VERSION = "spawnfile.workspace-bundle-key.v1";
+/** The identity of a file input set: every entry's path, mode and content identity. */
+export const filesIdentity = (input) => input.entries.map((entry) => [entry.path, entry.mode, entry.identity]);
+/**
+ * The cache key of a `files` bundle: every input file's path, mode and
+ * content identity, the archive writer that turns them into bytes, and the
+ * target platform.
+ */
+export const computeWorkspaceBundleKey = (input, platform) => createHash("sha256").update(JSON.stringify({ entries: filesIdentity(input), input: "files", platform, version: KEY_VERSION, writer: WORKSPACE_BUNDLE_TAR_WRITER })).digest("hex");
+/**
+ * The cache key of a recipe bundle: its kind, the full recipe (input
+ * identities, commands, pinned images, captured tool versions), the archive
+ * writer and the target platform. Callers build `recipe` with a fixed key order.
+ */
+export const computeRecipeBundleKey = (input, recipe, platform) => createHash("sha256").update(JSON.stringify({ input, platform, recipe, version: KEY_VERSION, writer: WORKSPACE_BUNDLE_TAR_WRITER })).digest("hex");