@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/git/apply.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `git apply` and `git merge-file` as primitives. The policy around them
+ * (idempotence, the context ladder, conflict handling) belongs to the
+ * caller; this file runs one attempt and reports what git said.
+ */
+import { join } from 'node:path';
+import { makeTempDir, remove, writeFile } from '../kernel/fs.js';
+import { unquoteC } from '../kernel/text.js';
+import { git, gitFailure, gitResult, withPrivateIndex } from './run.js';
+const FAILURE_REASON = /^error: (.+?): (already exists in (?:working directory|index)|does not exist in index|does not match index|No such file or directory|patch does not apply|wrong type|has type .+)$/;
+/** Messages for input that is not a patch git can read: an answer about the patch, not a git failure. */
+const UNREADABLE_PATCH = /corrupt patch|patch fragment without header|garbage|unrecognized input|No valid patches/;
+/**
+ * Reads the files git names in `git apply`'s stderr.
+ *
+ * @param stderr - What git printed
+ */
+export function parseApplyOutput(stderr) {
+    const conflicts = [];
+    const rejected = [];
+    for (const line of stderr.split('\n')) {
+        const failed = /^error: patch failed: (.+):(\d+)$/.exec(line);
+        const reason = FAILURE_REASON.exec(line);
+        const reject = /^Applying patch (.+) with \d+ rejects?\.\.\.$/.exec(line);
+        if (failed)
+            conflicts.push({ path: failed[1] ?? '', reason: 'patch failed', line: Number(failed[2]) });
+        else if (reason)
+            conflicts.push({ path: reason[1] ?? '', reason: reason[2] ?? '' });
+        if (reject?.[1] !== undefined) {
+            const name = reject[1];
+            rejected.push(name.startsWith('"') ? unquoteC(name).toString('utf8') : name);
+        }
+    }
+    return { conflicts, rejected };
+}
+function applyArgs(options, cached) {
+    return [
+        'apply',
+        '--allow-empty',
+        `--whitespace=${options.whitespace ?? 'nowarn'}`,
+        ...(options.check === true ? ['--check'] : []),
+        ...(options.reverse === true ? ['--reverse'] : []),
+        ...(options.reject === true ? ['--reject'] : []),
+        ...(options.context === undefined ? [] : [`-C${options.context}`]),
+        ...(cached ? ['--cached'] : options.target === 'index' ? ['--index'] : []),
+        '-',
+    ];
+}
+/**
+ * Applies a patch once. Not applying is a result (`applied: false`, with the
+ * files git named); only a failure to run git at all throws.
+ *
+ * @param cwd - The repository
+ * @param patch - The patch bytes
+ * @param options - See {@link ApplyOptions}
+ */
+export async function apply(cwd, patch, options = {}) {
+    const target = options.target;
+    const attempt = async (index) => {
+        const args = applyArgs(options, index !== undefined);
+        const result = await gitResult(args, {
+            cwd,
+            input: patch,
+            ...(index !== undefined && { index }),
+        });
+        if (result.exitCode >= 128 && !UNREADABLE_PATCH.test(result.stderr)) {
+            throw gitFailure(args, result, cwd);
+        }
+        const applied = result.exitCode === 0;
+        const tree = applied && index !== undefined && options.check !== true
+            ? (await git(['write-tree'], { cwd, index })).trim()
+            : undefined;
+        return {
+            applied,
+            ...(tree !== undefined && { tree }),
+            ...parseApplyOutput(result.stderr),
+            stderr: result.stderr,
+        };
+    };
+    return typeof target === 'object' ? withPrivateIndex(cwd, target.tree, attempt) : attempt();
+}
+/**
+ * Three-way merges file content (`git merge-file`). Conflicts are marked in
+ * the result with the given labels.
+ *
+ * @param cwd - The repository whose configuration applies
+ * @param input - The common ancestor and the two sides
+ * @param labels - Names for the conflict markers
+ * @returns The merged bytes and how many conflicts they hold
+ */
+export async function mergeFile(cwd, input, labels = {
+    ours: 'ours',
+    base: 'base',
+    theirs: 'theirs',
+}) {
+    const directory = await makeTempDir('fireforge-merge-');
+    try {
+        const files = {
+            ours: join(directory, 'ours'),
+            base: join(directory, 'base'),
+            theirs: join(directory, 'theirs'),
+        };
+        for (const side of ['ours', 'base', 'theirs']) {
+            await writeFile(files[side], input[side], { durable: false });
+        }
+        const args = [
+            'merge-file',
+            '-p',
+            '-L',
+            labels.ours,
+            '-L',
+            labels.base,
+            '-L',
+            labels.theirs,
+            files.ours,
+            files.base,
+            files.theirs,
+        ];
+        const result = await gitResult(args, { cwd });
+        // The exit code is the number of conflicts (at most 127); above that, an error.
+        if (result.exitCode > 127)
+            throw gitFailure(args, result, cwd);
+        return { content: result.stdout, conflicts: result.exitCode };
+    }
+    finally {
+        await remove(directory);
+    }
+}

package/dist/src/git/diff.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The one producer of patch bodies: byte-exact diffs between two trees, and
+ * of a working tree against a commit.
+ *
+ * Output is pinned so the same change gives the same bytes on every host:
+ * `a/`/`b/` prefixes, three lines of context, myers with the indent
+ * heuristic, full blob ids on every `index` line, no rename detection (a
+ * rename is a deletion and an addition), binary files as replayable
+ * `GIT binary patch` sections, no external diff or text conversion.
+ *
+ * A file whose bytes are not valid UTF-8 (a Latin-1 `.properties` file) is
+ * diffed as binary too. Git's own binary test only looks for NUL bytes, so
+ * it would emit such a file as text, and a text section cannot carry those
+ * bytes through anything that decodes it. The result is that every diff
+ * from here is valid UTF-8 unless the repository's own attributes force a
+ * file to be text.
+ */
+import { isUtf8 } from 'node:buffer';
+import { join } from 'node:path';
+import { makeTempDir, remove, writeFile } from '../kernel/fs.js';
+import { captureWorktree, emptyTree, readBlobs } from './objects.js';
+import { resolveRevision } from './repo.js';
+import { chunkPaths, git, GIT_NULL, gitBytes, listPaths } from './run.js';
+const DIFF_FORMAT = [
+    '-p',
+    '--binary',
+    '--full-index',
+    '--no-renames',
+    '--no-ext-diff',
+    '--no-textconv',
+    '--no-color',
+    '--no-relative',
+    '--src-prefix=a/',
+    '--dst-prefix=b/',
+    '--unified=3',
+    '--inter-hunk-context=0',
+    '--diff-algorithm=myers',
+    '--indent-heuristic',
+    `-O${GIT_NULL}`,
+];
+/**
+ * A gitattributes pattern matching exactly one path: anchored, C-quoted, with
+ * glob characters escaped. One pass keyed on the source character, so a
+ * backslash in the name is escaped for both the glob and the quoting layer.
+ */
+function literalAttributePattern(path) {
+    const escaped = path.replace(/["\\*?[\]]/g, (char) => {
+        if (char === '"')
+            return '\\"';
+        if (char === '\\')
+            return '\\\\\\\\';
+        return `\\\\${char}`;
+    });
+    return `"/${escaped}"`;
+}
+async function runDiffTree(cwd, from, to, paths, config = {}) {
+    const args = ['diff-tree', '-r', ...DIFF_FORMAT, from, to];
+    if (paths === undefined)
+        return gitBytes(args, { cwd, config });
+    const sorted = [...paths].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+    const chunks = [];
+    for (const chunk of chunkPaths(sorted))
+        chunks.push(await gitBytes([...args, '--', ...chunk], { cwd, config }));
+    return Buffer.concat(chunks);
+}
+/** Changed paths between two trees one of whose versions is not valid UTF-8. */
+async function nonUtf8Paths(cwd, from, to, paths) {
+    const changed = await listPaths(['diff-tree', '-r', '--no-renames', '--name-only', '-z', from, to], paths, { cwd });
+    const blobs = await readBlobs(cwd, changed.flatMap((path) => [`${from}:${path}`, `${to}:${path}`]));
+    return changed.filter((path) => [`${from}:${path}`, `${to}:${path}`].some((spec) => {
+        const bytes = blobs.get(spec);
+        return bytes !== undefined && !isUtf8(bytes);
+    }));
+}
+/**
+ * The diff from one tree to another, in the pinned format.
+ *
+ * @param cwd - The repository holding both trees
+ * @param from - The old tree-ish
+ * @param to - The new tree-ish
+ * @param options - `paths` limits the diff
+ * @returns The patch bytes; empty when the trees agree
+ */
+export async function diffTrees(cwd, from, to, options = {}) {
+    const output = await runDiffTree(cwd, from, to, options.paths);
+    if (isUtf8(output))
+        return output;
+    const binary = await nonUtf8Paths(cwd, from, to, options.paths);
+    if (binary.length === 0)
+        return output;
+    const directory = await makeTempDir('fireforge-attributes-');
+    try {
+        const attributes = join(directory, 'attributes');
+        await writeFile(attributes, binary.map((path) => `${literalAttributePattern(path)} -diff\n`).join(''), { durable: false });
+        return await runDiffTree(cwd, from, to, options.paths, { 'core.attributesFile': attributes });
+    }
+    finally {
+        await remove(directory);
+    }
+}
+/**
+ * The diff of a working tree against a commit: tracked changes, deletions
+ * and untracked files (ignored ones only when named outright), directories
+ * expanded. Computed through a private index, so the repository's index
+ * does not move.
+ *
+ * @param cwd - The repository
+ * @param options - `paths` limits the diff; `base` (default `HEAD`; an
+ *   unborn HEAD is the empty tree)
+ * @returns The patch bytes; empty when nothing changed
+ */
+export async function diffWorktree(cwd, options = {}) {
+    const base = options.base === undefined
+        ? ((await resolveRevision(cwd, 'HEAD', 'tree')) ?? (await emptyTree(cwd)))
+        : (await git(['rev-parse', '--verify', '--end-of-options', `${options.base}^{tree}`], {
+            cwd,
+        })).trim();
+    const tree = await captureWorktree(cwd, {
+        base,
+        ...(options.paths !== undefined && { paths: options.paths }),
+    });
+    return diffTrees(cwd, base, tree);
+}
+/**
+ * The paths that differ between two tree-ishes, or between a tree-ish and
+ * the working tree (untracked files aside) when `to` is omitted.
+ *
+ * @param cwd - The repository
+ * @param from - The old tree-ish
+ * @param to - The new tree-ish
+ */
+export async function changedPaths(cwd, from, to) {
+    const args = [
+        'diff',
+        '--name-only',
+        '--no-renames',
+        '-z',
+        from,
+        ...(to === undefined ? [] : [to]),
+    ];
+    return (await listPaths(args, undefined, { cwd })).sort();
+}

package/dist/src/git/index.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Git, for the whole tool. Nothing else runs git.
+ *
+ * Every function takes the repository's directory first (its top level, or
+ * a bare repository's directory) and runs git hermetically: host and user
+ * configuration are ignored, output-affecting settings are pinned,
+ * pathspecs are literal, parent directories are never searched, and reading
+ * never writes the index (`run.ts`). Paths are repository-relative with
+ * forward slashes. Failures are `FireForgeError`s with exit code
+ * `GIT_ERROR` and codes `git-failed`, `git-not-a-repository`,
+ * `git-index-locked`, `git-path-encoding` and `git-invalid-spec`, git's
+ * stderr in the message and the cause.
+ *
+ * Operations that build something without touching the user's state
+ * (trees, snapshots, dry-run applies, diffs of a working tree) use a private
+ * index; {@link withPrivateIndex} is the same tool for a caller's own
+ * sequence of plumbing.
+ */
+// Running git
+export { git, gitBytes, gitResult, withPrivateIndex } from './run.js';
+// Repositories, revisions, configuration, worktrees
+export { cloneRepository, currentBranch, fetchCommit, getConfig, gitDir, initRepository, isAncestor, isRepository, listWorktrees, mergeBase, objectFormat, resolveRevision, setConfig, } from './repo.js';
+// The working tree
+export { checkAttributes, checkIgnore, cleanPaths, isTracked, listFiles, reset, restorePaths, status, } from './status.js';
+// Objects
+export { captureWorktree, commitTree, emptyTree, listTree, readBlobs, writeBlobs, writeTree, } from './objects.js';
+// Refs and recovery snapshots
+export { listRefs, RECOVERY_REF_PREFIX, saveRecoverySnapshot, updateRef } from './refs.js';
+// Patch bodies
+export { changedPaths, diffTrees, diffWorktree } from './diff.js';
+// Applying and merging
+export { apply, mergeFile } from './apply.js';

package/dist/src/git/objects.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** Objects: reading and writing blobs, listing and building trees, committing them. */
+import { join } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { makeTempDir, pathInfo, remove, writeFile } from '../kernel/fs.js';
+import { objectFormat, resolveRevision } from './repo.js';
+import { git, gitBytes, listPaths, withPrivateIndex } from './run.js';
+/** Blob specs per `cat-file --batch` process, which bounds one read's memory. */
+const BLOB_BATCH = 500;
+/**
+ * Reads many blobs through one `git cat-file --batch` per batch.
+ *
+ * @param cwd - The repository
+ * @param specs - Blob ids or `revision:path` specs
+ * @returns Content by spec; a spec that names no blob is absent
+ */
+export async function readBlobs(cwd, specs) {
+    const blobs = new Map();
+    const unique = [...new Set(specs)];
+    if (unique.some((spec) => spec.includes('\n'))) {
+        throw new FireForgeError('git-invalid-spec', 'A blob spec cannot contain a line break.', {
+            exitCode: ExitCode.GIT_ERROR,
+        });
+    }
+    for (let start = 0; start < unique.length; start += BLOB_BATCH) {
+        const batch = unique.slice(start, start + BLOB_BATCH);
+        const output = await gitBytes(['cat-file', '--batch'], { cwd, input: `${batch.join('\n')}\n` });
+        let offset = 0;
+        for (const spec of batch) {
+            const end = output.indexOf(0x0a, offset);
+            if (end === -1)
+                break;
+            // `<id> <type> <size>`, or `<spec> missing` / `<spec> ambiguous` with no body.
+            const match = /^[0-9a-f]+ (\w+) (\d+)$/.exec(output.toString('utf8', offset, end));
+            offset = end + 1;
+            if (!match)
+                continue;
+            const size = Number(match[2]);
+            if (match[1] === 'blob')
+                blobs.set(spec, Buffer.from(output.subarray(offset, offset + size)));
+            offset += size + 1;
+        }
+    }
+    return blobs;
+}
+/**
+ * Stores bytes as blobs, exactly as given (no filters, no line-ending conversion).
+ *
+ * @param cwd - The repository
+ * @param contents - The blobs' bytes
+ * @returns Their ids, in input order
+ */
+export async function writeBlobs(cwd, contents) {
+    if (contents.length === 0)
+        return [];
+    const directory = await makeTempDir('fireforge-blobs-');
+    try {
+        const files = contents.map((_, index) => join(directory, String(index)));
+        for (const [index, file] of files.entries()) {
+            await writeFile(file, contents[index] ?? new Uint8Array(), { durable: false });
+        }
+        const output = await git(['hash-object', '-w', '--no-filters', '--stdin-paths'], {
+            cwd,
+            input: `${files.join('\n')}\n`,
+        });
+        return output.trim().split('\n');
+    }
+    finally {
+        await remove(directory);
+    }
+}
+/**
+ * Lists a tree's entries, by default recursively (files only).
+ *
+ * @param cwd - The repository
+ * @param treeish - A tree, commit or ref
+ * @param options - `paths` limits the listing; `recursive: false` lists one level
+ */
+export async function listTree(cwd, treeish, options = {}) {
+    const args = ['ls-tree', '-z', '--full-tree', ...(options.recursive === false ? [] : ['-r'])];
+    const records = await listPaths([...args, treeish], options.paths, { cwd });
+    return records
+        .flatMap((record) => {
+        const [, mode = '', type, oid = '', path = ''] = /^(\d+) (blob|tree|commit) ([0-9a-f]+)\t(.*)$/s.exec(record) ?? [];
+        return type === 'blob' || type === 'tree' || type === 'commit'
+            ? [{ mode, type, oid, path }]
+            : [];
+    })
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/**
+ * Writes a tree object: `base` (or nothing) with `edits` applied. Content is
+ * stored as given. Built in a private index; nothing in the repository's
+ * index or working tree moves.
+ *
+ * @param cwd - The repository
+ * @param edits - Files to add, replace or remove
+ * @param base - Tree-ish to start from, or undefined for an empty tree
+ * @returns The tree's id
+ */
+export async function writeTree(cwd, edits, base) {
+    const contents = edits.flatMap((edit) => ('content' in edit ? [edit.content] : []));
+    const oids = await writeBlobs(cwd, contents);
+    const zero = '0'.repeat((await objectFormat(cwd)) === 'sha256' ? 64 : 40);
+    let next = 0;
+    const records = edits.map((edit) => {
+        if ('remove' in edit)
+            return `0 ${zero}\t${edit.path}\0`;
+        if ('oid' in edit)
+            return `${edit.mode} ${edit.oid}\t${edit.path}\0`;
+        return `${edit.mode ?? '100644'} ${oids[next++] ?? ''}\t${edit.path}\0`;
+    });
+    return withPrivateIndex(cwd, base, async (index) => {
+        if (records.length > 0) {
+            await git(['update-index', '-z', '--index-info'], { cwd, index, input: records.join('') });
+        }
+        return (await git(['write-tree'], { cwd, index })).trim();
+    });
+}
+/** The files whose working-tree state differs from `base` under `paths`. */
+async function changedFiles(cwd, base, options) {
+    const found = new Set();
+    const add = (paths) => {
+        for (const path of paths)
+            found.add(path);
+    };
+    const scope = options.paths;
+    add(base === undefined
+        ? await listPaths(['ls-files', '-z', '--cached'], scope, { cwd })
+        : await listPaths(['diff', '--name-only', '--no-renames', '-z', base], scope, { cwd }));
+    const others = options.includeIgnored === true ? ['--others'] : ['--others', '--exclude-standard'];
+    add(await listPaths(['ls-files', '-z', ...others], scope, { cwd }));
+    // A file named outright is captured even when ignore rules match it.
+    for (const path of scope ?? []) {
+        const kind = (await pathInfo(join(cwd, path)))?.kind;
+        if (kind === 'file' || kind === 'symlink')
+            found.add(path);
+    }
+    return [...found];
+}
+/**
+ * Writes a tree of the working tree's current state: `base` with every
+ * changed, added and deleted file under `paths` taken from the working
+ * tree. Untracked files are included, ignored ones only when asked or named
+ * outright. Built in a private index; the repository's index, HEAD and
+ * branches do not move.
+ *
+ * @param cwd - The repository
+ * @param options - See {@link CaptureOptions}
+ * @returns The tree's id
+ */
+export async function captureWorktree(cwd, options = {}) {
+    const base = options.base === undefined
+        ? await resolveRevision(cwd, 'HEAD', 'tree')
+        : (options.base ?? undefined);
+    const files = await changedFiles(cwd, base, options);
+    return withPrivateIndex(cwd, base, async (index) => {
+        if (files.length > 0) {
+            await git(['update-index', '--add', '--remove', '-z', '--stdin'], {
+                cwd,
+                index,
+                input: files.map((path) => `${path}\0`).join(''),
+            });
+        }
+        return (await git(['write-tree'], { cwd, index })).trim();
+    });
+}
+/**
+ * Creates a commit object for a tree. No ref moves; see {@link updateRef}.
+ *
+ * @param cwd - The repository
+ * @param tree - The tree's id
+ * @param options - See {@link CommitOptions}
+ * @returns The commit's id
+ */
+export async function commitTree(cwd, tree, options) {
+    const { name, email } = options.identity ?? { name: 'FireForge', email: 'fireforge@localhost' };
+    const dated = options.date === undefined
+        ? {}
+        : { GIT_AUTHOR_DATE: options.date, GIT_COMMITTER_DATE: options.date };
+    const parents = (options.parents ?? []).flatMap((parent) => ['-p', parent]);
+    const output = await git(['commit-tree', tree, ...parents, '-m', options.message], {
+        cwd,
+        env: {
+            GIT_AUTHOR_NAME: name,
+            GIT_AUTHOR_EMAIL: email,
+            GIT_COMMITTER_NAME: name,
+            GIT_COMMITTER_EMAIL: email,
+            ...dated,
+        },
+    });
+    return output.trim();
+}
+/**
+ * The id of the empty tree, written so it exists in the repository.
+ *
+ * @param cwd - The repository
+ */
+export async function emptyTree(cwd) {
+    return (await git(['mktree'], { cwd, input: '' })).trim();
+}

package/dist/src/git/refs.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** Refs: moving them safely, listing them, and the recovery snapshots kept under them. */
+import { randomId } from '../kernel/hash.js';
+import { captureWorktree, commitTree } from './objects.js';
+import { resolveRevision } from './repo.js';
+import { git, gitFailure, gitResult } from './run.js';
+/**
+ * Points a ref at an object, or deletes it. With `expect`, the change is a
+ * compare-and-swap: it happens only if the ref still holds `expect` (`null`:
+ * only if the ref does not exist yet), so two writers cannot both win.
+ *
+ * @param cwd - The repository
+ * @param ref - The full ref name (`refs/fireforge/verified`)
+ * @param value - The object id, or null to delete the ref
+ * @param options - `expect`
+ * @returns False when `expect` did not hold and nothing changed
+ */
+export async function updateRef(cwd, ref, value, options = {}) {
+    const { expect } = options;
+    const zero = '0'.repeat(value?.length ?? expect?.length ?? 40);
+    const old = expect === undefined ? [] : [expect ?? zero];
+    const args = value === null ? ['update-ref', '-d', ref, ...old] : ['update-ref', ref, value, ...old];
+    const result = await gitResult(args, { cwd });
+    if (result.exitCode === 0)
+        return true;
+    if (expect !== undefined && (await resolveRevision(cwd, ref)) !== (expect ?? undefined)) {
+        return false;
+    }
+    throw gitFailure(args, result, cwd);
+}
+/**
+ * The refs under a prefix with the objects they point at, sorted by name.
+ *
+ * @param cwd - The repository
+ * @param prefix - A ref prefix (`refs/fireforge/recovery/`)
+ */
+export async function listRefs(cwd, prefix) {
+    const output = await git(['for-each-ref', '--format=%(objectname) %(refname)', '--', prefix], {
+        cwd,
+    });
+    return output
+        .split('\n')
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const space = line.indexOf(' ');
+        return { oid: line.slice(0, space), ref: line.slice(space + 1) };
+    })
+        .sort((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
+}
+/** Where recovery snapshots live. */
+export const RECOVERY_REF_PREFIX = 'refs/fireforge/recovery/';
+/**
+ * Saves the working tree's current state (tracked changes and untracked
+ * files, not ignored ones) as a commit on HEAD under
+ * `refs/fireforge/recovery/<time>-<label>`, before an operation that would
+ * destroy it. Built in a private index, so the repository's index, HEAD and
+ * branches do not move. Older snapshots beyond `keep` are deleted.
+ *
+ * @param cwd - The repository
+ * @param options - See {@link RecoveryOptions}
+ * @returns The snapshot, or undefined when the paths equal HEAD and there is nothing to lose
+ */
+export async function saveRecoverySnapshot(cwd, options) {
+    const head = await resolveRevision(cwd, 'HEAD', 'commit');
+    const headTree = head === undefined ? undefined : await resolveRevision(cwd, head, 'tree');
+    const tree = await captureWorktree(cwd, {
+        base: headTree ?? null,
+        ...(options.paths !== undefined && { paths: options.paths }),
+    });
+    if (tree === headTree)
+        return undefined;
+    const commit = await commitTree(cwd, tree, {
+        message: `fireforge recovery snapshot before ${options.label}`,
+        parents: head === undefined ? [] : [head],
+    });
+    const stamp = new Date().toISOString().replace(/[-:.]/g, '').toLowerCase();
+    const label = options.label.replace(/[^a-z0-9]+/gi, '-').toLowerCase();
+    const ref = `${RECOVERY_REF_PREFIX}${stamp}-${label}-${randomId().slice(0, 8)}`;
+    await updateRef(cwd, ref, commit, { expect: null });
+    const snapshots = await listRefs(cwd, RECOVERY_REF_PREFIX);
+    for (const stale of snapshots.slice(0, Math.max(0, snapshots.length - (options.keep ?? 20)))) {
+        await updateRef(cwd, stale.ref, null);
+    }
+    return { ref, commit };
+}