@hominis/fireforge 0.30.1 → 0.31.0

package/dist/src/core/patch-manifest-validate.d.ts

@@ -1,14 +1,7 @@
 /**
  * Schema validation for patches.json manifest data.
  */
-import type { PatchCategory, PatchesManifest, PatchMetadata } from '../types/commands/index.js';
-/**
- * Validates a single patch metadata entry from raw data.
- * @param data - Raw data to validate
- * @param index - Array index for error messages
- * @returns Validated PatchMetadata
- */
-export declare function validatePatchMetadata(data: unknown, index: number): PatchMetadata;
+import type { PatchCategory, PatchesManifest } from '../types/commands/index.js';
 /** Validates raw patches.json data and returns the typed manifest shape. */
 export declare function validatePatchesManifest(data: unknown): PatchesManifest;
 /**

package/dist/src/core/patch-manifest-validate.js

@@ -39,7 +39,7 @@ function parseStagedDependencies(data, label) {
  * @param index - Array index for error messages
  * @returns Validated PatchMetadata
  */
-export function validatePatchMetadata(data, index) {
+function validatePatchMetadata(data, index) {
     const rec = parseObject(data, `patches[${index}]`);
     const filename = rec.string('filename');
     const name = rec.string('name');

package/dist/src/core/patch-manifest.d.ts

@@ -5,7 +5,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';

package/dist/src/core/patch-manifest.js

@@ -6,7 +6,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';

package/dist/src/core/patch-policy.d.ts

@@ -8,8 +8,6 @@
  */
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
-/** Default patch filename contract used when a policy omits `filenamePattern`. */
-export declare const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = "^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$";
 /** Stable issue codes returned by patch policy evaluation. */
 export type PatchPolicyIssueCode = 'filename-pattern' | 'filename-captures' | 'filename-metadata-mismatch' | 'order-collision' | 'category-range' | 'reserved-range' | 'reserved-documentation' | 'reserved-files' | 'description-required' | 'numeric-gap';
 /** A single patch policy validation finding. */
@@ -26,8 +24,6 @@ export interface PatchPolicyEnforcementInput {
     command: string;
     forceUnsafe?: boolean;
 }
-/** Returns true when the loaded config includes an opt-in patch policy. */
-export declare function hasPatchPolicy(config: FireForgeConfig): boolean;
 /** Returns valid categories for prompts and CLI validation under the config. */
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
 /** Checks whether a category is accepted by legacy defaults or the policy ranges. */

package/dist/src/core/patch-policy.js

@@ -10,8 +10,9 @@
 import { InvalidArgumentError } from '../errors/base.js';
 import { warn } from '../utils/logger.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
+import { rewriteStagedDependencyOwners } from './patch-manifest-io.js';
 /** Default patch filename contract used when a policy omits `filenamePattern`. */
-export const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
+const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
 function policy(config) {
     return config.patchPolicy;
 }
@@ -22,7 +23,7 @@ function issueSeverity(config) {
     return mutationMode(config) === 'warn' ? 'warning' : 'error';
 }
 /** Returns true when the loaded config includes an opt-in patch policy. */
-export function hasPatchPolicy(config) {
+function hasPatchPolicy(config) {
     return policy(config) !== undefined;
 }
 /** Returns valid categories for prompts and CLI validation under the config. */
@@ -305,12 +306,17 @@ export function buildProjectedManifest(current, patches) {
 }
 /** Applies a filename/order rename projection to a manifest without mutating it. */
 export function applyRenameMapToManifest(manifest, renameMap) {
+    const ownerLookup = (oldFilename) => renameMap.get(oldFilename)?.newFilename;
     return buildProjectedManifest(manifest, manifest.patches.map((patch) => {
+        // Staged-dependency owners reference other patches' filenames, so the
+        // projection rewrites them on every row to mirror what
+        // renumberPatchesInManifest persists.
+        const withOwners = rewriteStagedDependencyOwners(patch, ownerLookup);
         const rename = renameMap.get(patch.filename);
         if (!rename)
-            return patch;
+            return withOwners;
         return {
-            ...patch,
+            ...withOwners,
             filename: rename.newFilename,
             order: rename.newOrder,
         };

package/dist/src/core/register-browser-content.d.ts

@@ -1,7 +1,7 @@
 /**
  * JS/content registration in browser/base/jar.mn.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Registers a JS/content file in browser/base/jar.mn.
  *

package/dist/src/core/register-module.d.ts

@@ -1,7 +1,7 @@
 /**
  * Module registration in browser/modules/{binaryName}/moz.build.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Registers a module in browser/modules/{binaryName}/moz.build.
  *

package/dist/src/core/register-result.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared result shape for manifest registration operations, split out of
+ * the `manifest-register.ts` barrel so the `register-*` leaf modules can
+ * import it without importing the barrel that re-exports them — that
+ * type-only back-edge made the registration dependency graph cyclic.
+ */
+/**
+ * Result of a manifest registration operation.
+ */
+export interface RegisterResult {
+    /** The manifest file that was modified */
+    manifest: string;
+    /** The entry that was inserted */
+    entry: string;
+    /** The entry after which the new entry was inserted (for user display) */
+    previousEntry?: string | undefined;
+    /** Whether the entry already existed (skipped) */
+    skipped: boolean;
+    /** Whether --after target was not found and fell back to alphabetical */
+    afterFallback?: boolean | undefined;
+}

package/dist/src/core/register-result.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared result shape for manifest registration operations, split out of
+ * the `manifest-register.ts` barrel so the `register-*` leaf modules can
+ * import it without importing the barrel that re-exports them — that
+ * type-only back-edge made the registration dependency graph cyclic.
+ */
+export {};
+//# sourceMappingURL=register-result.js.map

package/dist/src/core/register-shared-css.d.ts

@@ -1,7 +1,7 @@
 /**
  * CSS registration in browser/themes/shared/jar.inc.mn.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Measures the column at which the `(source)` parenthesis opens in
  * adjacent `skin/classic/browser/<x>.css (...)` entries inside an

package/dist/src/core/register-test-manifest.d.ts

@@ -1,7 +1,7 @@
 /**
  * Test manifest registration in browser/base/moz.build.
  */
-import type { RegisterResult } from './manifest-register.js';
+import type { RegisterResult } from './register-result.js';
 /**
  * Registers a test manifest (browser.toml) in browser/base/moz.build.
  *

package/dist/src/core/test-harness-crash.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Harness-crash classification for `fireforge test` (field reports C1/C2).
+ *
+ * The wrapped mach harness exhibits flaky non-test failures that an exit
+ * code (or a "did it print a summary" grep) cannot distinguish from real
+ * test results:
+ *
+ *  - startup crashes from the mozlog resource monitor on macOS
+ *    (`AttributeError: 'SystemResourceMonitor' object has no attribute
+ *    'poll_interval'`, `host_statistics64(HOST_VM_INFO64) syscall failed`,
+ *    `(ipc/mig) array not large enough` — a psutil/macOS mismatch) which
+ *    abort the run before any test executes;
+ *  - hangs after browser startup that die at the no-output timeout yet
+ *    still emit a `Passed: 0` summary;
+ *  - post-green shutdown re-entry, where a fully green run stalls on
+ *    "must wait for focus" and records "Application shut down (without
+ *    crashing) in the middle of a test!" as the only unexpected failure.
+ *
+ * Classification therefore keys on `TEST-START` presence — summary lines
+ * never count as proof that tests ran — and recognizes the crash shapes
+ * above so the command layer can retry them with a bounded budget instead
+ * of reporting phantom test failures (or phantom passes).
+ */
+/** How a completed harness run should be interpreted. */
+export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'no-tests';
+/** A recognized harness-crash shape with its evidence line. */
+export interface HarnessCrashSignature {
+    reason: string;
+    line: string;
+}
+/** Result of {@link classifyHarnessRun}. */
+export interface HarnessRunVerdict {
+    kind: HarnessRunClassification;
+    signature?: HarnessCrashSignature;
+}
+/**
+ * Detects the known harness-crash shapes in captured mach output.
+ * Returns undefined for anything that looks like a genuine test result.
+ */
+export declare function detectHarnessCrashSignature(output: string): HarnessCrashSignature | undefined;
+/**
+ * Classifies a completed harness run. The decision tree, in order:
+ *
+ * 1. A recognized crash signature wins regardless of exit code (the
+ *    shutdown re-entry shape exits non-zero on an otherwise green run;
+ *    the hang shape can even exit zero with a `Passed: 0` summary).
+ * 2. No `TEST-START` with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. Summary lines are not
+ *    trusted as evidence of execution.
+ * 3. Exit code zero with tests started is a pass; anything else is a
+ *    test failure for the regular diagnosis chain.
+ */
+export declare function classifyHarnessRun(exitCode: number, output: string, requestedPaths: readonly string[]): HarnessRunVerdict;
+/** Builds the operator-facing failure message after retries are exhausted. */
+export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number): string;
+/**
+ * Builds the message for a run that produced no `TEST-START` despite
+ * requesting paths — including exit-code-zero runs whose `Passed: 0`
+ * summary would otherwise read as a silent false green.
+ */
+export declare function buildNoTestsRanMessage(exitCode: number, requestedPaths: readonly string[]): string;

package/dist/src/core/test-harness-crash.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Harness-crash classification for `fireforge test` (field reports C1/C2).
+ *
+ * The wrapped mach harness exhibits flaky non-test failures that an exit
+ * code (or a "did it print a summary" grep) cannot distinguish from real
+ * test results:
+ *
+ *  - startup crashes from the mozlog resource monitor on macOS
+ *    (`AttributeError: 'SystemResourceMonitor' object has no attribute
+ *    'poll_interval'`, `host_statistics64(HOST_VM_INFO64) syscall failed`,
+ *    `(ipc/mig) array not large enough` — a psutil/macOS mismatch) which
+ *    abort the run before any test executes;
+ *  - hangs after browser startup that die at the no-output timeout yet
+ *    still emit a `Passed: 0` summary;
+ *  - post-green shutdown re-entry, where a fully green run stalls on
+ *    "must wait for focus" and records "Application shut down (without
+ *    crashing) in the middle of a test!" as the only unexpected failure.
+ *
+ * Classification therefore keys on `TEST-START` presence — summary lines
+ * never count as proof that tests ran — and recognizes the crash shapes
+ * above so the command layer can retry them with a bounded budget instead
+ * of reporting phantom test failures (or phantom passes).
+ */
+const TEST_START_PATTERN = /\bTEST-START\b/;
+const UNEXPECTED_LINE_PATTERN = /^.*\bTEST-UNEXPECTED-[A-Z-]+\b.*$/gm;
+const SHUTDOWN_REENTRY_PATTERN = /Application shut down \(without crashing\) in the middle of a test/i;
+const FOCUS_STALL_PATTERN = /must wait for focus/i;
+const TRACEBACK_PATTERN = /Traceback \(most recent call last\)/;
+const NO_OUTPUT_TIMEOUT_PATTERN = /timed out after \d+ seconds with no output/i;
+/**
+ * Startup-traceback fingerprints from the mozlog resource monitor / psutil
+ * on macOS. Each is matched per-line so the evidence line in the report is
+ * the concrete failure, not the whole traceback.
+ */
+const STARTUP_TRACEBACK_SIGNALS = [
+    /AttributeError:.*SystemResourceMonitor/,
+    /'SystemResourceMonitor' object has no attribute/,
+    /poll_interval/,
+    /host_statistics64/,
+    /HOST_VM_INFO64/,
+    /\(ipc\/mig\) array not large enough/,
+    /psutil\.[A-Za-z]*Error/,
+];
+function findLine(output, patterns) {
+    for (const line of output.split(/\r?\n/)) {
+        if (patterns.some((p) => p.test(line)))
+            return line.trim();
+    }
+    return undefined;
+}
+/** Unexpected-failure lines that are NOT the shutdown re-entry artifact. */
+function realUnexpectedFailureLines(output) {
+    const matches = output.match(UNEXPECTED_LINE_PATTERN) ?? [];
+    return matches.filter((line) => !SHUTDOWN_REENTRY_PATTERN.test(line));
+}
+/**
+ * Detects the known harness-crash shapes in captured mach output.
+ * Returns undefined for anything that looks like a genuine test result.
+ */
+export function detectHarnessCrashSignature(output) {
+    const hasTestStart = TEST_START_PATTERN.test(output);
+    const realFailures = realUnexpectedFailureLines(output);
+    // Startup traceback cluster (resource monitor / psutil). Real test
+    // failures take precedence: a traceback printed during teardown of a
+    // genuinely failing run must not get the whole run retried.
+    if (TRACEBACK_PATTERN.test(output) && realFailures.length === 0) {
+        const signalLine = findLine(output, STARTUP_TRACEBACK_SIGNALS);
+        if (signalLine) {
+            return { reason: 'harness startup traceback (resource monitor/psutil)', line: signalLine };
+        }
+    }
+    // Post-browser-startup hang: no test ever started, the harness died at
+    // the no-output timeout. A trailing "Passed: 0" summary is part of this
+    // shape and must not be read as a result.
+    if (!hasTestStart) {
+        const timeoutLine = findLine(output, [NO_OUTPUT_TIMEOUT_PATTERN]);
+        if (timeoutLine) {
+            return { reason: 'no-output timeout before any test started', line: timeoutLine };
+        }
+        return undefined;
+    }
+    // Post-green shutdown re-entry: every unexpected line is the
+    // shutdown-mid-test artifact, the run stalled on focus, and at least one
+    // such artifact exists — an otherwise green log.
+    const shutdownLine = findLine(output, [SHUTDOWN_REENTRY_PATTERN]);
+    if (shutdownLine && realFailures.length === 0 && FOCUS_STALL_PATTERN.test(output)) {
+        return { reason: 'post-green shutdown re-entry during harness teardown', line: shutdownLine };
+    }
+    return undefined;
+}
+/**
+ * Classifies a completed harness run. The decision tree, in order:
+ *
+ * 1. A recognized crash signature wins regardless of exit code (the
+ *    shutdown re-entry shape exits non-zero on an otherwise green run;
+ *    the hang shape can even exit zero with a `Passed: 0` summary).
+ * 2. No `TEST-START` with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. Summary lines are not
+ *    trusted as evidence of execution.
+ * 3. Exit code zero with tests started is a pass; anything else is a
+ *    test failure for the regular diagnosis chain.
+ */
+export function classifyHarnessRun(exitCode, output, requestedPaths) {
+    const signature = detectHarnessCrashSignature(output);
+    if (signature) {
+        return { kind: 'harness-crash', signature };
+    }
+    if (!TEST_START_PATTERN.test(output) && requestedPaths.length > 0) {
+        return { kind: 'no-tests' };
+    }
+    return exitCode === 0 ? { kind: 'tests-ran-ok' } : { kind: 'test-failures' };
+}
+/** Builds the operator-facing failure message after retries are exhausted. */
+export function buildHarnessCrashMessage(signature, attempts) {
+    return (`mach test crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
+        `Detected shape: ${signature.reason}\n` +
+        `Evidence line: ${signature.line}\n\n` +
+        'This failure mode is environmental (mozlog resource monitor / psutil on macOS, focus-stall ' +
+        'shutdown re-entry, or a pre-test hang) rather than a test regression. Re-run the command, ' +
+        'raise the retry budget with --harness-retries <n>, or run the file in isolation. ' +
+        'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
+        'patching it manually does not stick).');
+}
+/**
+ * Builds the message for a run that produced no `TEST-START` despite
+ * requesting paths — including exit-code-zero runs whose `Passed: 0`
+ * summary would otherwise read as a silent false green.
+ */
+export function buildNoTestsRanMessage(exitCode, requestedPaths) {
+    const exitNote = exitCode === 0
+        ? 'The harness exited 0 and may have printed a summary line, but a summary without a single TEST-START is not a test result.'
+        : `The harness exited ${exitCode} before any TEST-START line.`;
+    return ('mach test finished without starting any of the requested tests.\n\n' +
+        `${exitNote}\n\n` +
+        `Requested paths: ${requestedPaths.join(', ')}\n\n` +
+        'Check that the paths are registered in their test manifest (browser.toml / xpcshell.toml) ' +
+        'and that the manifest is reachable from moz.build, then retry.');
+}
+//# sourceMappingURL=test-harness-crash.js.map

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,4 @@
-import type { BuildBaseline } from './build-baseline.js';
+import type { BuildBaseline } from './build-baseline-types.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */

package/dist/src/core/test-stale-check.js

@@ -30,53 +30,9 @@ import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { isPackageablePath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
-import { hasChanges, isMissingHeadError } from './git.js';
-import { git } from './git-base.js';
-import { getUntrackedFiles } from './git-status.js';
+import { collectChangedEnginePaths } from './engine-changes.js';
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
-/**
- * Collects engine paths that changed since the baseline SHA plus any
- * workdir modifications. Mirrors the helper inside `build-prepare.ts` but
- * is kept separate so the test-side preflight does not need to pull in
- * the full build-prepare dependency graph (mozconfig generation, furnace
- * apply hooks, …).
- */
-async function collectChangedEnginePaths(engineDir, baseline) {
-    const collected = new Set();
-    if (baseline.engineHeadSha) {
-        try {
-            const diff = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
-            for (const line of diff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-        }
-        catch (error) {
-            if (!isMissingHeadError(error)) {
-                verbose(`Stale-build preflight: could not diff engine against baseline — ${toError(error).message}`);
-            }
-        }
-    }
-    try {
-        if (await hasChanges(engineDir)) {
-            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
-            for (const line of worktreeDiff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-            for (const untracked of await getUntrackedFiles(engineDir)) {
-                collected.add(untracked);
-            }
-        }
-    }
-    catch (error) {
-        verbose(`Stale-build preflight: could not enumerate workdir changes — ${toError(error).message}`);
-    }
-    return [...collected];
-}
 /**
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
@@ -92,7 +48,7 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     if (!baseline) {
         return { stale: false, changedPaths: [], truncated: 0, baseline: undefined };
     }
-    const changed = await collectChangedEnginePaths(engineDir, baseline);
+    const changed = await collectChangedEnginePaths(engineDir, baseline, 'Stale-build preflight');
     let packageable = changed.filter((path) => isPackageablePath(path)).sort();
     // Content-hash comparison: when the baseline carries a fingerprint set,
     // fold each candidate path through a live re-hash and drop paths whose

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -4,4 +4,4 @@ export interface XpcshellRetryClassification {
     nonXpcshell: readonly string[];
 }
 /** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[]): Promise<MachCommandResult>;
+export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -2,13 +2,15 @@
 import { testWithOutput } from './mach.js';
 import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
 /** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs) {
+export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env) {
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
         const repaired = await tryRepairStaleXpcshellTestSymlink(engineDir, objDir, `${result.stdout}\n${result.stderr}`);
         if (repaired) {
-            return testWithOutput(engineDir, normalizedPaths, extraArgs);
+            return env
+                ? testWithOutput(engineDir, normalizedPaths, extraArgs, env)
+                : testWithOutput(engineDir, normalizedPaths, extraArgs);
         }
     }
     return result;

package/dist/src/core/token-dark-mode.js

@@ -111,13 +111,22 @@ export function findDarkRootInsertionIndex(lines) {
     }
     if (rootOpenLine === -1)
         return -1;
-    // Depth-count starting from the `:root` opener. The first `{`
-    // encountered sets the entry depth to the initial counter value; the
-    // closing brace that returns to that depth terminates the block.
+    // Depth-count starting from the `:root` opener; see findBlockCloseIndex.
+    return findBlockCloseIndex(stripped, rootOpenLine);
+}
+/**
+ * Depth-counts braces from `startLine` (whose lines must already have
+ * block comments stripped), returning the index of the line on which the
+ * block opened there returns to its entry depth — i.e. the line carrying
+ * the block's closing `}` — or -1 when the block never closes. The first
+ * `{` encountered sets the entry depth, so the scan may start on the
+ * selector/at-rule line itself rather than on the opener.
+ */
+function findBlockCloseIndex(stripped, startLine) {
     let depth = 0;
     let entryDepth = 0;
     let enteredBlock = false;
-    for (let i = rootOpenLine; i < stripped.length; i++) {
+    for (let i = startLine; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
         for (const ch of line) {
             if (ch === '{') {
@@ -156,27 +165,6 @@ export function findDarkMediaCloseIndex(lines) {
     }
     if (darkMediaLine === -1)
         return -1;
-    let depth = 0;
-    let entryDepth = 0;
-    let enteredBlock = false;
-    for (let i = darkMediaLine; i < stripped.length; i++) {
-        const line = stripped[i] ?? '';
-        for (const ch of line) {
-            if (ch === '{') {
-                depth++;
-                if (!enteredBlock) {
-                    entryDepth = depth - 1;
-                    enteredBlock = true;
-                }
-            }
-            else if (ch === '}') {
-                depth--;
-            }
-        }
-        if (enteredBlock && depth === entryDepth) {
-            return i;
-        }
-    }
-    return -1;
+    return findBlockCloseIndex(stripped, darkMediaLine);
 }
 //# sourceMappingURL=token-dark-mode.js.map

package/dist/src/core/token-manager.d.ts

@@ -20,6 +20,8 @@ export interface AddTokenOptions {
     darkValue?: string | undefined;
     /** Dry run mode */
     dryRun?: boolean | undefined;
+    /** Declare the category banner in the tokens CSS when it does not exist yet. */
+    createCategory?: boolean | undefined;
 }
 /**
  * Result of adding a token.
@@ -35,6 +37,8 @@ export interface AddTokenResult {
     countUpdated: boolean;
     /** Whether the operation was skipped (already exists) */
     skipped: boolean;
+    /** Whether a new category banner was declared by this add. */
+    categoryCreated?: boolean;
 }
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export declare function getTokensCssPath(binaryName: string): string;