@hominis/fireforge 0.31.0 → 0.33.0

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/re-export-files.js

@@ -198,7 +198,10 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // standard re-export path).
     const { effectiveTier, effectiveLintIgnore, flagIgnoreSet } = resolveEffectiveTierAndLintIgnore(target, options);
     const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
-    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
+    const patchQueueCtx = (await pathExists(paths.patches))
+        ? await buildPatchQueueContext(paths.patches)
+        : undefined;
+    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, effectiveTier);
     const conflicts = await runProjectedCrossPatchLint(paths.patches, target.filename, projectedDiff);
     const filesUpdates = buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet);
     const manifest = await loadPatchesManifest(paths.patches);

package/dist/src/commands/re-export.js

@@ -7,6 +7,7 @@ import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
+import { buildPatchQueueContext } from '../core/patch-lint.js';
 import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
@@ -185,7 +186,13 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         command: 're-export',
         forceUnsafe: options.forceUnsafe === true,
     });
-    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
+    // Pass the whole-queue context so checkJs resolves cross-patch
+    // `resource:///` imports against the real owning sources (report scope
+    // stays this patch — see runPatchLint).
+    const patchQueueCtx = (await pathExists(paths.patches))
+        ? await buildPatchQueueContext(paths.patches)
+        : undefined;
+    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, patchQueueCtx, ignoreChecks, effectiveTier);
     if (isDryRun) {
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
         if (effectiveTier !== undefined && effectiveTier !== patch.tier) {

package/dist/src/commands/test-run.d.ts

@@ -14,6 +14,14 @@ import { type MachCommandResult } from '../core/mach.js';
 import { type HarnessRunVerdict } from '../core/test-harness-crash.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export declare const DEFAULT_HARNESS_RETRIES = 2;
+/**
+ * Which mach command a run dispatches to. Single-suite runs use the
+ * suite-specific command (`mach xpcshell-test` / `mach mochitest`), which
+ * skips the mozlog resource monitor that crashes generic `mach test` on a
+ * broken host (field report E1). `generic` is the historical `mach test`
+ * path (mixed/all-tests runs, or the `--generic-mach-test` opt-out).
+ */
+export type TestSuite = 'xpcshell' | 'mochitest' | 'generic';
 /** Inputs shared by every harness invocation in one `fireforge test` run. */
 export interface TestRunContext {
     engineDir: string;
@@ -22,6 +30,8 @@ export interface TestRunContext {
         xpcshell: string[];
         nonXpcshell: string[];
     };
+    /** Suite-specific dispatch target for this run (E1). */
+    suite: TestSuite;
     /** Extra mach args before per-shard appdir injection. */
     baseExtraArgs: readonly string[];
     /** Bounded harness-crash retry budget (0 disables retries). */

package/dist/src/commands/test-run.js

@@ -11,7 +11,7 @@
  * harness runs cost startup time but make results reproducible; the
  * combined invocation stays available via `--no-shard`.
  */
-import { testWithOutput } from '../core/mach.js';
+import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.js';
 import { buildHarnessCrashMessage, classifyHarnessRun, } from '../core/test-harness-crash.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { BuildError } from '../errors/build.js';
@@ -19,6 +19,14 @@ import { info, note, warn } from '../utils/logger.js';
 import { maybeInjectAppdirArg } from './test-appdir.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
+/** Resolves the capturing mach dispatcher for a suite. */
+function dispatchForSuite(suite) {
+    if (suite === 'xpcshell')
+        return xpcshellTestWithOutput;
+    if (suite === 'mochitest')
+        return mochitestWithOutput;
+    return testWithOutput;
+}
 /**
  * Runs one mach test invocation for `paths`, retrying recognized harness
  * crashes up to the configured budget. Every attempt goes through the
@@ -27,6 +35,7 @@ export const DEFAULT_HARNESS_RETRIES = 2;
 export async function runTestsWithRetries(ctx, paths) {
     const extraArgs = [...ctx.baseExtraArgs];
     const appdirInjectionAttempted = await maybeInjectAppdirArg(ctx.engineDir, paths, ctx.objDir, extraArgs);
+    const dispatch = dispatchForSuite(ctx.suite);
     const maxAttempts = Math.max(1, ctx.harnessRetries + 1);
     let attempts = 0;
     let result;
@@ -34,9 +43,9 @@ export async function runTestsWithRetries(ctx, paths) {
     for (;;) {
         attempts += 1;
         result = ctx.env
-            ? await testWithOutput(ctx.engineDir, paths, extraArgs, ctx.env)
-            : await testWithOutput(ctx.engineDir, paths, extraArgs);
-        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, ctx.env);
+            ? await dispatch(ctx.engineDir, paths, extraArgs, ctx.env)
+            : await dispatch(ctx.engineDir, paths, extraArgs);
+        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, ctx.env, dispatch);
         const combined = `${result.stdout}\n${result.stderr}`;
         verdict = classifyHarnessRun(result.exitCode, combined, paths);
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)

package/dist/src/commands/test.js

@@ -5,6 +5,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, withBuildLock, } from '../core/mach.js';
 import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
+import { buildHarnessCrashMessage, detectHarnessCrashSignature, } from '../core/test-harness-crash.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
@@ -42,6 +43,25 @@ async function classifyTestHarnesses(engineDir, normalizedPaths) {
     }
     return result;
 }
+/**
+ * Picks the mach dispatch target for a (non-mixed) run. A single-suite run
+ * auto-routes to the suite-specific command (`mach xpcshell-test` /
+ * `mach mochitest`), which degrades a broken host resource monitor to a
+ * warning instead of crashing generic `mach test` at startup (E1). Mixed runs
+ * are rejected before this point; a path-less "run all" or an explicit
+ * `--generic-mach-test` opt-out stays on the generic command.
+ */
+function resolveTestSuite(classification, forceGeneric) {
+    if (forceGeneric)
+        return 'generic';
+    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length === 0) {
+        return 'xpcshell';
+    }
+    if (classification.nonXpcshell.length > 0 && classification.xpcshell.length === 0) {
+        return 'mochitest';
+    }
+    return 'generic';
+}
 function buildMixedHarnessMessage(classification) {
     return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
         'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
@@ -80,16 +100,31 @@ async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
     }
     return bundleCheck.expectedPath;
 }
-async function runPreTestBuild(projectRoot, paths, projectConfig) {
+async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries) {
     await withBuildLock(projectRoot, async () => {
         await prepareBuildEnvironment(projectRoot, paths, projectConfig);
         const s = spinner('Running incremental build...');
-        const buildResult = await buildUI(paths.engine);
-        if (buildResult.exitCode !== 0) {
+        // The pre-test build runs through mach too, so the same resource-monitor
+        // startup crash that aborts `mach test` can abort `mach build faster`.
+        // Run the harness-crash classifier over the build output and retry within
+        // the same `--harness-retries` budget rather than hard-failing with a
+        // bare "Pre-test build failed" (field report E2).
+        const maxAttempts = Math.max(1, harnessRetries + 1);
+        for (let attempt = 1;; attempt += 1) {
+            const buildResult = await buildUI(paths.engine);
+            if (buildResult.exitCode === 0) {
+                s.stop('Build complete');
+                return;
+            }
+            const signature = detectHarnessCrashSignature(`${buildResult.stdout}\n${buildResult.stderr}`);
+            if (signature && attempt < maxAttempts) {
+                s.message(`Pre-test build hit a harness crash (${signature.reason}); ` +
+                    `retrying (attempt ${attempt + 1} of ${maxAttempts})...`);
+                continue;
+            }
             s.error('Pre-test build failed');
-            throw new BuildError('Pre-test build failed', 'mach build faster');
+            throw new BuildError(signature ? buildHarnessCrashMessage(signature, attempt) : 'Pre-test build failed', 'mach build faster');
         }
-        s.stop('Build complete');
     });
 }
 function logTestSelection(normalizedPaths) {
@@ -239,9 +274,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // missing-bundle path instead of a cryptic `Browser process exited
     // during spawn (exit code 1, signal none). stderr tail: (empty)`.
     const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
+    const harnessRetries = options.harnessRetries ?? DEFAULT_HARNESS_RETRIES;
     // Run incremental build if requested
     if (options.build) {
-        await runPreTestBuild(projectRoot, paths, projectConfig);
+        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries);
         info('');
     }
     else {
@@ -299,6 +335,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
         throw new GeneralError(buildMixedHarnessMessage(classification));
     }
+    const suite = resolveTestSuite(classification, options.genericMachTest === true);
     const forwardedMachArgs = options.machArg && options.machArg.length > 0
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
         : [];
@@ -325,8 +362,9 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         engineDir: paths.engine,
         objDir: buildCheck.objDir,
         classification,
+        suite,
         baseExtraArgs: extraArgs,
-        harnessRetries: options.harnessRetries ?? DEFAULT_HARNESS_RETRIES,
+        harnessRetries,
         ...(perfSampleEnv ? { env: perfSampleEnv } : {}),
     };
     const postRebuildContext = options.build
@@ -381,6 +419,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         }
         return n;
     })
+        .option('--generic-mach-test', 'Force dispatch through generic `mach test` instead of the suite-specific `mach xpcshell-test` / `mach mochitest` a single-suite run auto-selects (the suite-specific commands skip the mozlog resource monitor that crashes `mach test` on some hosts).')
         .option('--no-shard', 'Run multiple test paths in one combined mach invocation instead of sequential per-file shards')
         .option('--perf-samples <path>', 'Publish a perf-sample artifact path to the harness via <BINARYNAME>_PERF_SAMPLE_JSON (resolved against the project root)')
         .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) auto-forwarded mach args: --setpref=marionette.port=<n> (browser listener) and --marionette=127.0.0.1:<n> (mochitest client). Omits the client flag when --mach-arg already sets --marionette. Use when 2828 is busy or CI assigns another port.', (raw) => {

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

@@ -243,6 +243,28 @@ const PATCH_LINT_CHECKJS_COMPILER_OPTION_KEYS = [
     'noUnusedLocals',
     'noUnusedParameters',
 ];
+/**
+ * Validates the reviewed `paths` mapping: an object of pattern → string[]
+ * targets, each pattern carrying at most one `*`. Lets patch-owned modules
+ * be typed from their real sources without an ambient stub shim.
+ */
+function parseCheckJsPathsMapping(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new ConfigError('Config field "patchLint.checkJsCompilerOptions.paths" must be a plain object');
+    }
+    const rec = raw;
+    const out = {};
+    for (const [pattern, targets] of Object.entries(rec)) {
+        if ((pattern.match(/\*/g) ?? []).length > 1) {
+            throw new ConfigError(`Config field "patchLint.checkJsCompilerOptions.paths" key "${pattern}" may contain at most one "*"`);
+        }
+        if (!Array.isArray(targets) || targets.some((t) => typeof t !== 'string')) {
+            throw new ConfigError(`Config field "patchLint.checkJsCompilerOptions.paths.${pattern}" must be an array of strings`);
+        }
+        out[pattern] = targets;
+    }
+    return out;
+}
 function parsePatchLintCheckJsCompilerOptions(raw) {
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
         throw new ConfigError('Config field "patchLint.checkJsCompilerOptions" must be a plain object');
@@ -251,6 +273,10 @@ function parsePatchLintCheckJsCompilerOptions(raw) {
     const allowed = new Set(PATCH_LINT_CHECKJS_COMPILER_OPTION_KEYS);
     const out = {};
     for (const key of Object.keys(rec)) {
+        if (key === 'paths') {
+            out.paths = parseCheckJsPathsMapping(rec[key]);
+            continue;
+        }
         if (!allowed.has(key)) {
             throw new ConfigError(`Config field "patchLint.checkJsCompilerOptions" has unknown key "${key}"`);
         }
@@ -375,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 {};