@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/source/materialize.js

@@ -0,0 +1,382 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Materialization: bringing an engine checkout of the pristine commit to
+ * exactly pristine plus the checkout's owned files, writing only what
+ * differs. It runs before every build and test, so an unchanged run reads
+ * no file content: the ledger remembers each owned file's signature (size,
+ * mtime, ctime and inode) and what was written for it. A signature vouches
+ * for content only for a file last modified well before the run that
+ * recorded it started, so an edit within the same timestamp tick is never
+ * mistaken for no edit; the ctime and inode catch a file replaced or
+ * rewritten with its mtime preserved.
+ *
+ * Ownership rule. Materialization owns exactly two sets of engine paths:
+ * the paths its ledger records (what it wrote last time) and the paths the
+ * checkout owns now. Every other engine path, including the build's output
+ * and files other steps deploy after it (Furnace components), is never
+ * read or written. Within its paths it changes an engine file only when the
+ * file holds an image it can account for: what the ledger says it wrote,
+ * what a later step deployed on top of that ({@link recordDeployment}), or,
+ * for a path the ledger does not record, the pristine bytes (or absence,
+ * for a path upstream lacks). Anything else is drift someone else made; it
+ * is reported and nothing is changed.
+ *
+ * The engine writes and the ledger update run as one journal transaction,
+ * so an error, a signal or a crash leaves the old state or the new one. An
+ * interrupted run is undone before the next one looks at the engine.
+ */
+import { join } from 'node:path';
+import { listTree, objectFormat, resolveRevision } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { listDir, pathInfo, readBytes, walkFiles, writeFile } from '../kernel/fs.js';
+import { recoverJournal, transaction } from '../kernel/journal.js';
+import { readJsonIfExists, stringifyJson } from '../kernel/json.js';
+import { s } from '../kernel/schema.js';
+import { blobId, readPristineBlobs } from './objects.js';
+import { compareText } from './records.js';
+import { readSourceTree } from './tree.js';
+const signatureSchema = s.object({
+    size: s.int({ min: 0 }),
+    mtimeMs: s.number(),
+    ctimeMs: s.number(),
+    ino: s.number(),
+});
+const ledgerSchema = s.object({
+    pristineCommit: s.string(),
+    /** When the run that wrote the ledger started reading files, in epoch milliseconds. */
+    readAt: s.number(),
+    files: s.record(s.object({
+        /** What materialization left at the path; null for a deletion. */
+        blob: s.union(s.string(), s.literal(null)),
+        mode: s.enum(['100644', '100755']),
+        /** The engine file's signature as last seen. */
+        engine: signatureSchema.optional(),
+        /** The owned file's signature when `blob` was read from it. */
+        source: signatureSchema.optional(),
+        /** The blob a later step (a component deployment) left at the path over `blob`. */
+        deployed: s.string().optional(),
+    })),
+});
+const LEDGER = 'source-ledger.json';
+const JOURNAL = 'source-materialize.journal';
+/**
+ * How much older than the reading run a file's timestamps must be before its
+ * signature vouches for its content: the coarsest timestamp granularity in use
+ * (FAT keeps two seconds).
+ */
+const RACY_MS = 2_000;
+/** The facts about a file that stand in for reading it. */
+function signatureOf(file) {
+    return { size: file.size, mtimeMs: file.mtimeMs, ctimeMs: file.ctimeMs, ino: file.ino };
+}
+function sameImage(a, b) {
+    return a === null || b === null ? a === b : a.blob === b.blob && a.mode === b.mode;
+}
+/** Whether a recorded signature still vouches for the content it was recorded with. */
+function vouches(recorded, now, readAt) {
+    return (recorded !== undefined &&
+        recorded.size === now.size &&
+        recorded.mtimeMs === now.mtimeMs &&
+        recorded.ctimeMs === now.ctimeMs &&
+        recorded.ino === now.ino &&
+        Math.max(now.mtimeMs, now.ctimeMs) < readAt - RACY_MS);
+}
+const ledgerImage = (entry) => entry.blob === null ? null : { blob: entry.blob, mode: entry.mode };
+const deployedImage = (entry) => entry.deployed === undefined ? undefined : { blob: entry.deployed, mode: entry.mode };
+class Planner {
+    engine;
+    format;
+    previous;
+    /** Owned bytes read while hashing, reused for the write. */
+    bytes = new Map();
+    ledger;
+    constructor(engine, format, previous, next) {
+        this.engine = engine;
+        this.format = format;
+        this.previous = previous;
+        this.ledger = { pristineCommit: next.commit, readAt: next.readAt, files: {} };
+    }
+    /** The image an owned entry supplies, reading the file only when the ledger can vouch for none. */
+    async desired(entry) {
+        if (entry.file === undefined)
+            return null;
+        const known = this.previous.files[entry.path];
+        const signature = signatureOf(entry.file);
+        if (known !== undefined &&
+            known.blob !== null &&
+            vouches(known.source, signature, this.previous.readAt)) {
+            return { blob: known.blob, mode: entry.file.mode };
+        }
+        const bytes = await readBytes(entry.file.absolute);
+        this.bytes.set(entry.path, bytes);
+        return { blob: blobId(bytes, this.format), mode: entry.file.mode };
+    }
+    /** The engine's image at a path, or what is there instead of a file. */
+    async actual(path) {
+        const info = await pathInfo(join(this.engine, path));
+        if (info === undefined)
+            return { image: null };
+        if (info.kind === 'directory')
+            return 'directory';
+        if (info.kind !== 'file')
+            return 'other';
+        const signature = signatureOf(info);
+        const mode = (info.mode & 0o111) !== 0 ? '100755' : '100644';
+        const known = this.previous.files[path];
+        if (known !== undefined &&
+            known.blob !== null &&
+            known.mode === mode &&
+            vouches(known.engine, signature, this.previous.readAt)) {
+            return { image: { blob: known.deployed ?? known.blob, mode }, signature };
+        }
+        const bytes = await readBytes(join(this.engine, path));
+        return { image: { blob: blobId(bytes, this.format), mode }, signature };
+    }
+    record(path, target, entry, engine = {}) {
+        const file = entry?.file;
+        const recorded = {
+            blob: target?.blob ?? null,
+            mode: target?.mode ?? '100644',
+            ...(engine.signature === undefined ? {} : { engine: engine.signature }),
+            ...(file === undefined ? {} : { source: signatureOf(file) }),
+            ...(engine.deployed === undefined ? {} : { deployed: engine.deployed }),
+        };
+        this.ledger.files[path] = recorded;
+    }
+}
+/** Pristine images of paths, from the pristine repository. */
+async function pristineImages(pristine, paths) {
+    const images = new Map(paths.map((path) => [path, null]));
+    if (paths.length === 0)
+        return images;
+    for (const entry of await listTree(pristine.repo, pristine.commit, {
+        paths,
+        recursive: false,
+    })) {
+        if (entry.type === 'blob' && (entry.mode === '100644' || entry.mode === '100755')) {
+            images.set(entry.path, { blob: entry.oid, mode: entry.mode });
+        }
+    }
+    return images;
+}
+function refuseBlocked(tree) {
+    const blocking = tree.problems.filter((problem) => problem.blocking);
+    if (blocking.length === 0)
+        return;
+    throw new FireForgeError('source-invalid', `The owned files cannot be materialized:\n${blocking
+        .map((problem) => `  ${problem.path}: ${problem.message}`)
+        .join('\n')}`, { exitCode: ExitCode.CONFIG_ERROR, hint: 'Run "fireforge verify" and fix what it reports.' });
+}
+async function readLedger(stateDir, pristine) {
+    const ledger = await readJsonIfExists(join(stateDir, LEDGER), ledgerSchema, {
+        code: 'state-invalid',
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: 'Run "fireforge workspace repair" to rebuild the workspace.',
+    });
+    if (ledger !== undefined && ledger.pristineCommit !== pristine.commit) {
+        throw new FireForgeError('materialize-pin-mismatch', `The workspace was materialized for pristine commit ${ledger.pristineCommit}, not ${pristine.commit}.`, { exitCode: ExitCode.CONFIG_ERROR, hint: 'Run "fireforge workspace repair".' });
+    }
+    return ledger;
+}
+/** Plans one path. */
+async function planPath(planner, path, owned, pristine, removing) {
+    const target = owned === undefined ? pristine : owned.image;
+    const known = planner.previous.files[path];
+    const deployed = known === undefined ? undefined : deployedImage(known);
+    const accounted = known === undefined
+        ? [pristine]
+        : [ledgerImage(known), ...(deployed === undefined ? [] : [deployed])];
+    const actual = await planner.actual(path);
+    const entry = owned?.entry;
+    const action = owned !== undefined
+        ? target === null
+            ? 'remove'
+            : 'write'
+        : target === null
+            ? 'remove'
+            : 'restore';
+    if (actual === 'other')
+        return { path, target, action, drift: true, ...(entry && { entry }) };
+    if (actual === 'directory') {
+        // A directory gives way to a file only when everything in it leaves in this run.
+        const inside = await walkFiles(join(planner.engine, path));
+        const clears = target !== null && inside.every((file) => removing.has(`${path}/${file}`));
+        return { path, target, action, drift: !clears, ...(entry && { entry }) };
+    }
+    const signature = actual.signature === undefined ? {} : { signature: actual.signature };
+    if (sameImage(actual.image, target)) {
+        if (owned !== undefined)
+            planner.record(path, target, entry, signature);
+        return { path, target, action: 'keep', drift: false, ...(entry && { entry }) };
+    }
+    // The owned bytes are unchanged and the engine holds what a deployment made of them.
+    if (owned !== undefined &&
+        known !== undefined &&
+        deployed !== undefined &&
+        sameImage(target, ledgerImage(known)) &&
+        sameImage(actual.image, deployed)) {
+        planner.record(path, target, entry, { ...signature, deployed: deployed.blob });
+        return { path, target, action: 'keep', drift: false, ...(entry && { entry }) };
+    }
+    return {
+        path,
+        target,
+        action,
+        drift: !accounted.some((image) => sameImage(actual.image, image)),
+        ...(entry && { entry }),
+    };
+}
+/** Removes the directories a removal left empty, deepest first, up to the engine root. */
+async function emptiedDirectories(engineDir, removed) {
+    const candidates = new Set();
+    for (const path of removed) {
+        const parts = path.split('/');
+        for (let depth = parts.length - 1; depth > 0; depth--)
+            candidates.add(parts.slice(0, depth).join('/'));
+    }
+    const empty = new Set();
+    const ordered = [...candidates].sort((a, b) => b.split('/').length - a.split('/').length);
+    for (const directory of ordered) {
+        const entries = await listDir(join(engineDir, directory));
+        if (entries.every((entry) => empty.has(`${directory}/${entry.name}`)))
+            empty.add(directory);
+    }
+    return ordered.filter((directory) => empty.has(directory));
+}
+/**
+ * Brings an engine checkout of the pristine commit to exactly pristine plus
+ * the checkout's owned files: writes owned files that differ, restores the
+ * pristine bytes of upstream paths no longer owned, deletes tombstoned paths
+ * and created files no longer owned, and keeps executable modes. A run an
+ * earlier process left unfinished is undone first. See the module comment
+ * for which engine paths it may change.
+ *
+ * @param project - A source-mode project
+ * @param pristine - The pinned pristine repository
+ * @param target - The engine and where its ledger and journal live
+ * @throws `source-invalid` when an owned path is undefined, `materialize-drift`
+ *   when an engine file changed outside FireForge, `materialize-pin-mismatch`,
+ *   `materialize-wrong-engine`, and the journal recovery errors
+ */
+export async function materialize(project, pristine, target) {
+    const { engineDir, stateDir } = target;
+    await recoverJournal(join(stateDir, JOURNAL));
+    const readAt = Date.now();
+    const tree = await readSourceTree(project, pristine);
+    refuseBlocked(tree);
+    if ((await resolveRevision(engineDir, 'HEAD', 'commit')) !== pristine.commit) {
+        throw new FireForgeError('materialize-wrong-engine', `${engineDir} is not a checkout of pristine commit ${pristine.commit}.`, { exitCode: ExitCode.GIT_ERROR, hint: 'Run "fireforge workspace repair".' });
+    }
+    const previous = (await readLedger(stateDir, pristine)) ?? {
+        pristineCommit: pristine.commit,
+        readAt: 0,
+        files: {},
+    };
+    const planner = new Planner(engineDir, await objectFormat(pristine.repo), previous, {
+        commit: pristine.commit,
+        readAt,
+    });
+    const owned = new Map();
+    for (const entry of tree.entries)
+        owned.set(entry.path, { entry, image: await planner.desired(entry) });
+    const leaving = Object.keys(previous.files).filter((path) => !owned.has(path));
+    // Owned entries carry their pristine image; a created file has none upstream.
+    const upstream = await pristineImages(pristine, leaving);
+    for (const entry of tree.entries)
+        upstream.set(entry.path, entry.upstream ?? null);
+    const paths = [...new Set([...owned.keys(), ...leaving])].sort(compareText);
+    const targetOf = (path) => {
+        const supplied = owned.get(path);
+        return supplied === undefined ? (upstream.get(path) ?? null) : supplied.image;
+    };
+    const removing = new Set(paths.filter((path) => targetOf(path) === null));
+    const steps = [];
+    for (const path of paths) {
+        steps.push(await planPath(planner, path, owned.get(path), upstream.get(path) ?? null, removing));
+    }
+    const drifted = steps.filter((step) => step.drift);
+    if (drifted.length > 0) {
+        throw new FireForgeError('materialize-drift', `Engine files changed outside FireForge; materialization would overwrite them:\n${drifted
+            .slice(0, 20)
+            .map((step) => `  ${step.path}`)
+            .join('\n')}${drifted.length > 20 ? `\n  and ${drifted.length - 20} more` : ''}`, { hint: 'Save anything you need from them, then run "fireforge workspace repair".' });
+    }
+    return apply(planner, steps, { pristine, engineDir, stateDir });
+}
+async function apply(planner, steps, context) {
+    const { pristine, engineDir, stateDir } = context;
+    const changing = steps.filter((step) => step.action !== 'keep');
+    const ledgerPath = join(stateDir, LEDGER);
+    if (changing.length === 0) {
+        await writeFile(ledgerPath, stringifyJson(planner.ledger, { sortKeys: true }));
+        return { written: [], restored: [], removed: [] };
+    }
+    const restoredBlobs = changing.flatMap((step) => step.action === 'restore' && step.target !== null ? [step.target.blob] : []);
+    const pristineBytes = await readPristineBlobs(pristine, restoredBlobs);
+    const removals = changing
+        .filter((step) => step.target === null)
+        .sort((a, b) => b.path.split('/').length - a.path.split('/').length || compareText(a.path, b.path));
+    const writes = changing.filter((step) => step.target !== null);
+    await transaction(join(stateDir, JOURNAL), 'the materialization', async (tx) => {
+        for (const step of removals)
+            await tx.remove(join(engineDir, step.path));
+        for (const directory of await emptiedDirectories(engineDir, removals.map((step) => step.path))) {
+            await tx.remove(join(engineDir, directory));
+        }
+        for (const step of writes) {
+            const target = join(engineDir, step.path);
+            if ((await pathInfo(target))?.kind === 'directory')
+                await tx.remove(target);
+            const bytes = step.entry === undefined
+                ? pristineBytes.get(step.target?.blob ?? '')
+                : (planner.bytes.get(step.path) ?? (await readBytes(step.entry.file?.absolute ?? '')));
+            await tx.write(target, bytes ?? Buffer.alloc(0), {
+                mode: step.target?.mode === '100755' ? 0o755 : 0o644,
+            });
+        }
+        for (const step of changing) {
+            if (step.entry === undefined)
+                continue;
+            const info = step.target === null ? undefined : await pathInfo(join(engineDir, step.path));
+            planner.record(step.path, step.target, step.entry, info === undefined ? {} : { signature: signatureOf(info) });
+        }
+        await tx.write(ledgerPath, stringifyJson(planner.ledger, { sortKeys: true }));
+    });
+    const pathsOf = (action) => changing.filter((step) => step.action === action).map((step) => step.path);
+    return { written: pathsOf('write'), restored: pathsOf('restore'), removed: pathsOf('remove') };
+}
+/**
+ * Accepts what a step after materialization (a component deployment) wrote
+ * at owned paths of an engine, so the next materialization counts those
+ * bytes as accounted for rather than as drift. Paths the ledger does not
+ * record are not materialization's and are left out.
+ *
+ * @param pristine - The pinned pristine repository
+ * @param target - The engine and where its ledger lives
+ * @param paths - Engine paths the step wrote or removed
+ */
+export async function recordDeployment(pristine, target, paths) {
+    const ledger = await readLedger(target.stateDir, pristine);
+    if (ledger === undefined)
+        return;
+    const format = await objectFormat(pristine.repo);
+    let changed = false;
+    for (const path of paths) {
+        const entry = ledger.files[path];
+        const absolute = join(target.engineDir, path);
+        const info = await pathInfo(absolute);
+        if (entry === undefined || entry.blob === null || info?.kind !== 'file')
+            continue;
+        const blob = blobId(await readBytes(absolute), format);
+        const next = { ...entry, engine: signatureOf(info) };
+        if (blob === entry.blob)
+            delete next.deployed;
+        else
+            next.deployed = blob;
+        ledger.files[path] = next;
+        changed = true;
+    }
+    if (changed) {
+        await writeFile(join(target.stateDir, LEDGER), stringifyJson(ledger, { sortKeys: true }));
+    }
+}

package/dist/src/source/merge.js

@@ -0,0 +1,255 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The merge driver for owned files. Two branches that each first-touch one
+ * upstream file add it on both sides with no common ancestor in the
+ * project's history, so git sees an add/add conflict over the whole file.
+ * `<sourceRoot>/.gitattributes` routes owned files through this driver,
+ * which merges them against the pristine blob the override record names.
+ *
+ * Git hands a driver an empty ancestor both for a path missing from the
+ * ancestor and for a committed empty file, so the driver asks which commit
+ * git took the ancestor from (the `%S` label, Git 2.44 and later) and uses
+ * the pristine blob only when that commit lacks the path. When no single
+ * commit is named (several merge bases, `git am -3`, a stash, an older Git)
+ * the driver merges the empty ancestor as given, which is git's own add/add
+ * conflict.
+ */
+import { join, relative } from 'node:path';
+import { getConfig, git, listTree, mergeFile, readBlobs, resolveRevision, setConfig, } from '../git/index.js';
+import { toError } from '../kernel/errors.js';
+import { readBytes, toPosixPath, writeFile } from '../kernel/fs.js';
+import { parseJson } from '../kernel/json.js';
+import { warn } from '../kernel/log.js';
+import { readPristineBlobs } from './objects.js';
+import { overrideRecordSchema } from './records.js';
+import { layoutOf, recordFile } from './tree.js';
+/** The driver's name in `.gitattributes` and git configuration. */
+export const MERGE_DRIVER = 'fireforge';
+/** The oldest Git that passes the ancestor label `%S` to a merge driver. */
+const LABEL_GIT = [2, 44];
+const ABBREVIATED_ID = '[0-9a-f]{4,64}';
+function isText(bytes) {
+    if (bytes.includes(0))
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Three-way merges content. A side equal to the base yields the other side;
+ * text merges line by line; competing binary edits conflict without markers.
+ *
+ * @param cwd - A repository whose configuration applies to `git merge-file`
+ * @param sides - The base and the two sides
+ * @param labels - Names for the conflict markers
+ */
+export async function mergeContent(cwd, sides, labels) {
+    const { base, ours, theirs } = sides;
+    if (ours.equals(theirs) || theirs.equals(base))
+        return { clean: true, content: ours };
+    if (ours.equals(base))
+        return { clean: true, content: theirs };
+    if (![base, ours, theirs].every(isText))
+        return { clean: false, reason: 'binary' };
+    const merged = await mergeFile(cwd, sides, labels);
+    return merged.conflicts === 0
+        ? { clean: true, content: merged.content }
+        : { clean: false, reason: 'content', markers: merged.content };
+}
+/**
+ * Whether the git on PATH passes the ancestor label to merge drivers.
+ *
+ * @param cwd - Any directory git can run in
+ */
+async function gitPassesAncestorLabel(cwd) {
+    const version = /(\d+)\.(\d+)/.exec(await git(['--version'], { cwd }));
+    const [major, minor] = [Number(version?.[1] ?? 0), Number(version?.[2] ?? 0)];
+    return major > LABEL_GIT[0] || (major === LABEL_GIT[0] && minor >= LABEL_GIT[1]);
+}
+/**
+ * The shell program git runs as the driver. It finds FireForge where the
+ * project installs it (`<project>/node_modules/.bin/fireforge`, in this
+ * worktree or else in the main one), else on PATH, so moving or upgrading
+ * the tool never leaves a stale path behind.
+ * Whatever goes wrong in FireForge, the merge still ends as a conflict with
+ * both sides in it: when the driver fails without writing a result, git's
+ * own text merge writes the conflict markers instead.
+ */
+const DRIVER_SCRIPT = [
+    'd=${1:-.}',
+    'shift',
+    'f=$d/node_modules/.bin/fireforge',
+    '[ -x "$f" ] || f=$(git rev-parse --path-format=absolute --git-common-dir)/../$d/node_modules/.bin/fireforge',
+    '[ -x "$f" ] || f=fireforge',
+    'cp "$2" "$2.fireforge-ours" || exit 1',
+    '"$f" merge-driver run "$@"',
+    's=$?',
+    'if [ $s -ne 0 ] && cmp -s "$2" "$2.fireforge-ours"; then git merge-file -L ours -L base -L theirs "$2" "$1" "$3"; fi',
+    'rm -f "$2.fireforge-ours"',
+    '[ $s -eq 0 ]',
+].join('; ');
+/**
+ * The driver command line this FireForge configures for a project.
+ *
+ * @param project - A source-mode project
+ */
+export function mergeDriverCommand(project) {
+    const { worktree } = layoutOf(project);
+    const dir = toPosixPath(relative(worktree, project.root)) || '.';
+    const quoted = `'${dir.replaceAll("'", `'\\''`)}'`;
+    return `sh -c '${DRIVER_SCRIPT}' fireforge-merge-driver ${quoted} %O %A %B %P %S`;
+}
+/**
+ * Configures the merge driver in the repository's own configuration, shared
+ * by all its worktrees, replacing any other command configured for it.
+ *
+ * @param project - A source-mode project
+ */
+export async function installMergeDriver(project) {
+    const { worktree } = layoutOf(project);
+    const key = `merge.${MERGE_DRIVER}.driver`;
+    const labelSupported = await gitPassesAncestorLabel(worktree);
+    const driver = mergeDriverCommand(project);
+    if ((await getConfig(worktree, key)) === driver) {
+        return { driver, changed: false, labelSupported };
+    }
+    await setConfig(worktree, `merge.${MERGE_DRIVER}.name`, 'FireForge owned source');
+    await setConfig(worktree, key, driver);
+    return { driver, changed: true, labelSupported };
+}
+/** The commit `name` resolves to, or undefined. */
+async function commitOf(worktree, name) {
+    return resolveRevision(worktree, name, 'commit').catch(() => undefined);
+}
+/** The single parent of a commit; a root or merge commit has none. */
+async function parentOf(worktree, name) {
+    const child = await commitOf(worktree, name);
+    if (child === undefined)
+        return undefined;
+    const parents = (await git(['rev-list', '--parents', '-n', '1', child], { cwd: worktree }))
+        .trim()
+        .split(' ')
+        .slice(1);
+    return parents.length === 1 ? parents[0] : undefined;
+}
+/**
+ * The ancestor commit named by git's `%S` label: an abbreviated id for a
+ * merge with one merge base, `parent of <id> (<subject>)` for a cherry-pick
+ * or rebase step, `<id> (<subject>)` for a revert. Other labels name none.
+ */
+async function labelledAncestor(worktree, label) {
+    if (new RegExp(`^${ABBREVIATED_ID}$`).test(label))
+        return commitOf(worktree, label);
+    const picked = new RegExp(`^parent of (${ABBREVIATED_ID}) `).exec(label)?.[1];
+    if (picked !== undefined)
+        return parentOf(worktree, picked);
+    const reverted = new RegExp(`^(${ABBREVIATED_ID}) \\(`).exec(label)?.[1];
+    return reverted === undefined ? undefined : commitOf(worktree, reverted);
+}
+/**
+ * Whether `path` is absent from the commit git's `%S` label names.
+ * Undefined when the label names no single commit or the tree cannot be read.
+ *
+ * @param worktree - The checkout's top directory
+ * @param path - Worktree-relative path
+ * @param label - Git's `%S`
+ */
+export async function ancestorAbsent(worktree, path, label) {
+    const commit = await labelledAncestor(worktree, label);
+    if (commit === undefined)
+        return undefined;
+    try {
+        return (await listTree(worktree, commit, { paths: [path], recursive: false })).length === 0;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The pristine bytes a first touch of an owned file started from, per the record at HEAD. */
+async function firstTouchBase(project, pristine, path) {
+    const layout = layoutOf(project);
+    if (!path.startsWith(`${layout.source}/`))
+        return undefined;
+    const enginePath = path.slice(layout.source.length + 1);
+    const spec = `HEAD:${recordFile(layout, enginePath)}`;
+    const raw = (await readBlobs(layout.worktree, [spec])).get(spec);
+    if (raw === undefined)
+        return undefined;
+    const record = overrideRecordSchema.parse(parseJson(raw.toString('utf8'), { source: spec }), {
+        source: spec,
+    });
+    const [entry] = await listTree(pristine.repo, pristine.commit, {
+        paths: [enginePath],
+        recursive: false,
+    });
+    if (record.base.commit !== pristine.commit ||
+        entry?.oid !== record.base.blob ||
+        entry.mode !== record.base.mode) {
+        throw new Error(`the override record of ${enginePath} is not at the pinned upstream file`);
+    }
+    return (await readPristineBlobs(pristine, [entry.oid])).get(entry.oid);
+}
+/**
+ * Merges one owned file as git's merge driver, leaving the result in the
+ * `ours` file.
+ *
+ * @param project - The source-mode project the file belongs to
+ * @param pristine - Resolves the pinned pristine repository, asked only for a first touch
+ * @param input - What git passed
+ * @returns True for a clean merge, false for a conflict (the driver's exit status)
+ */
+export async function runMergeDriver(project, pristine, input) {
+    const worktree = layoutOf(project).worktree;
+    let ancestor = await readBytes(input.base);
+    if (ancestor.length === 0) {
+        try {
+            const label = input.label ?? '';
+            if (label === '' || label === '%S') {
+                throw new Error('this git does not pass the ancestor label (Git 2.44 or later does)');
+            }
+            const absent = await ancestorAbsent(worktree, input.path, label);
+            if (absent === undefined)
+                throw new Error(`"${label}" names no single ancestor commit`);
+            if (absent)
+                ancestor = (await firstTouchBase(project, await pristine(), input.path)) ?? ancestor;
+        }
+        catch (error) {
+            warn(`No pristine ancestor for ${input.path}: ${toError(error).message}. Merging as add/add.`);
+        }
+    }
+    const merged = await mergeContent(worktree, { base: ancestor, ours: await readBytes(input.ours), theirs: await readBytes(input.theirs) }, { ours: 'ours', base: 'base', theirs: 'theirs' });
+    if (merged.clean)
+        await writeFile(input.ours, merged.content, { durable: false });
+    else if (merged.markers !== undefined) {
+        await writeFile(input.ours, merged.markers, { durable: false });
+    }
+    return merged.clean;
+}
+/** The attributes the source root needs: exact bytes, and this driver. */
+const SOURCE_ATTRIBUTES = ['* -text', `* merge=${MERGE_DRIVER}`];
+/**
+ * The source root's `.gitattributes` with every line of
+ * {@link SOURCE_ATTRIBUTES} present, or undefined when it already has them.
+ *
+ * @param current - The file's text, or undefined when absent
+ */
+export function completedAttributes(current) {
+    const lines = (current ?? '').split('\n').map((line) => line.trim());
+    const missing = SOURCE_ATTRIBUTES.filter((line) => !lines.includes(line));
+    if (missing.length === 0)
+        return undefined;
+    const text = current ?? '';
+    return `${text}${text === '' || text.endsWith('\n') ? '' : '\n'}${missing.join('\n')}\n`;
+}
+/**
+ * The absolute path of the source root's `.gitattributes`.
+ *
+ * @param project - A source-mode project
+ */
+export function attributesFile(project) {
+    return join(project.paths.source, '.gitattributes');
+}