@hominis/fireforge 0.49.1 → 0.50.0

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

@@ -0,0 +1,9 @@
+import { type FurnaceOptInCheck, type FurnaceValidationException } from '../types/furnace.js';
+/**
+ * Parses `validationExceptions[]`: `{ component, check, reason }` objects,
+ * no other keys, every field a non-empty string, and no two entries for the
+ * same component and check.
+ */
+export declare function parseValidationExceptions(raw: unknown): FurnaceValidationException[];
+/** Parses `optInChecks[]`: names from {@link FURNACE_OPT_IN_CHECKS}. */
+export declare function parseOptInChecks(raw: unknown): FurnaceOptInCheck[];

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

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validators for the two `furnace validate` policy fields of furnace.json:
+ * `validationExceptions[]` and `optInChecks[]`.
+ *
+ * Strict on purpose, like `buildAudit.unpackaged`: every exception is a
+ * standing suppression of a finding, so a malformed one must fail at load
+ * rather than quietly suppress nothing (or everything).
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { FURNACE_OPT_IN_CHECKS, } from '../types/furnace.js';
+import { isArray, isObject, isString } from '../utils/validation.js';
+const EXCEPTION_KEYS = new Set(['component', 'check', 'reason']);
+function requireNonEmptyString(entry, key, field) {
+    const value = entry[key];
+    if (!isString(value) || value.trim().length === 0) {
+        throw new FurnaceError(`Furnace config: "${field}.${key}" must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Parses `validationExceptions[]`: `{ component, check, reason }` objects,
+ * no other keys, every field a non-empty string, and no two entries for the
+ * same component and check.
+ */
+export function parseValidationExceptions(raw) {
+    if (!isArray(raw)) {
+        throw new FurnaceError('Furnace config: "validationExceptions" must be an array');
+    }
+    const seen = new Set();
+    return raw.map((entry, index) => {
+        const field = `validationExceptions[${String(index)}]`;
+        if (!isObject(entry)) {
+            throw new FurnaceError(`Furnace config: "${field}" must be an object with "component", "check" and "reason"`);
+        }
+        for (const key of Object.keys(entry)) {
+            if (!EXCEPTION_KEYS.has(key)) {
+                throw new FurnaceError(`Furnace config: "${field}" has unknown key "${key}"`);
+            }
+        }
+        const exception = {
+            component: requireNonEmptyString(entry, 'component', field),
+            check: requireNonEmptyString(entry, 'check', field),
+            reason: requireNonEmptyString(entry, 'reason', field),
+        };
+        const identity = `${exception.component}\u0000${exception.check}`;
+        if (seen.has(identity)) {
+            throw new FurnaceError(`Furnace config: "${field}" repeats the exception for ${exception.component} [${exception.check}]`);
+        }
+        seen.add(identity);
+        return exception;
+    });
+}
+function isOptInCheck(value) {
+    return FURNACE_OPT_IN_CHECKS.includes(value);
+}
+/** Parses `optInChecks[]`: names from {@link FURNACE_OPT_IN_CHECKS}. */
+export function parseOptInChecks(raw) {
+    if (!isArray(raw)) {
+        throw new FurnaceError('Furnace config: "optInChecks" must be an array');
+    }
+    const checks = [];
+    for (const value of raw) {
+        if (!isString(value) || !isOptInCheck(value)) {
+            throw new FurnaceError(`Furnace config: "optInChecks" entry ${JSON.stringify(value)} is not an opt-in check. Valid: ${FURNACE_OPT_IN_CHECKS.join(', ')}`);
+        }
+        if (!checks.includes(value))
+            checks.push(value);
+    }
+    return checks;
+}

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

@@ -8,6 +8,7 @@
 import { FurnaceError } from '../errors/furnace.js';
 import { isJsonObject, isString } from '../utils/validation.js';
 import { parseStringArray } from './furnace-config-array-utils.js';
+import { parseOptInChecks, parseValidationExceptions, } from './furnace-config-validate-exceptions.js';
 /**
  * Validates an override component config object.
  * @param data - Raw data to validate
@@ -129,4 +130,11 @@ export function applyOptionalFurnaceFields(migrated, config) {
         }
         config.scanPaths = paths;
     }
+    // `furnace validate` policy: reviewed exceptions and opt-in checks.
+    if (migrated['validationExceptions'] !== undefined) {
+        config.validationExceptions = parseValidationExceptions(migrated['validationExceptions']);
+    }
+    if (migrated['optInChecks'] !== undefined) {
+        config.optInChecks = parseOptInChecks(migrated['optInChecks']);
+    }
 }

package/dist/src/core/furnace-css-fragments.d.ts

@@ -35,6 +35,16 @@ export declare function listFragmentIncludes(css: string): string[];
  * against its workspace source and to re-expand idempotently.
  */
 export declare function stripExpandedFragments(css: string): string;
+/**
+ * Marks the lines of a stylesheet that belong to a fenced fragment
+ * expansion: the directive, the inlined body and the end marker. Index `i`
+ * is line `i + 1` of `css`. Fences are found exactly as
+ * {@link stripExpandedFragments} finds them, so a bare directive or an
+ * unterminated fence marks nothing. The patch-size metric reads this
+ * off a file's post-image, because a hunk can start inside a span and
+ * carry no directive of its own.
+ */
+export declare function expandedFragmentLineMask(css: string): boolean[];
 /**
  * Expands every `@fireforge-include` directive in `css` with the current
  * content of its fragment file from `sharedDir`, fencing each expansion

package/dist/src/core/furnace-css-fragments.js

@@ -78,6 +78,32 @@ export function stripExpandedFragments(css) {
     }
     return out.join('\n');
 }
+/**
+ * Marks the lines of a stylesheet that belong to a fenced fragment
+ * expansion: the directive, the inlined body and the end marker. Index `i`
+ * is line `i + 1` of `css`. Fences are found exactly as
+ * {@link stripExpandedFragments} finds them, so a bare directive or an
+ * unterminated fence marks nothing. The patch-size metric reads this
+ * off a file's post-image, because a hunk can start inside a span and
+ * carry no directive of its own.
+ */
+export function expandedFragmentLineMask(css) {
+    const lines = css.split('\n');
+    const mask = lines.map(() => false);
+    for (let i = 0; i < lines.length; i++) {
+        const inc = INCLUDE_PATTERN.exec(lines[i] ?? '');
+        if (!inc?.[1])
+            continue;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (END_INCLUDE_PATTERN.exec(lines[j] ?? '')?.[1] !== inc[1])
+                continue;
+            mask.fill(true, i, j + 1);
+            i = j;
+            break;
+        }
+    }
+    return mask;
+}
 /**
  * Expands every `@fireforge-include` directive in `css` with the current
  * content of its fragment file from `sharedDir`, fencing each expansion

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

@@ -63,9 +63,9 @@ export interface RunFurnaceMutationOptions {
      * never passed: `furnace deploy --wait-lock 1800` waited 1800 s for the
      * engine session lock and then met `.fireforge/furnace.lock` with a fixed
      * 30 s, which is the worst shape a budget can have: it pays the whole
-     * wait and still refuses. When absent, {@link sessionWaitLockMs} supplies
-     * the session-wide budget so the twelve furnace mutators that declare no
-     * flag are covered too.
+     * wait and still refuses. Every furnace leaf that takes this lock threads
+     * its `--wait-lock` here. When absent, {@link sessionWaitLockMs} supplies
+     * the session-wide budget (`FIREFORGE_WAIT_LOCK`).
      */
     lockTimeoutMs?: number;
     /**

package/dist/src/core/furnace-registration-remove.d.ts

@@ -15,11 +15,32 @@
  * - Two registration shapes are recognised:
  *     (A) Standalone statement:
  *           customElements.setElementCreationCallback("tag", ...);
- *     (B) Entry inside a `for (... of [ ... ])` registration array:
+ *     (B) Entry inside a `for (... of [ ... ])` registration array, or an
+ *         array declared by name and iterated with `for (... of NAME)`:
  *           ["tag", "chrome://..."]
  *   Both are deleted together with any trailing comma and newline so the
  *   resulting file is still valid JavaScript.
  */
+import type * as estree from 'estree';
+import { type AcornESTreeNode } from './ast-utils.js';
+/** A `[start, end)` source range in customElements.js. */
+export interface RemovalRange {
+    start: number;
+    end: number;
+}
+/**
+ * Walks the AST and returns the source range of every registration of
+ * `tagName`: each `[tag, module]` entry of a registration list, and each
+ * statement enclosing a `setElementCreationCallback(tag, ...)` call.
+ * Ancestor tracking lets us tell an "entry" array from a random
+ * `["moz-foo", ...]` literal (only direct children of a registration list
+ * are entries). Shared by removal and the in-place rename.
+ *
+ * @param ast - Parsed customElements.js
+ * @param tagName - Tag whose registrations to find
+ * @returns Unexpanded `[start, end)` ranges, in source order
+ */
+export declare function findRegistrationRanges(ast: AcornESTreeNode<estree.Program>, tagName: string): RemovalRange[];
 /**
  * Removes a custom element registration from customElements.js.
  *

package/dist/src/core/furnace-registration-remove.js

@@ -16,7 +16,8 @@
  * - Two registration shapes are recognised:
  *     (A) Standalone statement:
  *           customElements.setElementCreationCallback("tag", ...);
- *     (B) Entry inside a `for (... of [ ... ])` registration array:
+ *     (B) Entry inside a `for (... of [ ... ])` registration array, or an
+ *         array declared by name and iterated with `for (... of NAME)`:
  *           ["tag", "chrome://..."]
  *   Both are deleted together with any trailing comma and newline so the
  *   resulting file is still valid JavaScript.
@@ -120,28 +121,63 @@ function isStandaloneCallbackCallFor(call, tagName) {
     return tagArg.value === tagName;
 }
 /**
- * Walks the AST and collects every removal range for `tagName`. Ancestor
- * tracking lets us tell an "entry" array from a random `["moz-foo", ...]`
- * literal (only direct children of the outer registration `ArrayExpression`
- * are entries) and lets us lift a `setElementCreationCallback` call up to
- * its enclosing statement.
+ * Names of the identifiers used as the right-hand side of a `for (... of X)`
+ * loop. A registration list declared as `const ELEMENTS = [...]` and
+ * iterated by name is a registration array just like an inline literal: the
+ * add path (`addCustomElementRegistration`) has always written into
+ * it, so the remove and rename paths must find entries there too or a
+ * rename leaves the old entry behind.
  */
-function collectRemovalRanges(ast, content, tagName) {
+function collectForOfIdentifiers(ast) {
+    const names = new Set();
+    walkAST(ast, {
+        enter(node) {
+            if (node.type !== 'ForOfStatement')
+                return;
+            const right = asEstree(node).right;
+            if (right.type === 'Identifier')
+                names.add(right.name);
+        },
+    });
+    return names;
+}
+/** True when `parent`/`grandparent` make an array a registration list. */
+function isRegistrationList(parent, grandparent, forOfIdentifiers) {
+    if (parent?.type !== 'ArrayExpression' || !grandparent)
+        return false;
+    if (grandparent.type === 'ForOfStatement')
+        return true;
+    if (grandparent.type !== 'VariableDeclarator')
+        return false;
+    const id = asEstree(grandparent).id;
+    return id.type === 'Identifier' && forOfIdentifiers.has(id.name);
+}
+/**
+ * Walks the AST and returns the source range of every registration of
+ * `tagName`: each `[tag, module]` entry of a registration list, and each
+ * statement enclosing a `setElementCreationCallback(tag, ...)` call.
+ * Ancestor tracking lets us tell an "entry" array from a random
+ * `["moz-foo", ...]` literal (only direct children of a registration list
+ * are entries). Shared by removal and the in-place rename.
+ *
+ * @param ast - Parsed customElements.js
+ * @param tagName - Tag whose registrations to find
+ * @returns Unexpanded `[start, end)` ranges, in source order
+ */
+export function findRegistrationRanges(ast, tagName) {
     const ranges = [];
     const ancestors = [];
+    const forOfIdentifiers = collectForOfIdentifiers(ast);
     walkAST(ast, {
         enter(node) {
-            // Entry array: [tag, module] inside the outer for-of array literal.
-            // The immediate parent must be an ArrayExpression (the registration
-            // list) whose own grandparent is the `for (...) of <array>` loop.
+            // Entry array: [tag, module] inside a registration list, either the
+            // for-of array literal itself or an array declared by name and
+            // iterated by a for-of loop.
             if (node.type === 'ArrayExpression' && isEntryArrayFor(node, tagName)) {
                 const parent = ancestors[ancestors.length - 1];
                 const grandparent = ancestors[ancestors.length - 2];
-                if (parent &&
-                    parent.type === 'ArrayExpression' &&
-                    grandparent &&
-                    grandparent.type === 'ForOfStatement') {
-                    ranges.push(expandRemovalRange(content, node.start, node.end));
+                if (isRegistrationList(parent, grandparent, forOfIdentifiers)) {
+                    ranges.push({ start: node.start, end: node.end });
                 }
             }
             // Standalone call: customElements.setElementCreationCallback(tag, …)
@@ -162,7 +198,7 @@ function collectRemovalRanges(ast, content, tagName) {
                         }
                     }
                     const target = enclosing ?? call;
-                    ranges.push(expandRemovalRange(content, target.start, target.end));
+                    ranges.push({ start: target.start, end: target.end });
                 }
             }
             ancestors.push(node);
@@ -207,7 +243,7 @@ export async function removeCustomElementRegistration(engineDir, tagName) {
         // risks corrupting it. The caller's regex fallback handles the retry.
         return;
     }
-    const ranges = collectRemovalRanges(ast, content, tagName);
+    const ranges = findRegistrationRanges(ast, tagName).map((range) => expandRemovalRange(content, range.start, range.end));
     if (ranges.length === 0) {
         return;
     }

package/dist/src/core/furnace-registration-rename.d.ts

@@ -0,0 +1,26 @@
+/**
+ * In-place rename of a custom element registration in customElements.js.
+ *
+ * `furnace rename` used to remove the old entry and add a new one. On a
+ * registration list the remove path could not see, that left the old entry
+ * beside the new one, and the new entry was written without the project
+ * marker every sibling line carries (`// <MARKER>:`), so the next lint
+ * flagged it as an unmarked engine edit. Rewriting the tag and module
+ * literals inside the existing entry keeps the entry's position, layout and
+ * trailing marker comments exactly as they were.
+ */
+/**
+ * Renames `oldTag`'s registration in customElements.js in place.
+ *
+ * Returns false, writing nothing, when the file is missing or unparsable,
+ * holds no registration for `oldTag`, or already registers `newTag` (an
+ * in-place rewrite would then register it twice); the caller then falls
+ * back to remove-and-add, whose add is idempotent. Never parses with a line-based heuristic: an unparsable
+ * file is a doctor problem, not something a rename edits around.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param oldTag - Tag being renamed away from
+ * @param newTag - Tag being renamed to
+ * @returns True when at least one registration was rewritten
+ */
+export declare function renameCustomElementRegistration(engineDir: string, oldTag: string, newTag: string): Promise<boolean>;

package/dist/src/core/furnace-registration-rename.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * In-place rename of a custom element registration in customElements.js.
+ *
+ * `furnace rename` used to remove the old entry and add a new one. On a
+ * registration list the remove path could not see, that left the old entry
+ * beside the new one, and the new entry was written without the project
+ * marker every sibling line carries (`// <MARKER>:`), so the next lint
+ * flagged it as an unmarked engine edit. Rewriting the tag and module
+ * literals inside the existing entry keeps the entry's position, layout and
+ * trailing marker comments exactly as they were.
+ */
+import { join } from 'node:path';
+import MagicString from 'magic-string';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+import { parseScript } from './ast-utils.js';
+import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
+import { isTagAlreadyRegistered } from './furnace-registration-ast.js';
+import { findRegistrationRanges } from './furnace-registration-remove.js';
+/**
+ * Rewrites the old tag's literals inside one registration's source: the
+ * quoted tag itself and the module file name in its chrome:// URI.
+ * Everything else in the range (indentation, line breaks, comments between
+ * elements) is left byte-for-byte.
+ */
+function renameRegistrationSource(source, oldTag, newTag) {
+    const escaped = escapeRegex(oldTag);
+    return source
+        .replace(new RegExp(`(["'])${escaped}\\1`, 'g'), `$1${newTag}$1`)
+        .replace(new RegExp(`/${escaped}(\\.m?js["'])`, 'g'), `/${newTag}$1`);
+}
+/**
+ * Renames `oldTag`'s registration in customElements.js in place.
+ *
+ * Returns false, writing nothing, when the file is missing or unparsable,
+ * holds no registration for `oldTag`, or already registers `newTag` (an
+ * in-place rewrite would then register it twice); the caller then falls
+ * back to remove-and-add, whose add is idempotent. Never parses with a line-based heuristic: an unparsable
+ * file is a doctor problem, not something a rename edits around.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param oldTag - Tag being renamed away from
+ * @param newTag - Tag being renamed to
+ * @returns True when at least one registration was rewritten
+ */
+export async function renameCustomElementRegistration(engineDir, oldTag, newTag) {
+    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
+    if (!(await pathExists(filePath)))
+        return false;
+    const content = await readText(filePath);
+    if (!content.includes(`"${oldTag}"`) && !content.includes(`'${oldTag}'`))
+        return false;
+    if (isTagAlreadyRegistered(content, newTag))
+        return false;
+    let ranges;
+    try {
+        ranges = findRegistrationRanges(parseScript(content), oldTag);
+    }
+    catch {
+        return false;
+    }
+    if (ranges.length === 0)
+        return false;
+    const ms = new MagicString(content);
+    for (const range of ranges) {
+        const source = content.slice(range.start, range.end);
+        const renamed = renameRegistrationSource(source, oldTag, newTag);
+        if (renamed !== source)
+            ms.overwrite(range.start, range.end, renamed);
+    }
+    const next = ms.toString();
+    if (next === content)
+        return false;
+    await writeText(filePath, next);
+    return true;
+}

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

@@ -1,5 +1,6 @@
 export { addCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
 export { removeCustomElementRegistration } from './furnace-registration-remove.js';
+export { renameCustomElementRegistration } from './furnace-registration-rename.js';
 /**
  * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
  * component's files.
@@ -21,9 +22,9 @@ export { removeCustomElementRegistration } from './furnace-registration-remove.j
  *   in alphabetical order relative to these.
  * - **Fallback**: if no `content/global/elements/` line exists (empty
  *   project), looks for any `content/global/` line and inserts after it.
- * - **Idempotency**: entries already present (checked by exact path match
- *   on `content/global/elements/{file}` with a trailing whitespace or
- *   end-of-line boundary) are skipped.
+ * - **Idempotency**: entries already present anywhere in the file (an exact
+ *   target match on `content/global/elements/{file}`, or a source match on
+ *   `(widgets/{tagName}/{file})`) are skipped, including hand-written ones.
  *
  * If Firefox upstream changes the jar.mn section ordering or switches to a
  * different resource registration mechanism, the preflight validation in
@@ -57,11 +58,20 @@ export declare function addJarMnEntries(engineDir: string, tagName: string, file
  * @returns Number of entries inserted (0 when already present, or jar.mn missing)
  */
 export declare function addLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<number>;
+/**
+ * True when the locale jar.mn carries a per-widget line for `tagName`.
+ * False when the jar.mn is missing. Used by `furnace rename --dry-run` to
+ * say whether a rename would re-point a line or leave the jar alone.
+ */
+export declare function hasLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<boolean>;
 /**
  * Removes a locale jar.mn entry previously written by `addLocaleFtlJarMnEntry`.
  * Idempotent: if the entry is absent or the file is missing, nothing happens.
+ *
+ * @returns True when a line was removed, so a rename re-points only an
+ *   entry that existed instead of inventing one
  */
-export declare function removeLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<void>;
+export declare function removeLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<boolean>;
 /**
  * Removes all jar.mn entries for a given tag name.
  *

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

@@ -27,8 +27,24 @@ function detectJarMnIndent(lines) {
 // Re-export everything from the AST module so existing imports keep working
 export { addCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
 export { removeCustomElementRegistration } from './furnace-registration-remove.js';
+export { renameCustomElementRegistration } from './furnace-registration-rename.js';
 import { escapeRegex } from '../utils/regex.js';
 import { JAR_MN } from './furnace-constants.js';
+/**
+ * True when jar.mn already registers `file` of component `tagName` anywhere
+ * in the file: either a line targeting `content/global/elements/<file>` or a
+ * line sourcing `(widgets/<tagName>/<file>)`. The position of the existing
+ * line is irrelevant. A hand-written line below an unrelated entry counts
+ * exactly like one Furnace wrote itself, so apply never adds a second line
+ * and mach never fails with "Item already in manifest". Boundary-aware so
+ * `moz-card.css` does not match `moz-card-group.css`.
+ */
+function isJarMnFileRegistered(content, tagName, file) {
+    const escapedFile = escapeRegex(file);
+    const target = new RegExp(`content/global/elements/${escapedFile}(?:\\s|$)`, 'm');
+    const source = new RegExp(`\\(widgets/${escapeRegex(tagName)}/${escapedFile}\\)`);
+    return target.test(content) || source.test(content);
+}
 /**
  * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
  * component's files.
@@ -50,9 +66,9 @@ import { JAR_MN } from './furnace-constants.js';
  *   in alphabetical order relative to these.
  * - **Fallback**: if no `content/global/elements/` line exists (empty
  *   project), looks for any `content/global/` line and inserts after it.
- * - **Idempotency**: entries already present (checked by exact path match
- *   on `content/global/elements/{file}` with a trailing whitespace or
- *   end-of-line boundary) are skipped.
+ * - **Idempotency**: entries already present anywhere in the file (an exact
+ *   target match on `content/global/elements/{file}`, or a source match on
+ *   `(widgets/{tagName}/{file})`) are skipped, including hand-written ones.
  *
  * If Firefox upstream changes the jar.mn section ordering or switches to a
  * different resource registration mechanism, the preflight validation in
@@ -70,9 +86,8 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     }
     let content = await readText(filePath);
     const lines = content.split('\n');
-    // Filter to files not already registered. Use a word-boundary-aware
-    // check so that "moz-card.css" does not match "moz-card-group.css".
-    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeRegex(f)}(?:\\s|$)`, 'm').test(content));
+    // Filter to files not already registered anywhere in the jar.
+    const newFiles = [...new Set(files)].filter((f) => !isJarMnFileRegistered(content, tagName, f));
     if (newFiles.length === 0)
         return 0;
     // Build new entry lines using the indent detected from existing entries.
@@ -181,22 +196,41 @@ function detectLocaleJarMnIndent(lines, chromeSubPath) {
     // Fall back to any existing `locale/...` indent before giving up.
     return detectIndent(lines, exact) ?? detectIndent(lines, /^(\s+)locale\//) ?? '  ';
 }
+/** Matches a per-widget locale jar.mn line for `<chromeSubPath>/<tagName>.ftl`. */
+function localeFtlJarMnPattern(tagName, chromeSubPath) {
+    return new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeRegex(chromeSubPath)}\\/${escapeRegex(tagName)}\\.ftl`);
+}
+/**
+ * True when the locale jar.mn carries a per-widget line for `tagName`.
+ * False when the jar.mn is missing. Used by `furnace rename --dry-run` to
+ * say whether a rename would re-point a line or leave the jar alone.
+ */
+export async function hasLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, chromeSubPath) {
+    const filePath = join(engineDir, jarMnRelPath);
+    if (!(await pathExists(filePath)))
+        return false;
+    return localeFtlJarMnPattern(tagName, chromeSubPath).test(await readText(filePath));
+}
 /**
  * Removes a locale jar.mn entry previously written by `addLocaleFtlJarMnEntry`.
  * Idempotent: if the entry is absent or the file is missing, nothing happens.
+ *
+ * @returns True when a line was removed, so a rename re-points only an
+ *   entry that existed instead of inventing one
  */
 export async function removeLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, chromeSubPath) {
     const filePath = join(engineDir, jarMnRelPath);
     if (!(await pathExists(filePath))) {
-        return;
+        return false;
     }
     const content = await readText(filePath);
     const lines = content.split('\n');
-    const pattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeRegex(chromeSubPath)}\\/${escapeRegex(tagName)}\\.ftl`);
+    const pattern = localeFtlJarMnPattern(tagName, chromeSubPath);
     const filtered = lines.filter((line) => !pattern.test(line));
     if (filtered.length === lines.length)
-        return;
+        return false;
     await writeText(filePath, filtered.join('\n'));
+    return true;
 }
 /**
  * Removes all jar.mn entries for a given tag name.
@@ -284,7 +318,7 @@ export async function validateJarMnInsertionForFiles(engineDir, tagName, files)
     }
     const content = await readText(filePath);
     const lines = content.split('\n');
-    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeRegex(f)}(?:\\s|$)`, 'm').test(content));
+    const newFiles = files.filter((f) => !isJarMnFileRegistered(content, tagName, f));
     if (newFiles.length === 0)
         return;
     const elementLinePattern = /^\s+content\/global\/elements\/([^.]+)\./;

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

@@ -8,6 +8,13 @@
  * The check is advisory only: errors (broken furnace config, partial
  * state, transient filesystem failure) must never block the caller.
  */
+/**
+ * Names of the tracked override and custom components whose source changed
+ * on disk since the last apply, i.e. edits engine/ does not hold yet.
+ * Throws on a broken config or state; {@link warnIfFurnaceStale} downgrades
+ * that.
+ */
+export declare function listStaleFurnaceComponents(projectRoot: string): Promise<string[]>;
 /**
  * Emits a warning when any tracked override or custom component has
  * changed on disk since the last apply. Safe to call from any build-time

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

@@ -13,6 +13,39 @@ import { pathExists } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { extractComponentChecksums, hasComponentChanged } from './furnace-apply-helpers.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+/**
+ * Names of the tracked override and custom components whose source changed
+ * on disk since the last apply, i.e. edits engine/ does not hold yet.
+ * Throws on a broken config or state; {@link warnIfFurnaceStale} downgrades
+ * that.
+ */
+export async function listStaleFurnaceComponents(projectRoot) {
+    if (!(await furnaceConfigExists(projectRoot)))
+        return [];
+    const config = await loadFurnaceConfig(projectRoot);
+    const state = await loadFurnaceState(projectRoot);
+    const furnacePaths = getFurnacePaths(projectRoot);
+    if (!state.appliedChecksums)
+        return [];
+    const stale = [];
+    for (const name of Object.keys(config.overrides)) {
+        const dir = `${furnacePaths.overridesDir}/${name}`;
+        if (!(await pathExists(dir)))
+            continue;
+        const prev = extractComponentChecksums(state.appliedChecksums, 'override', name);
+        if (await hasComponentChanged(dir, prev))
+            stale.push(name);
+    }
+    for (const name of Object.keys(config.custom)) {
+        const dir = `${furnacePaths.customDir}/${name}`;
+        if (!(await pathExists(dir)))
+            continue;
+        const prev = extractComponentChecksums(state.appliedChecksums, 'custom', name);
+        if (await hasComponentChanged(dir, prev))
+            stale.push(name);
+    }
+    return stale;
+}
 /**
  * Emits a warning when any tracked override or custom component has
  * changed on disk since the last apply. Safe to call from any build-time
@@ -21,30 +54,7 @@ import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceSta
  */
 export async function warnIfFurnaceStale(projectRoot) {
     try {
-        if (!(await furnaceConfigExists(projectRoot)))
-            return;
-        const config = await loadFurnaceConfig(projectRoot);
-        const state = await loadFurnaceState(projectRoot);
-        const furnacePaths = getFurnacePaths(projectRoot);
-        if (!state.appliedChecksums)
-            return;
-        const stale = [];
-        for (const name of Object.keys(config.overrides)) {
-            const dir = `${furnacePaths.overridesDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'override', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
-        for (const name of Object.keys(config.custom)) {
-            const dir = `${furnacePaths.customDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'custom', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
+        const stale = await listStaleFurnaceComponents(projectRoot);
         if (stale.length > 0) {
             warn(`Furnace component${stale.length === 1 ? '' : 's'} modified since last apply: ${stale.join(', ')}. ` +
                 'Run "fireforge furnace apply" (or "fireforge build" which auto-applies) to update the engine.');