@hominis/fireforge 0.32.0 → 0.34.0

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

@@ -401,6 +401,32 @@ function parseTypecheckBlock(rec) {
     if (extraShim !== undefined) {
         out.extraShim = parseShimPath(extraShim, 'typecheck.extraShim');
     }
+    const overrides = parseTypecheckProjectOverrides(rec.raw('projectOverrides'), projects);
+    if (overrides) {
+        out.projectOverrides = overrides;
+    }
+    return out;
+}
+/**
+ * Validates the optional `typecheck.projectOverrides` map: keys must name a
+ * declared project, values must be either `null` (opt out of the shared extra
+ * shim) or a contained relative `.d.ts` path (per-project override). Returns
+ * `undefined` when the field is absent.
+ */
+function parseTypecheckProjectOverrides(raw, projects) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new ConfigError('Config field "typecheck.projectOverrides" must be an object');
+    }
+    const known = new Set(projects);
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!known.has(key)) {
+            throw new ConfigError(`Config field "typecheck.projectOverrides" key "${key}" does not match any entry in "typecheck.projects"`);
+        }
+        out[key] = value === null ? null : parseShimPath(value, `typecheck.projectOverrides["${key}"]`);
+    }
     return out;
 }
 //# sourceMappingURL=config-validate.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * Dry-run action planning for custom-component apply. Extracted from
+ * `furnace-apply-helpers.ts` so the apply path and its dry-run mirror each
+ * stay within the per-file line budget. Consumed only by that module.
+ */
+import type { CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
+interface DirectoryEntry {
+    isFile(): boolean;
+    isSymbolicLink?(): boolean;
+    name: string;
+}
+/** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
+export declare function buildCustomDryRunActions(name: string, componentDir: string, engineDir: string, config: CustomComponentConfig, targetDir: string, entries: DirectoryEntry[], ftlDir: string): Promise<{
+    actions: DryRunAction[];
+    stepErrors: StepError[];
+}>;
+export {};

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

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Dry-run action planning for custom-component apply. Extracted from
+ * `furnace-apply-helpers.ts` so the apply path and its dry-run mirror each
+ * stay within the per-file line budget. Consumed only by that module.
+ */
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { describeLocaleFtlJarMnRegistration, describeSharedFtlPrune } from './furnace-apply-ftl.js';
+import { describeFragmentExpansion } from './furnace-css-fragments.js';
+import { validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
+function isRegularFile(entry) {
+    if (!entry.isFile())
+        return false;
+    if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink())
+        return false;
+    return true;
+}
+/** Computes the planned dry-run actions (and pre-flight step errors) for a custom component. */
+export async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir) {
+    const actions = [];
+    const stepErrors = [];
+    for (const entry of entries) {
+        if (!isRegularFile(entry))
+            continue;
+        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
+            continue;
+        const fragmentNote = await describeFragmentExpansion(join(componentDir, entry.name));
+        actions.push({
+            component: name,
+            action: fragmentNote ? 'expand-fragments' : 'copy',
+            source: join(componentDir, entry.name),
+            target: join(targetDir, entry.name),
+            description: `Copy ${entry.name} to ${config.targetPath}${fragmentNote}`,
+        });
+    }
+    // Per-component .ftl handling is skipped when the component opts into a
+    // shared feature-scoped bundle via `sharedFtl`. The shared file is
+    // registered (and copied) by whoever owns the feature bundle, so
+    // emitting a copy-ftl / register-jar action here would duplicate (or
+    // later orphan) the entry.
+    if (config.localized && !config.sharedFtl) {
+        const ftlFile = `${name}.ftl`;
+        const ftlSrc = join(componentDir, ftlFile);
+        if (await pathExists(ftlSrc)) {
+            actions.push({
+                component: name,
+                action: 'copy-ftl',
+                source: ftlSrc,
+                target: join(engineDir, ftlDir, ftlFile),
+                description: `Copy ${ftlFile} to ${ftlDir}`,
+            });
+            const localeAction = describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile);
+            if (localeAction) {
+                actions.push(localeAction);
+            }
+        }
+    }
+    // A sharedFtl widget owns its strings via the shared bundle; surface the
+    // removal of any dangling per-widget locale jar.mn entry so the dry-run
+    // plan matches what apply will do (and explains the unblocked build).
+    const pruneAction = await describeSharedFtlPrune(engineDir, name, ftlDir, config);
+    if (pruneAction) {
+        actions.push(pruneAction);
+    }
+    if (config.register) {
+        try {
+            const modulePath = `chrome://global/content/elements/${name}.mjs`;
+            await validateCustomElementRegistration(engineDir, name, modulePath);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'customElements.js registration',
+                error: toError(error).message,
+            });
+        }
+        actions.push({
+            component: name,
+            action: 'register-ce',
+            description: `Register ${name} in customElements.js (DOMContentLoaded block)`,
+        });
+    }
+    const copiedFileNames = entries
+        .filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
+        .map((entry) => entry.name);
+    if (copiedFileNames.length > 0) {
+        try {
+            await validateJarMnInsertionForFiles(engineDir, name, copiedFileNames);
+        }
+        catch (error) {
+            stepErrors.push({
+                step: 'jar.mn registration',
+                error: toError(error).message,
+            });
+        }
+        actions.push({
+            component: name,
+            action: 'register-jar',
+            description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
+        });
+    }
+    return { actions, stepErrors };
+}
+//# sourceMappingURL=furnace-apply-dry-run.js.map

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

@@ -10,6 +10,18 @@
  */
 import type { CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';
+/**
+ * Apply-path wrapper around {@link pruneSharedFtlPerWidgetLocaleEntry} that
+ * records the affected path / step error in the caller's collectors, mirroring
+ * {@link applyCustomFtlFile}'s contract so the main apply helper stays terse.
+ */
+export declare function applySharedFtlPrune(engineDir: string, name: string, ftlDir: string, config: CustomComponentConfig, affectedPaths: string[], stepErrors: StepError[], rollbackJournal?: RollbackJournal): Promise<void>;
+/**
+ * Read-only dry-run describer for {@link pruneSharedFtlPerWidgetLocaleEntry}:
+ * returns an action when a dangling per-widget locale entry exists for a
+ * `sharedFtl` widget, else `undefined`.
+ */
+export declare function describeSharedFtlPrune(engineDir: string, name: string, ftlDir: string, config: CustomComponentConfig): Promise<DryRunAction | undefined>;
 /**
  * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
  * in the locale jar.mn.

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

@@ -11,10 +11,106 @@
  */
 import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
-import { copyFile, pathExists } from '../utils/fs.js';
+import { copyFile, pathExists, readText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
 import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath } from './furnace-constants.js';
 import { addLocaleFtlJarMnEntry, removeLocaleFtlJarMnEntry } from './furnace-registration.js';
 import { snapshotFile } from './furnace-rollback.js';
+/**
+ * Builds the presence regex for a per-widget locale jar.mn line
+ * (`locale/@AB_CD@/<chromeSubPath>/<tagName>.ftl`). Shared by the prune
+ * helper and its dry-run describer so both agree on what "dangling" means.
+ */
+function perWidgetLocaleEntryPattern(chromeSubPath, tagName) {
+    return new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeRegex(chromeSubPath)}\\/${escapeRegex(tagName)}\\.ftl`, 'm');
+}
+/**
+ * Resolves the engine-relative locale jar.mn and the per-widget entry regex
+ * for a `sharedFtl` widget, or `undefined` when the FTL tree exposes no
+ * locale jar.mn we can confidently name.
+ */
+function resolveSharedFtlPruneTarget(name, ftlDir) {
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
+    if (chromeSubPath === undefined || localeJarRel === undefined)
+        return undefined;
+    return { localeJarRel, pattern: perWidgetLocaleEntryPattern(chromeSubPath, name) };
+}
+/**
+ * Removes a dangling per-widget locale jar.mn entry for a `sharedFtl` widget.
+ *
+ * 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.
+ *
+ * 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
+ * pruning one widget cannot orphan the shared bundle. Idempotent: when no
+ * dangling entry exists the file is left untouched (no journal churn).
+ * Returns the engine-relative jar.mn path when a line was removed, else
+ * `undefined`.
+ */
+async function pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal) {
+    if (!config.sharedFtl)
+        return undefined;
+    const target = resolveSharedFtlPruneTarget(name, ftlDir);
+    if (!target)
+        return undefined;
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    if (chromeSubPath === undefined)
+        return undefined;
+    const localeJarAbs = join(engineDir, target.localeJarRel);
+    if (!(await pathExists(localeJarAbs)))
+        return undefined;
+    if (!target.pattern.test(await readText(localeJarAbs)))
+        return undefined;
+    if (rollbackJournal) {
+        await snapshotFile(rollbackJournal, localeJarAbs);
+    }
+    await removeLocaleFtlJarMnEntry(engineDir, target.localeJarRel, name, chromeSubPath);
+    return target.localeJarRel;
+}
+/**
+ * Apply-path wrapper around {@link pruneSharedFtlPerWidgetLocaleEntry} that
+ * 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) {
+    try {
+        const prunedPath = await pruneSharedFtlPerWidgetLocaleEntry(engineDir, name, ftlDir, config, rollbackJournal);
+        if (prunedPath)
+            affectedPaths.push(prunedPath);
+    }
+    catch (error) {
+        stepErrors.push({ step: 'locale jar.mn prune', error: toError(error).message });
+    }
+}
+/**
+ * Read-only dry-run describer for {@link pruneSharedFtlPerWidgetLocaleEntry}:
+ * 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) {
+    if (!config.sharedFtl)
+        return undefined;
+    const target = resolveSharedFtlPruneTarget(name, ftlDir);
+    if (!target)
+        return undefined;
+    const localeJarAbs = join(engineDir, target.localeJarRel);
+    if (!(await pathExists(localeJarAbs)))
+        return undefined;
+    if (!target.pattern.test(await readText(localeJarAbs)))
+        return undefined;
+    return {
+        component: name,
+        action: 'register-jar',
+        description: `Remove dangling per-widget locale entry for ${name} from ${target.localeJarRel} (sharedFtl bundle owns its strings)`,
+    };
+}
 /**
  * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
  * in the locale jar.mn.

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

@@ -6,10 +6,11 @@ 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 { applyCustomFtlFile, describeLocaleFtlJarMnRegistration, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
+import { buildCustomDryRunActions } from './furnace-apply-dry-run.js';
+import { applyCustomFtlFile, applySharedFtlPrune, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
-import { deployFileWithFragments, describeFragmentExpansion, SHARED_FRAGMENTS_DIR, } from './furnace-css-fragments.js';
-import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnInsertionForFiles, } from './furnace-registration.js';
+import { deployFileWithFragments, SHARED_FRAGMENTS_DIR } from './furnace-css-fragments.js';
+import { addCustomElementRegistration, addJarMnEntries } from './furnace-registration.js';
 import { recordCreatedDir, snapshotFile } from './furnace-rollback.js';
 import { checkRegistrationConsistency } from './furnace-validate-registration.js';
 import { isGitRepository } from './git.js';
@@ -278,83 +279,6 @@ export async function hasCustomEngineDrift(root, name, componentDir, config, ftl
     }
     return false;
 }
-async function buildCustomDryRunActions(name, componentDir, engineDir, config, targetDir, entries, ftlDir) {
-    const actions = [];
-    const stepErrors = [];
-    for (const entry of entries) {
-        if (!isRegularFile(entry))
-            continue;
-        if (!entry.name.endsWith('.mjs') && !entry.name.endsWith('.css'))
-            continue;
-        const fragmentNote = await describeFragmentExpansion(join(componentDir, entry.name));
-        actions.push({
-            component: name,
-            action: fragmentNote ? 'expand-fragments' : 'copy',
-            source: join(componentDir, entry.name),
-            target: join(targetDir, entry.name),
-            description: `Copy ${entry.name} to ${config.targetPath}${fragmentNote}`,
-        });
-    }
-    // Per-component .ftl handling is skipped when the component opts into a
-    // shared feature-scoped bundle via `sharedFtl`. The shared file is
-    // registered (and copied) by whoever owns the feature bundle, so
-    // emitting a copy-ftl / register-jar action here would duplicate (or
-    // later orphan) the entry.
-    if (config.localized && !config.sharedFtl) {
-        const ftlFile = `${name}.ftl`;
-        const ftlSrc = join(componentDir, ftlFile);
-        if (await pathExists(ftlSrc)) {
-            actions.push({
-                component: name,
-                action: 'copy-ftl',
-                source: ftlSrc,
-                target: join(engineDir, ftlDir, ftlFile),
-                description: `Copy ${ftlFile} to ${ftlDir}`,
-            });
-            const localeAction = describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile);
-            if (localeAction) {
-                actions.push(localeAction);
-            }
-        }
-    }
-    if (config.register) {
-        try {
-            const modulePath = `chrome://global/content/elements/${name}.mjs`;
-            await validateCustomElementRegistration(engineDir, name, modulePath);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'customElements.js registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-ce',
-            description: `Register ${name} in customElements.js (DOMContentLoaded block)`,
-        });
-    }
-    const copiedFileNames = entries
-        .filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')))
-        .map((entry) => entry.name);
-    if (copiedFileNames.length > 0) {
-        try {
-            await validateJarMnInsertionForFiles(engineDir, name, copiedFileNames);
-        }
-        catch (error) {
-            stepErrors.push({
-                step: 'jar.mn registration',
-                error: toError(error).message,
-            });
-        }
-        actions.push({
-            component: name,
-            action: 'register-jar',
-            description: `Add ${copiedFileNames.join(', ')} to jar.mn`,
-        });
-    }
-    return { actions, stepErrors };
-}
 /** 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 = {}) {
     if (!/^[a-z][a-z0-9-]*$/.test(name)) {
@@ -406,6 +330,12 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
     if (config.localized && !config.sharedFtl) {
         await applyCustomFtlFile(engineDir, name, componentDir, ftlDir, 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);
+    }
     if (config.register) {
         try {
             const modulePath = `chrome://global/content/elements/${name}.mjs`;

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

@@ -71,6 +71,30 @@ export declare function removeLocaleFtlJarMnEntry(engineDir: string, jarMnRelPat
  * @param tagName - Custom element tag name whose entries should be removed
  */
 export declare function removeJarMnEntries(engineDir: string, tagName: string): Promise<void>;
+/** A jar.mn widget registration line whose source file no longer exists. */
+export interface StaleJarMnEntry {
+    /** Component tag name from the `(widgets/<tag>/<file>)` source mapping. */
+    tagName: string;
+    /** File name from the source mapping. */
+    fileName: string;
+    /** The full (trimmed) jar.mn line. */
+    line: string;
+}
+/**
+ * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)`
+ * whose workspace source file no longer exists (0.34.0 field report: a
+ * renamed component helper left the old line pointing at a deleted file,
+ * and every build failed at packaging). Only tags in `managedTags`
+ * (furnace-managed custom components) are inspected so upstream lines are
+ * never touched.
+ */
+export declare function findStaleJarMnEntries(engineDir: string, customDir: string, managedTags: readonly string[]): Promise<StaleJarMnEntry[]>;
+/**
+ * Removes every stale widget registration line found by
+ * {@link findStaleJarMnEntries}. Returns the removed entries. Used by
+ * `furnace validate --fix` and `doctor --repair-furnace`.
+ */
+export declare function pruneStaleJarMnEntries(engineDir: string, customDir: string, managedTags: readonly string[]): Promise<StaleJarMnEntry[]>;
 /**
  * Validates that jar.mn entries *could* be added without writing anything.
  * Used by dry-run to surface structural problems early.

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

@@ -224,14 +224,67 @@ export async function removeJarMnEntries(engineDir, tagName) {
     }
     let content = await readText(filePath);
     const lines = content.split('\n');
-    // Use a regex with word boundary so "moz-card" does not match "moz-card-group".
-    const pattern = new RegExp(`content/global/elements/${escapeForRegex(tagName)}\\.`);
-    const filtered = lines.filter((line) => !pattern.test(line));
+    // Match by the SOURCE MAPPING segment `(widgets/<tagName>/...)` so every
+    // line the component registered is removed regardless of the target
+    // basename — a helper `.mjs` whose name does not start with the tag
+    // (e.g. a renamed `foo-utils.mjs`) used to survive the remove pass and
+    // leave a stale registration that broke packaging (0.34.0 field
+    // report). The legacy target-path match is kept as an OR for lines
+    // written by older FireForge versions without a source mapping. Word
+    // boundaries keep "moz-card" from matching "moz-card-group".
+    const sourcePattern = new RegExp(`\\(widgets/${escapeForRegex(tagName)}/`);
+    const legacyTargetPattern = new RegExp(`content/global/elements/${escapeForRegex(tagName)}\\.`);
+    const filtered = lines.filter((line) => !sourcePattern.test(line) && !legacyTargetPattern.test(line));
     if (filtered.length === lines.length)
         return;
     content = filtered.join('\n');
     await writeText(filePath, content);
 }
+const WIDGET_SOURCE_MAPPING_PATTERN = /\(widgets\/([^/)]+)\/([^)]+)\)/;
+/**
+ * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)`
+ * whose workspace source file no longer exists (0.34.0 field report: a
+ * renamed component helper left the old line pointing at a deleted file,
+ * and every build failed at packaging). Only tags in `managedTags`
+ * (furnace-managed custom components) are inspected so upstream lines are
+ * never touched.
+ */
+export async function findStaleJarMnEntries(engineDir, customDir, managedTags) {
+    const filePath = join(engineDir, JAR_MN);
+    if (!(await pathExists(filePath)))
+        return [];
+    const managed = new Set(managedTags);
+    const stale = [];
+    for (const line of (await readText(filePath)).split('\n')) {
+        const match = WIDGET_SOURCE_MAPPING_PATTERN.exec(line);
+        if (!match)
+            continue;
+        const tagName = match[1] ?? '';
+        const fileName = match[2] ?? '';
+        if (!managed.has(tagName))
+            continue;
+        if (!(await pathExists(join(customDir, tagName, fileName)))) {
+            stale.push({ tagName, fileName, line: line.trim() });
+        }
+    }
+    return stale;
+}
+/**
+ * Removes every stale widget registration line found by
+ * {@link findStaleJarMnEntries}. Returns the removed entries. Used by
+ * `furnace validate --fix` and `doctor --repair-furnace`.
+ */
+export async function pruneStaleJarMnEntries(engineDir, customDir, managedTags) {
+    const stale = await findStaleJarMnEntries(engineDir, customDir, managedTags);
+    if (stale.length === 0)
+        return [];
+    const filePath = join(engineDir, JAR_MN);
+    const staleLines = new Set(stale.map((entry) => entry.line));
+    const lines = (await readText(filePath)).split('\n');
+    const filtered = lines.filter((line) => !staleLines.has(line.trim()));
+    await writeText(filePath, filtered.join('\n'));
+    return stale;
+}
 /**
  * Validates that jar.mn entries *could* be added without writing anything.
  * Used by dry-run to surface structural problems early.

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

@@ -10,6 +10,7 @@ import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, FTL_DIR, JAR_MN } from './furnace-constants.js';
 import { expandCssFragments, listFragmentIncludes } from './furnace-css-fragments.js';
+import { findStaleJarMnEntries } from './furnace-registration.js';
 import { isTagInCorrectCustomElementsPlacement } from './furnace-registration-validate.js';
 import { getTokensCssPath } from './token-manager.js';
 /**
@@ -210,6 +211,23 @@ export async function validateJarMnEntries(root, config) {
             });
         }
     }
+    // Stale registrations: lines pointing at component files that no longer
+    // exist in the workspace (left behind by a rename/delete under an older
+    // FireForge). These break `mach build` at packaging ("File ... not
+    // found"), so they are errors and `--fix` prunes them (0.34.0 field
+    // report: both validate --fix and doctor --repair-furnace reported
+    // success without pruning).
+    const staleEntries = await findStaleJarMnEntries(engineDir, furnacePaths.customDir, Object.keys(config.custom));
+    for (const stale of staleEntries) {
+        issues.push({
+            component: stale.tagName,
+            severity: 'error',
+            check: 'stale-jar-registration',
+            message: `jar.mn registers ${stale.fileName} for ${stale.tagName}, but the source file no longer exists ` +
+                `(stale line: "${stale.line}"). Packaging will fail until the line is removed — run ` +
+                '"fireforge furnace validate --fix" or "fireforge doctor --repair-furnace" to prune it.',
+        });
+    }
     return issues;
 }
 /**

package/dist/src/core/mach-resource-shim.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Resource-monitor degrade guard for mach dispatches.
+ *
+ * mozbuild's build resource monitor calls `psutil.virtual_memory()` at
+ * startup (`start_resource_recording`) and again later from
+ * `mozbuild.base._run_make`. On some hosts (psutil vs Darwin 27) those
+ * raise `RuntimeError: host_statistics64(HOST_VM_INFO64) syscall failed`,
+ * and a `SystemResourceMonitor.__init__` that fails partway leaves an
+ * instance without `poll_interval`, so later polling dies with
+ * `AttributeError: ... poll_interval`. Any of these aborts `mach build` /
+ * `mach build faster` before the compiler ever runs.
+ *
+ * 0.33.0 injected a `sitecustomize.py` via the mach subprocess PYTHONPATH.
+ * Field report (0.34.0 cycle): mach re-execs itself into its private
+ * virtualenv and drops PYTHONPATH, so the env-var route never loads and
+ * the crash family escaped on every protected entry point. FireForge now
+ * owns the guard in-process on its mach dispatches by installing a
+ * `fireforge_mach_guard.pth` + module pair directly into every discovered
+ * mach virtualenv site-packages directory: `.pth` files execute at
+ * interpreter startup from the venv's own site-packages, which survives
+ * the re-exec. The PYTHONPATH `sitecustomize.py` is retained only as a
+ * belt-and-suspenders for the pre-venv bootstrap phase (first build, no
+ * `_virtualenvs` on disk yet).
+ *
+ * The guard itself covers the whole crash family:
+ *  - wraps `psutil.virtual_memory` / `swap_memory` / `cpu_percent` /
+ *    `cpu_times` / `disk_io_counters` module-wide, so every call site —
+ *    including the direct `psutil.virtual_memory()` in
+ *    `mozbuild.base._run_make` — degrades to a `UserWarning` and a zeroed
+ *    reading instead of aborting;
+ *  - guards `SystemResourceMonitor` CONSTRUCTION via an import hook:
+ *    `poll_interval` is pre-populated before the real `__init__` runs, a
+ *    failing `__init__` marks the instance degraded instead of raising,
+ *    and every monitor method no-ops on a degraded instance — so a
+ *    partially-constructed monitor can never surface the
+ *    `AttributeError: poll_interval` variant.
+ */
+/** Result of installing the mach resource guard before a dispatch. */
+export interface MachResourceGuardInstallation {
+    /**
+     * Env overlay for the mach subprocess: the PYTHONPATH sitecustomize
+     * fallback that covers the pre-venv bootstrap phase. Merged over
+     * `process.env` by the exec layer.
+     */
+    env: Record<string, string>;
+    /** site-packages directories the in-venv guard was written into. */
+    sitePackagesDirs: string[];
+}
+/**
+ * Installs the resource-monitor degrade guard for a mach dispatch:
+ * `fireforge_mach_guard.pth` + `fireforge_mach_guard.py` into every
+ * discovered mach virtualenv site-packages (survives mach's venv re-exec),
+ * plus the PYTHONPATH sitecustomize fallback for the pre-venv bootstrap
+ * phase. Idempotent and re-run before EVERY protected dispatch (including
+ * each retry) so a venv created by a crashed first attempt is guarded on
+ * the next one instead of re-dying on the same wedged state.
+ */
+export declare function installMachResourceGuard(engineDir: string): Promise<MachResourceGuardInstallation>;