@hominis/fireforge 0.39.0 → 0.41.0

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

@@ -3,14 +3,14 @@ import { join } from 'node:path';
 import { confirm, select, text } from '@clack/prompts';
 import { addLicenseHeaderToFile, hasThirdPartyPermissiveBanner } from '../core/license-headers.js';
 import { findAllPatchesForFiles } from '../core/patch-export.js';
-import { commentStyleForFile, detectNewFilesInDiff, isAcceptableNewFileHeader, lintExportedPatch, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { commentStyleForFile, detectNewFilesInDiff, formatPatchLintIssue, isAcceptableNewFileHeader, lintExportedPatch, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { getPatchPolicyCategories, isCategoryAllowedByConfig } from '../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
-import { PATCH_CATEGORIES, validatePatchName } from '../utils/validation.js';
+import { normalizePatchDisplayName, PATCH_CATEGORIES, validatePatchName, } from '../utils/validation.js';
 /**
  * Runs the full patch lint pipeline and reports results.
  * Warnings are always displayed. Errors block the export unless skipLint is true.
@@ -55,24 +55,33 @@ export async function runPatchLint(engineDir, filesAffected, diffContent, config
         ? resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent))
         : undefined;
     const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx, ignoreChecks, patchTier, checkJsReportScope ? { checkJsReportScope } : undefined);
+    reportPatchLintOutcome(issues, skipLint);
+}
+/**
+ * Prints a patch-lint issue list with `runPatchLint`'s exact severity
+ * buckets and skip-lint semantics, throwing on errors unless `skipLint`.
+ * Factored out so `re-export`'s cached-lint path (FORGE J1) can replay
+ * stored issues through the identical reporter without re-linting.
+ */
+export function reportPatchLintOutcome(issues, skipLint) {
     if (issues.length === 0)
         return;
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
     const notices = issues.filter((i) => i.severity === 'notice');
     for (const issue of notices) {
-        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+        info(`NOTICE ${formatPatchLintIssue(issue)}`);
     }
     for (const issue of warnings) {
-        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+        warn(formatPatchLintIssue(issue));
     }
     if (errors.length > 0) {
         for (const issue of errors) {
             if (skipLint) {
-                warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+                warn(formatPatchLintIssue(issue));
             }
             else {
-                warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+                warn(`ERROR ${formatPatchLintIssue(issue)}`);
             }
         }
         if (!skipLint) {
@@ -101,7 +110,10 @@ export async function runPatchLint(engineDir, filesAffected, diffContent, config
  */
 export async function promptExportPatchMetadata(options, isInteractive, commandName, config) {
     const categories = config !== undefined ? getPatchPolicyCategories(config) : [...PATCH_CATEGORIES];
-    let patchName = options.name;
+    // A filename-shaped `--name foo.patch` must not die on the dot rule —
+    // strip the extension before validation so the one-step flow works for
+    // both name shapes (FORGE G13).
+    let patchName = options.name?.trim().replace(/\.patch$/i, '');
     if (patchName) {
         const validationError = validatePatchName(patchName);
         if (validationError) {
@@ -121,7 +133,7 @@ export async function promptExportPatchMetadata(options, isInteractive, commandN
             cancel('Export cancelled');
             return null;
         }
-        patchName = String(nameResult).trim();
+        patchName = nameResult.trim();
     }
     let category = options.category;
     if (category) {
@@ -153,11 +165,19 @@ export async function promptExportPatchMetadata(options, isInteractive, commandN
             placeholder: 'Brief description of what this patch does',
         });
         if (!isCancel(descResult)) {
-            description = String(descResult);
+            description = descResult;
         }
     }
+    // The filename slug pipeline strips redundant category prefixes; the
+    // manifest display name must agree, or every `export --name ui-foo`
+    // needs a follow-up `patch rename` to satisfy bare-slug naming policy
+    // (FORGE G13).
+    const normalized = normalizePatchDisplayName(patchName, category);
+    if (normalized !== patchName) {
+        info(`Patch name normalized: "${patchName}" → "${normalized}" (the filename carries the order and category prefix).`);
+    }
     return {
-        patchName,
+        patchName: normalized,
         selectedCategory: category,
         description,
     };

package/dist/src/commands/export.js

@@ -20,7 +20,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
-import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, stringListOption, } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag } from '../utils/validation.js';
 import { commitPlacementExport, renderDryRunPreview } from './export-flow.js';
@@ -418,7 +418,7 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
         .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
         .addOption(new Option('--tier <tier>', 'Force a tier override on the new patch (only "branding" recognised)').choices(['branding']))
-        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], []);
+        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', ...stringListOption());
     addWaitLockOption(exportCmd).action(withErrorHandling(async (paths, options) => {
         const { category, tier, lintIgnore, ...rest } = options;
         const projectRoot = getProjectRoot();

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

@@ -10,6 +10,7 @@ import { getPersistableAppliedEntry, persistSingleComponentState, shouldPersistS
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftError, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
 import { FurnaceError } from '../../errors/furnace.js';
+import { getNodeErrorCode, toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, spinner, warn } from '../../utils/logger.js';
 /** Interval (ms) for the periodic checksum poll that catches events missed by fs.watch. */
@@ -48,11 +49,11 @@ function checksumMapsEqual(a, b) {
  * collapsed all causes into one string and made diagnosis difficult.
  */
 function classifyWatchApplyError(err) {
-    const message = err instanceof Error ? err.message : String(err);
+    const message = toError(err).message;
     if (err instanceof FurnaceError) {
         return `Apply failed: ${message}`;
     }
-    const code = err instanceof Error ? err.code : undefined;
+    const code = getNodeErrorCode(err);
     switch (code) {
         case 'EACCES':
         case 'EPERM':
@@ -165,7 +166,7 @@ async function runWatchLoop(projectRoot) {
             // Directory vanished between the pathExists check and fs.watch, or
             // fs.watch otherwise refused. refreshWatchers will retry on the next
             // poll tick.
-            warn(`Could not start watcher on ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+            warn(`Could not start watcher on ${dir}: ${toError(err).message}`);
             return false;
         }
     };

package/dist/src/commands/furnace/chrome-doc-remove.js

@@ -7,9 +7,10 @@ import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { loadConfig } from '../../core/config.js';
-import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 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, note, outro } from '../../utils/logger.js';
 import { buildChromeDocPlan, validateChromeDocName } from './chrome-doc.js';
@@ -86,7 +87,16 @@ async function performChromeDocRemoveMutations(args) {
         await removeEmptyDirIfPresent(join(args.engineDir, 'browser/base/content/test', `${args.binaryName}-xpcshell`), journal);
     }
     catch (error) {
-        await restoreRollbackJournalOrThrow(journal, `Failed to remove chrome-doc "${args.name}"`);
+        try {
+            await restoreRollbackJournalOrThrow(journal, `Failed to remove chrome-doc "${args.name}"`);
+        }
+        catch (rollbackError) {
+            // Matches the seven sibling mutation sites: a failed rollback leaves the
+            // engine in an unknown state, so record the repair breadcrumb and let
+            // the rollback error win rather than discarding it.
+            await recordFurnaceRollbackFailure(args.projectRoot, 'chrome-doc-rollback', `chrome-doc "${args.name}": ${toError(rollbackError).message}`);
+            throw rollbackError;
+        }
         throw error;
     }
     return { removedFiles, removedJarEntries, removedTestDir };
@@ -126,6 +136,7 @@ export async function furnaceChromeDocRemoveCommand(projectRoot, name, options =
         }
     }
     const result = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocRemoveMutations({
+        projectRoot,
         name,
         engineDir,
         plan,

package/dist/src/commands/furnace/chrome-doc.js

@@ -19,11 +19,12 @@
 import { join } from 'node:path';
 import { loadConfig } from '../../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
-import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
 import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
+import { toError } from '../../utils/errors.js';
 import { pathExists, readText, writeText } from '../../utils/fs.js';
 import { intro, note, outro, warn } from '../../utils/logger.js';
 import { generateBrowserWindowXhtml, generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, localesFtlWildcardCapturesScaffoldedName, } from './chrome-doc-templates.js';
@@ -273,7 +274,16 @@ async function performChromeDocMutations(args) {
         }
     }
     catch (error) {
-        await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
+        try {
+            await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
+        }
+        catch (rollbackError) {
+            // Matches the seven sibling mutation sites: when the rollback itself
+            // fails the engine is in an unknown state, so leave a breadcrumb for
+            // `doctor --repair-furnace` and let the rollback error win.
+            await recordFurnaceRollbackFailure(args.projectRoot, 'chrome-doc-rollback', `chrome-doc "${args.name}": ${toError(rollbackError).message}`);
+            throw rollbackError;
+        }
         throw error;
     }
     return written;
@@ -331,6 +341,7 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
         return;
     }
     const written = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocMutations({
+        projectRoot,
         name,
         license,
         engineDir,

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

@@ -21,7 +21,12 @@ export declare function resolveValidatedTestDir(rawTestDir: string | undefined,
  */
 export declare function resolveTestDirOverride(raw: string): string;
 /**
+ * Writes the browser-mochitest scaffold for a component: the test file, its
+ * `browser.toml` manifest entry, and the parent `moz.build` registration.
  *
+ * Every write is recorded in `journal` when one is supplied, so a failure
+ * partway through is rolled back rather than leaving a half-registered test
+ * the harness will try to run.
  */
 export declare function scaffoldTestFiles(componentName: string, license: ProjectLicense, forgeConfig: {
     binaryName: string;

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

@@ -57,7 +57,12 @@ export function resolveTestDirOverride(raw) {
 // Exported for direct unit testing of the --test-dir / collision-safety
 // behaviour (the full create command needs a furnace project fixture).
 /**
+ * Writes the browser-mochitest scaffold for a component: the test file, its
+ * `browser.toml` manifest entry, and the parent `moz.build` registration.
  *
+ * Every write is recorded in `journal` when one is supplied, so a failure
+ * partway through is rolled back rather than leaving a half-registered test
+ * the harness will try to run.
  */
 export async function scaffoldTestFiles(componentName, license, forgeConfig, paths, journal, testDirOverride) {
     const strippedName = componentName.startsWith('moz-') ? componentName.slice(4) : componentName;

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

@@ -222,7 +222,7 @@ async function resolveDescription(isInteractive, options) {
             placeholder: 'A brief description of the component',
         });
         if (!isCancel(descResult)) {
-            description = String(descResult);
+            description = descResult;
         }
     }
     return description;
@@ -267,7 +267,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
             cancel('Create cancelled');
             return;
         }
-        componentName = String(nameResult);
+        componentName = nameResult;
     }
     // Load the current furnace config only after the interactive name prompt
     // succeeds so a cancelled create in a fresh project does not strand a new

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

@@ -8,6 +8,7 @@ import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js
 import { isComponentSourceFile, resolveFtlDir } from '../../core/furnace-constants.js';
 import { getFileContentAtRef } from '../../core/git-file-ops.js';
 import { FurnaceError } from '../../errors/furnace.js';
+import { toError } from '../../utils/errors.js';
 import { pathExists, readText } from '../../utils/fs.js';
 import { formatErrorText, formatSuccessText, info, intro, outro } from '../../utils/logger.js';
 /**
@@ -72,7 +73,7 @@ async function diffOverride(name, projectRoot, config) {
         }
         catch (error) {
             throw new FurnaceError(`Cannot read baseline for "${entry.name}" at commit ${baseCommit.slice(0, 8)}: ` +
-                `${error instanceof Error ? error.message : String(error)}. ` +
+                `${toError(error).message}. ` +
                 `The commit may no longer exist in the engine history (e.g. after a re-download). ` +
                 `Run "fireforge furnace refresh --reset-base ${name}" to establish a new baseline.`, name);
         }

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

@@ -9,7 +9,7 @@ import { registerSharedCSS } from '../../core/register-shared-css.js';
 import { getTokensCssPath } from '../../core/token-manager.js';
 import { generateDefaultTokensCss } from '../../core/token-scaffold.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
+import { getNodeErrorCode, toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
 import { cancel, info, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
 /**
@@ -77,8 +77,8 @@ async function validateFtlBasePath(value, engineDir) {
     if (engineDir) {
         const resolved = join(engineDir, value);
         try {
-            const info = await stat(resolved);
-            if (!info.isDirectory()) {
+            const stats = await stat(resolved);
+            if (!stats.isDirectory()) {
                 throw new FurnaceError(`ftlBasePath "${value}" resolves to a non-directory at ${resolved}. FireForge expects a locale directory (for example toolkit/locales/en-US/toolkit/global or browser/locales/en-US/browser).`);
             }
         }
@@ -89,9 +89,7 @@ async function validateFtlBasePath(value, engineDir) {
                 throw error;
             // ENOENT is expected on a fresh project before `fireforge
             // download` has populated engine/; only warn.
-            const code = typeof error === 'object' && error !== null && 'code' in error
-                ? error.code
-                : undefined;
+            const code = getNodeErrorCode(error);
             if (code === 'ENOENT') {
                 warn(`ftlBasePath "${value}" does not yet exist at ${resolved}. This is fine if you have not run "fireforge download" yet; rerun "fireforge furnace init --force" after the engine is extracted to re-validate.`);
             }

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

@@ -282,7 +282,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
             placeholder: 'What are you changing about this component?',
         });
         if (!isCancel(descResult)) {
-            description = String(descResult);
+            description = descResult;
         }
     }
     // --- Copy original files ---
@@ -417,7 +417,7 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
         catch (error) {
             failed.push({
                 name: componentName,
-                error: error instanceof Error ? error.message : String(error),
+                error: toError(error).message,
             });
         }
     }

package/dist/src/commands/furnace/remove-mutations.d.ts

@@ -0,0 +1,40 @@
+import type { loadFurnaceConfig } from '../../core/furnace-config.js';
+import { getFurnacePaths } from '../../core/furnace-config.js';
+import type { RollbackJournal } from '../../core/furnace-rollback.js';
+import type { FurnaceState } from '../../types/furnace.js';
+/**
+ * Engine-side and workspace-side removal for an OVERRIDE component.
+ *
+ * Extracted in 0.41.0: this and its custom-component sibling were the only
+ * large inline blocks in the furnace subsystem never wrapped in a
+ * `perform*Mutations` helper, and together they held `remove.ts` at 496/500
+ * file lines with `furnaceRemoveCommand` at 149/150 — one line from a build
+ * failure. Both run inside the caller's rollback journal rather than opening
+ * their own, so a failure anywhere still restores the whole operation.
+ */
+export declare function performOverrideRemovalMutations(args: {
+    name: string;
+    paths: {
+        engine: string;
+    };
+    furnacePaths: ReturnType<typeof getFurnacePaths>;
+    freshConfig: Awaited<ReturnType<typeof loadFurnaceConfig>>;
+    freshState: FurnaceState;
+    ftlDir: string;
+    journal: RollbackJournal;
+}): Promise<void>;
+/**
+ * Engine-side and workspace-side removal for a CUSTOM component.
+ * Sibling of {@link performOverrideRemovalMutations}; see its note.
+ */
+export declare function performCustomRemovalMutations(args: {
+    projectRoot: string;
+    name: string;
+    paths: {
+        engine: string;
+    };
+    furnacePaths: ReturnType<typeof getFurnacePaths>;
+    freshConfig: Awaited<ReturnType<typeof loadFurnaceConfig>>;
+    ftlDir: string;
+    journal: RollbackJournal;
+}): Promise<void>;

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

@@ -0,0 +1,171 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Engine-side and workspace-side mutation bodies for `furnace remove`.
+ *
+ * Split out of `remove.ts` in 0.41.0. The two `perform*RemovalMutations`
+ * functions were the only large inline blocks in the furnace subsystem never
+ * wrapped in a helper, and together they held `remove.ts` at 496/500 file
+ * lines with `furnaceRemoveCommand` at 149/150 — one line from a build
+ * failure. Extracting them inside the same file traded a function-length
+ * problem for a file-length one, so they live here instead.
+ *
+ * Both run inside the CALLER's rollback journal rather than opening their
+ * own, so a failure anywhere in the remove still restores the whole
+ * operation as a single unit.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { removeCustomFtlJarMnEntry } from '../../core/furnace-apply-ftl.js';
+import { getOverrideEngineTargetPath, isOverrideCopyCandidate, restoreOverrideFileToBaseline, } from '../../core/furnace-apply-helpers.js';
+import { extractComponentChecksums } from '../../core/furnace-checksum-utils.js';
+import { getFurnacePaths } from '../../core/furnace-config.js';
+import { removeCustomElementRegistration, removeJarMnEntries, } from '../../core/furnace-registration.js';
+import { snapshotDir, snapshotFile } from '../../core/furnace-rollback.js';
+import { isGitRepository } from '../../core/git.js';
+import { FurnaceError } from '../../errors/furnace.js';
+import { pathExists, removeDir, removeFile } from '../../utils/fs.js';
+import { info } from '../../utils/logger.js';
+import { removeDeployedCustomFiles } from './remove-state.js';
+/**
+ * Restores every override-deployed file in `engine/` to its pristine HEAD
+ * state, inverting what `applyOverrideComponent` would have written. Files that
+ * existed in HEAD are restored via `git restore`; files the override
+ * introduced (not in HEAD) are deleted outright.
+ *
+ * The restore set is the **union** of (a) files currently in the override
+ * workspace directory and (b) filenames recorded in `previousChecksumKeys`
+ * — i.e. files we know we deployed last time, even if the developer has
+ * since deleted them from the workspace. Without (b), a workspace deletion
+ * leaves an orphaned engine copy that `furnace remove` would never see.
+ *
+ * Every touched engine file is snapshotted into the rollback journal before
+ * mutation so a mid-remove failure still rolls the engine back to its
+ * pre-command state.
+ */
+async function restoreOverrideEngineFiles(engineDir, overrideDir, overrideConfig, previousChecksumKeys, ftlDir, journal) {
+    // Engine-as-git is a hard precondition for restoration: git HEAD is the only
+    // honest oracle for "what was there before the override". If the engine is
+    // not a git repo we refuse rather than silently leaving files behind — the
+    // previous warn-and-continue behaviour is exactly what this fix removes.
+    if (!(await isGitRepository(engineDir))) {
+        throw new FurnaceError('Cannot restore override files: engine is not a git repository. Run "fireforge download" to initialise it.');
+    }
+    // Build the union of "files we still see on disk" and "files state.json
+    // claims we deployed". The state set is the only authority for files that
+    // were deployed and later deleted from the workspace; the workspace set is
+    // the only authority for files added since last apply that have not yet
+    // been recorded in state. We need both.
+    const fileSet = new Set();
+    if (await pathExists(overrideDir)) {
+        const entries = await readdir(overrideDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!isOverrideCopyCandidate(entry.name, overrideConfig.type))
+                continue;
+            fileSet.add(entry.name);
+        }
+    }
+    for (const key of previousChecksumKeys) {
+        fileSet.add(key);
+    }
+    let restored = 0;
+    let removed = 0;
+    for (const fileName of fileSet) {
+        const enginePath = getOverrideEngineTargetPath(engineDir, overrideConfig, fileName, ftlDir);
+        const action = await restoreOverrideFileToBaseline(engineDir, enginePath, journal);
+        if (action === 'restored')
+            restored += 1;
+        else if (action === 'removed')
+            removed += 1;
+    }
+    return { restored, removed };
+}
+/**
+ * Engine-side and workspace-side removal for an OVERRIDE component.
+ *
+ * Extracted in 0.41.0: this and its custom-component sibling were the only
+ * large inline blocks in the furnace subsystem never wrapped in a
+ * `perform*Mutations` helper, and together they held `remove.ts` at 496/500
+ * file lines with `furnaceRemoveCommand` at 149/150 — one line from a build
+ * failure. Both run inside the caller's rollback journal rather than opening
+ * their own, so a failure anywhere still restores the whole operation.
+ */
+export async function performOverrideRemovalMutations(args) {
+    const { name, paths, furnacePaths, freshConfig, freshState, ftlDir, journal } = args;
+    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
+    // the workspace and (b) files state.json says we deployed last time
+    // — without (b), source-side deletions would orphan engine copies
+    // that this command can never see again.
+    if (overrideConfig?.basePath) {
+        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`);
+        }
+        if (removed > 0) {
+            info(`Removed ${removed} override-introduced file${removed === 1 ? '' : 's'} from engine/${overrideConfig.basePath}`);
+        }
+    }
+    if (await pathExists(dir)) {
+        await snapshotDir(journal, dir);
+        await removeDir(dir);
+        info(`Deleted components/overrides/${name}/`);
+    }
+}
+/**
+ * Engine-side and workspace-side removal for a CUSTOM component.
+ * Sibling of {@link performOverrideRemovalMutations}; see its note.
+ */
+export async function performCustomRemovalMutations(args) {
+    const { projectRoot, name, paths, furnacePaths, freshConfig, ftlDir, journal } = args;
+    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
+    // the command runs. The git-as-engine precondition is enforced
+    // before the lock is acquired (see furnaceRemoveCommand above)
+    // so if we reach this point, the engine is a git repository.
+    if (customConfig?.register) {
+        // customElements.js is the only file removeCustomElementRegistration touches.
+        await snapshotFile(journal, join(paths.engine, 'toolkit/content/customElements.js'));
+        await removeCustomElementRegistration(paths.engine, name);
+        info(`Deregistered ${name} from customElements.js`);
+    }
+    // jar.mn is the only file removeJarMnEntries touches.
+    await snapshotFile(journal, join(paths.engine, 'toolkit/content/jar.mn'));
+    await removeJarMnEntries(paths.engine, name);
+    info(`Removed ${name} entries from toolkit/content/jar.mn`);
+    const dir = join(furnacePaths.customDir, name);
+    if (await pathExists(dir)) {
+        await snapshotDir(journal, dir);
+        await removeDir(dir);
+        info(`Deleted components/custom/${name}/`);
+    }
+    // Clean up deployed files in engine (per-file — see helper doc).
+    if (customConfig?.targetPath) {
+        await removeDeployedCustomFiles(projectRoot, paths.engine, name, customConfig.targetPath, journal);
+    }
+    // Localized components deploy a .ftl outside targetPath into the
+    // shared Fluent tree; apply writes it, so remove must delete it too
+    // or the locale payload is orphaned.
+    if (customConfig?.localized) {
+        const ftlRel = join(ftlDir, `${name}.ftl`);
+        const ftlPath = join(paths.engine, ftlRel);
+        if (await pathExists(ftlPath)) {
+            await snapshotFile(journal, ftlPath);
+            await removeFile(ftlPath);
+            info(`Deleted localized file engine/${ftlRel}`);
+        }
+        // Drop the locale jar.mn chrome registration that `applyCustomFtlFile`
+        // wrote during deploy — otherwise the engine is left with a
+        // `locale/.../${name}.ftl` entry pointing at a file we just
+        // deleted. 2026-04-21 eval (Finding #1): `furnace remove` left
+        // `browser/locales/jar.mn` referencing the missing FTL, which
+        // would break the next package-manifest validation.
+        await removeCustomFtlJarMnEntry(paths.engine, `${name}.ftl`, ftlDir, customConfig, journal);
+    }
+}