@hominis/fireforge 0.27.2 → 0.27.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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`.

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,57 @@ 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}...`);
@@ -143,6 +196,65 @@ async function downloadAndExtractFirefox(args) {
         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
@@ -155,6 +267,10 @@ export async function downloadCommand(projectRoot, options) {
     info(`Firefox version: ${version}`);
     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) {
@@ -235,93 +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);
-        await downloadAndExtractFirefox({
-            version,
-            product: config.firefox.product,
-            engineDir: paths.engine,
-            cacheDir,
-            ...(config.firefox.sha256 !== undefined ? { sha256: config.firefox.sha256 } : {}),
-        });
-        // 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)...');
-        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(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);
-                },
+            await downloadAndExtractFirefox({
+                version,
+                product: config.firefox.product,
+                engineDir: installEngineDir,
+                cacheDir,
+                ...(config.firefox.sha256 !== undefined ? { sha256: config.firefox.sha256 } : {}),
             });
-            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);
+            if (replacementEngineDir && backupEngineDir) {
+                warn('Activating replacement engine directory...');
+                await activateReplacementEngine({
+                    engineDir: paths.engine,
+                    replacementDir: replacementEngineDir,
+                    backupDir: backupEngineDir,
+                });
+                replacementActivated = true;
+                installEngineDir = paths.engine;
+            }
         }
         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/core/firefox-archive.js

@@ -6,9 +6,13 @@ import { ConfigError } from '../errors/config.js';
 import { parseObject } from '../utils/parse.js';
 import { isValidFirefoxProduct } from '../utils/validation.js';
 /**
- * Base URL for Firefox releases on archive.mozilla.org.
+ * Base URLs for Firefox source archives on archive.mozilla.org.
  */
-const ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox/releases';
+const FIREFOX_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox/releases';
+const DEVEDITION_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/devedition/releases';
+function getArchiveBaseUrl(product) {
+    return product === 'firefox-devedition' ? DEVEDITION_ARCHIVE_BASE_URL : FIREFOX_ARCHIVE_BASE_URL;
+}
 /**
  * Validates raw JSON data as ArchiveMetadata.
  * @param data - Unknown data to validate
@@ -55,7 +59,7 @@ export function resolveArchive(version, product = 'firefox') {
         requestedVersion: version,
         product,
         archiveVersion,
-        url: `${ARCHIVE_BASE_URL}/${archiveVersion}/source/firefox-${archiveVersion}.source.tar.xz`,
+        url: `${getArchiveBaseUrl(product)}/${archiveVersion}/source/firefox-${archiveVersion}.source.tar.xz`,
         filename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz`,
         metadataFilename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz.json`,
     };

package/dist/src/core/firefox-cache.js

@@ -7,7 +7,7 @@ import { createReadStream } from 'node:fs';
 import { rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
-import { DownloadError } from '../errors/download.js';
+import { ChecksumMismatchError } from '../errors/download.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, removeFile, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
@@ -115,7 +115,7 @@ async function downloadToCache(archive, cacheDir, onProgress, expectedSha256, on
         onCacheProgress?.(`Calculating source archive SHA-256 for ${archive.filename}...`);
         const sha256 = await sha256File(tarballPath);
         if (expectedSha256 && sha256 !== expectedSha256) {
-            throw new DownloadError(`Downloaded archive SHA-256 mismatch: expected ${expectedSha256}, got ${sha256}`, archive.url);
+            throw new ChecksumMismatchError(archive.product, expectedSha256, sha256, archive.url);
         }
         onCacheProgress?.(`Writing source archive cache metadata for ${archive.metadataFilename}...`);
         await writeJson(metadataPath, {

package/dist/src/errors/download.d.ts

@@ -1,3 +1,4 @@
+import type { FirefoxProduct } from '../types/config.js';
 import { FireForgeError } from './base.js';
 /**
  * Error thrown when Firefox source download fails.
@@ -8,6 +9,16 @@ export declare class DownloadError extends FireForgeError {
     constructor(message: string, url?: string | undefined, cause?: Error);
     get userMessage(): string;
 }
+/**
+ * Error thrown when a pinned Firefox source archive checksum does not match.
+ */
+export declare class ChecksumMismatchError extends DownloadError {
+    readonly product: FirefoxProduct;
+    readonly expectedSha256: string;
+    readonly actualSha256: string;
+    constructor(product: FirefoxProduct, expectedSha256: string, actualSha256: string, url: string);
+    get userMessage(): string;
+}
 /**
  * Error thrown when extraction of the downloaded archive fails.
  */

package/dist/src/errors/download.js

@@ -1,4 +1,3 @@
-// SPDX-License-Identifier: EUPL-1.2
 import { FireForgeError } from './base.js';
 import { ExitCode } from './codes.js';
 /**
@@ -23,6 +22,39 @@ export class DownloadError extends FireForgeError {
         return msg;
     }
 }
+/**
+ * Error thrown when a pinned Firefox source archive checksum does not match.
+ */
+export class ChecksumMismatchError extends DownloadError {
+    product;
+    expectedSha256;
+    actualSha256;
+    constructor(product, expectedSha256, actualSha256, url) {
+        super(`Downloaded archive SHA-256 mismatch: expected ${expectedSha256}, got ${actualSha256}`, url);
+        this.product = product;
+        this.expectedSha256 = expectedSha256;
+        this.actualSha256 = actualSha256;
+    }
+    get userMessage() {
+        let msg = `Download Error: Firefox source archive checksum mismatch.\n\n` +
+            `Product: ${this.product}\n` +
+            `URL: ${this.url}\n` +
+            `Expected SHA-256: ${this.expectedSha256}\n` +
+            `Actual SHA-256: ${this.actualSha256}`;
+        msg += '\n\nTo fix this:\n';
+        msg += '  1. Verify firefox.product, firefox.version, and firefox.sha256 in fireforge.json\n';
+        msg += '  2. Compare the pinned hash with Mozilla SHA256SUMMARY for the resolved archive\n';
+        if (this.product === 'firefox-devedition') {
+            msg +=
+                '  3. Developer Edition archives should resolve under https://archive.mozilla.org/pub/devedition/releases/\n';
+            msg += '  4. Re-run "fireforge download --force" after correcting the source settings';
+        }
+        else {
+            msg += '  3. Re-run "fireforge download --force" after correcting the source settings';
+        }
+        return msg;
+    }
+}
 /**
  * Error thrown when extraction of the downloaded archive fails.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.27.2",
+  "version": "0.27.3",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",