@hominis/fireforge 0.27.1 → 0.27.3

package/CHANGELOG.md

@@ -1,9 +1,21 @@
 # Changelog
 
+## 0.27.3
+
+- Fixed `firefox-devedition` source downloads so archive resolution uses `/pub/devedition/releases`.
+- Kept existing `engine/` trees intact during `download --force` until the replacement archive downloads, validates, and extracts successfully.
+- Improved checksum mismatch diagnostics with resolved URL and product context.
+
 ## 0.27.0
 
 - Added first-class `firefox-devedition` source support and atomic `fireforge source set`.
+- Fixed `source set --version` so the subcommand accepts both space and equals forms without colliding with the root CLI version flag.
+- Added `sourceProduct` and `sourceVersion` patch metadata while preserving `sourceEsrVersion` as a deprecated compatibility alias.
+- Renamed source-rebase reporting away from ESR-only wording and clarified summaries with total patch counts.
+- Unified status, ownership, doctor, and verify worktree classification, including an explained patch-owned drift state for manually resolved or re-exported files.
+- Hardened build diagnostics so backend regeneration success/failure and failed make/mach commands include exit codes, tails, log hints, and verbose rerun suggestions.
 - Improved `download --force` git indexing progress with phase, count, and heartbeat output.
+- Added cache metadata progress for archive validation, SHA-256 calculation, and sidecar JSON writes.
 - Added elapsed progress for extraction, initial source commits, and rebase/re-export patch refreshes.
 - Added `re-export --files --allow-shrink` so patch ownership shrinkage is refused unless explicitly acknowledged, with clearer dry-run previews.
 - Surfaced likely new sibling files during plain re-export and aligned verify/status ownership reporting for unowned worktree changes.

package/README.md

@@ -11,12 +11,12 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 ## What It Does
 
 - **Patch based** Edit Firefox inside the `engine/` directory, then export changes into `.patch` files with manifest metadata.
-- **ESR rebasing** Reapply your patches onto a newer Firefox source tree, resolve rejects and re-export the queue against the new baseline, hopefully...
+- **Source rebasing** Reapply your patches onto newer Firefox source trees, including ESR, Beta, and Developer Edition archives, resolve rejects and re-export the queue against the new baseline, hopefully...
 - **Firefox source and build helpers** Download, bootstrap, build, run, test, package, smoke-check, etc.
 - **Wiring and registration** Add chrome scripts, DOM fragments, modules, styles, tests and manifest entries through commands built by learning from existing Firefox conventions.
 - **Furnace components** Create or override `MozLitElement` widgets easily to add new or adapt existing UI components to your needs.
 - **Quality** `lint`, `typecheck`, `verify` and `doctor` catch common issues early.
-- **Tests** Fireforge was build by taking apart and applying patches of all sorts to original Firefox ESR source code across different versions, learning what works vs doesn't and creating some quite extensive tests based on that covering all manner of scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally on my MacBook, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Actions will be added soonishlyTM but might need a different runner...
+- **Tests** Fireforge was build by taking apart and applying patches of all sorts to original Firefox source code across different versions and products, learning what works vs doesn't and creating some quite extensive tests based on that covering all manner of scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally on my MacBook, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Actions will be added soonishlyTM but might need a different runner...
 
 ## Requirements
 
@@ -63,9 +63,9 @@ npx fireforge test browser/base/content/test/browser/
 
 Use `fireforge --help` for the full set of commands.
 
-## Rebasing Firefox
+## Rebasing Firefox Source
 
-When Mozilla publishes a new ESR you need to update the configured Firefox version, download the new source code and reapply the patches:
+When Mozilla publishes a new Firefox source release you need to update the configured version/product, download the new source code and reapply the patches:
 
 ```bash
 npx fireforge source set --version 145.0.0esr --product firefox-esr --sha256 <archive-sha256>
@@ -95,7 +95,7 @@ Use `fireforge furnace --help` for the full set of component commands.
 - **Docker builds** Reproducible builds using Docker containers.
 - **CI mode** Automated setup for continuous integration pipelines.
 - **Update manifests** Generate update server manifests for auto-updates.
-- **Nightly support** Requires implementing `hg clone` support via mozilla-central. Currently fireforge only downloads from the archive.
+- **Nightly source support** Requires implementing `hg clone` support via mozilla-central. ESR, Beta, and Developer Edition source archives are supported through `fireforge source set`.
 - **E2E Github Actions** Requires either a higher tier of Githubs offering, an external VPS or another provider entirely. In any case, full end-to-end testing is currently run solely locally.
 
 ## Licence

package/dist/src/cli.js

@@ -154,6 +154,7 @@ function buildGroupedHelpFormatter(manifest) {
             const desc = helper.optionDescription(opt);
             return formatHelpLine(term, desc, termWidth, helpWidth);
         });
+        optionLines.unshift(formatHelpLine('-V, --version', 'output the version number', termWidth, helpWidth));
         if (optionLines.length > 0) {
             output.push('Options:');
             output.push(...optionLines);
@@ -234,7 +235,6 @@ export function createProgram() {
     program
         .name('fireforge')
         .description('A build tool for customizing Firefox')
-        .version(getPackageVersion())
         .option('-v, --verbose', 'Enable debug output')
         .hook('preAction', (thisCommand) => {
         const opts = thisCommand.opts();
@@ -256,6 +256,10 @@ export function createProgram() {
  * Main CLI entry point.
  */
 export async function main() {
+    if (process.argv.length === 3 && (process.argv[2] === '--version' || process.argv[2] === '-V')) {
+        process.stdout.write(`${getPackageVersion()}\n`);
+        return;
+    }
     const program = createProgram();
     await program.parseAsync(process.argv);
 }

package/dist/src/commands/build.js

@@ -69,6 +69,65 @@ function resolveJobCount(options, configJobs) {
     }
     return jobs;
 }
+function tailLines(text, maxLines) {
+    const lines = text
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0);
+    return lines.slice(-maxLines).join('\n');
+}
+function extractLastMakeError(captured) {
+    const lines = captured.split(/\r?\n/).filter((line) => /\bmake(?:\[\d+\])?: \*\*\*/.test(line));
+    return lines.at(-1)?.trim();
+}
+function extractLikelyFailingCommand(captured) {
+    const lines = captured
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    for (let index = lines.length - 1; index >= 0; index--) {
+        const line = lines[index];
+        if (!line)
+            continue;
+        if (/^make(?:\[\d+\])?:/.test(line))
+            continue;
+        if (/^g?make(?:\[\d+\])?:/.test(line))
+            continue;
+        if (/^Error running mach:/.test(line))
+            continue;
+        if (/^\d+:\d+\.\d+\s+/.test(line))
+            continue;
+        if (/\b(?:cp|clang|clang\+\+|rustc|python|node|make|install_name_tool)\b/.test(line)) {
+            return line;
+        }
+    }
+    return undefined;
+}
+function buildFailureDiagnostics(result, engineDir, objDir, machCommand) {
+    const captured = `${result.stderr}\n${result.stdout}`;
+    const stderrTail = tailLines(result.stderr, 20);
+    const combinedTail = tailLines(captured, 30);
+    const makeError = extractLastMakeError(captured);
+    const failingCommand = extractLikelyFailingCommand(captured);
+    const logHint = objDir
+        ? `engine/${objDir}/ (inspect build logs, warnings, and generated make targets under this objdir)`
+        : 'engine/obj-* (inspect the active objdir for build logs, warnings, and generated make targets)';
+    const verboseRerun = objDir
+        ? `cd ${engineDir} && ./mach build -v; if a make target is named above, retry it with: make -C ${objDir} <target> V=1`
+        : `cd ${engineDir} && ./mach build -v`;
+    return [
+        `Build failed with exit code ${result.exitCode}.`,
+        `Mach phase: ${machCommand}`,
+        makeError ? `Last make error: ${makeError}` : undefined,
+        failingCommand ? `Final failing command/error line: ${failingCommand}` : undefined,
+        stderrTail ? `Captured stderr tail:\n${stderrTail}` : undefined,
+        `Captured output tail:\n${combinedTail}`,
+        `Logs/profile/warnings: ${logHint}`,
+        `Verbose rerun: ${verboseRerun}`,
+    ]
+        .filter((part) => part !== undefined && part.length > 0)
+        .join('\n\n');
+}
 /**
  * Runs the build command.
  * @param projectRoot - Root directory of the project
@@ -172,7 +231,8 @@ export async function buildCommand(projectRoot, options) {
     const timeStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
     if (result.exitCode !== 0) {
         error(`Build failed after ${timeStr}`);
-        throw new BuildError(`Build failed with exit code ${result.exitCode}`, options.ui ? 'mach build faster' : 'mach build');
+        const machCommand = options.ui ? 'mach build faster' : 'mach build';
+        throw new BuildError(buildFailureDiagnostics(result, paths.engine, buildCheck.objDir, machCommand), machCommand);
     }
     // Tool-managed branding edits that land on `browser/moz.configure`
     // before the build cause mach's post-build guard to print one of two

package/dist/src/commands/doctor-working-tree.js

@@ -20,6 +20,7 @@ function summarizeWorkingTreeChangeCount(changeCount) {
 function formatManagedDetail(counts) {
     return [
         counts.patchBacked > 0 ? `${counts.patchBacked} patch-backed` : null,
+        counts.patchOwnedDrift > 0 ? `${counts.patchOwnedDrift} patch-owned drift` : null,
         counts.branding > 0 ? `${counts.branding} branding` : null,
         counts.furnace > 0 ? `${counts.furnace} furnace` : null,
     ]
@@ -57,6 +58,7 @@ export async function inspectEngineWorkingTree(ctx) {
         branding: 0,
         furnace: 0,
         patchBacked: 0,
+        patchOwnedDrift: 0,
         conflict: 0,
         unmanaged: 0,
     };
@@ -67,6 +69,8 @@ export async function inspectEngineWorkingTree(ctx) {
             counts.furnace++;
         else if (entry.classification === 'patch-backed')
             counts.patchBacked++;
+        else if (entry.classification === 'patch-owned-drift')
+            counts.patchOwnedDrift++;
         else if (entry.classification === 'conflict')
             counts.conflict++;
         else
@@ -75,7 +79,7 @@ export async function inspectEngineWorkingTree(ctx) {
     if (counts.conflict > 0) {
         return warning('Engine working tree', `Engine working tree has ${counts.conflict} cross-patch ownership conflict${counts.conflict === 1 ? '' : 's'}. Multiple patches in patches.json claim the same file.`, 'Run "fireforge status --ownership" to see the conflicting patches, then run "fireforge verify" and resolve the overlap.');
     }
-    const managedTotal = counts.branding + counts.furnace + counts.patchBacked;
+    const managedTotal = counts.branding + counts.furnace + counts.patchBacked + counts.patchOwnedDrift;
     if (counts.unmanaged === 0) {
         const managedDetail = formatManagedDetail(counts);
         return {

package/dist/src/commands/download.js

@@ -1,4 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { randomUUID } from 'node:crypto';
+import { rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getProjectPaths, loadConfig, updateState } from '../core/config.js';
 import { withFileLock } from '../core/file-lock.js';
@@ -111,6 +113,148 @@ function closeRestoreSpinner(restoreSpinner, result) {
     }
     restoreSpinner.stop('Patch-touched files restored');
 }
+async function clearStaleFurnaceApplyState(projectRoot) {
+    // --force installs a new baseCommit, which invalidates every applied
+    // checksum in furnace-state.json. Preserve pendingRepair: authoring-side
+    // rollback markers describe unresolved component workspace state and
+    // should survive an engine refresh.
+    const furnacePaths = getFurnacePaths(projectRoot);
+    if (await pathExists(furnacePaths.furnaceState)) {
+        await updateFurnaceState(projectRoot, (current) => ({
+            ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
+        }));
+    }
+}
+async function activateReplacementEngine(args) {
+    const { engineDir, replacementDir, backupDir } = args;
+    await rename(engineDir, backupDir);
+    try {
+        await rename(replacementDir, engineDir);
+    }
+    catch (error) {
+        try {
+            await rename(backupDir, engineDir);
+        }
+        catch (restoreError) {
+            const cause = toError(restoreError);
+            warn(`Could not restore previous engine after replacement activation failed. Previous engine backup remains at ${backupDir}. Remove ${engineDir} if it exists, then move the backup back to engine/.`);
+            verbose(`Engine restore failure detail: ${cause.message}`);
+            if (cause.stack) {
+                verbose(cause.stack);
+            }
+        }
+        throw error;
+    }
+}
+async function restorePreviousEngine(args) {
+    const { engineDir, backupDir, reason } = args;
+    const cause = toError(reason);
+    verbose(`Restoring previous engine after failed forced download: ${cause.message}`);
+    try {
+        await removeDir(engineDir);
+        await rename(backupDir, engineDir);
+        warn('Restored the previous engine/ after the forced replacement failed.');
+    }
+    catch (restoreError) {
+        const restoreCause = toError(restoreError);
+        warn(`Could not restore the previous engine automatically. Previous engine backup remains at ${backupDir}. Remove the failed engine/ and move that backup back to engine/ before retrying.`);
+        verbose(`Engine restore failure detail: ${restoreCause.message}`);
+        if (restoreCause.stack) {
+            verbose(restoreCause.stack);
+        }
+    }
+}
+async function downloadAndExtractFirefox(args) {
+    const { version, product, engineDir, cacheDir, sha256 } = args;
+    let s = spinner(`Downloading Firefox ${version}...`);
+    let lastPercent = 0;
+    const phaseState = { value: 'download' };
+    try {
+        await downloadFirefoxSource(version, product, engineDir, cacheDir, (downloaded, total) => {
+            if (total <= 0)
+                return;
+            const percent = Math.floor((downloaded / total) * 100);
+            if (percent !== lastPercent && percent % 5 === 0) {
+                s.message(`Downloading Firefox ${version}... ${percent}% (${formatBytes(downloaded)} / ${formatBytes(total)})`);
+                lastPercent = percent;
+            }
+        }, (phase) => {
+            if (phase === 'extract' && phaseState.value === 'download') {
+                s.stop(`Firefox ${version} downloaded`);
+                phaseState.value = 'extract';
+                s = spinner(`Extracting Firefox ${version}... (decompressing ~600 MB of source; typically 30–90s)`);
+            }
+        }, sha256, (message) => {
+            s.message(message);
+        });
+        s.stop(phaseState.value === 'extract'
+            ? `Firefox ${version} extracted`
+            : `Firefox ${version} downloaded`);
+    }
+    catch (error) {
+        s.error(phaseState.value === 'extract' ? 'Extraction failed' : 'Download failed');
+        throw error;
+    }
+}
+async function initializeDownloadedEngine(args) {
+    const { projectRoot, patchesDir, version, engineDir, replacementActivated, backupEngineDir } = args;
+    // Finding #17: the git indexing phase of `download` can block for
+    // minutes on a ~600 MB Firefox tree. Emit a one-line heads-up banner
+    // before the spinner starts so CI logs show the expected duration.
+    try {
+        info('Indexing downloaded source into git (one-time; typically 3–5 minutes on a ~600 MB Firefox tree)...');
+        info('Git phase: initializing/resetting source repository metadata.');
+        const gitSpinner = spinner('Initializing git repository (this may take a few minutes)...');
+        let baseCommit;
+        try {
+            await initRepository(engineDir, 'firefox', {
+                onProgress: (message) => {
+                    gitSpinner.message(message);
+                },
+            });
+            baseCommit = await getHead(engineDir);
+            gitSpinner.stop('Git repository initialized');
+        }
+        catch (error) {
+            gitSpinner.error('Failed to initialize git repository');
+            warn(replacementActivated
+                ? 'Replacement engine/ failed during baseline git initialization. FireForge will try to restore the previous engine.'
+                : 'engine/ may now contain a partially initialized git repository. Re-run "fireforge download --force" to recreate the baseline cleanly.');
+            throw error;
+        }
+        const restoreSpinner = spinner('Restoring patch-touched files to baseline...');
+        try {
+            const restoreResult = await cleanPatchTouchedFiles(engineDir, patchesDir);
+            closeRestoreSpinner(restoreSpinner, restoreResult);
+        }
+        catch (error) {
+            restoreSpinner.error('Failed to restore patch-touched files');
+            throw error;
+        }
+        if (replacementActivated) {
+            await clearStaleFurnaceApplyState(projectRoot);
+        }
+        await updateState(projectRoot, {
+            downloadedVersion: version,
+            baseCommit,
+        });
+        await noteUnappliedPatches(patchesDir);
+        if (backupEngineDir) {
+            await removeDir(backupEngineDir);
+        }
+        outro(`Firefox ${version} is ready!`);
+    }
+    catch (error) {
+        if (replacementActivated && backupEngineDir) {
+            await restorePreviousEngine({
+                engineDir,
+                backupDir: backupEngineDir,
+                reason: error,
+            });
+        }
+        throw error;
+    }
+}
 /**
  * Runs the download command.
  * @param projectRoot - Root directory of the project
@@ -118,14 +262,15 @@ function closeRestoreSpinner(restoreSpinner, result) {
  */
 export async function downloadCommand(projectRoot, options) {
     intro('FireForge Download');
-    // Load configuration
-    const config = await loadConfig(projectRoot);
+    const config = await loadConfig(projectRoot), version = config.firefox.version;
     const paths = getProjectPaths(projectRoot);
-    const version = config.firefox.version;
     info(`Firefox version: ${version}`);
-    // Disk space pre-flight: Firefox source is ~5 GB
     await checkDiskSpace(projectRoot, 5 * 1024 * 1024 * 1024, warn);
     await withFileLock(join(paths.fireforgeDir, 'download.fireforge.lock'), async () => {
+        let installEngineDir = paths.engine;
+        let replacementEngineDir;
+        let backupEngineDir;
+        let replacementActivated = false;
         // Check if engine already exists
         if (await pathExistsStrict(paths.engine)) {
             if (!options.force) {
@@ -206,126 +351,47 @@ export async function downloadCommand(projectRoot, options) {
                 }
                 throw new EngineExistsError(paths.engine);
             }
-            warn('Removing existing engine directory...');
-            await removeDir(paths.engine);
-            // --force installs a new baseCommit, which invalidates every applied
-            // checksum in furnace-state.json. Clearing the state now prevents a
-            // subsequent `furnace apply` from reporting "up to date" against an
-            // engine that no longer contains any of the deployed files. Preserve
-            // pendingRepair: authoring-side rollback markers describe unresolved
-            // component workspace state and should survive an engine refresh.
-            const furnacePaths = getFurnacePaths(projectRoot);
-            if (await pathExists(furnacePaths.furnaceState)) {
-                await updateFurnaceState(projectRoot, (current) => ({
-                    ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
-                }));
-            }
+            replacementEngineDir = `${paths.engine}.replacement-${randomUUID()}`;
+            backupEngineDir = `${paths.engine}.backup-${randomUUID()}`;
+            installEngineDir = replacementEngineDir;
+            warn('Preparing replacement engine directory; existing engine/ will remain in place until the new archive downloads, validates, and extracts.');
         }
         // Ensure cache directory exists
         const cacheDir = join(paths.fireforgeDir, 'cache');
         await ensureDir(cacheDir);
-        // Phase-switched spinners: the download phase runs with the byte-count
-        // progress callbacks below; the extract phase is blocking tar-xz and
-        // has no incremental progress, but it can take 30–90s on a ~600 MB
-        // Firefox tree, so it gets its own spinner message. Before the phase
-        // split, a single "Downloading Firefox … 100%" spinner covered both
-        // — the first-run setup looked hung precisely when the archive had
-        // already reached disk and `tar` was the long pole.
-        let s = spinner(`Downloading Firefox ${version}...`);
-        let lastPercent = 0;
-        const phaseState = { value: 'download' };
         try {
-            await downloadFirefoxSource(version, config.firefox.product, paths.engine, cacheDir, (downloaded, total) => {
-                if (total <= 0)
-                    return;
-                const percent = Math.floor((downloaded / total) * 100);
-                if (percent !== lastPercent && percent % 5 === 0) {
-                    s.message(`Downloading Firefox ${version}... ${percent}% (${formatBytes(downloaded)} / ${formatBytes(total)})`);
-                    lastPercent = percent;
-                }
-            }, (phase) => {
-                if (phase === 'extract' && phaseState.value === 'download') {
-                    s.stop(`Firefox ${version} downloaded`);
-                    phaseState.value = 'extract';
-                    s = spinner(`Extracting Firefox ${version}... (decompressing ~600 MB of source; typically 30–90s)`);
-                }
-            }, config.firefox.sha256, (message) => {
-                if (phaseState.value === 'extract')
-                    s.message(message);
+            await downloadAndExtractFirefox({
+                version,
+                product: config.firefox.product,
+                engineDir: installEngineDir,
+                cacheDir,
+                ...(config.firefox.sha256 !== undefined ? { sha256: config.firefox.sha256 } : {}),
             });
-            if (phaseState.value === 'extract') {
-                s.stop(`Firefox ${version} extracted`);
-            }
-            else {
-                s.stop(`Firefox ${version} downloaded`);
+            if (replacementEngineDir && backupEngineDir) {
+                warn('Activating replacement engine directory...');
+                await activateReplacementEngine({
+                    engineDir: paths.engine,
+                    replacementDir: replacementEngineDir,
+                    backupDir: backupEngineDir,
+                });
+                replacementActivated = true;
+                installEngineDir = paths.engine;
             }
         }
         catch (error) {
-            s.error(phaseState.value === 'extract' ? 'Extraction failed' : 'Download failed');
-            throw error;
-        }
-        // Finding #17: the git indexing phase of `download` can block for
-        // minutes on a ~600 MB Firefox tree — the spinner updates less often
-        // than operators expect during the monolithic `git add -A` pass, and
-        // non-TTY shells see long stretches of silence. Emit a one-line
-        // heads-up banner BEFORE the spinner starts so even a log-scraping
-        // CI job notes the expected duration. The progress callbacks below
-        // still fire as usual; this is an additional up-front signal, not a
-        // replacement.
-        info('Indexing downloaded source into git (one-time; typically 3–5 minutes on a ~600 MB Firefox tree)...');
-        // Initialize git repository
-        const gitSpinner = spinner('Initializing git repository (this may take a few minutes)...');
-        let baseCommit;
-        try {
-            await initRepository(paths.engine, 'firefox', {
-                // Same one-authority rule as the resume path above: the non-TTY
-                // spinner fallback already emits `step(msg)` internally, so
-                // calling `step()` in addition to `.message()` duplicated every
-                // git-init progress line in CI logs.
-                onProgress: (message) => {
-                    gitSpinner.message(message);
-                },
-            });
-            baseCommit = await getHead(paths.engine);
-            gitSpinner.stop('Git repository initialized');
-        }
-        catch (error) {
-            gitSpinner.error('Failed to initialize git repository');
-            warn('engine/ may now contain a partially initialized git repository. Re-run "fireforge download --force" to recreate the baseline cleanly.');
-            throw error;
-        }
-        // Restore any patch-touched files that ended up dirty after the initial
-        // commit (e.g. line-ending normalisation or extraction artefacts) so that
-        // a subsequent `fireforge import` works without --force.
-        //
-        // Wrapped in a dedicated spinner because the restore can itself take
-        // tens of seconds on a ~600 MB Firefox tree: it walks every file in the
-        // patch manifest, calls `git status` / `git checkout` for each, and the
-        // eval's "download looks hung" report landed at least partly on this
-        // post-commit window. An operator watching the CLI needs to see that
-        // this phase is distinct from the preceding git-add work.
-        //
-        // This runs BEFORE updateState so a restore failure keeps the previous
-        // downloadedVersion in state.json. The invariant we preserve is
-        // "state.downloadedVersion matches a clean engine": stamping the new
-        // version only after the restore succeeds means a failed clean-up will
-        // re-enter the resume path on the next `fireforge download` rather than
-        // reporting success against a dirty engine.
-        const restoreSpinner = spinner('Restoring patch-touched files to baseline...');
-        try {
-            const restoreResult = await cleanPatchTouchedFiles(paths.engine, paths.patches);
-            closeRestoreSpinner(restoreSpinner, restoreResult);
-        }
-        catch (error) {
-            restoreSpinner.error('Failed to restore patch-touched files');
+            if (replacementEngineDir) {
+                await removeDir(replacementEngineDir);
+            }
             throw error;
         }
-        await updateState(projectRoot, {
-            downloadedVersion: version,
-            baseCommit,
+        await initializeDownloadedEngine({
+            projectRoot,
+            patchesDir: paths.patches,
+            version,
+            engineDir: installEngineDir,
+            replacementActivated,
+            ...(backupEngineDir !== undefined ? { backupEngineDir } : {}),
         });
-        await noteUnappliedPatches(paths.patches);
-        outro(`Firefox ${version} is ready!`);
     });
 }
 /** Registers the download command on the CLI program. */

package/dist/src/commands/export-all.js

@@ -8,6 +8,7 @@ import { extractAffectedFiles } from '../core/patch-apply.js';
 import { commitExportedPatch, findAllPatchesForFiles } from '../core/patch-export.js';
 import { buildPatchQueueContext, collectNewFileCreatorsByPath, detectNewFilesInDiff, } from '../core/patch-lint.js';
 import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
+import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { GeneralError } from '../errors/base.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
@@ -262,7 +263,7 @@ export async function exportAllCommand(projectRoot, options = {}) {
                 name: patchName,
                 description,
                 filesAffected,
-                sourceEsrVersion: config.firefox.version,
+                ...buildPatchSourceMetadata(config.firefox),
                 explicitSupersede: options.supersede === true,
                 allowOverlap: options.allowOverlap === true,
                 config,
@@ -299,7 +300,7 @@ export async function exportAllCommand(projectRoot, options = {}) {
             description,
             diff,
             filesAffected,
-            sourceEsrVersion: config.firefox.version,
+            ...buildPatchSourceMetadata(config.firefox),
             config,
             policyCommand: 'export-all',
             forceUnsafe: options.forceUnsafe === true,

package/dist/src/commands/export-flow.d.ts

@@ -93,6 +93,8 @@ export interface DryRunPreviewInput {
     description: string;
     filesAffected: string[];
     sourceEsrVersion: string;
+    sourceProduct?: FireForgeConfig['firefox']['product'];
+    sourceVersion?: string;
     explicitSupersede: boolean;
     allowOverlap: boolean;
     /** Optional `PatchMetadata.tier` opt-in carried from the CLI. */

package/dist/src/commands/export-flow.js

@@ -354,6 +354,8 @@ export async function renderDryRunPreview(input) {
         description: input.description,
         filesAffected: input.filesAffected,
         sourceEsrVersion: input.sourceEsrVersion,
+        ...(input.sourceProduct !== undefined ? { sourceProduct: input.sourceProduct } : {}),
+        ...(input.sourceVersion !== undefined ? { sourceVersion: input.sourceVersion } : {}),
         ...(input.tier !== undefined ? { tier: input.tier } : {}),
         ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
         ...(input.config !== undefined ? { config: input.config } : {}),

package/dist/src/commands/export.js

@@ -13,6 +13,7 @@ import { extractAffectedFiles } from '../core/patch-apply.js';
 import { commitExportedPatch, findAllPatchesForFiles } from '../core/patch-export.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { applyRenameMapToManifest, buildProjectedManifest, enforcePatchPolicy, } from '../core/patch-policy.js';
+import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
@@ -211,7 +212,7 @@ export async function exportCommand(projectRoot, files, options) {
                         name: patchName,
                         description,
                         createdAt: new Date().toISOString(),
-                        sourceEsrVersion: config.firefox.version,
+                        ...buildPatchSourceMetadata(config.firefox),
                         filesAffected,
                         ...(options.tier !== undefined ? { tier: options.tier } : {}),
                         ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
@@ -263,7 +264,7 @@ export async function exportCommand(projectRoot, files, options) {
                 name: patchName,
                 description,
                 filesAffected,
-                sourceEsrVersion: config.firefox.version,
+                ...buildPatchSourceMetadata(config.firefox),
                 explicitSupersede: options.supersede === true,
                 allowOverlap: options.allowOverlap === true,
                 ...(options.tier !== undefined ? { tier: options.tier } : {}),
@@ -288,7 +289,7 @@ export async function exportCommand(projectRoot, files, options) {
                 name: patchName,
                 description,
                 createdAt: new Date().toISOString(),
-                sourceEsrVersion: config.firefox.version,
+                ...buildPatchSourceMetadata(config.firefox),
                 filesAffected,
                 ...(options.tier !== undefined ? { tier: options.tier } : {}),
                 ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
@@ -366,7 +367,7 @@ export async function exportCommand(projectRoot, files, options) {
             description,
             diff,
             filesAffected,
-            sourceEsrVersion: config.firefox.version,
+            ...buildPatchSourceMetadata(config.firefox),
             ...(options.tier !== undefined ? { tier: options.tier } : {}),
             ...(options.lintIgnore !== undefined && options.lintIgnore.length > 0
                 ? { lintIgnore: options.lintIgnore }

package/dist/src/commands/import.js

@@ -6,6 +6,7 @@ import { getHead } from '../core/git.js';
 import { getDirtyFiles } from '../core/git-status.js';
 import { applyPatchesWithContinue, computePatchedContent, countPatches, discoverPatches, extractAffectedFiles, PatchError, } from '../core/patch-apply.js';
 import { checkVersionCompatibility, loadPatchesManifest, validatePatchesManifestConsistency, validatePatchIntegrity, } from '../core/patch-manifest.js';
+import { getPatchSourceVersion } from '../core/patch-source-metadata.js';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
@@ -269,7 +270,7 @@ export async function importCommand(projectRoot, options = {}) {
             // doesn't need to see version warnings for patches outside the range.
             if (options.until !== undefined && !untilFilenameSet.has(patch.filename))
                 continue;
-            const warning = checkVersionCompatibility(patch.sourceEsrVersion, currentVersion);
+            const warning = checkVersionCompatibility(getPatchSourceVersion(patch), currentVersion);
             if (warning) {
                 warn(`${patch.filename}: ${warning}`);
             }