@hominis/fireforge 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.33.0
+
+- Fixed `furnace deploy`/`apply` to prune a dangling per-widget locale `jar.mn` entry for a `localized: true` widget that uses the `sharedFtl` browser-bundle convention. A stale `locale/@AB_CD@/toolkit/global/<name>.ftl` line (written by an older FireForge) pointed at a `.ftl` that never exists, so `mach build` failed hard (`Cannot find toolkit/global/<name>.ftl`) and blocked every build; apply now drops that per-widget line idempotently while leaving the shared bundle's own line untouched.
+- Added `fireforge token add --variant '[data-skin=precision]'` (also `[data-private]`) to author a declaration inside an attribute-keyed `:root[<attr>]` block, creating the block if absent or appending to it if present — so skin/state token overrides no longer have to be hand-edited. The selector is validated and quoted-normalized, variant overrides are CSS-only (the base token owns its docs row), and `token coverage` still accepts the result.
+- Fixed `fireforge register` to sort `EXTRA_JS_MODULES` (and the sibling sorted moz.build / jar.mn list helpers) **case-insensitively**, matching mozbuild's `UnsortedError` rule — so e.g. `AppearanceController.sys.mjs` lands before `AppMenuIntegration.sys.mjs` (`appe` < `appm`) instead of in raw byte order, which made `mach configure` abort. The build wrapper now runs `mach configure` with output capture and surfaces the underlying mozbuild error text (e.g. `UnsortedError`) instead of a bare "configure failed with exit code N".
+- Changed `fireforge typecheck` to staleness-check and regenerate the Furnace-managed jsconfig (`furnace.json` → `typecheckJsconfig`) before running, using the same reconciler `furnace deploy`/`sync` use — so a stale generated `compilerOptions.paths` shim no longer reports phantom type errors in files the session never touched.
+- Fixed `fireforge patch split --dry-run` projected lint to model the forward edge a split introduces into the freshly-created patch: it auto-declares the staged forward-import (the new patch's owner is known) so the dry-run diagnostics match the real `lint --per-patch --max-warnings 0` gate, and persists the declaration on commit so a sound split reads as sound instead of as a cross-patch "has no exported member" error.
+- Fixed `fireforge test <one xpcshell .js>` to recognize the suite-specific xpcshell result-summary block (`TEST_END`, `Ran N checks`, `Unexpected results: 0`) as a valid execution signal. The post-run guard keyed only on `TEST-START` lines — which the xpcshell dispatch never prints — so a passing single-file xpcshell run was reported as "finished without starting any of the requested tests" and exited 1; it now exits 0 while a failing summary still flows to the failure diagnosis.
+- Changed `fireforge build` / `build --ui` to inject a resource-monitor degrade shim (a `sitecustomize.py` on the mach subprocess `PYTHONPATH`) so a host `psutil.virtual_memory()` failure (`host_statistics64(HOST_VM_INFO64) syscall failed`) degrades to a non-fatal warning instead of aborting `mach build` / `mach build faster` in `start_resource_recording`. The build path no longer depends on which mach entry was used.
+- Added per-project `typecheck.projectOverrides` so a project can override or opt out of the shared `extraShim` (`null` opts out, a path overrides). The composed shim is now built per project rather than injected identically everywhere, so a project that narrows `lib`/`types` (e.g. `lib: ["ES2024","DOM"]`) is not forced to absorb another project's Gecko declaration libraries (Element/Node identity splits, nsIPrincipal mismatch).
+
 ## 0.32.0
 
 - Fixed `fireforge lint <files>` to evaluate the `large-patch-files` rule against each file's resolved owning patch instead of the ad-hoc file-list cardinality, so a cross-patch selection no longer synthesizes a phantom oversized patch (e.g. eight files across four patches no longer report `Patch affects 8 files` when no single owner exceeds the threshold). The size rules now run per owning patch — using its real `filesAffected` count, diff, and `tier` — and unowned files are evaluated together as one prospective new patch.

package/dist/src/commands/patch/split-plan.d.ts

@@ -7,6 +7,7 @@
  */
 import { type ConflictReport } from '../../core/destructive.js';
 import { buildProjectedManifest } from '../../core/patch-policy.js';
+import type { PatchStagedForwardImport } from '../../types/commands/index.js';
 import type { PatchCategory, PatchMetadata } from '../../types/commands/index.js';
 import type { FireForgeConfig } from '../../types/config.js';
 import { type PlacementPlan } from '../export-flow.js';
@@ -29,6 +30,14 @@ export interface SplitPlan {
     description: string;
     /** Patches (by current filename) whose staged-dependency owners re-point to the new patch. */
     ownerRewrites: string[];
+    /**
+     * Staged forward-import declarations the split introduces, keyed by the
+     * importing patch's post-rename filename. These are the new forward edges
+     * from existing patches into the freshly-created patch (owner known); they
+     * are injected into the projected lint so dry-run matches the real gate,
+     * and persisted on commit so the real per-patch gate stays clean.
+     */
+    stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
 }
 /**
  *
@@ -45,12 +54,19 @@ export declare function buildSplitDiff(engineDir: string, files: readonly string
 export declare function findOwnerRewriteHolders(patches: readonly PatchMetadata[], sourceFilename: string, movedSet: ReadonlySet<string>): string[];
 /** Rewrites split-affected owners on one manifest row. */
 export declare function rewriteSplitOwners(patch: PatchMetadata, sourceFilename: string, movedSet: ReadonlySet<string>, newFilename: string): PatchMetadata;
+/** Merges `decls` into a patch's `stagedDependencies.forwardImports` (no duplicates). */
+export declare function mergeStagedForwardImports(patch: PatchMetadata, decls: readonly PatchStagedForwardImport[]): PatchMetadata;
 /**
  * Projects the full split (renumber + shrunken source + synthetic new
  * patch + owner rewrites) through cross-patch lint, reporting only the
- * regressions the split itself would introduce.
+ * regressions the split itself would introduce. Forward edges into the new
+ * patch are auto-declared (and the declarations returned) so the projection
+ * matches the real per-patch gate the split leaves behind.
  */
-export declare function runProjectedSplitLint(patchesDir: string, plan: SplitPlan): Promise<ConflictReport | null>;
+export declare function runProjectedSplitLint(patchesDir: string, plan: SplitPlan): Promise<{
+    conflicts: ConflictReport | null;
+    stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
+}>;
 /** Builds the projected manifest for policy enforcement. */
 export declare function projectSplitManifest(manifest: {
     version: 1;

package/dist/src/commands/patch/split-plan.js

@@ -10,7 +10,7 @@ import { join } from 'node:path';
 import { getDiffForFilesAgainstHead } from '../../core/git-diff.js';
 import { computeProjectedLintRegressions } from '../../core/lint-projection.js';
 import { extractAffectedFiles } from '../../core/patch-apply.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
 import { rewriteStagedDependencyOwners } from '../../core/patch-manifest.js';
 import { applyRenameMapToManifest, buildProjectedManifest } from '../../core/patch-policy.js';
 import { buildPatchSourceMetadata } from '../../core/patch-source-metadata.js';
@@ -82,16 +82,12 @@ function buildEntryProjection(diff) {
     }
     return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
 }
-/**
- * Projects the full split (renumber + shrunken source + synthetic new
- * patch + owner rewrites) through cross-patch lint, reporting only the
- * regressions the split itself would introduce.
- */
-export async function runProjectedSplitLint(patchesDir, plan) {
+/** Builds the projected post-split queue entries (renumber + shrunken source + new patch). */
+async function buildProjectedSplitEntries(patchesDir, plan) {
     const movedSet = new Set(plan.movedFiles);
     const ownerLookup = (old) => plan.placement.renameMap.get(old)?.newFilename;
     const baseCtx = await buildPatchQueueContext(patchesDir);
-    const projectedEntries = baseCtx.entries.map((entry) => {
+    const entries = baseCtx.entries.map((entry) => {
         let metadata = entry.metadata;
         if (metadata) {
             metadata = rewriteStagedDependencyOwners(metadata, ownerLookup);
@@ -105,13 +101,90 @@ export async function runProjectedSplitLint(patchesDir, plan) {
             return base;
         return { ...base, ...buildEntryProjection(plan.remainingDiff) };
     });
-    projectedEntries.push({
+    entries.push({
         filename: plan.placement.newFilename,
         order: plan.placement.insertionOrder,
         metadata: null,
         ...buildEntryProjection(plan.movedDiff),
     });
-    projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    entries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    return { baseCtx, entries };
+}
+/**
+ * Computes the staged forward-import declarations the split introduces:
+ * forward edges from existing patches into the freshly-created patch (its
+ * `creates` files are the moved files; the owner is the new patch, so it is
+ * known). Keyed by the importing patch's projected (post-rename) filename.
+ *
+ * These edges did not exist before the split (importer and imported file
+ * lived in the same patch), so they have no declaration yet — without this
+ * the projected lint flags them while the real per-patch gate would resolve
+ * them once declared. Auto-declaring keeps the two in lock-step and lets a
+ * sound split read as sound.
+ */
+function computeSplitStagedDependencyAdditions(projectedEntries, newFilename) {
+    const additions = new Map();
+    for (const edge of collectForwardImportEdges({ entries: projectedEntries })) {
+        if (edge.owner !== newFilename)
+            continue;
+        const decl = {
+            file: edge.sitePath,
+            specifier: edge.specifier,
+            creates: edge.creates,
+            owner: newFilename,
+        };
+        const list = additions.get(edge.entry) ?? [];
+        const dup = list.some((d) => d.file === decl.file &&
+            d.specifier === decl.specifier &&
+            d.creates === decl.creates &&
+            d.owner === decl.owner);
+        if (!dup)
+            list.push(decl);
+        additions.set(edge.entry, list);
+    }
+    return additions;
+}
+/** Merges `decls` into a patch's `stagedDependencies.forwardImports` (no duplicates). */
+export function mergeStagedForwardImports(patch, decls) {
+    if (decls.length === 0)
+        return patch;
+    const existing = patch.stagedDependencies?.forwardImports ?? [];
+    const merged = [...existing];
+    for (const decl of decls) {
+        const dup = merged.some((d) => d.file === decl.file &&
+            d.specifier === decl.specifier &&
+            d.creates === decl.creates &&
+            (d.owner ?? '') === (decl.owner ?? ''));
+        if (!dup)
+            merged.push(decl);
+    }
+    return {
+        ...patch,
+        stagedDependencies: { ...patch.stagedDependencies, forwardImports: merged },
+    };
+}
+/** Injects the computed staged-dependency additions into projected entries' metadata. */
+function injectStagedDependencyAdditions(entries, additions) {
+    for (const entry of entries) {
+        const decls = additions.get(entry.filename);
+        if (!decls?.length || !entry.metadata)
+            continue;
+        entry.metadata = mergeStagedForwardImports(entry.metadata, decls);
+    }
+}
+/**
+ * Projects the full split (renumber + shrunken source + synthetic new
+ * patch + owner rewrites) through cross-patch lint, reporting only the
+ * regressions the split itself would introduce. Forward edges into the new
+ * patch are auto-declared (and the declarations returned) so the projection
+ * matches the real per-patch gate the split leaves behind.
+ */
+export async function runProjectedSplitLint(patchesDir, plan) {
+    const { baseCtx, entries: projectedEntries } = await buildProjectedSplitEntries(patchesDir, plan);
+    // Discover and auto-declare the forward edges this split introduces into
+    // the new patch, then inject them before linting so they resolve.
+    const stagedDependencyAdditions = computeSplitStagedDependencyAdditions(projectedEntries, plan.placement.newFilename);
+    injectStagedDependencyAdditions(projectedEntries, stagedDependencyAdditions);
     const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
     const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
     const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
@@ -119,12 +192,13 @@ export async function runProjectedSplitLint(patchesDir, plan) {
         warn(`Note: projected queue still has ${baselineIssues.length} pre-existing cross-patch ` +
             'error(s) unrelated to this split. Run "fireforge verify" to list them.');
     }
-    if (regressions.length === 0)
-        return null;
-    return {
-        reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
-        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
-    };
+    const conflicts = regressions.length === 0
+        ? null
+        : {
+            reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
+            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+        };
+    return { conflicts, stagedDependencyAdditions };
 }
 /** Builds the projected manifest for policy enforcement. */
 export function projectSplitManifest(manifest, plan, newMetadata) {

package/dist/src/commands/patch/split.js

@@ -32,7 +32,7 @@ import { info, intro, outro, success, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, mergeStagedForwardImports, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
 /**
  * Commits a confirmed split under the patch directory lock: renumber →
  * write new patch body → write shrunken source body → single manifest
@@ -74,7 +74,13 @@ async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
             if (!fresh)
                 throw new GeneralError('Manifest disappeared during split commit.');
             const updatedPatches = fresh.patches.map((patch) => {
-                const withOwners = rewriteSplitOwners(patch, effectiveSourceFilename, movedSet, plan.placement.newFilename);
+                let withOwners = rewriteSplitOwners(patch, effectiveSourceFilename, movedSet, plan.placement.newFilename);
+                // Persist the auto-declared forward edges into the new patch so the
+                // real per-patch gate stays clean (keyed by post-rename filename).
+                const decls = plan.stagedDependencyAdditions.get(withOwners.filename);
+                if (decls?.length) {
+                    withOwners = mergeStagedForwardImports(withOwners, decls);
+                }
                 if (patch.filename !== effectiveSourceFilename)
                     return withOwners;
                 return { ...withOwners, filesAffected: plan.remainingFiles };
@@ -199,13 +205,16 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         name: options.name,
         description: options.description ?? '',
         ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
+        // Populated by runProjectedSplitLint below (forward edges into the new patch).
+        stagedDependencyAdditions: new Map(),
     };
     // Per-patch lint both projected bodies, threading the source patch's
     // tier/lintIgnore so an intentional-advisory patch can still split.
     const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
     await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
     await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
-    const conflicts = await runProjectedSplitLint(paths.patches, plan);
+    const { conflicts, stagedDependencyAdditions } = await runProjectedSplitLint(paths.patches, plan);
+    plan.stagedDependencyAdditions = stagedDependencyAdditions;
     const newMetadata = buildNewPatchMetadata(plan, config);
     enforcePatchPolicy({
         config,

package/dist/src/commands/token.js

@@ -74,12 +74,18 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
             ...(options.description !== undefined ? { description: options.description } : {}),
             ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
             ...(options.createCategory === true ? { createCategory: true } : {}),
+            ...(options.variant !== undefined ? { variant: options.variant } : {}),
             dryRun: true,
         });
         info('[dry-run] Would add token:');
         info(`  Name: ${tokenName}`);
         info(`  Value: ${value}`);
-        info(`  Category: ${options.category}${options.createCategory === true ? ' (created if missing)' : ''}`);
+        if (options.variant !== undefined) {
+            info(`  Variant: :root${options.variant}`);
+        }
+        else {
+            info(`  Category: ${options.category}${options.createCategory === true ? ' (created if missing)' : ''}`);
+        }
         info(`  Mode: ${options.mode}`);
         if (options.description)
             info(`  Description: ${options.description}`);
@@ -96,6 +102,7 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
         ...(options.description !== undefined ? { description: options.description } : {}),
         ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
         ...(options.createCategory === true ? { createCategory: true } : {}),
+        ...(options.variant !== undefined ? { variant: options.variant } : {}),
     });
     if (result.skipped) {
         info(`Token ${tokenName} already exists (skipped)`);
@@ -151,6 +158,9 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .makeOptionMandatory(true))
         .option('--description <desc>', 'Comment description for the CSS file')
         .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
+        .option('--variant <selector>', 'Attribute selector fragment routing the declaration into a `:root<selector>` block ' +
+        "(e.g. '[data-skin=precision]' or '[data-private]'); creates or updates the block. " +
+        'CSS-only — cannot be combined with --mode override.')
         .option('--create-category', 'Declare the category banner in the tokens CSS if it does not exist yet')
         .option('--dry-run', 'Show what would be changed without writing')
         .action(withErrorHandling(async (tokenName, value, options) => {
@@ -162,6 +172,7 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
                 darkValue: options.darkValue,
                 dryRun: options.dryRun,
                 createCategory: options.createCategory,
+                variant: options.variant,
             }),
         });
     }));

package/dist/src/commands/typecheck.js

@@ -16,6 +16,8 @@
  * but do not fail. Designed for CI use.
  */
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
+import { findJsconfigPathsDrift, syncFurnaceJsconfigPaths } from '../core/furnace-jsconfig.js';
 import { relativeForDisplay, runTypecheck } from '../core/typecheck.js';
 import { GeneralError } from '../errors/base.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
@@ -32,6 +34,11 @@ export function resolveTypecheckProjects(configTypecheck, override) {
         return {
             projects: [override],
             ...(configTypecheck?.extraShim !== undefined ? { extraShim: configTypecheck.extraShim } : {}),
+            // Preserve any per-project override for the targeted path so a one-off
+            // `--project` run honours its opt-out / shim override just like a full run.
+            ...(configTypecheck?.projectOverrides !== undefined
+                ? { projectOverrides: configTypecheck.projectOverrides }
+                : {}),
         };
     }
     if (!configTypecheck) {
@@ -64,10 +71,38 @@ export async function typecheckCommand(projectRoot, options) {
     getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
     const cfg = resolveTypecheckProjects(config.typecheck, options.project);
+    // Regenerate a stale Furnace-managed jsconfig before running: the generated
+    // `compilerOptions.paths` shim drifts when components are added/renamed
+    // without a re-deploy, and a stale shim reports type errors in files the
+    // session never touched (e.g. 47 phantom errors from an out-of-date
+    // chrome-module mapping). Run the same reconciler `furnace deploy`/`sync`
+    // use so typecheck checks against the current workspace.
+    await regenerateStaleGeneratedJsconfig(projectRoot);
     info(`Running typecheck across ${String(cfg.projects.length)} project(s): ${cfg.projects.join(', ')}`);
     const results = await runTypecheck(projectRoot, cfg);
     reportResults(projectRoot, results);
 }
+/**
+ * Staleness-checks and regenerates the Furnace-managed jsconfig
+ * (`furnace.json` → `typecheckJsconfig`) before typecheck runs. No-op when
+ * the project has no furnace.json or no `typecheckJsconfig` is configured.
+ * A missing `typecheckJsconfig` file surfaces the reconciler's own clear
+ * error rather than producing phantom type diagnostics.
+ */
+async function regenerateStaleGeneratedJsconfig(projectRoot) {
+    if (!(await furnaceConfigExists(projectRoot)))
+        return;
+    const furnaceConfig = await loadFurnaceConfig(projectRoot);
+    if (!furnaceConfig.typecheckJsconfig)
+        return;
+    const drift = await findJsconfigPathsDrift(projectRoot, furnaceConfig);
+    if (!drift.changed)
+        return;
+    info(`Regenerating stale generated jsconfig ${furnaceConfig.typecheckJsconfig} before typecheck ` +
+        `(+${String(drift.added.length)} added, ~${String(drift.updated.length)} updated, ` +
+        `-${String(drift.pruned.length)} pruned).`);
+    await syncFurnaceJsconfigPaths(projectRoot, furnaceConfig);
+}
 /**
  * Prints all issues, computes the per-project + total counts, and
  * throws on errors. Extracted so it can be exercised directly by

package/dist/src/core/build-prepare.js

@@ -14,9 +14,23 @@ import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
 import { runFurnaceMutation } from './furnace-operation.js';
 import { cleanStories } from './furnace-stories.js';
-import { generateMozconfig, runMach } from './mach.js';
+import { generateMozconfig, runMachCapture } from './mach.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
+/**
+ * Extracts the tail of captured `mach configure` output so the underlying
+ * mozbuild failure (e.g. `mozbuild.util.UnsortedError: ... is not in sorted
+ * order`) is carried into the thrown `BuildError` instead of being reduced to
+ * a bare exit code. mozbuild writes the error and its traceback to stderr;
+ * stdout is included as a fallback for shells that interleave the streams.
+ * Returns an empty string when nothing useful was captured.
+ */
+function extractMachConfigureError(result) {
+    const combined = `${result.stderr}\n${result.stdout}`.trim();
+    if (!combined)
+        return '';
+    return combined.split('\n').slice(-40).join('\n').trim();
+}
 /**
  * Returns true when the file path matches a pattern that forces
  * `mach configure` to regenerate the backend. Exported for testing.
@@ -65,10 +79,16 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
             info(`Backend command: mach configure`);
             const configureSpinner = spinner('Running mach configure...');
             try {
-                const exitCode = await runMach(['configure'], paths.engine);
+                const captured = await runMachCapture(['configure'], paths.engine);
+                const exitCode = captured.exitCode;
                 if (exitCode !== 0) {
                     configureSpinner.error(`mach configure failed with exit code ${exitCode}`);
-                    throw new BuildError(`Backend regeneration failed: mach configure exited with code ${exitCode}. Build stopped because continuing would hide the real configure failure.`, 'mach configure');
+                    // Surface the underlying mozbuild error (e.g. UnsortedError) instead
+                    // of a bare exit code — the generic message hid the actual cause.
+                    const detail = extractMachConfigureError(captured);
+                    throw new BuildError(`Backend regeneration failed: mach configure exited with code ${exitCode}.` +
+                        (detail ? `\n\nmach configure output (tail):\n${detail}` : '') +
+                        '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
                 }
                 else {
                     configureSpinner.stop('Backend regenerated successfully (mach configure exit code 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.