@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/source/objects.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Git objects for the owned changes. Patch bodies are produced by the one
+ * diff generator (`git/diff.ts`) from two trees in one repository: the
+ * upstream side of every owned path and the owned side. Both live in a
+ * private bare repository under the project's state directory, so neither
+ * the checkout's repository nor the read-only pristine repository receives
+ * an object. The store is a cache; deleting it loses nothing.
+ */
+import { join } from 'node:path';
+import { formatPatch, parsePatch } from '../diff/index.js';
+import { diffTrees, git, initRepository, objectFormat, readBlobs, writeBlobs, writeTree, } from '../git/index.js';
+import { invariant } from '../kernel/errors.js';
+import { exists } from '../kernel/fs.js';
+import { hash } from '../kernel/hash.js';
+/**
+ * The git blob id of some bytes, as `git hash-object` computes it.
+ *
+ * @param bytes - The content
+ * @param format - The repository's object format
+ */
+export function blobId(bytes, format) {
+    const header = Buffer.from(`blob ${bytes.length}\0`);
+    return hash(Buffer.concat([header, bytes]), format);
+}
+/**
+ * Reads pristine blobs by id.
+ *
+ * @param pristine - The pristine repository
+ * @param blobs - Blob ids
+ * @throws An internal error when the repository lacks one
+ */
+export async function readPristineBlobs(pristine, blobs) {
+    const found = await readBlobs(pristine.repo, blobs);
+    for (const blob of blobs) {
+        invariant(found.has(blob), () => `the pristine repository holds blob ${blob}`);
+    }
+    return found;
+}
+/**
+ * The private object store of a project, created on first use with the
+ * pristine repository's object format.
+ *
+ * @param tree - The source tree whose project and pristine repository to use
+ */
+async function objectStore(tree) {
+    const store = join(tree.project.paths.stateDir, 'source', 'objects.git');
+    if (!(await exists(join(store, 'HEAD')))) {
+        await initRepository(store, {
+            bare: true,
+            objectFormat: await objectFormat(tree.pristine.repo),
+        });
+    }
+    return store;
+}
+/**
+ * Stores files from disk as blobs, byte for byte.
+ *
+ * @param store - The repository
+ * @param files - Absolute paths
+ * @returns Their blob ids, in input order
+ */
+async function storeFiles(store, files) {
+    if (files.length === 0)
+        return [];
+    const output = await git(['hash-object', '-w', '--no-filters', '--stdin-paths'], {
+        cwd: store,
+        input: `${files.join('\n')}\n`,
+    });
+    return output.trim().split('\n');
+}
+/**
+ * Writes the upstream and owned sides of entries as two trees.
+ *
+ * @param tree - The source tree
+ * @param entries - The entries to include
+ */
+export async function writeDeltaTrees(tree, entries) {
+    const store = await objectStore(tree);
+    const upstream = entries.flatMap((entry) => entry.upstream === undefined ? [] : [{ path: entry.path, ...entry.upstream }]);
+    const contents = await readPristineBlobs(tree.pristine, upstream.map((entry) => entry.blob));
+    const stored = await writeBlobs(store, upstream.map((entry) => contents.get(entry.blob) ?? Buffer.alloc(0)));
+    upstream.forEach((entry, index) => {
+        invariant(stored[index] === entry.blob, () => `blob of ${entry.path} stores under its id`);
+    });
+    const owned = entries.flatMap((entry) => entry.file === undefined ? [] : [{ path: entry.path, ...entry.file }]);
+    const ids = await storeFiles(store, owned.map((entry) => entry.absolute));
+    const before = await writeTree(store, upstream.map((entry) => ({ path: entry.path, oid: entry.blob, mode: entry.mode })));
+    const after = await writeTree(store, owned.map((entry, index) => ({ path: entry.path, oid: ids[index] ?? '', mode: entry.mode })));
+    return { store, before, after };
+}
+/**
+ * The patch section of every changed path between the two trees, keyed by
+ * path, in git's path order. An entry whose owned bytes equal upstream has
+ * no section.
+ *
+ * @param trees - See {@link writeDeltaTrees}
+ */
+export async function diffSections(trees) {
+    const patch = parsePatch(await diffTrees(trees.store, trees.before, trees.after));
+    return new Map(patch.files.map((file) => [file.path, formatPatch({ ...patch, preamble: [], files: [file] })]));
+}

package/dist/src/source/previous.js

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The previous format of a source-mode project's metadata, and its
+ * conversion to the current one. This file is the only place that knows it:
+ *
+ * - override records carried `schemaVersion`, their own `path` and the
+ *   archive digest `base.pin` beside the fields a record holds today;
+ * - `waivers.json` held the lint waivers and size tiers of the patches the
+ *   project was first cut from, each with the paths it covered;
+ * - `policy.json` held a reviewed decision per `patchPolicy.scopeRules`
+ *   entry: `retire` it, or `retain` it as a path scope;
+ * - `cutover-map.json` and `legacy-manifest.json` authenticated the two;
+ * - the merge driver was called `fireforge-authored`.
+ *
+ * Everything here is a pure function of file content. Nothing is guessed: a
+ * file that is neither the current nor the previous format is a problem the
+ * caller reports.
+ */
+import { hash } from '../kernel/hash.js';
+import { isRecord, omitKeys, parseJson } from '../kernel/json.js';
+import { s } from '../kernel/schema.js';
+import { MERGE_DRIVER } from './merge.js';
+import { encodeRecord, overrideRecordSchema } from './records.js';
+/** The merge driver's earlier name in `.gitattributes` and git configuration. */
+export const PREVIOUS_MERGE_DRIVER = 'fireforge-authored';
+/** Files of the metadata root that only the previous format read. */
+export const PREVIOUS_METADATA_FILES = [
+    'waivers.json',
+    'policy.json',
+    'cutover-map.json',
+    'legacy-manifest.json',
+];
+/**
+ * Converts an override record of the previous format to the current bytes.
+ *
+ * @param text - The record file's content
+ * @param path - The engine path the file's location names
+ */
+export function upgradeRecord(text, path) {
+    let value;
+    try {
+        value = parseJson(text);
+    }
+    catch {
+        return { state: 'invalid', problem: 'is not JSON' };
+    }
+    if (overrideRecordSchema.validate(value).ok)
+        return { state: 'current' };
+    if (!isRecord(value) || !isRecord(value['base'])) {
+        return { state: 'invalid', problem: 'is not an override record' };
+    }
+    const { schemaVersion, path: recorded, base, ...rest } = value;
+    if (schemaVersion !== 1) {
+        return { state: 'invalid', problem: `has schemaVersion ${JSON.stringify(schemaVersion)}` };
+    }
+    if (recorded !== path) {
+        return {
+            state: 'invalid',
+            problem: `names path ${JSON.stringify(recorded)}, not the path of its own location`,
+        };
+    }
+    const result = overrideRecordSchema.validate({ ...rest, base: omitKeys(base, 'pin') });
+    if (!result.ok) {
+        const [issue] = result.issues;
+        return {
+            state: 'invalid',
+            problem: `"${issue?.path ?? ''}" ${issue?.message ?? 'is invalid'}`,
+        };
+    }
+    return { state: 'converted', text: encodeRecord(result.value) };
+}
+/**
+ * A source root's `.gitattributes` with the previous merge driver replaced
+ * by the current one, or undefined when it does not name the previous one.
+ *
+ * @param text - The file's content
+ */
+export function upgradeAttributes(text) {
+    const pattern = new RegExp(`(^|\\s)merge=${PREVIOUS_MERGE_DRIVER}(?=\\s|$)`, 'gm');
+    const next = text.replace(pattern, `$1merge=${MERGE_DRIVER}`);
+    return next === text ? undefined : next;
+}
+const ceiling = s.object({
+    rule: s.string({ min: 1 }),
+    max: s.int({ min: 0 }),
+    reason: s.string({ min: 1 }),
+    share: s.enum(['product', 'test']).optional(),
+    meta: s.record(s.unknown()).optional(),
+});
+const waiversSchema = s.object({
+    schemaVersion: s.literal(1),
+    exceptions: s.array(s.object({
+        component: s.string({ min: 1 }),
+        paths: s.array(s.string({ min: 1 })),
+        checks: s.array(s.union(s.string({ min: 1 }), ceiling)),
+        tier: s.literal('branding').optional(),
+        provenance: s.string().optional(),
+    })),
+});
+/**
+ * Reads a `waivers.json`.
+ *
+ * @param text - The file's content
+ * @param source - The file's path, for messages
+ * @throws `migrate-metadata-invalid` (exit code 2) when it is not the previous format
+ */
+export function parsePreviousWaivers(text, source) {
+    const { exceptions } = waiversSchema.parse(parseJson(text, { source }), {
+        source,
+        code: 'migrate-metadata-invalid',
+    });
+    return exceptions.map(({ component, paths, checks, tier }) => ({
+        component,
+        paths,
+        checks,
+        ...(tier === undefined ? {} : { tier }),
+    }));
+}
+const policySchema = s.object({
+    schemaVersion: s.literal(1),
+    status: s.literal('approved'),
+    adr: s.string().optional(),
+    legacyScopeDigest: s.string().optional(),
+    retireCreatedPatchBudgets: s.boolean().optional(),
+    createdPatchBudgetReason: s.string().optional(),
+    scopeRules: s.array(s.object({
+        legacyRule: s.string({ min: 1 }),
+        decision: s.enum(['retire', 'retain']),
+        reason: s.string({ min: 1 }),
+        select: s.array(s.string()).optional(),
+        allow: s.array(s.string()).optional(),
+    })),
+});
+/** JSON with sorted keys and no whitespace, the form the previous format hashed. */
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    return `{${Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+        .join(',')}}`;
+}
+/**
+ * The decision a `policy.json` holds for each scope rule, by the rule's
+ * index. A decision is bound to its rule by a digest of the rule and its
+ * position, so a rule edited since the review has none.
+ *
+ * @param text - The file's content
+ * @param source - The file's path, for messages
+ * @param rules - `patchPolicy.scopeRules` as the previous format wrote them
+ * @throws `migrate-metadata-invalid` (exit code 2) when it is not the previous format
+ */
+export function parseScopeDecisions(text, source, rules) {
+    const policy = policySchema.parse(parseJson(text, { source }), {
+        source,
+        code: 'migrate-metadata-invalid',
+    });
+    return rules.map((rule, index) => {
+        const id = hash(canonical({ index, rule }));
+        const found = policy.scopeRules.find((entry) => entry.legacyRule === id);
+        return found === undefined ? undefined : { decision: found.decision, reason: found.reason };
+    });
+}

package/dist/src/source/records.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Override records and engine paths. An override record at
+ * `<metadataRoot>/overrides/<engine path>.json` is the upstream identity of
+ * one upstream file the project touches: the pristine commit, blob and mode
+ * the touch started from, the component it belongs to, and whether it is an
+ * edit (`override`, with the owned bytes at `<sourceRoot>/<path>`) or an
+ * explicit deletion (`delete`, a tombstone with no owned file).
+ */
+import { posix } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { stringifyJson } from '../kernel/json.js';
+import { s } from '../kernel/schema.js';
+const objectId = s.string({
+    pattern: /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/,
+    format: 'a complete lowercase Git object ID',
+});
+/** Component names: they become patch names on export. */
+export const COMPONENT_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/** The schema of one override record. */
+export const overrideRecordSchema = s
+    .object({
+    kind: s
+        .enum(['override', 'delete'])
+        .describe('override: the owned file replaces upstream; delete: upstream is removed'),
+    base: s
+        .object({
+        commit: objectId.describe('The pristine commit the touch started from'),
+        blob: objectId.describe('The upstream blob at that commit'),
+        mode: s.enum(['100644', '100755']).describe('The upstream mode at that commit'),
+    })
+        .describe('The upstream identity the touch started from'),
+    component: s
+        .string({ pattern: COMPONENT_PATTERN, format: 'a component name such as "ui-sidebar"' })
+        .describe('The component the change belongs to; one exported patch per component'),
+    classification: s
+        .enum(['registration', 'exception'])
+        .describe('registration: wiring an addition in; exception: a reviewed upstream change'),
+    adr: s
+        .string({ pattern: /\S/, format: 'a project-relative path' })
+        .describe('The decision record approving an exception')
+        .optional(),
+})
+    .refine((record) => record.classification === 'exception' && record.adr === undefined
+    ? 'needs "adr" for an exception'
+    : undefined);
+/**
+ * The bytes of a record file: sorted keys, two-space indent, final newline,
+ * so a record is a function of its content.
+ *
+ * @param record - The record
+ */
+export function encodeRecord(record) {
+    return stringifyJson(record, { sortKeys: true });
+}
+/**
+ * The component a path belongs to when none is named: its top directory (or
+ * top-level file), without leading dots or other characters a component name
+ * cannot start with.
+ *
+ * @param path - An engine path
+ */
+export function defaultComponent(path) {
+    const top = (path.split('/')[0] ?? path).replace(/^[^a-zA-Z0-9]+/, '');
+    return top === '' ? 'root' : top;
+}
+/** File names that, under the source root, configure git instead of supplying an engine file. */
+const GIT_CONTROL_NAMES = new Set(['.gitattributes', '.gitignore']);
+/** Top-level engine paths FireForge itself writes. */
+const RESERVED_ENGINE_PATHS = new Set(['mozconfig']);
+/**
+ * Why a valid engine path cannot be owned, or undefined.
+ *
+ * @param path - An engine path
+ */
+export function unownableReason(path) {
+    const name = posix.basename(path);
+    if (GIT_CONTROL_NAMES.has(name)) {
+        return `is named ${name}, which under the source root would configure git for the owned files instead of supplying an engine file`;
+    }
+    return RESERVED_ENGINE_PATHS.has(path) ? 'is written by FireForge' : undefined;
+}
+/**
+ * A path folded as a case-insensitive file system compares it.
+ *
+ * @param path - Any path
+ */
+export function foldCase(path) {
+    return path.normalize('NFC').toLocaleLowerCase('en-US');
+}
+/**
+ * Why a string cannot be an engine path, or undefined: it must be one
+ * canonical relative POSIX spelling with no `.`, `..` or `.git` segment and
+ * no backslash or control character.
+ *
+ * @param path - The candidate
+ */
+export function enginePathProblem(path) {
+    if (path === '' || posix.isAbsolute(path) || /^[A-Za-z]:/.test(path)) {
+        return 'is not a relative path';
+    }
+    if (/[\\\p{Cc}]/u.test(path))
+        return 'holds a backslash or a control character';
+    if (posix.normalize(path) !== path || path.endsWith('/'))
+        return 'is not in canonical form';
+    if (path.split('/').some((part) => part === '.' || part === '..' || foldCase(part) === '.git')) {
+        return 'has a ".", ".." or ".git" segment';
+    }
+    return undefined;
+}
+/**
+ * Refuses a string that is not an engine path.
+ *
+ * @param path - The candidate, as the user typed it
+ * @throws `source-invalid-path` (exit code 8)
+ */
+export function assertEnginePath(path) {
+    const problem = enginePathProblem(path);
+    if (problem !== undefined) {
+        throw new FireForgeError('source-invalid-path', `"${path}" ${problem}.`, {
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            hint: 'Name the file by its engine path, such as browser/base/jar.mn.',
+        });
+    }
+}
+/**
+ * The ancestors of a path, outermost first: `a/b/c` gives `a`, `a/b`.
+ *
+ * @param path - An engine path
+ */
+export function ancestorsOf(path) {
+    const parts = path.split('/');
+    return parts.slice(0, -1).map((_, index) => parts.slice(0, index + 1).join('/'));
+}
+/** Code-unit order, which no locale changes. */
+export function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/src/source/refresh.js

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Moving a source-mode checkout to a new pin, the way `git rebase` moves a
+ * branch: every owned path is three-way merged from the old pristine file
+ * (base), the owned file (ours) and the new pristine file (theirs), and the
+ * result is applied in place to the source root, the override records and
+ * the pin in `fireforge.json`, in one journal transaction. The user reviews
+ * it with `git diff` and undoes it with git.
+ *
+ * A conflict is left the way git leaves one: text conflict markers in the
+ * owned file, and the three versions as unmerged entries in the checkout's
+ * index, so `git status` lists it, `git checkout --ours/--theirs` and
+ * `git add` resolve it, and a commit is refused until then. Records of
+ * conflicted paths already name the new upstream file, so resolving is only
+ * a matter of the owned file's content.
+ */
+import { join, relative } from 'node:path';
+import { setConfigValue } from '../config/index.js';
+import { git, gitDir, listTree, objectFormat, status, writeBlobs, } from '../git/index.js';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { readBytes, toPosixPath } from '../kernel/fs.js';
+import { transaction } from '../kernel/journal.js';
+import { journalOf, withSourceLock } from './edit.js';
+import { mergeContent } from './merge.js';
+import { readPristineBlobs } from './objects.js';
+import { ancestorsOf, compareText, defaultComponent, encodeRecord, } from './records.js';
+import { readSourceTree, recordFile } from './tree.js';
+function same(a, b) {
+    return a === undefined || b === undefined
+        ? a === b
+        : a.mode === b.mode && a.bytes.equals(b.bytes);
+}
+function rebased(record, commit, upstream) {
+    return {
+        ...record,
+        base: { commit, blob: upstream.oid, mode: upstream.mode },
+    };
+}
+function refused(code, message, hint) {
+    return new FireForgeError(code, message, { exitCode: ExitCode.CONFIG_ERROR, hint });
+}
+/** Refuses a refresh that would start from anything but a clean, valid checkout at the old pin. */
+async function assertReady(tree, oldPristine, newPristine) {
+    const { project, layout } = tree;
+    if (project.config.source.pristineCommit !== oldPristine.commit) {
+        throw refused('refresh-pin-mismatch', `The project is pinned to ${project.config.source.pristineCommit}, not ${oldPristine.commit}.`, 'Pass the pristine repository of the current pin as the old one.');
+    }
+    if (newPristine.commit === oldPristine.commit) {
+        throw refused('refresh-pin-unchanged', 'The new pin is the current pin.', 'Name another pin.');
+    }
+    if (tree.problems.length > 0) {
+        throw refused('source-invalid', `The owned files must be valid before a rebase:\n${tree.problems
+            .map((problem) => `  ${problem.path}: ${problem.message}`)
+            .join('\n')}`, 'Run "fireforge verify" and fix what it reports.');
+    }
+    const configFile = toPosixPath(relative(layout.worktree, project.paths.config));
+    const dirty = await status(layout.worktree, {
+        paths: [layout.source, layout.metadata, configFile],
+    });
+    if (dirty.length > 0) {
+        throw refused('refresh-dirty', `The source has uncommitted changes:\n${dirty
+            .slice(0, 20)
+            .map((entry) => `  ${entry.path}`)
+            .join('\n')}`, 'Commit or stash them first, so the rebase can be reviewed and undone with git.');
+    }
+}
+/** New pristine entries of the owned paths, refusing paths the new tree makes impossible. */
+async function newUpstream(tree, newPristine) {
+    const paths = tree.entries.map((entry) => entry.path);
+    const wanted = new Set(paths.flatMap((path) => [path, ...ancestorsOf(path)]));
+    const entries = new Map((await listTree(newPristine.repo, newPristine.commit, { paths: [...wanted], recursive: false })).map((entry) => [entry.path, entry]));
+    const blocked = [];
+    for (const path of paths) {
+        const entry = entries.get(path);
+        const fileAbove = ancestorsOf(path).find((ancestor) => entries.get(ancestor)?.type === 'blob');
+        if (fileAbove !== undefined)
+            blocked.push(`${path}: upstream now has a file at ${fileAbove}`);
+        else if (entry !== undefined && entry.type !== 'blob') {
+            blocked.push(`${path}: upstream now has a directory here`);
+        }
+        else if (entry !== undefined && entry.mode !== '100644' && entry.mode !== '100755') {
+            blocked.push(`${path}: upstream now has an entry of mode ${entry.mode} here`);
+        }
+    }
+    if (blocked.length > 0) {
+        throw refused('refresh-blocked', `The new pin leaves no place for these owned paths:\n${blocked.map((line) => `  ${line}`).join('\n')}`, 'Move or remove them, commit, and rebase again.');
+    }
+    return entries;
+}
+/** The merge of an owned upstream path whose three sides are all present and differ. */
+async function mergeThree(cwd, entry, sides, record) {
+    const { base, ours, theirs } = sides;
+    const mode = ours.mode === theirs.mode
+        ? ours.mode
+        : ours.mode === base.mode
+            ? theirs.mode
+            : theirs.mode === base.mode
+                ? ours.mode
+                : undefined;
+    const merged = await mergeContent(cwd, { base: base.bytes, ours: ours.bytes, theirs: theirs.bytes }, { ours: 'local', base: 'old pristine', theirs: 'new pristine' });
+    const conflict = (reason, bytes) => ({
+        path: entry.path,
+        result: { path: entry.path, outcome: 'conflict', reason },
+        file: { bytes, mode: mode ?? ours.mode },
+        record,
+        stages: sides,
+    });
+    if (!merged.clean)
+        return conflict(merged.reason, merged.markers ?? ours.bytes);
+    if (mode === undefined)
+        return conflict('mode', merged.content);
+    if (same({ bytes: merged.content, mode }, theirs)) {
+        return {
+            path: entry.path,
+            result: { path: entry.path, outcome: 'retired' },
+            file: null,
+            record: null,
+        };
+    }
+    return {
+        path: entry.path,
+        result: { path: entry.path, outcome: 'merged' },
+        file: { bytes: merged.content, mode },
+        record,
+    };
+}
+/** Plans one owned path. */
+async function planEntry(tree, entry, sides, upstream, commit) {
+    const { path } = entry;
+    const { base, ours, theirs } = sides;
+    const retired = { path, result: { path, outcome: 'retired' }, file: null, record: null };
+    if (entry.record === undefined || base === undefined) {
+        if (upstream === undefined || theirs === undefined) {
+            return { path, result: { path, outcome: 'kept' } };
+        }
+        return {
+            path,
+            result: { path, outcome: 'conflict', reason: 'upstream-collision' },
+            record: {
+                kind: 'override',
+                base: { commit, blob: upstream.oid, mode: theirs.mode },
+                component: defaultComponent(path),
+                classification: 'registration',
+            },
+            stages: { base: undefined, ours, theirs },
+        };
+    }
+    const record = upstream === undefined ? null : rebased(entry.record, commit, upstream);
+    if (same(base, theirs))
+        return { path, result: { path, outcome: 'kept' }, record };
+    // Upstream now holds our side, or our side left upstream alone: nothing is left to own.
+    if (same(ours, theirs) || same(base, ours))
+        return retired;
+    if (ours === undefined || theirs === undefined || record === null) {
+        return {
+            path,
+            result: { path, outcome: 'conflict', reason: 'delete-edit' },
+            record,
+            stages: sides,
+        };
+    }
+    return mergeThree(tree.layout.worktree, entry, { base, ours, theirs }, record);
+}
+/** Writes the unmerged index entries of the conflicts. */
+async function writeStages(tree, plans) {
+    const { worktree, source } = tree.layout;
+    const conflicted = plans.filter((plan) => plan.stages !== undefined);
+    if (conflicted.length === 0)
+        return;
+    const zero = '0'.repeat((await objectFormat(worktree)) === 'sha256' ? 64 : 40);
+    const lines = [];
+    for (const plan of conflicted) {
+        const file = `${source}/${plan.path}`;
+        const stages = plan.stages ?? { base: undefined, ours: undefined, theirs: undefined };
+        const present = [stages.base, stages.ours, stages.theirs].flatMap((side, index) => side === undefined ? [] : [{ side, stage: index + 1 }]);
+        const oids = await writeBlobs(worktree, present.map((each) => each.side.bytes));
+        lines.push(`0 ${zero}\t${file}\0`);
+        present.forEach((each, index) => {
+            lines.push(`${each.side.mode} ${oids[index] ?? ''} ${each.stage}\t${file}\0`);
+        });
+    }
+    await git(['update-index', '-z', '--index-info'], { cwd: worktree, input: lines.join('') });
+}
+async function applyPlans(tx, tree, plans) {
+    const { layout, project } = tree;
+    for (const plan of plans) {
+        const file = join(project.paths.source, plan.path);
+        const record = join(layout.worktree, recordFile(layout, plan.path));
+        if (plan.file === null)
+            await tx.remove(file);
+        else if (plan.file !== undefined) {
+            await tx.write(file, plan.file.bytes, { mode: plan.file.mode === '100755' ? 0o755 : 0o644 });
+        }
+        if (plan.record === null)
+            await tx.remove(record);
+        else if (plan.record !== undefined)
+            await tx.write(record, encodeRecord(plan.record));
+    }
+}
+/**
+ * Moves a clean source-mode checkout from the old pin to a new one: merges
+ * every owned path three ways, applies the result to the owned files and
+ * records, and updates `source.pristineCommit` and `firefox` in
+ * `fireforge.json`, all in one transaction. Conflicts are left as git
+ * leaves them (see the module comment).
+ *
+ * @param project - A source-mode project at the old pin with no uncommitted source changes
+ * @param oldPristine - The pristine repository of the current pin
+ * @param newPristine - The pristine repository of the new pin
+ * @param firefox - The new pin's release
+ * @throws `refresh-pin-mismatch`, `refresh-pin-unchanged`, `refresh-dirty`,
+ *   `refresh-blocked`, `source-invalid`
+ */
+export function refreshPin(project, oldPristine, newPristine, firefox) {
+    // Under the source lock, so no other FireForge writer changes an owned file between the read and the merge.
+    return withSourceLock(project, async () => {
+        const tree = await readSourceTree(project, oldPristine);
+        await assertReady(tree, oldPristine, newPristine);
+        const plans = await planRefresh(tree, oldPristine, newPristine);
+        const index = join(await gitDir(tree.layout.worktree), 'index');
+        await transaction(journalOf(project), 'the rebase', async (tx) => {
+            await applyPlans(tx, tree, plans);
+            await tx.change([index], () => writeStages(tree, plans));
+            await tx.change([project.paths.config], async () => {
+                await setConfigValue(project.root, 'source.pristineCommit', newPristine.commit);
+                await setConfigValue(project.root, 'firefox', JSON.stringify(firefox));
+            });
+        });
+        const paths = plans.map((plan) => plan.result);
+        return {
+            paths,
+            conflicts: paths.filter((path) => path.outcome === 'conflict').map((path) => path.path),
+        };
+    });
+}
+/** Plans every owned path of the tree against the new pin. */
+async function planRefresh(tree, oldPristine, newPristine) {
+    const upstream = await newUpstream(tree, newPristine);
+    const oldBlobs = await readPristineBlobs(oldPristine, tree.entries.flatMap((entry) => (entry.upstream === undefined ? [] : [entry.upstream.blob])));
+    const newBlobs = await readPristineBlobs(newPristine, tree.entries.flatMap((entry) => {
+        const found = upstream.get(entry.path);
+        return found === undefined ? [] : [found.oid];
+    }));
+    const plans = [];
+    for (const entry of [...tree.entries].sort((a, b) => compareText(a.path, b.path))) {
+        const found = upstream.get(entry.path);
+        const sides = {
+            base: entry.upstream === undefined
+                ? undefined
+                : {
+                    bytes: oldBlobs.get(entry.upstream.blob) ?? Buffer.alloc(0),
+                    mode: entry.upstream.mode,
+                },
+            ours: entry.file === undefined
+                ? undefined
+                : { bytes: await readBytes(entry.file.absolute), mode: entry.file.mode },
+            theirs: found === undefined
+                ? undefined
+                : { bytes: newBlobs.get(found.oid) ?? Buffer.alloc(0), mode: found.mode },
+        };
+        plans.push(await planEntry(tree, entry, sides, found, newPristine.commit));
+    }
+    return plans;
+}