@hominis/fireforge 0.19.6 → 0.21.0

package/dist/src/commands/furnace/remove.js

@@ -16,6 +16,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists, readText, removeDir, removeFile, writeText } from '../../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, warn } from '../../utils/logger.js';
+import { dropChecksumsByPrefix } from './remove-state.js';
 /**
  * Removes an entire TOML section (header + body lines) for a given test file.
  * Matches from `["filename"]` up to the next section header `[` or end-of-file,
@@ -328,15 +329,22 @@ async function cleanupCustomXpcshellTestFiles(name, projectRoot, journal) {
     }
     return { partialFailures };
 }
-function dropChecksumsByPrefix(state, prefix) {
-    const result = { ...state };
-    if (state.appliedChecksums) {
-        result.appliedChecksums = Object.fromEntries(Object.entries(state.appliedChecksums).filter(([k]) => !k.startsWith(prefix)));
-    }
-    if (state.engineChecksums) {
-        result.engineChecksums = Object.fromEntries(Object.entries(state.engineChecksums).filter(([k]) => !k.startsWith(prefix)));
+async function loadFreshRemoveTarget(projectRoot, name, engineDir) {
+    const config = await loadFurnaceConfig(projectRoot);
+    const state = await loadFurnaceState(projectRoot);
+    const type = findComponentType(config, name);
+    if (!type) {
+        throw new FurnaceError(`Component "${name}" not found in furnace.json. Run "fireforge furnace list" to see registered components.`, name);
     }
-    return result;
+    await requireGitEngineForRemove(type, name, engineDir);
+    return { config, ftlDir: resolveFtlDir(config.ftlBasePath), state, type };
+}
+async function cleanupAllCustomTestFiles(name, projectRoot, journal) {
+    const result = await cleanupCustomTestFiles(name, projectRoot, journal);
+    const failures = [...result.partialFailures];
+    failures.push(...(await cleanupCustomXpcshellTestFiles(name, projectRoot, journal)).partialFailures);
+    failures.push(...(await cleanupCustomMochikitTestFiles(name, projectRoot, journal)).partialFailures);
+    return failures;
 }
 /**
  * Confirms the remove operation interactively when TTY is available, or
@@ -380,9 +388,7 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
     intro('Furnace Remove');
     const config = await loadFurnaceConfig(projectRoot);
-    const state = await loadFurnaceState(projectRoot);
     const furnacePaths = getFurnacePaths(projectRoot);
-    const ftlDir = resolveFtlDir(config.ftlBasePath);
     // Find which section the component belongs to
     const type = findComponentType(config, name);
     if (!type) {
@@ -402,8 +408,9 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
         const journal = createRollbackJournal();
         ctx.registerJournal(journal);
         try {
-            if (type === 'override') {
-                const overrideConfig = config.overrides[name];
+            const { config: freshConfig, ftlDir, state: freshState, type: freshType, } = await loadFreshRemoveTarget(projectRoot, name, paths.engine);
+            if (freshType === 'override') {
+                const overrideConfig = freshConfig.overrides[name];
                 const dir = join(furnacePaths.overridesDir, name);
                 // Restore deployed engine files BEFORE removing the workspace
                 // directory. The restore set is the union of (a) files currently in
@@ -411,7 +418,7 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                 // — without (b), source-side deletions would orphan engine copies
                 // that this command can never see again.
                 if (overrideConfig?.basePath) {
-                    const previousKeys = Object.keys(extractComponentChecksums(state.appliedChecksums, 'override', name));
+                    const previousKeys = Object.keys(extractComponentChecksums(freshState.appliedChecksums, 'override', name));
                     const { restored, removed } = await restoreOverrideEngineFiles(paths.engine, dir, overrideConfig, previousKeys, ftlDir, journal);
                     if (restored > 0) {
                         info(`Restored ${restored} file${restored === 1 ? '' : 's'} in engine/${overrideConfig.basePath} to Firefox baseline`);
@@ -426,8 +433,8 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                     info(`Deleted components/overrides/${name}/`);
                 }
             }
-            else if (type === 'custom') {
-                const customConfig = config.custom[name];
+            else if (freshType === 'custom') {
+                const customConfig = freshConfig.custom[name];
                 // Custom-component removal mutates engine files (jar.mn,
                 // customElements.js, deployed widgets, optional .ftl) and the
                 // rollback journal is the only safety net for those edits while
@@ -479,46 +486,27 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                     await removeCustomFtlJarMnEntry(paths.engine, `${name}.ftl`, ftlDir, customConfig, journal);
                 }
             }
-            let testCleanupFailures = [];
-            if (type === 'custom') {
-                const result = await cleanupCustomTestFiles(name, projectRoot, journal);
-                testCleanupFailures = result.partialFailures;
-                // 2026-04-24 eval Finding 5: also clean up xpcshell scaffolds
-                // generated by `furnace create --with-tests --xpcshell`. The
-                // mochitest cleanup above covers `browser/base/content/test/
-                // <binary>/`, but xpcshell scaffolds live in the sibling
-                // `<binary>-xpcshell/` directory and were orphaned by prior
-                // versions.
-                const xpcshellResult = await cleanupCustomXpcshellTestFiles(name, projectRoot, journal);
-                testCleanupFailures.push(...xpcshellResult.partialFailures);
-                // 2026-04-25 eval Finding 13: mochikit-style scaffolds
-                // (`--test-style mochikit`) live under
-                // `engine/toolkit/content/tests/widgets/` with `chrome.toml`
-                // entries — neither the browser-chrome path nor the xpcshell
-                // path touches them. Without this pass, a `furnace create
-                // --with-tests --test-style mochikit` followed by `furnace
-                // remove` left the test file and its toml entry referencing a
-                // component that no longer exists.
-                const mochikitResult = await cleanupCustomMochikitTestFiles(name, projectRoot, journal);
-                testCleanupFailures.push(...mochikitResult.partialFailures);
-            }
+            const testCleanupFailures = freshType === 'custom' ? await cleanupAllCustomTestFiles(name, projectRoot, journal) : [];
             // Remove entry from furnace.json
-            if (type === 'stock') {
-                config.stock = config.stock.filter((s) => s !== name);
+            if (freshType === 'stock') {
+                freshConfig.stock = freshConfig.stock.filter((s) => s !== name);
             }
-            else if (type === 'override') {
-                config.overrides = Object.fromEntries(Object.entries(config.overrides).filter(([key]) => key !== name));
+            else if (freshType === 'override') {
+                freshConfig.overrides = Object.fromEntries(Object.entries(freshConfig.overrides).filter(([key]) => key !== name));
+                if (!freshConfig.stock.includes(name)) {
+                    freshConfig.stock.push(name);
+                }
             }
             else {
-                config.custom = Object.fromEntries(Object.entries(config.custom).filter(([key]) => key !== name));
+                freshConfig.custom = Object.fromEntries(Object.entries(freshConfig.custom).filter(([key]) => key !== name));
             }
             await snapshotFile(journal, furnacePaths.furnaceConfig);
-            await writeFurnaceConfig(projectRoot, config);
+            await writeFurnaceConfig(projectRoot, freshConfig);
             // Drop stale per-file checksums inside the same transactional block.
             // Snapshotting the state file into the rollback journal means the
             // entire remove operation is a single atomic unit.
             await snapshotFile(journal, furnacePaths.furnaceState);
-            await updateFurnaceState(projectRoot, (state) => dropChecksumsByPrefix(state, `${type}/${name}/`));
+            await updateFurnaceState(projectRoot, (state) => dropChecksumsByPrefix(state, `${freshType}/${name}/`));
             // Test-cleanup failures are warn-and-continue by design (test files
             // are secondary artefacts), but the caller deserves a single summary
             // line pointing at the residue so they don't have to re-scan earlier

package/dist/src/commands/furnace/rename-browser-test.d.ts

@@ -0,0 +1,2 @@
+/** Rewrites scaffolded browser-chrome test literals after a component rename. */
+export declare function updateBrowserChromeTestContent(content: string, oldName: string, newName: string, binaryName: string): string;

package/dist/src/commands/furnace/rename-browser-test.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { tagNameToClassName } from '../../core/furnace-constants.js';
+/** Escapes regex metacharacters so a user-supplied name is literal inside a RegExp. */
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function deriveTestStem(componentName, binaryName) {
+    const strippedName = componentName.startsWith('moz-') ? componentName.slice(4) : componentName;
+    const withoutBinaryPrefix = strippedName.startsWith(binaryName + '-')
+        ? strippedName.slice(binaryName.length + 1)
+        : strippedName;
+    return withoutBinaryPrefix.replace(/-/g, '_');
+}
+/** Rewrites scaffolded browser-chrome test literals after a component rename. */
+export function updateBrowserChromeTestContent(content, oldName, newName, binaryName) {
+    const oldClassName = tagNameToClassName(oldName);
+    const newClassName = tagNameToClassName(newName);
+    const oldUnderscored = oldName.replace(/-/g, '_');
+    const newUnderscored = newName.replace(/-/g, '_');
+    const oldTestStem = deriveTestStem(oldName, binaryName);
+    const newTestStem = deriveTestStem(newName, binaryName);
+    return content
+        .replace(new RegExp(escapeRegex(oldName), 'g'), newName)
+        .replace(new RegExp(escapeRegex(oldClassName), 'g'), newClassName)
+        .replace(new RegExp(escapeRegex(oldUnderscored), 'g'), newUnderscored)
+        .replace(new RegExp(escapeRegex(oldTestStem), 'g'), newTestStem);
+}
+//# sourceMappingURL=rename-browser-test.js.map

package/dist/src/commands/furnace/rename-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { FurnaceConfig } from '../../types/furnace.js';
+/**
+ * Applies a component rename to scaffold-owned filenames only.
+ */
+export declare function renameComponentFileName(fileName: string, oldName: string, newName: string): string;
+/**
+ * Re-keys a custom component config entry and same-config compose references.
+ */
+export declare function updateConfigForCustomRename(config: FurnaceConfig, oldName: string, newName: string): void;
+/**
+ * Re-keys an override component config entry.
+ */
+export declare function updateConfigForOverrideRename(config: FurnaceConfig, oldName: string, newName: string): void;

package/dist/src/commands/furnace/rename-helpers.js

@@ -0,0 +1,42 @@
+/**
+ * Applies a component rename to scaffold-owned filenames only.
+ */
+export function renameComponentFileName(fileName, oldName, newName) {
+    if (fileName === oldName)
+        return newName;
+    if (fileName.startsWith(oldName + '.')) {
+        return newName + fileName.slice(oldName.length);
+    }
+    return fileName;
+}
+/**
+ * Re-keys a custom component config entry and same-config compose references.
+ */
+export function updateConfigForCustomRename(config, oldName, newName) {
+    const oldConfig = config.custom[oldName];
+    if (!oldConfig)
+        return;
+    config.custom[newName] = {
+        ...oldConfig,
+        targetPath: oldConfig.targetPath.replace(new RegExp(`(^|/)${oldName}$`), `$1${newName}`),
+    };
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- idiomatic key removal from config record
+    delete config.custom[oldName];
+    for (const customConfig of Object.values(config.custom)) {
+        if (customConfig.composes) {
+            customConfig.composes = customConfig.composes.map((ref) => (ref === oldName ? newName : ref));
+        }
+    }
+}
+/**
+ * Re-keys an override component config entry.
+ */
+export function updateConfigForOverrideRename(config, oldName, newName) {
+    const oldConfig = config.overrides[oldName];
+    if (!oldConfig)
+        return;
+    config.overrides[newName] = { ...oldConfig };
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- idiomatic key removal from config record
+    delete config.overrides[oldName];
+}
+//# sourceMappingURL=rename-helpers.js.map

package/dist/src/commands/furnace/rename.js

@@ -14,52 +14,13 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeDir, removeFile, writeText, } from '../../utils/fs.js';
 import { info, intro, note, outro, warn } from '../../utils/logger.js';
+import { updateBrowserChromeTestContent } from './rename-browser-test.js';
+import { renameComponentFileName, updateConfigForCustomRename, updateConfigForOverrideRename, } from './rename-helpers.js';
 import { renameXpcshellTestFiles } from './rename-xpcshell.js';
 /** Escapes regex metacharacters so a user-supplied name is literal inside a RegExp. */
 function escapeRegex(input) {
     return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-/**
- * Applies the component rename to a filename. Only replaces the leading
- * component name when it is followed by `.` (extension) or equals the
- * filename exactly; every other filename is returned unchanged so stray
- * assets, editor backups, or files whose name coincidentally contains the
- * old component name in the middle or at the end are not accidentally
- * renamed.
- */
-function renameComponentFileName(fileName, oldName, newName) {
-    if (fileName === oldName)
-        return newName;
-    if (fileName.startsWith(oldName + '.')) {
-        return newName + fileName.slice(oldName.length);
-    }
-    return fileName;
-}
-function updateConfigForCustomRename(config, oldName, newName) {
-    const oldConfig = config.custom[oldName];
-    if (!oldConfig)
-        return;
-    config.custom[newName] = {
-        ...oldConfig,
-        targetPath: oldConfig.targetPath.replace(new RegExp(`(^|/)${oldName}$`), `$1${newName}`),
-    };
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- idiomatic key removal from config record
-    delete config.custom[oldName];
-    // Update composes references in other components
-    for (const customConfig of Object.values(config.custom)) {
-        if (customConfig.composes) {
-            customConfig.composes = customConfig.composes.map((ref) => (ref === oldName ? newName : ref));
-        }
-    }
-}
-function updateConfigForOverrideRename(config, oldName, newName) {
-    const oldConfig = config.overrides[oldName];
-    if (!oldConfig)
-        return;
-    config.overrides[newName] = { ...oldConfig };
-    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- idiomatic key removal from config record
-    delete config.overrides[oldName];
-}
 /**
  * Derives the test file name for a component, matching the convention used by
  * `furnace create --with-tests`.
@@ -98,7 +59,7 @@ async function renameTestFiles(engineDir, projectRoot, oldName, newName, journal
         try {
             await snapshotFile(journal, oldTestPath);
             const content = await readText(oldTestPath);
-            await writeText(newTestPath, content);
+            await writeText(newTestPath, updateBrowserChromeTestContent(content, oldName, newName, binaryName));
             await removeFile(oldTestPath);
             info(`Renamed test file: ${oldTestFileName} → ${newTestFileName}`);
         }
@@ -215,18 +176,37 @@ async function renameMochikitTestFiles(engineDir, oldName, newName, journal) {
  * Performs the transactional rename mutation inside a furnace lock.
  */
 async function performRenameMutations(args) {
-    const { projectRoot, oldName, newName, oldDir, newDir, isCustom, componentType, config } = args;
+    const { projectRoot, oldName, newName } = args;
     const oldClassName = tagNameToClassName(oldName);
     const newClassName = tagNameToClassName(newName);
-    // Capture the pre-rename deployed target path so we know what to
-    // clean up in the engine tree. `updateConfigForCustomRename` rewrites
-    // `targetPath` in-place once the mutation enters phase 2, so we read
-    // it here while it still points at the old name's deployment.
-    const oldCustomTargetPath = isCustom ? config.custom[oldName]?.targetPath : undefined;
     await runFurnaceMutation(projectRoot, 'rename-rollback', async (ctx) => {
         const journal = createRollbackJournal();
         ctx.registerJournal(journal);
+        let newDir = args.newDir;
         try {
+            const config = await loadFurnaceConfig(projectRoot);
+            const isCustom = oldName in config.custom;
+            const isOverride = oldName in config.overrides;
+            if (!isCustom && !isOverride) {
+                throw new FurnaceError(`Component "${oldName}" not found in furnace.json. Only custom and override components can be renamed.`, oldName);
+            }
+            if (newName in config.custom ||
+                newName in config.overrides ||
+                config.stock.includes(newName)) {
+                throw new FurnaceError(`A component named "${newName}" already exists in furnace.json.`, newName);
+            }
+            const componentType = isCustom ? 'custom' : 'override';
+            const componentDirLabel = isCustom ? 'custom' : 'overrides';
+            const baseDir = isCustom ? args.furnacePaths.customDir : args.furnacePaths.overridesDir;
+            const oldDir = join(baseDir, oldName);
+            newDir = join(baseDir, newName);
+            const oldCustomTargetPath = isCustom ? config.custom[oldName]?.targetPath : undefined;
+            if (!(await pathExists(oldDir))) {
+                throw new FurnaceError(`Component directory not found: components/${componentDirLabel}/${oldName}`, oldName);
+            }
+            if (await pathExists(newDir)) {
+                throw new FurnaceError(`Target directory already exists: components/${componentDirLabel}/${newName}`, newName);
+            }
             await snapshotDir(journal, oldDir);
             await snapshotFile(journal, args.furnaceConfigPath);
             // 1. Create new directory with renamed files and updated content
@@ -472,6 +452,7 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
         componentType,
         config,
         furnaceConfigPath: furnacePaths.furnaceConfig,
+        furnacePaths,
         engineDir: paths.engine,
     });
     note(`Component renamed: ${oldName} → ${newName}\n\n` +

package/dist/src/commands/status.js

@@ -221,7 +221,7 @@ function filterFireForgeTempFiles(files) {
 async function renderJsonStatus(files, paths, projectRoot, binaryName) {
     const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
     const classified = await classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
-    const output = classified.map((f) => {
+    const outputFiles = classified.map((f) => {
         const entry = {
             file: f.file,
             status: f.status.trim(),
@@ -236,6 +236,24 @@ async function renderJsonStatus(files, paths, projectRoot, binaryName) {
         }
         return entry;
     });
+    const byClassification = {
+        unmanaged: 0,
+        'patch-backed': 0,
+        branding: 0,
+        furnace: 0,
+        conflict: 0,
+    };
+    for (const file of outputFiles) {
+        byClassification[file.classification]++;
+    }
+    const output = {
+        schemaVersion: 1,
+        summary: {
+            total: outputFiles.length,
+            byClassification,
+        },
+        files: outputFiles,
+    };
     process.stdout.write(JSON.stringify(output, null, 2) + '\n');
 }
 /**
@@ -267,7 +285,8 @@ async function assertEngineHasBaselineCommit(engineDir, options) {
             // throw still falls through to the styled error renderer in
             // withErrorHandling, leaving JSON consumers with non-JSON output on
             // exactly the failure mode they care about catching.
-            process.stdout.write(JSON.stringify({ error: guidance, code: 'engine-baseline-missing' }) + '\n');
+            process.stdout.write(JSON.stringify({ schemaVersion: 1, error: guidance, code: 'engine-baseline-missing' }) +
+                '\n');
         }
         throw new GeneralError(guidance);
     }
@@ -307,7 +326,7 @@ export async function statusCommand(projectRoot, options = {}) {
     // `withErrorHandling` does not log: bin/fireforge.ts catches it,
     // exits with the carried code, and stdout stays a single JSON line.
     const emitJsonError = (code, message) => {
-        process.stdout.write(JSON.stringify({ error: message, code }) + '\n');
+        process.stdout.write(JSON.stringify({ schemaVersion: 1, error: message, code }) + '\n');
         throw new CommandError(ExitCode.GENERAL_ERROR);
     };
     // Ownership mode is a flat file→patch table; sources are the manifest's

package/dist/src/commands/test.js

@@ -201,8 +201,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // here so `test --doctor` against an incomplete build surfaces the
     // missing-bundle path instead of a cryptic `Browser process exited
     // during spawn (exit code 1, signal none). stderr tail: (empty)`.
+    let launchablePath;
     if (buildCheck.objDir) {
         const bundleCheck = await hasRunnableBundle(paths.engine, projectConfig.binaryName, buildCheck.objDir);
+        launchablePath = bundleCheck.expectedPath;
         if (!bundleCheck.runnable) {
             const expectedSuffix = bundleCheck.expectedPath
                 ? ` (expected at engine/${bundleCheck.expectedPath})`
@@ -287,6 +289,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         // (`info`/`warn`) is retained so TTY users keep the visual framing.
         const directLine = formatMarionettePreflightLine(preflight);
         process.stdout.write(`${directLine}\n`);
+        process.stdout.write(`Marionette preflight environment: objdir=${buildCheck.objDir ?? '(none)'}; binary=${projectConfig.binaryName}; app=${launchablePath ? `engine/${launchablePath}` : '(unknown)'}; port=${effectivePort ?? 2828}; elapsed=${preflight.durationMs}ms\n`);
         reportMarionettePreflight(preflight);
         if (testPaths.length === 0) {
             if (!preflight.ok) {

package/dist/src/commands/watch.js

@@ -60,14 +60,21 @@ function buildWatchmanConfigureTimeMessage() {
  * @param watchmanPath - Optional absolute path to the resolved watchman binary; surfaced in the guidance so the operator can see whether FireForge actually found one.
  * @returns User-facing failure guidance
  */
-function buildUnsupportedWatchMessage(exitCode, watchmanPath) {
+function hasWatchPermissionFailure(output) {
+    return /Operation not permitted|EPERM|EACCES/i.test(output);
+}
+function buildUnsupportedWatchMessage(exitCode, watchmanPath, output = '') {
     const watchmanLine = watchmanPath
         ? `  - FireForge resolved watchman at ${watchmanPath} and prepended its directory to the mach subprocess PATH. If mach still did not see it, ensure that path is stable between runs.\n`
         : '';
+    const permissionLine = hasWatchPermissionFailure(output)
+        ? '  - macOS may be blocking watchman or Terminal/Codex from reading the engine directory. Grant Full Disk Access or Files and Folders access to your terminal app and watchman, then restart watchman with "watchman shutdown-server".\n'
+        : '';
     return (`Watch failed with exit code ${exitCode}. Check the output above for details.\n\n` +
         'Common causes:\n' +
         '  - watchman is not installed or not in PATH right now\n' +
         '  - watchman was installed only after the current obj-* directory was configured; delete obj-* and rebuild\n' +
+        permissionLine +
         '  - mach watch is unsupported in the current objdir or build environment\n' +
         watchmanLine +
         '\n' +
@@ -194,7 +201,7 @@ export async function watchCommand(projectRoot) {
             throw new GeneralError(buildWatchmanConfigureTimeMessage());
         }
         // 130 is SIGINT (Ctrl+C), which is expected
-        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode, watchmanPath), 'mach watch');
+        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode, watchmanPath, combinedOutput), 'mach watch');
     }
     outro('Watch mode stopped');
 }

package/dist/src/core/config-paths.d.ts

@@ -19,7 +19,7 @@ export declare const SRC_DIR = "src";
 /** Supported top-level fireforge.json keys backed by the current schema. */
 export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -41,6 +41,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'firefox',
     'firefox.version',
     'firefox.product',
+    'firefox.sha256',
     'build',
     'build.jobs',
     'wire',

package/dist/src/core/config-validate.js

@@ -75,6 +75,10 @@ export function validateConfig(data) {
     if (compatError) {
         throw new ConfigError(compatError);
     }
+    const firefoxSha256 = optionalConfigString(firefoxRec, 'sha256', 'firefox.sha256');
+    if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
+        throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
+    }
     // Optional configs
     const config = {
         name,
@@ -84,6 +88,7 @@ export function validateConfig(data) {
         firefox: {
             version: firefoxVersion,
             product: firefoxProduct,
+            ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
         },
     };
     // Build

package/dist/src/core/config.js

@@ -11,7 +11,7 @@
 import { basename } from 'node:path';
 import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import * as fsUtils from '../utils/fs.js';
 import { getProjectPaths } from './config-paths.js';
 import { validateConfig } from './config-validate.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
@@ -21,6 +21,10 @@ export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPOR
 export { loadState, saveState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 // ---- config I/O (stays here because it bridges paths + validation) ----
+async function configPathExists(path) {
+    const fs = fsUtils;
+    return (fs.pathExistsStrict ?? fsUtils.pathExists)(path);
+}
 /**
  * Checks if a fireforge.json exists in the given directory.
  * @param root - Root directory to check
@@ -28,7 +32,7 @@ export { validateConfig } from './config-validate.js';
  */
 export async function configExists(root) {
     const paths = getProjectPaths(root);
-    return pathExists(paths.config);
+    return configPathExists(paths.config);
 }
 /**
  * Loads and validates the fireforge.json configuration.
@@ -38,11 +42,11 @@ export async function configExists(root) {
  */
 export async function loadConfig(root) {
     const paths = getProjectPaths(root);
-    if (!(await pathExists(paths.config))) {
+    if (!(await configPathExists(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {
-        const data = await readJson(paths.config);
+        const data = await fsUtils.readJson(paths.config);
         return validateConfig(data);
     }
     catch (error) {
@@ -70,11 +74,11 @@ export async function loadConfig(root) {
  */
 export async function loadRawConfigDocument(root) {
     const paths = getProjectPaths(root);
-    if (!(await pathExists(paths.config))) {
+    if (!(await configPathExists(paths.config))) {
         throw new ConfigNotFoundError(paths.config);
     }
     try {
-        const data = await readJson(paths.config);
+        const data = await fsUtils.readJson(paths.config);
         if (data === null || typeof data !== 'object' || Array.isArray(data)) {
             throw new ConfigError(`Invalid fireforge.json at ${paths.config}: expected an object`);
         }
@@ -110,7 +114,7 @@ export async function writeConfig(root, config) {
  */
 export async function writeConfigDocument(root, config) {
     const paths = getProjectPaths(root);
-    await writeJson(paths.config, config);
+    await fsUtils.writeJson(paths.config, config);
 }
 /**
  * Runs an operation while holding a sidecar lock on `fireforge.json`.

package/dist/src/core/file-lock.js

@@ -35,8 +35,8 @@ function isProcessAlive(pid) {
         process.kill(pid, 0);
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        return getNodeErrorCode(error) !== 'ESRCH';
     }
 }
 async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {

package/dist/src/core/firefox-cache.d.ts

@@ -14,7 +14,7 @@ export declare function sha256File(filePath: string): Promise<string>;
  * @param cacheDir - Cache directory
  * @param onProgress - Optional progress callback
  */
-export declare function ensureCachedArchive(archive: ResolvedArchive, cacheDir: string, onProgress?: ProgressCallback): Promise<void>;
+export declare function ensureCachedArchive(archive: ResolvedArchive, cacheDir: string, onProgress?: ProgressCallback, expectedSha256?: string): Promise<void>;
 /**
  * Removes cached tarball, metadata, and partial download files for an archive.
  * @param archive - Resolved archive descriptor