@astrosheep/keiyaku 4.0.0 → 4.0.2

package/build/src/git/repository.js

@@ -1,13 +1,14 @@
-import { execFileSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { isAbsolute, resolve } from "node:path";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { consumeProcessStdout } from "../runtime/proc/run.js";
 import { gitObjectId } from "./identity.js";
 import { parseTreeObject, prepareTreeUpdate, treeUpdate, validPath, } from "./tree.js";
 export const GIT_REF = "refs/heads/keiyaku-state";
 export const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
 export const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
 export const GIT_FORMAT_PATH = "meta/format.json";
-const CURRENT_FORMAT_VERSION = 3;
+const CURRENT_FORMAT_VERSION = 4;
 export const GIT_FORMAT_BYTES = `{"version":${CURRENT_FORMAT_VERSION}}\n`;
 export function isKeiyakuOwnedRef(ref) {
     return ref === GIT_REF
@@ -25,20 +26,23 @@ export class NoGitWorldError extends Error {
     }
 }
 export class GitPlumbingError extends Error {
+    stdout;
     stderr;
     status;
     pid;
     constructor(input) {
         super(input.message);
         this.name = "GitPlumbingError";
+        this.stdout = Buffer.from(input.stdout ?? "");
         this.stderr = Buffer.from(input.stderr);
         this.status = input.status;
         this.pid = input.pid ?? null;
     }
 }
-function worktreePathsFromPorcelain(output) {
+const GIT_STDERR_BYTES = 16 * 1024;
+function worktreesFromPorcelain(output) {
     const fields = output.toString("utf8").split("\0");
-    const paths = [];
+    const worktrees = [];
     let record = [];
     const finishRecord = () => {
         if (record.length === 0)
@@ -50,7 +54,11 @@ function worktreePathsFromPorcelain(output) {
         const path = worktree.slice("worktree ".length);
         if (path.length === 0)
             throw new Error("Git worktree porcelain output has an empty worktree path");
-        paths.push(resolve(path));
+        const branchField = record.find((field) => field.startsWith("branch "));
+        const branch = branchField === undefined ? null : branchField.slice("branch ".length);
+        if (branch !== null && !branch.startsWith("refs/"))
+            throw new Error("Git worktree porcelain output has an invalid branch");
+        worktrees.push({ path: resolve(path), branch });
         record = [];
     };
     for (const field of fields) {
@@ -61,22 +69,31 @@ function worktreePathsFromPorcelain(output) {
         record.push(field);
     }
     finishRecord();
-    if (paths.length === 0)
+    if (worktrees.length === 0)
         throw new Error("Git worktree porcelain output has no worktrees");
-    return paths;
+    return worktrees;
 }
-export function registeredWorktreePaths(repository) {
-    return worktreePathsFromPorcelain(runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
+export async function registeredWorktrees(repository) {
+    return worktreesFromPorcelain(await runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
 }
-export function repositoryAt(cwd) {
+export async function registeredWorktreePaths(repository) {
+    return (await registeredWorktrees(repository)).map((worktree) => worktree.path);
+}
+export async function repositoryAt(cwd) {
     if (typeof cwd !== "string" || cwd.length === 0) {
         throw new Error("repository path must be a nonempty string");
     }
     const effectiveCwd = resolve(cwd);
-    const provisional = { effectiveCwd, primaryWorktree: effectiveCwd };
+    const provisional = {
+        effectiveCwd,
+        primaryWorktree: effectiveCwd,
+        commonDirectory: effectiveCwd,
+    };
     let primaryWorktree;
+    let commonDirectory;
     try {
-        primaryWorktree = registeredWorktreePaths(provisional)[0];
+        primaryWorktree = (await registeredWorktreePaths(provisional))[0];
+        commonDirectory = await absoluteGitPath(provisional, ["--git-common-dir"], "common Git directory");
     }
     catch (error) {
         if (error instanceof GitPlumbingError && error.status === 128) {
@@ -84,58 +101,100 @@ export function repositoryAt(cwd) {
         }
         throw error;
     }
-    return { effectiveCwd, primaryWorktree };
+    return { effectiveCwd, primaryWorktree, commonDirectory };
 }
-function absoluteGitPath(repository, args, label) {
-    const value = runGit(repository, ["rev-parse", "--path-format=absolute", ...args]).toString("utf8").trim();
+async function absoluteGitPath(repository, args, label) {
+    const value = (await runGit(repository, ["rev-parse", "--path-format=absolute", ...args])).toString("utf8").trim();
     if (value.length === 0)
         throw new Error(`${label} is empty`);
     return resolve(isAbsolute(value) ? value : resolve(repository.effectiveCwd, value));
 }
 export function commonGitDirectory(repository) {
-    return absoluteGitPath(repository, ["--git-common-dir"], "common Git directory");
+    return repository.commonDirectory;
 }
-export function worktreeGitDirectory(repository, worktree) {
+export async function worktreeGitDirectory(repository, worktree) {
     const scoped = { ...repository, effectiveCwd: worktree };
-    return absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
+    return await absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
+}
+export async function worktreeRoot(repository) {
+    return await absoluteGitPath(repository, ["--show-toplevel"], "worktree root");
 }
 function commandError(command, error) {
     const candidate = error;
     const stderr = candidate.stderr === undefined ? Buffer.alloc(0) : Buffer.from(candidate.stderr);
+    const stdout = candidate.stdout === undefined ? Buffer.alloc(0) : Buffer.from(candidate.stdout);
     const detail = stderr.length === 0 ? candidate.message ?? "git command failed" : stderr.toString("utf8");
     return new GitPlumbingError({
+        stdout,
         stderr,
         status: candidate.status ?? null,
         message: `${command.join(" ")}: ${detail}`,
         pid: candidate.pid ?? null,
     });
 }
-export function runGit(repository, args, input) {
-    try {
-        const output = execFileSync("git", [...args], {
-            cwd: repository.effectiveCwd,
-            input,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        return Buffer.isBuffer(output) ? output : Buffer.from(output);
-    }
-    catch (error) {
-        throw commandError(args, error);
-    }
+async function executeGit(repository, args, input, environment) {
+    const stdout = [];
+    const stderr = [];
+    let stderrBytes = 0;
+    let inputError;
+    const child = spawn("git", [...args], {
+        cwd: repository.effectiveCwd,
+        ...(environment === undefined ? {} : { env: { ...process.env, ...environment } }),
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => {
+        if (stderrBytes >= GIT_STDERR_BYTES)
+            return;
+        const retained = chunk.subarray(0, GIT_STDERR_BYTES - stderrBytes);
+        stderr.push(retained);
+        stderrBytes += retained.length;
+    });
+    child.stdin.on("error", (error) => { inputError = error; });
+    child.stdin.end(input);
+    const terminal = await new Promise((resolveTerminal) => {
+        child.once("error", (error) => resolveTerminal({ code: null, error }));
+        child.once("close", (code) => resolveTerminal({ code }));
+    });
+    const output = Buffer.concat(stdout);
+    if (terminal.code === 0 && inputError === undefined)
+        return output;
+    throw commandError(args, {
+        message: terminal.error?.message ?? inputError?.message ?? `git exited with status ${terminal.code ?? "unknown"}`,
+        stdout: output,
+        stderr: Buffer.concat(stderr),
+        status: terminal.code,
+        pid: child.pid,
+    });
 }
-export function runGitWithEnvironment(repository, args, input, environment) {
-    try {
-        const output = execFileSync("git", [...args], {
-            cwd: repository.effectiveCwd,
-            input,
-            env: { ...process.env, ...environment },
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        return Buffer.isBuffer(output) ? output : Buffer.from(output);
-    }
-    catch (error) {
-        throw commandError(args, error);
-    }
+export async function runGit(repository, args, input) {
+    return await executeGit(repository, args, input);
+}
+export async function consumeGitStdout(repository, args, consume) {
+    const result = await consumeProcessStdout({
+        argv: ["git", ...args],
+        cwd: repository.effectiveCwd,
+    }, consume);
+    const { outcome } = result;
+    if (outcome.kind === "terminal" && outcome.code === 0)
+        return;
+    const status = outcome.kind === "terminal" ? outcome.code : null;
+    const stderr = outcome.kind === "terminal" ? outcome.stderr : "";
+    const message = outcome.kind === "terminal"
+        ? `git exited with status ${outcome.code}`
+        : outcome.kind === "spawn-error" || outcome.kind === "stream-error"
+            ? outcome.diagnostic
+            : `git process ended with ${outcome.kind}`;
+    throw commandError(args, {
+        message,
+        stderr,
+        status,
+        pid: result.pid ?? undefined,
+    });
+}
+export async function runGitWithEnvironment(repository, args, input, environment) {
+    return await executeGit(repository, args, input, environment);
 }
 function assertOid(oid, label) {
     gitObjectId(oid, label);
@@ -145,10 +204,14 @@ function assertRef(ref) {
         throw new Error(`invalid Git ref: ${ref}`);
     }
 }
-export function readRef(repository, ref) {
-    assertRef(ref);
+function assertAssertionRef(ref) {
+    if (ref !== "HEAD")
+        assertRef(ref);
+}
+export async function readRef(repository, ref) {
+    assertAssertionRef(ref);
     try {
-        const oid = runGit(repository, ["rev-parse", "--verify", "--quiet", ref]).toString("utf8").trim();
+        const oid = (await runGit(repository, ["rev-parse", "--verify", "--quiet", ref])).toString("utf8").trim();
         if (oid.length === 0)
             return null;
         assertOid(oid, `ref ${ref}`);
@@ -160,9 +223,9 @@ export function readRef(repository, ref) {
         throw error;
     }
 }
-function readTreeForCommit(repository, commit) {
+async function readTreeForCommit(repository, commit) {
     assertOid(commit, "Git commit");
-    const tree = runGit(repository, ["rev-parse", "--verify", `${commit}^{tree}`]).toString("utf8").trim();
+    const tree = (await runGit(repository, ["show", "-s", "--format=%T", commit])).toString("utf8").trim();
     assertOid(tree, "Git tree");
     return tree;
 }
@@ -184,30 +247,30 @@ function parseTreeEntries(output) {
     }
     return entries;
 }
-function readTreeEntries(repository, tree) {
+export async function readTreeEntries(repository, tree) {
     assertOid(tree, "tree");
-    const output = runGit(repository, ["ls-tree", "-r", "-z", "--full-tree", tree]);
+    const output = await runGit(repository, ["ls-tree", "-r", "-z", "--full-tree", tree]);
     return parseTreeEntries(output);
 }
-export function readGit(repository) {
-    const commit = readRef(repository, GIT_REF);
+export async function readGit(repository) {
+    const commit = await readRef(repository, GIT_REF);
     if (commit === null) {
         return { commit: null, tree: null, paths: new Map() };
     }
-    const tree = readTreeForCommit(repository, commit);
-    const paths = readTreeEntries(repository, tree);
-    validateGitFormat(repository, paths);
+    const tree = await readTreeForCommit(repository, commit);
+    const paths = await readTreeEntries(repository, tree);
+    await validateGitFormat(repository, paths);
     return { commit, tree, paths };
 }
 /** Read only the requested private Git paths from one immutable Git tree. */
-export function readGitPaths(repository, requestedPaths) {
+export async function readGitPaths(repository, requestedPaths) {
     for (const path of requestedPaths)
         validPath(path);
-    const commit = readRef(repository, GIT_REF);
+    const commit = await readRef(repository, GIT_REF);
     if (commit === null)
         return { commit: null, tree: null, paths: new Map() };
-    const tree = readTreeForCommit(repository, commit);
-    const paths = parseTreeEntries(runGit(repository, [
+    const tree = await readTreeForCommit(repository, commit);
+    const paths = parseTreeEntries(await runGit(repository, [
         "ls-tree",
         "-z",
         "--full-tree",
@@ -216,16 +279,16 @@ export function readGitPaths(repository, requestedPaths) {
         GIT_FORMAT_PATH,
         ...requestedPaths,
     ]));
-    validateGitFormat(repository, paths);
+    await validateGitFormat(repository, paths);
     return { commit, tree, paths };
 }
 /** Add paths from the same immutable Git tree without rereading its ref. */
-export function extendGitPaths(repository, snapshot, requestedPaths) {
+export async function extendGitPaths(repository, snapshot, requestedPaths) {
     for (const path of requestedPaths)
         validPath(path);
     if (snapshot.tree === null || requestedPaths.length === 0)
         return snapshot;
-    const additions = parseTreeEntries(runGit(repository, [
+    const additions = parseTreeEntries(await runGit(repository, [
         "ls-tree",
         "-z",
         "--full-tree",
@@ -236,19 +299,19 @@ export function extendGitPaths(repository, snapshot, requestedPaths) {
     return { ...snapshot, paths: new Map([...snapshot.paths, ...additions]) };
 }
 /** Expand a targeted immutable snapshot to its complete already-pinned tree. */
-export function expandGitSnapshot(repository, snapshot) {
+export async function expandGitSnapshot(repository, snapshot) {
     if (snapshot.tree === null)
         return snapshot;
-    return { ...snapshot, paths: readTreeEntries(repository, snapshot.tree) };
+    return { ...snapshot, paths: await readTreeEntries(repository, snapshot.tree) };
 }
-export function writeBlob(repository, bytes) {
-    const oid = runGit(repository, ["hash-object", "-w", "--stdin"], bytes).toString("utf8").trim();
+export async function writeBlob(repository, bytes) {
+    const oid = (await runGit(repository, ["hash-object", "-w", "--stdin"], bytes)).toString("utf8").trim();
     assertOid(oid, "written blob");
     return oid;
 }
-export function readBlob(repository, oid) {
+export async function readBlob(repository, oid) {
     assertOid(oid, "blob");
-    return runGit(repository, ["cat-file", "blob", oid]);
+    return await runGit(repository, ["cat-file", "blob", oid]);
 }
 function malformedBatchOutput(detail) {
     throw new GitPlumbingError({
@@ -257,13 +320,13 @@ function malformedBatchOutput(detail) {
         message: `malformed cat-file --batch output: ${detail}`,
     });
 }
-function readObjects(repository, oids) {
+async function readObjects(repository, oids) {
     const unique = [...new Set(oids)];
     for (const oid of unique)
         assertOid(oid, "Git object");
     if (unique.length === 0)
         return new Map();
-    const output = runGit(repository, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
+    const output = await runGit(repository, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
     const objects = new Map();
     let offset = 0;
     for (const oid of unique) {
@@ -299,32 +362,22 @@ function readObjects(repository, oids) {
         malformedBatchOutput("trailing bytes");
     return objects;
 }
-/** Read immutable Git objects through one structured, length-delimited batch. */
-export function readBlobs(repository, oids) {
-    const blobs = new Map();
-    for (const [oid, object] of readObjects(repository, oids)) {
-        if (object.type !== "blob")
-            malformedBatchOutput(`expected blob for ${oid}, found ${object.type}`);
-        blobs.set(oid, object.bytes);
-    }
-    return blobs;
-}
-function validateGitFormat(repository, paths) {
+async function validateGitFormat(repository, paths) {
     const format = paths.get(GIT_FORMAT_PATH);
     if (format === undefined)
         throw new AuthorityCorruptionError(`Git is missing ${GIT_FORMAT_PATH}`);
     if (format.type !== "blob")
         throw new AuthorityCorruptionError(`Git format is not a blob: ${GIT_FORMAT_PATH}`);
-    const bytes = readBlob(repository, format.oid);
+    const bytes = await readBlob(repository, format.oid);
     if (bytes.toString("utf8") !== GIT_FORMAT_BYTES) {
         throw new AuthorityCorruptionError(`Git format is not current: ${GIT_FORMAT_PATH}`);
     }
 }
-function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
+async function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
     const byPath = new Map();
     if (baseTree === null)
         return byPath;
-    const ancestry = parseTreeEntries(runGit(repository, [
+    const ancestry = parseTreeEntries(await runGit(repository, [
         "ls-tree",
         "-z",
         "-t",
@@ -345,7 +398,7 @@ function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
             throw new Error(`Git path is both file and directory: ${path}`);
         treeByPath.set(path, entry.oid);
     }
-    const objects = readObjects(repository, [...treeByPath.values()]);
+    const objects = await readObjects(repository, [...treeByPath.values()]);
     const oidBytes = baseTree.length / 2;
     for (const [path, oid] of treeByPath) {
         const object = objects.get(oid);
@@ -356,8 +409,8 @@ function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
     }
     return byPath;
 }
-function writePreparedTrees(repository, prepared) {
-    const output = runGit(repository, ["mktree", "--batch"], prepared.map(({ records }) => `${records}\n`).join(""));
+async function writePreparedTrees(repository, prepared) {
+    const output = await runGit(repository, ["mktree", "--batch"], prepared.map(({ records }) => `${records}\n`).join(""));
     const written = output.toString("ascii").trimEnd().split("\n");
     if (written.length !== prepared.length) {
         throw new GitPlumbingError({ stderr: output, status: null, message: "malformed mktree --batch output" });
@@ -372,17 +425,31 @@ function writePreparedTrees(repository, prepared) {
     }
 }
 /** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
-export function updateGitTree(repository, baseTree, changes) {
+export async function updateGitTree(repository, baseTree, changes) {
     const update = treeUpdate(changes);
-    const bases = baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
-    const representativeOid = baseTree ?? changes.values().next().value?.oid;
+    const bases = await baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
+    const representativeOid = baseTree ?? [...changes.values()].find((change) => change !== null)?.oid;
     if (representativeOid === undefined)
         throw new Error("cannot write an empty Git tree without an object format");
     const prepared = prepareTreeUpdate({ update, bases, oidBytes: representativeOid.length / 2 });
-    writePreparedTrees(repository, prepared.trees);
+    await writePreparedTrees(repository, prepared.trees);
+    return prepared.root;
+}
+/** Write a tree update from directory entries frozen with the admitted base tree. */
+export async function updateGitTreeFromFrozenDirectories(repository, baseTree, directories, changes) {
+    const update = treeUpdate(changes);
+    const representativeOid = baseTree ?? [...changes.values()].find((change) => change !== null)?.oid;
+    if (representativeOid === undefined)
+        throw new Error("cannot write an empty Git tree without an object format");
+    const prepared = prepareTreeUpdate({
+        update,
+        bases: directories,
+        oidBytes: representativeOid.length / 2,
+    });
+    await writePreparedTrees(repository, prepared.trees);
     return prepared.root;
 }
-function writeCommitObject(input) {
+async function writeCommitObject(input) {
     const { repository, tree, parents, message, actor, email, at } = input;
     assertOid(tree, "commit tree");
     for (const parent of parents)
@@ -390,20 +457,20 @@ function writeCommitObject(input) {
     const args = ["commit-tree", tree];
     for (const parent of parents)
         args.push("-p", parent);
-    const commit = runGitWithEnvironment(repository, args, `${message}\n`, {
+    const commit = (await runGitWithEnvironment(repository, args, `${message}\n`, {
         GIT_AUTHOR_NAME: actor,
         GIT_AUTHOR_EMAIL: email,
         GIT_COMMITTER_NAME: actor,
         GIT_COMMITTER_EMAIL: email,
         ...(at === undefined ? {} : { GIT_AUTHOR_DATE: at, GIT_COMMITTER_DATE: at }),
-    })
+    }))
         .toString("utf8")
         .trim();
     assertOid(commit, "written Git commit");
     return commit;
 }
-export function writeCommit(input) {
-    return writeCommitObject({
+export async function writeCommit(input) {
+    return await writeCommitObject({
         repository: input.repository,
         tree: input.tree,
         parents: input.parent === null ? [] : [input.parent],
@@ -413,7 +480,23 @@ export function writeCommit(input) {
         ...(input.at === undefined ? {} : { at: input.at }),
     });
 }
-export function updateRefsAtomically(repository, updates) {
+function refAssertionLine(assertion) {
+    assertAssertionRef(assertion.ref);
+    assertOid(assertion.oid, `expected oid for ${assertion.ref}`);
+    return `${assertion.ref === "HEAD" ? "" : "option no-deref\n"}verify ${assertion.ref} ${assertion.oid}`;
+}
+function refUpdateLine(update, index) {
+    assertRef(update.ref);
+    if (index > 0 && update.ref === GIT_REF)
+        throw new Error(`duplicate ref update: ${update.ref}`);
+    if (index > 0 && update.expectedOid === null)
+        throw new Error("target ref updates require non-null OIDs");
+    assertOid(update.newOid, `new oid for ${update.ref}`);
+    if (update.expectedOid !== null)
+        assertOid(update.expectedOid, `expected oid for ${update.ref}`);
+    return `option no-deref\nupdate ${update.ref} ${update.newOid} ${update.expectedOid ?? "0".repeat(update.newOid.length)}`;
+}
+export async function updateRefsAtomically(repository, updates, assertions = []) {
     if (updates.length === 0)
         throw new Error("an atomic ref transaction needs a Git update");
     if (updates.length > 2)
@@ -422,24 +505,16 @@ export function updateRefsAtomically(repository, updates) {
     if (git === undefined || git.ref !== GIT_REF) {
         throw new Error(`the first atomic update must be the Git ref: ${GIT_REF}`);
     }
-    const lines = ["start"];
-    for (const [index, update] of updates.entries()) {
-        assertRef(update.ref);
-        if (index > 0 && update.ref === GIT_REF) {
-            throw new Error(`duplicate ref update: ${update.ref}`);
-        }
-        if (index > 0 && (update.newOid === null || update.expectedOid === null)) {
-            throw new Error("target ref updates require non-null OIDs");
-        }
-        assertOid(update.newOid, `new oid for ${update.ref}`);
-        if (update.expectedOid !== null)
-            assertOid(update.expectedOid, `expected oid for ${update.ref}`);
-        const expectedOid = update.expectedOid ?? "0".repeat(update.newOid.length);
-        lines.push(`update ${update.ref} ${update.newOid} ${expectedOid}`);
-    }
-    lines.push("prepare", "commit", "");
+    const lines = [
+        "start",
+        ...assertions.map(refAssertionLine),
+        ...updates.map(refUpdateLine),
+        "prepare",
+        "commit",
+        "",
+    ];
     try {
-        runGit(repository, ["update-ref", "--stdin", "--no-deref"], lines.join("\n"));
+        await runGit(repository, ["update-ref", "--stdin"], lines.join("\n"));
         return { kind: "published" };
     }
     catch (error) {
@@ -454,3 +529,34 @@ export function updateRefsAtomically(repository, updates) {
         throw error;
     }
 }
+export function decodeGitNumstat(output) {
+    const fields = output.toString("utf8").split("\0");
+    if (fields.at(-1) !== "")
+        throw new Error("Git numstat output is not NUL terminated");
+    let filesChanged = 0;
+    let insertions = 0;
+    let deletions = 0;
+    for (let index = 0; index < fields.length - 1; index += 1) {
+        const field = fields[index];
+        const [added, deleted, path, extra] = field.split("\t");
+        if (added === undefined || deleted === undefined || path === undefined || extra !== undefined) {
+            throw new Error("Git numstat output is malformed");
+        }
+        if (path.length === 0) {
+            if (fields[index + 1] === undefined || fields[index + 2] === undefined) {
+                throw new Error("Git rename numstat output is missing paths");
+            }
+            index += 2;
+        }
+        filesChanged += 1;
+        insertions += added === "-" ? 0 : Number.parseInt(added, 10);
+        deletions += deleted === "-" ? 0 : Number.parseInt(deleted, 10);
+    }
+    return { filesChanged, insertions, deletions };
+}
+export function decodeGitNameOnly(output) {
+    const names = output.toString("utf8").split("\0");
+    if (names.at(-1) !== "")
+        throw new Error("Git name-only output is not NUL terminated");
+    return names.slice(0, -1);
+}

package/build/src/git/scratch.d.ts

@@ -0,0 +1,17 @@
+import type { SnapshotId } from "../core/facts/types.js";
+import { type GitRepository } from "./repository.js";
+export type MaterializedScratchCandidate = Readonly<{
+    cwd: string;
+    dispose: () => Promise<WorktreeLeak | null>;
+}>;
+export type CollectableScratchWorktree = Readonly<{
+    path: string;
+    release(): void;
+}>;
+export type WorktreeLeak = Readonly<{
+    path: string;
+    diagnostic: string;
+}>;
+export declare function collectableScratchWorktrees(paths: Iterable<string>): Promise<readonly CollectableScratchWorktree[]>;
+/** Materialize a disposable candidate worktree and own only its removal. */
+export declare function materializeScratchCandidate(repository: GitRepository, candidate: SnapshotId): Promise<MaterializedScratchCandidate>;

package/build/src/git/scratch.js

@@ -0,0 +1,73 @@
+import { randomBytes } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
+import { gitObjectIdForSnapshot } from "./identity.js";
+import { runGit } from "./repository.js";
+const SCRATCH_PREFIX = "keiyaku-v4-verify-";
+const SCRATCH_ROOT = await realpath(tmpdir());
+const SCRATCH_PATTERN = /^keiyaku-v4-verify-([0-9a-f]{24})$/;
+function scratchPath() {
+    return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${randomBytes(12).toString("hex")}`);
+}
+function ownershipLockPath(path) {
+    if (dirname(path) !== SCRATCH_ROOT)
+        return null;
+    const match = SCRATCH_PATTERN.exec(basename(path));
+    return match === null ? null : join(SCRATCH_ROOT, `.${SCRATCH_PREFIX}${match[1]}.owner.sqlite`);
+}
+export async function collectableScratchWorktrees(paths) {
+    const collectable = [];
+    for (const path of paths) {
+        const lockPath = ownershipLockPath(path);
+        if (lockPath === null)
+            continue;
+        const lock = await tryAcquireSqliteTransactionLock({ path: lockPath, mode: "exclusive" });
+        if (lock !== null)
+            collectable.push({ path, release: () => lock.close() });
+    }
+    return collectable;
+}
+/** Materialize a disposable candidate worktree and own only its removal. */
+export async function materializeScratchCandidate(repository, candidate) {
+    const cwd = scratchPath();
+    const lockPath = ownershipLockPath(cwd);
+    if (lockPath === null)
+        throw new Error("scratch ownership lock path is invalid");
+    const ownership = await tryAcquireSqliteTransactionLock({
+        path: lockPath,
+        mode: "exclusive",
+    });
+    if (ownership === null)
+        throw new Error("new scratch ownership lock is unexpectedly held");
+    try {
+        await runGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
+    }
+    catch (error) {
+        ownership.close();
+        throw error;
+    }
+    let disposed = false;
+    return {
+        cwd,
+        dispose: async () => {
+            if (disposed)
+                return null;
+            disposed = true;
+            try {
+                await runGit(repository, ["worktree", "remove", "--force", cwd]);
+                return null;
+            }
+            catch (error) {
+                return {
+                    path: cwd,
+                    diagnostic: error instanceof Error ? error.message : String(error),
+                };
+            }
+            finally {
+                ownership.close();
+            }
+        },
+    };
+}