@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { CustomComponentConfig, DryRunAction, OverrideComponentConfig, StepError } from '../types/furnace.js';
+import type { ComponentApplyContext, CustomComponentConfig, DryRunAction, OverrideComponentConfig, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';
 interface DirectoryEntry {
     isFile(): boolean;
@@ -7,8 +7,8 @@ interface DirectoryEntry {
 }
 /**
  * True for a plain-file directory entry — symlinks and directories are
- * never copy candidates. Exported for the patch-owned overwrite probe
- *, which walks the same override copy-candidate set as apply.
+ * never copy candidates. Exported for the patch-owned overwrite probe,
+ * which walks the same override copy-candidate set as apply.
  */
 export declare function isRegularFile(entry: DirectoryEntry): boolean;
 /**
@@ -86,14 +86,14 @@ export declare function hasComponentChanged(componentDir: string, previousChecks
  * the comparison when the engine hash still matches, which is the common case
  * for projects with many components.
  */
-export declare function hasOverrideEngineDrift(engineDir: string, componentDir: string, config: OverrideComponentConfig, ftlDir: string, cachedEngineChecksums?: Record<string, string>): Promise<boolean>;
+export declare function hasOverrideEngineDrift(ctx: Pick<ComponentApplyContext, 'engineDir' | 'componentDir' | 'ftlDir'>, config: OverrideComponentConfig, cachedEngineChecksums?: Record<string, string>): Promise<boolean>;
 /**
  * Detects whether a custom component's deployed copies, jar.mn entries, or
  * customElements.js registration are missing from the engine or out of sync.
  * Delegates to `checkRegistrationConsistency` so the oracle stays aligned with
  * the validate command.
  */
-export declare function hasCustomEngineDrift(root: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string): Promise<boolean>;
+export declare function hasCustomEngineDrift(ctx: Pick<ComponentApplyContext, 'root' | 'name' | 'componentDir' | 'ftlDir'>, config: CustomComponentConfig): Promise<boolean>;
 /** Extra knobs threaded into `applyCustomComponent` from the project config. */
 export interface CustomApplyOptions {
     /**
@@ -104,13 +104,13 @@ export interface CustomApplyOptions {
     markerComment?: string;
 }
 /** Applies a custom component into the engine tree and captures registration step errors. */
-export declare function applyCustomComponent(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal, applyOptions?: CustomApplyOptions): Promise<{
+export declare function applyCustomComponent(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, config: CustomComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal, applyOptions?: CustomApplyOptions): Promise<{
     affectedPaths: string[];
     stepErrors: StepError[];
     actions?: DryRunAction[];
 }>;
 /** Applies an override component by copying its matching files onto the engine tree. */
-export declare function applyOverrideComponent(engineDir: string, name: string, componentDir: string, config: OverrideComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
+export declare function applyOverrideComponent(ctx: Pick<ComponentApplyContext, 'engineDir' | 'name' | 'componentDir' | 'ftlDir'>, config: OverrideComponentConfig, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
     affectedPaths: string[];
     actions?: DryRunAction[];
 }>;

package/dist/src/core/furnace-apply-helpers.js

@@ -8,6 +8,7 @@ import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/
 import { verbose } from '../utils/logger.js';
 import { buildCustomDryRunActions } from './furnace-apply-dry-run.js';
 import { applyCustomFtlFile, applySharedFtlPrune, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
+import { normalizeForChecksum } from './furnace-checksum-utils.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
 import { deployFileWithFragments, SHARED_FRAGMENTS_DIR } from './furnace-css-fragments.js';
 import { addCustomElementRegistration, addJarMnEntries } from './furnace-registration.js';
@@ -17,8 +18,8 @@ import { isGitRepository } from './git.js';
 import { fileExistsInHead, restoreTrackedPath } from './git-file-ops.js';
 /**
  * True for a plain-file directory entry — symlinks and directories are
- * never copy candidates. Exported for the patch-owned overwrite probe
- *, which walks the same override copy-candidate set as apply.
+ * never copy candidates. Exported for the patch-owned overwrite probe,
+ * which walks the same override copy-candidate set as apply.
  */
 export function isRegularFile(entry) {
     if (!entry.isFile())
@@ -98,8 +99,7 @@ export async function computeComponentChecksums(componentDir) {
         if (!isChecksummedComponentFile(entry.name))
             continue;
         const content = await readText(join(componentDir, entry.name));
-        const normalized = content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
-        const hash = createHash('sha256').update(normalized).digest('hex');
+        const hash = createHash('sha256').update(normalizeForChecksum(content)).digest('hex');
         checksums[entry.name] = hash;
     }
     return checksums;
@@ -200,9 +200,6 @@ function componentChecksumsChanged(current, previousChecksums) {
     }
     return false;
 }
-function normalizeForChecksum(content) {
-    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
-}
 /**
  * Detects whether an override component's deployed files are missing from the
  * engine or differ from the source. Used as a guard before skipping apply on a
@@ -215,7 +212,8 @@ function normalizeForChecksum(content) {
  * the comparison when the engine hash still matches, which is the common case
  * for projects with many components.
  */
-export async function hasOverrideEngineDrift(engineDir, componentDir, config, ftlDir, cachedEngineChecksums) {
+export async function hasOverrideEngineDrift(ctx, config, cachedEngineChecksums) {
+    const { engineDir, componentDir, ftlDir } = ctx;
     const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
     for (const entry of entries) {
         if (!isRegularFile(entry))
@@ -251,7 +249,8 @@ export async function hasOverrideEngineDrift(engineDir, componentDir, config, ft
  * Delegates to `checkRegistrationConsistency` so the oracle stays aligned with
  * the validate command.
  */
-export async function hasCustomEngineDrift(root, name, componentDir, config, ftlDir) {
+export async function hasCustomEngineDrift(ctx, config) {
+    const { root, name, componentDir, ftlDir } = ctx;
     const status = await checkRegistrationConsistency(root, name, config, ftlDir);
     if (!status.targetExists || !status.filesInSync) {
         return true;
@@ -289,7 +288,10 @@ export async function hasCustomEngineDrift(root, name, componentDir, config, ftl
     return false;
 }
 /** Applies a custom component into the engine tree and captures registration step errors. */
-export async function applyCustomComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal, applyOptions = {}) {
+export async function applyCustomComponent(ctx, config, dryRun = false, rollbackJournal, applyOptions = {}) {
+    // `ftlDir` stays on the context (the FTL and dry-run callees below read
+    // it) but is not needed by name here.
+    const { engineDir, name, componentDir } = ctx;
     if (!/^[a-z][a-z0-9-]*$/.test(name)) {
         throw new FurnaceError(`Invalid component name "${name}": must match /^[a-z][a-z0-9-]*$/`);
     }
@@ -300,7 +302,7 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
         verbose(`Skipped ${customSymlinks.length} symlink(s) in "${name}": ${customSymlinks.map((e) => e.name).join(', ')}`);
     }
     if (dryRun) {
-        const { actions, stepErrors } = await buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir);
+        const { actions, stepErrors } = await buildCustomDryRunActions(ctx, config, targetDir, entries);
         return { affectedPaths: [], stepErrors, actions };
     }
     if (rollbackJournal && !(await pathExists(targetDir))) {
@@ -323,8 +325,8 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     }
     // Copy phase (parallel — independent file writes to different paths).
     // CSS files carrying @fireforge-include directives are written as their
-    // fragment-expanded form (field report D2); the workspace source keeps
-    // only the directive, so shared CSS stays single-sourced.
+    // fragment-expanded form; the workspace source keeps only the directive,
+    // so shared CSS stays single-sourced.
     const sharedDir = join(componentDir, '..', '..', SHARED_FRAGMENTS_DIR);
     await Promise.all(filesToCopy.map(async (entry) => {
         const src = join(componentDir, entry.name);
@@ -337,13 +339,13 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     // the shared bundle is owned elsewhere and FireForge must not copy or
     // register a per-component `.ftl` on its behalf.
     if (config.localized && !config.sharedFtl) {
-        await applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal);
+        await applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbackJournal);
     }
     else if (config.localized && config.sharedFtl) {
         // Drop any dangling per-widget locale jar.mn entry that would point at a
         // non-existent `<chromeSubPath>/<name>.ftl` and fail `mach build`. The
         // shared bundle (a different chrome path/base name) is never touched.
-        await applySharedFtlPrune(engineDir, name, ftlDir, config, affectedPaths, stepErrors, rollbackJournal);
+        await applySharedFtlPrune(ctx, config, affectedPaths, stepErrors, rollbackJournal);
     }
     if (config.register) {
         try {
@@ -383,7 +385,8 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     return { affectedPaths, stepErrors };
 }
 /** Applies an override component by copying its matching files onto the engine tree. */
-export async function applyOverrideComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal) {
+export async function applyOverrideComponent(ctx, config, dryRun = false, rollbackJournal) {
+    const { engineDir, name, componentDir, ftlDir } = ctx;
     const targetDir = join(engineDir, config.basePath);
     if (!(await pathExists(targetDir))) {
         throw new FurnaceError(`Override target path not found in engine: ${config.basePath}`, name);

package/dist/src/core/furnace-apply-overwrite-warn.d.ts

@@ -2,19 +2,18 @@
  * Patch-owned overwrite warnings for `furnace apply`.
  *
  * For Furnace-managed components, apply OVERWRITES the deployed engine
- * copies with the `components/` sources. A fix made directly in `engine/`
- * and exported into a patch — but never back-ported to the component
- * source — is silently undone by the next apply, and the only prior
- * signal was a drift line that read like "someone's uncommitted work".
- * This module detects that exact case BEFORE the copy: the deployed
- * bytes differ from the component source AND the file is patch-owned,
- * and produces a loud per-file warning naming the file, the owning
+ * copies with the `components/` sources. A fix made directly in `engine/` and
+ * exported into a patch — but never back-ported to the component source — is
+ * silently undone by the next apply, and a plain drift line reads like
+ * "someone's uncommitted work". This module detects that exact case BEFORE
+ * the copy (deployed bytes differ from the component source AND the file is
+ * patch-owned) and produces a per-file warning naming the file, the owning
  * patch, and the consequence.
  *
  * The per-file byte comparison already exists —
  * `checkRegistrationConsistency` for custom components (fragment- and
- * ftl-aware) and the copy-candidate walk for overrides — this module
- * only surfaces what was previously computed and thrown away.
+ * ftl-aware) and the copy-candidate walk for overrides — so this module only
+ * surfaces what was previously computed and thrown away.
  */
 import type { CustomComponentConfig, OverrideComponentConfig } from '../types/furnace.js';
 /** One deployed, patch-owned file about to be overwritten with different bytes. */

package/dist/src/core/furnace-apply-overwrite-warn.js

@@ -3,19 +3,18 @@
  * Patch-owned overwrite warnings for `furnace apply`.
  *
  * For Furnace-managed components, apply OVERWRITES the deployed engine
- * copies with the `components/` sources. A fix made directly in `engine/`
- * and exported into a patch — but never back-ported to the component
- * source — is silently undone by the next apply, and the only prior
- * signal was a drift line that read like "someone's uncommitted work".
- * This module detects that exact case BEFORE the copy: the deployed
- * bytes differ from the component source AND the file is patch-owned,
- * and produces a loud per-file warning naming the file, the owning
+ * copies with the `components/` sources. A fix made directly in `engine/` and
+ * exported into a patch — but never back-ported to the component source — is
+ * silently undone by the next apply, and a plain drift line reads like
+ * "someone's uncommitted work". This module detects that exact case BEFORE
+ * the copy (deployed bytes differ from the component source AND the file is
+ * patch-owned) and produces a per-file warning naming the file, the owning
  * patch, and the consequence.
  *
  * The per-file byte comparison already exists —
  * `checkRegistrationConsistency` for custom components (fragment- and
- * ftl-aware) and the copy-candidate walk for overrides — this module
- * only surfaces what was previously computed and thrown away.
+ * ftl-aware) and the copy-candidate walk for overrides — so this module only
+ * surfaces what was previously computed and thrown away.
  */
 import { readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';

package/dist/src/core/furnace-apply-undeploy-actions.d.ts

@@ -1,8 +1,7 @@
 /**
- * Dry-run action builders for files deleted from a component workspace
- * since the last apply. Split out of `furnace-apply.ts` (at the per-file
- * line budget after the overwrite-warning wiring); the real
- * undeploy paths stay in `furnace-apply-helpers.ts`.
+ * Dry-run action builders for files deleted from a component workspace since
+ * the last apply. Split out of `furnace-apply.ts` to stay under the per-file
+ * line budget; the real undeploy paths stay in `furnace-apply-helpers.ts`.
  */
 import type { CustomComponentConfig, DryRunAction, OverrideComponentConfig } from '../types/furnace.js';
 /** Plans the engine-restore actions for deleted override workspace files. */

package/dist/src/core/furnace-apply-undeploy-actions.js

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Dry-run action builders for files deleted from a component workspace
- * since the last apply. Split out of `furnace-apply.ts` (at the per-file
- * line budget after the overwrite-warning wiring); the real
- * undeploy paths stay in `furnace-apply-helpers.ts`.
+ * Dry-run action builders for files deleted from a component workspace since
+ * the last apply. Split out of `furnace-apply.ts` to stay under the per-file
+ * line budget; the real undeploy paths stay in `furnace-apply-helpers.ts`.
  */
 import { join } from 'node:path';
 import { getOverrideEngineTargetPath } from './furnace-apply-helpers.js';

package/dist/src/core/furnace-apply.d.ts

@@ -1,14 +1,12 @@
 import type { ApplyResult, DryRunAction } from '../types/furnace.js';
 import { type FurnaceOperationContext } from './furnace-operation.js';
 import { type RollbackJournal } from './furnace-rollback.js';
-export { computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
+export { computeComponentChecksums, hasComponentChanged, prefixChecksums, } from './furnace-apply-helpers.js';
 /**
  * Result of {@link applyAllComponents}.
  *
- * Named because the anonymous intersection this replaced forced eight
- * `Awaited<ReturnType<typeof applyAllComponents>>` indirections across
- * `furnace/deploy.ts`, `furnace/preview.ts`, `furnace-state-persist.ts` and
- * `build-prepare.ts` — none of which could be read without opening this file.
+ * Named so consumers can refer to the shape directly instead of going
+ * through `Awaited<ReturnType<typeof applyAllComponents>>`.
  *
  * `actions` is populated only on a dry run; `rollbackJournal` only when
  * `persistState: false` hands journal ownership back to the caller.
@@ -46,7 +44,6 @@ export declare function applyAllComponents(root: string, dryRun?: boolean, optio
 }): Promise<ApplyAllComponentsResult>; /**
  * Shared context threaded through the batch apply loops. Bundles the state
  * both loops mutate (result/actions/checksums) with the immutable run
- * parameters — the previous 12–13 positional parameters let call sites
- * drift (the named-apply state-wipe bug) and made every new parameter a
- * two-signature change.
+ * parameters; the 12–13 positional parameters this replaced let call sites
+ * drift and made every new parameter a two-signature change.
  */

package/dist/src/core/furnace-apply.js

@@ -14,11 +14,12 @@ import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from './furnace-constants.j
 import { topologicalSortCustom } from './furnace-graph-utils.js';
 import { resolveFurnaceMarkerComment } from './furnace-marker.js';
 import { recordFurnaceRollbackFailure } from './furnace-operation.js';
+import { assertFurnaceEngineDirReady } from './furnace-precondition.js';
 import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
 import { blockingStepErrors, hasBlockingStepErrors } from './furnace-step-errors.js';
 import { runPostApplyConsistencyChecks } from './furnace-validate-registration.js';
-export { computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
+export { computeComponentChecksums, hasComponentChanged, prefixChecksums, } from './furnace-apply-helpers.js';
 function addMissingComponentError(result, name, directoryPath) {
     result.errors.push({
         name,
@@ -50,7 +51,7 @@ async function applyOverrideBatch(ctx) {
                 // reset/download/manual edits can silently erase engine files; the
                 // checksum record alone cannot detect that.
                 const cachedEngine = extractComponentChecksums(state.engineChecksums, 'override', name);
-                const drifted = await hasOverrideEngineDrift(engineDir, componentDir, overrideConfig, ftlDir, cachedEngine);
+                const drifted = await hasOverrideEngineDrift({ engineDir, componentDir, ftlDir }, overrideConfig, cachedEngine);
                 if (!drifted) {
                     result.skipped.push({ name, reason: 'No changes since last apply' });
                     Object.assign(newChecksums, prefixChecksums(previous, 'override', name));
@@ -76,7 +77,7 @@ async function applyOverrideBatch(ctx) {
             if (!dryRun) {
                 // Runs unconditionally — including when the component source
                 // changed — because the lost-work case is precisely a deployed
-                // engine edit that the incoming copy is about to replace (J6).
+                // engine edit that the incoming copy is about to replace.
                 recordOverwriteWarnings(result, await findPatchOwnedOverwrites({
                     type: 'override',
                     engineDir,
@@ -87,7 +88,7 @@ async function applyOverrideBatch(ctx) {
                     patchClaims: ctx.patchClaims,
                 }));
             }
-            const { affectedPaths: filesAffected, actions } = await applyOverrideComponent(engineDir, name, componentDir, overrideConfig, ftlDir, dryRun, rollbackJournal);
+            const { affectedPaths: filesAffected, actions } = await applyOverrideComponent({ engineDir, name, componentDir, ftlDir }, overrideConfig, dryRun, rollbackJournal);
             if (dryRun && actions) {
                 allActions.push(...actions);
             }
@@ -208,7 +209,7 @@ async function applyCustomBatch(ctx, root, markerComment) {
                 // As with overrides, the checksum record is not sufficient on its
                 // own: a reset/download that cleared the engine must trigger a
                 // re-apply even though the workspace is unchanged.
-                const drifted = await hasCustomEngineDrift(root, name, componentDir, customConfig, ftlDir);
+                const drifted = await hasCustomEngineDrift({ root, name, componentDir, ftlDir }, customConfig);
                 if (!drifted) {
                     result.skipped.push({ name, reason: 'No changes since last apply' });
                     Object.assign(newChecksums, prefixChecksums(previous, 'custom', name));
@@ -244,7 +245,7 @@ async function applyCustomBatch(ctx, root, markerComment) {
                     patchClaims: ctx.patchClaims,
                 }));
             }
-            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, dryRun, rollbackJournal, markerComment !== undefined ? { markerComment } : {});
+            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent({ engineDir, name, componentDir, ftlDir }, customConfig, dryRun, rollbackJournal, markerComment !== undefined ? { markerComment } : {});
             if (dryRun && actions) {
                 allActions.push(...actions);
             }
@@ -304,19 +305,14 @@ export async function applyAllComponents(root, dryRun = false, options) {
     const { engine: engineDir } = getProjectPaths(root);
     const furnacePaths = getFurnacePaths(root);
     const ftlDir = resolveFtlDir(config.ftlBasePath);
-    // 2026-04-26 eval Finding 6: when `markerComment` is unset in
-    // fireforge.json, default it to `binaryName.toUpperCase()` so the
-    // furnace-emitted edits to upstream files (e.g. customElements.js)
-    // carry a marker that satisfies `lintModificationComments` — that
-    // rule keys on `${binaryName.toUpperCase()}:` and was firing
-    // `[missing-modification-comment]` on every furnace-applied
-    // upstream edit because the implicit default was `undefined`. An
-    // explicit `markerComment` in fireforge.json still wins.
+    // When `markerComment` is unset in fireforge.json, default it to
+    // `binaryName.toUpperCase()` so the furnace-emitted edits to upstream
+    // files (e.g. customElements.js) carry a marker that satisfies
+    // `lintModificationComments` — that rule keys on
+    // `${binaryName.toUpperCase()}:`. An explicit `markerComment` still wins.
     const forgeConfig = await loadConfig(root).catch(() => undefined);
     const markerComment = resolveFurnaceMarkerComment(forgeConfig);
-    if (!(await pathExists(engineDir))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
+    await assertFurnaceEngineDirReady(engineDir);
     const rollbackJournal = dryRun ? undefined : createRollbackJournal();
     if (rollbackJournal && operationContext) {
         operationContext.registerJournal(rollbackJournal);
@@ -376,10 +372,10 @@ export async function applyAllComponents(root, dryRun = false, options) {
     }
     // Recompute AFTER the consistency checks: they MUTATE entry.stepErrors
     // when the applied output is inconsistent (e.g. a jar.mn entry that
-    // silently mis-landed). Reading the pre-check snapshot meant those
-    // failures skipped rollback and persisted checksums for a component
-    // known to be inconsistent — while the CLI simultaneously reported
-    // "failed to apply cleanly".
+    // silently mis-landed). Reading the pre-check snapshot lets those failures
+    // skip rollback and persist checksums for a component known to be
+    // inconsistent, while the CLI simultaneously reports "failed to apply
+    // cleanly".
     const hasStepErrors = result.applied.some((entry) => hasBlockingStepErrors(entry));
     // --- Rollback on failure, persist on success (skip for dry-run) ---
     if (!dryRun) {
@@ -426,7 +422,6 @@ export async function applyAllComponents(root, dryRun = false, options) {
 } /**
  * Shared context threaded through the batch apply loops. Bundles the state
  * both loops mutate (result/actions/checksums) with the immutable run
- * parameters — the previous 12–13 positional parameters let call sites
- * drift (the named-apply state-wipe bug) and made every new parameter a
- * two-signature change.
+ * parameters; the 12–13 positional parameters this replaced let call sites
+ * drift and made every new parameter a two-signature change.
  */

package/dist/src/core/furnace-checksum-utils.d.ts

@@ -9,3 +9,17 @@ export declare function prefixChecksums(checksums: Record<string, string>, type:
  * (sorted alphabetically) so test snapshots and CLI output are deterministic.
  */
 export declare function diffDeletedFiles(previous: Record<string, string>, current: Record<string, string>): string[];
+/**
+ * Canonical content normalization for every FireForge component checksum.
+ *
+ * Strips a leading BOM and folds CRLF to LF, so a file that differs from its
+ * deployed copy only by line endings or a byte-order mark is not reported as
+ * drift. Every comparison that decides "has this component changed?" must
+ * use it — otherwise `furnace status` and `furnace validate` can disagree
+ * with `apply`'s skip fast-path about the same pair of files on a CRLF
+ * checkout.
+ *
+ * @param content - Raw file content
+ * @returns Content with the BOM removed and CRLF folded to LF
+ */
+export declare function normalizeForChecksum(content: string): string;

package/dist/src/core/furnace-checksum-utils.js

@@ -36,3 +36,19 @@ export function diffDeletedFiles(previous, current) {
     }
     return deleted.sort();
 }
+/**
+ * Canonical content normalization for every FireForge component checksum.
+ *
+ * Strips a leading BOM and folds CRLF to LF, so a file that differs from its
+ * deployed copy only by line endings or a byte-order mark is not reported as
+ * drift. Every comparison that decides "has this component changed?" must
+ * use it — otherwise `furnace status` and `furnace validate` can disagree
+ * with `apply`'s skip fast-path about the same pair of files on a CRLF
+ * checkout.
+ *
+ * @param content - Raw file content
+ * @returns Content with the BOM removed and CRLF folded to LF
+ */
+export function normalizeForChecksum(content) {
+    return content.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n');
+}

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

@@ -53,8 +53,7 @@ export declare function loadFurnaceConfig(root: string): Promise<FurnaceConfig>;
  * reset, rebase, rebase --abort): every applied checksum describes content
  * that no longer exists, but pendingRepair tracks authoring-side rollback
  * issues in the component WORKSPACE and must survive an engine refresh.
- * No-ops when the state file does not exist. Centralized because the same
- * reset logic had drifted into four separate command files.
+ * No-ops when the state file does not exist.
  */
 export declare function clearAppliedFurnaceState(root: string): Promise<void>;
 /**
@@ -65,20 +64,15 @@ export declare function clearAppliedFurnaceState(root: string): Promise<void>;
 export declare function writeFurnaceConfig(root: string, config: FurnaceConfig): Promise<void>;
 /**
  * Stamps every override's `baseVersion` to the supplied version. Used by
- * `fireforge rebase` after a successful patch re-export so a successful
- * ESR bump does not leave Furnace overrides in a doctor-failing drift
- * state. Returns the number of overrides stamped (zero if furnace.json
- * has no overrides, or if the file is missing).
+ * `fireforge rebase` after a successful patch re-export, so an ESR bump does
+ * not leave Furnace overrides in a doctor-failing drift state: `rebase`
+ * stamps patch `sourceEsrVersion` via `stampPatchVersions`, and without the
+ * matching override stamp `doctor` fails Furnace component validation on
+ * every override.
  *
- * Motivating case: a 140.9.0esr → 140.9.1esr rebase stamps patch
- * `sourceEsrVersion` via `stampPatchVersions`, but before 0.16.0 no
- * equivalent stamping ran for Furnace override `baseVersion`. `doctor`
- * then immediately failed Furnace component validation on every
- * override. The stamp is deliberately unconditional — `fireforge
- * furnace validate` is the right tool for "does this override still
- * apply", and rebase already attested that the patch layer re-validated
- * against the new ESR; the per-override health check belongs in a
- * separate pass, not inline with the stamp.
+ * The stamp is deliberately unconditional — `fireforge furnace validate` is
+ * the right tool for "does this override still apply", and rebase has
+ * already attested that the patch layer re-validated against the new ESR.
  *
  * @param root - Root directory of the project
  * @param version - Firefox version string to stamp onto every override
@@ -90,23 +84,20 @@ export declare function stampFurnaceOverrideBaseVersions(root: string, version:
  * Creates a default furnace configuration.
  *
  * When a `binaryName` is provided, the default config carries a
- * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
- * `fireforge token coverage` on a fresh project reports `0 tokens` and
- * labels every custom-property reference as `unknown` — the scan has
- * no prefix to key off. The 2026-04-21 eval walked directly into this
- * state (`furnace init` → `token add` → `token coverage` → zero
- * tokens), and only recovered after hand-editing furnace.json. Deriving
- * the prefix from the binary name matches the convention the scaffolded
- * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ * `tokenPrefix` derived as `--<binaryName>-`. Without it, `fireforge token
+ * coverage` on a fresh project reports `0 tokens` and labels every
+ * custom-property reference as `unknown`, because the scan has no prefix to
+ * key off. Deriving the prefix from the binary name matches the convention
+ * the scaffolded tokens CSS already uses for its `--<binaryName>-*`
+ * declarations.
  *
- * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
- * on the legacy no-arg call shape (existing tests, programmatic callers
- * bootstrapping from a not-yet-loaded config) still get a valid config
- * without a prefix; the CLI init path always has a `binaryName` from
- * `fireforge.json` and always sets one.
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers on
+ * the no-arg call shape still get a valid config without a prefix; the CLI
+ * init path always has a `binaryName` from `fireforge.json` and always sets
+ * one.
  *
- * @param options - Optional init context; pass `{ binaryName }` to
- *   derive the token prefix.
+ * @param options - Optional init context; pass `{ binaryName }` to derive
+ *   the token prefix.
  * @returns A valid FurnaceConfig
  */
 export declare function createDefaultFurnaceConfig(options?: {