@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -7,15 +7,14 @@
  * Every helper here degrades gracefully: if the locale jar.mn is missing or
  * the FTL tree is non-standard, apply logs an ADVISORY `stepError`
  * (`advisory: true`) rather than aborting the whole command. Advisory step
- * errors are reported as warnings and never trigger rollback — missing
- * jar.mn on a fork without a locale package should not block a working
- * `.mjs`/`.css` from shipping (the blocking/advisory split exists because
- * this contract used to be contradicted: any FTL step error rolled back
- * the whole apply).
+ * errors are reported as warnings and never trigger rollback — a missing
+ * jar.mn on a fork without a locale package must not block a working
+ * `.mjs`/`.css` from shipping.
  */
 import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { copyFile, pathExists, readText } from '../utils/fs.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath } from './furnace-constants.js';
 import { addLocaleFtlJarMnEntry, removeLocaleFtlJarMnEntry } from './furnace-registration.js';
@@ -46,10 +45,9 @@ function resolveSharedFtlPruneTarget(name, ftlDir) {
  * A `localized: true` widget that opts into a feature-scoped `sharedFtl`
  * bundle (its strings live under `browser/...` and load via
  * `insertFTLIfNeeded`) must NOT carry a per-widget
- * `locale/@AB_CD@/<chromeSubPath>/<name>.ftl` line. Such a line — written by
- * an older FireForge before the sharedFtl apply guard, or by a layout
- * migration — points at a `.ftl` that does not exist, so `mach build` fails
- * hard (`Cannot find <chromeSubPath>/<name>.ftl`) and blocks every build.
+ * `locale/@AB_CD@/<chromeSubPath>/<name>.ftl` line. Such a line points at a
+ * `.ftl` that does not exist, so `mach build` fails hard (`Cannot find
+ * <chromeSubPath>/<name>.ftl`) and blocks every build.
  *
  * The pruned line is the per-widget toolkit entry only; the shared bundle's
  * own line (a different chrome sub-path / base name) is never matched, so
@@ -83,7 +81,8 @@ async function pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, confi
  * records the affected path / step error in the caller's collectors, mirroring
  * {@link applyCustomFtlFile}'s contract so the main apply helper stays terse.
  */
-export async function applySharedFtlPrune(engineDir, name, ftlDir, config, affectedPaths, stepErrors, rollbackJournal) {
+export async function applySharedFtlPrune(ctx, config, affectedPaths, stepErrors, rollbackJournal) {
+    const { engineDir, name, ftlDir } = ctx;
     try {
         const prunedPath = await pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal);
         if (prunedPath)
@@ -98,7 +97,8 @@ export async function applySharedFtlPrune(engineDir, name, ftlDir, config, affec
  * returns an action when a dangling per-widget locale entry exists for a
  * `sharedFtl` widget, else `undefined`.
  */
-export async function describeSharedFtlPrune(engineDir, name, ftlDir, config) {
+export async function describeSharedFtlPrune(ctx, config) {
+    const { engineDir, name, ftlDir } = ctx;
     if (!config.sharedFtl)
         return undefined;
     const target = resolveSharedFtlPruneTarget(name, ftlDir);
@@ -123,7 +123,8 @@ export async function describeSharedFtlPrune(engineDir, name, ftlDir, config) {
  * stepErrors rather than thrown — a well-formed `.mjs`/`.css` must never be
  * blocked by a broken locale path.
  */
-export async function applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal) {
+export async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbackJournal) {
+    const { engineDir, name, componentDir, ftlDir } = ctx;
     const ftlFile = `${name}.ftl`;
     const ftlSrc = join(componentDir, ftlFile);
     if (!(await pathExists(ftlSrc)))
@@ -133,7 +134,9 @@ export async function applyCustomFtlFile(engineDir, name, componentDir, ftlDir,
         await snapshotFile(rollbackJournal, ftlDest);
     }
     await copyFile(ftlSrc, ftlDest);
-    affectedPaths.push(relative(engineDir, ftlDest));
+    // Sibling pushes on this list are POSIX literals (`localeJarRel`); keep
+    // the computed one in the same spelling.
+    affectedPaths.push(normalizePathSlashes(relative(engineDir, ftlDest)));
     const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
     const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
     if (chromeSubPath === undefined || localeJarRel === undefined)

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

@@ -6,8 +6,10 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.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 +19,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())
@@ -69,7 +71,12 @@ export function getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir)
  * caller should treat that as a successful no-op rather than an error.
  */
 export async function restoreOverrideFileToBaseline(engineDir, enginePath, journal) {
-    const relPath = relative(engineDir, enginePath);
+    // Engine-relative paths are IDENTIFIERS here, not filesystem arguments:
+    // they are handed to git, recorded in furnace state, and compared against
+    // the POSIX paths furnace.json and jar.mn already carry. `relative()`
+    // returns backslashes on Windows, so without this the same file has two
+    // spellings and every cross-check misses.
+    const relPath = normalizePathSlashes(relative(engineDir, enginePath));
     // Snapshot before mutation so a later rollback can undo both restoration
     // (writes whatever content we removed back) and deletion (recreates the
     // file). Snapshotting a missing path records `{ existed: false }`, which
@@ -98,8 +105,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;
@@ -129,7 +135,7 @@ export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDi
         }
         if (await pathExists(enginePath)) {
             await removeFile(enginePath);
-            removed.push(relative(engineDir, enginePath));
+            removed.push(normalizePathSlashes(relative(engineDir, enginePath)));
         }
         // When an `.ftl` is deleted from the workspace the corresponding locale
         // jar.mn entry must also be dropped — otherwise the chrome URI points at
@@ -173,7 +179,7 @@ export async function undeployOverrideFiles(engineDir, config, deletedFiles, ftl
     for (const fileName of deletedFiles) {
         const enginePath = getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir);
         const action = await restoreOverrideFileToBaseline(engineDir, enginePath, rollbackJournal);
-        const relPath = relative(engineDir, enginePath);
+        const relPath = normalizePathSlashes(relative(engineDir, enginePath));
         if (action === 'restored')
             restored.push(relPath);
         else if (action === 'removed')
@@ -200,9 +206,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 +218,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 +255,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 +294,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 +308,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,27 +331,27 @@ 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);
         const dest = join(targetDir, entry.name);
         await deployFileWithFragments(src, dest, sharedDir);
-        affectedPaths.push(relative(engineDir, dest));
+        affectedPaths.push(normalizePathSlashes(relative(engineDir, dest)));
         copiedFileNames.push(entry.name);
     }));
     // See buildCustomDryRunActions for the rationale: when `sharedFtl` is set
     // 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 +391,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);
@@ -422,7 +431,7 @@ export async function applyOverrideComponent(engineDir, name, componentDir, conf
         const src = join(componentDir, entry.name);
         const dest = getOverrideEngineTargetPath(engineDir, config, entry.name, ftlDir);
         await copyFile(src, dest);
-        affectedPaths.push(relative(engineDir, dest));
+        affectedPaths.push(normalizePathSlashes(relative(engineDir, dest)));
     }));
     if (affectedPaths.length === 0) {
         throw new FurnaceError(`No matching files found in override directory for "${name}"`, 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');
+}