@hominis/fireforge 0.15.5 → 0.15.7

package/dist/src/commands/furnace/chrome-doc.js

@@ -26,6 +26,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { pathExists, readText, writeText } from '../../utils/fs.js';
 import { intro, note, outro } from '../../utils/logger.js';
 import { generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, } from './chrome-doc-templates.js';
+import { chromeDocPackagingTestFileName, generateChromeDocPackagingManifest, generateChromeDocPackagingTest, } from './chrome-doc-tests.js';
 /** Chrome-doc name shape: lowercase ASCII, optional hyphens, no leading digit. */
 const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 /**
@@ -123,6 +124,28 @@ async function performChromeDocMutations(args) {
         const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
         await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
         written.push('browser/locales/jar.mn');
+        // --with-tests scaffolds an xpcshell packaging verification. All writes
+        // go through the same rollback journal so a SIGINT here restores the
+        // source files and jar.mn edits above alongside the test scaffold.
+        if (args.withTests) {
+            const testParentDir = `${args.binaryName}-xpcshell`;
+            const testDir = join(args.engineDir, 'browser/base/content/test', testParentDir, args.name);
+            const { ensureDir } = await import('../../utils/fs.js');
+            if (!(await pathExists(testDir))) {
+                recordCreatedDir(journal, testDir);
+            }
+            await ensureDir(testDir);
+            const hashHeader = getLicenseHeader(args.license, 'hash');
+            const testFileName = chromeDocPackagingTestFileName(args.name);
+            const testFilePath = join(testDir, testFileName);
+            await snapshotFile(journal, testFilePath);
+            await writeText(testFilePath, generateChromeDocPackagingTest(args.name, jsHeader));
+            written.push(`browser/base/content/test/${testParentDir}/${args.name}/${testFileName}`);
+            const manifestPath = join(testDir, 'xpcshell.toml');
+            await snapshotFile(journal, manifestPath);
+            await writeText(manifestPath, generateChromeDocPackagingManifest(args.name, hashHeader));
+            written.push(`browser/base/content/test/${testParentDir}/${args.name}/xpcshell.toml`);
+        }
     }
     catch (error) {
         await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
@@ -146,22 +169,32 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first to scaffold a chrome-doc.');
     }
     const withTitlebar = options.titlebar ?? true;
+    const withTests = options.withTests ?? false;
     const written = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocMutations({
         name,
         license,
         engineDir,
         withTitlebar,
+        withTests,
+        binaryName: forgeConfig.binaryName,
         operationContext: ctx,
     }));
+    const nextSteps = [
+        `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
+        `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,
+        `  3. Run "fireforge build" to validate packaging (post-build audit will flag`,
+        '     any entry whose file does not land in the dist bundle).',
+    ];
+    if (withTests) {
+        nextSteps.push(`  4. Register the xpcshell test directory in the nearest moz.build under`, `     XPCSHELL_TESTS_MANIFESTS, then run "fireforge test browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${name}/xpcshell.toml".`);
+    }
+    nextSteps.push('', 'Platform-module compatibility: this chrome document carries the', `  data-furnace-chrome-doc="${name}" sentinel on its root element. Upstream`, '  platform modules (DevToolsStartup, PageActions, SessionStore, …) observe', '  "browser-delayed-startup-finished" and walk INTO the window assuming the', '  browser.xhtml DOM; use the sentinel attribute as a guard in fork-side', '  patches to those modules. See README "Platform module compatibility".');
     note([
         `Chrome document "${name}" scaffolded:`,
         ...written.map((f) => `  engine/${f}`),
         '',
         'Next steps:',
-        `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
-        `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,
-        `  3. Run "fireforge build" to validate packaging (post-build audit will flag`,
-        '     any entry whose file does not land in the dist bundle).',
+        ...nextSteps,
     ].join('\n'), name);
     outro('Chrome document created');
 }

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedTestStyle } from './create.js';
+export interface DryRunPlanInput {
+    componentName: string;
+    localized: boolean;
+    register: boolean;
+    composes: string[] | undefined;
+    testStyle: ResolvedTestStyle;
+    description: string;
+    binaryName: string;
+}
+/**
+ * Builds the success-note body printed after `furnace create` has applied
+ * its mutations. Lives beside the dry-run formatter so the two renderings
+ * stay in lock-step when the scaffolded layout changes.
+ */
+export declare function formatSuccessNote(args: {
+    componentName: string;
+    files: string[];
+    testFiles: string[];
+    testStyle: ResolvedTestStyle;
+    binaryName: string;
+}): string;
+/**
+ * Builds the planned component + test file list for a dry-run preview.
+ *
+ * Mirrors the order `writeComponentFiles` and the test-style scaffolders
+ * would produce so the dry-run output matches what a real run prints on
+ * success. The component directory path is rendered relative to
+ * `components/custom/` to match the wording of the real success note.
+ */
+export declare function formatDryRunPlan(args: DryRunPlanInput): string;

package/dist/src/commands/furnace/create-dry-run.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Dry-run plan formatter for `furnace create`.
+ *
+ * Lives outside `create.ts` so the authoring command stays under the
+ * per-file LOC budget. The formatter is pure — all inputs are already
+ * resolved by the command's validation phase — so it can be exercised
+ * independently of the mutation plumbing.
+ */
+/**
+ * Builds the test-section fragment of the dry-run plan for a given
+ * harness choice. Kept separate from the top-level formatter so the
+ * switch over `testStyle` does not push the caller over the per-function
+ * complexity budget.
+ */
+function formatTestSection(args) {
+    const { testStyle, componentName, binaryName } = args;
+    if (testStyle === 'none')
+        return '';
+    const strippedName = componentName.startsWith('moz-') ? componentName.slice(4) : componentName;
+    const withoutBinaryPrefix = strippedName.startsWith(binaryName + '-')
+        ? strippedName.slice(binaryName.length + 1)
+        : strippedName;
+    const underscored = withoutBinaryPrefix.replace(/-/g, '_');
+    if (testStyle === 'browser-chrome') {
+        const testRoot = `engine/browser/base/content/test/${binaryName}/`;
+        return (`\n\nWould create test files in ${testRoot}:\n` +
+            `  browser.toml\n  head.js\n  browser_${binaryName}_${underscored}.js` +
+            `\n\nWould register ${binaryName}/browser.toml in engine/browser/base/moz.build`);
+    }
+    if (testStyle === 'xpcshell') {
+        const testRoot = `engine/browser/base/content/test/${binaryName}-xpcshell/${componentName}/`;
+        return `\n\nWould create xpcshell test files in ${testRoot}`;
+    }
+    // testStyle === 'mochikit' (last remaining branch in ResolvedTestStyle).
+    const testRoot = 'engine/toolkit/content/tests/widgets/';
+    return `\n\nWould create mochikit test file in ${testRoot}`;
+}
+/**
+ * Builds the success-note body printed after `furnace create` has applied
+ * its mutations. Lives beside the dry-run formatter so the two renderings
+ * stay in lock-step when the scaffolded layout changes.
+ */
+export function formatSuccessNote(args) {
+    const { componentName, files, testFiles, testStyle, binaryName } = args;
+    let note = `Files created in components/custom/${componentName}/:\n` +
+        files.map((f) => `  ${f}`).join('\n');
+    if (testFiles.length > 0) {
+        let testRoot;
+        if (testStyle === 'xpcshell') {
+            testRoot = `engine/browser/base/content/test/${binaryName}-xpcshell/${componentName}/`;
+        }
+        else if (testStyle === 'mochikit') {
+            testRoot = 'engine/toolkit/content/tests/widgets/';
+        }
+        else {
+            testRoot = `engine/browser/base/content/test/${binaryName}/`;
+        }
+        note += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
+    }
+    note +=
+        '\n\n' +
+            'Next steps:\n' +
+            `  1. Edit component files in components/custom/${componentName}/\n` +
+            '  2. Run "fireforge furnace preview" to see it\n' +
+            '  3. Run "fireforge build" to apply and build';
+    return note;
+}
+/**
+ * Builds the planned component + test file list for a dry-run preview.
+ *
+ * Mirrors the order `writeComponentFiles` and the test-style scaffolders
+ * would produce so the dry-run output matches what a real run prints on
+ * success. The component directory path is rendered relative to
+ * `components/custom/` to match the wording of the real success note.
+ */
+export function formatDryRunPlan(args) {
+    const { componentName, localized, register, composes, testStyle, description, binaryName } = args;
+    const componentFiles = [`${componentName}.mjs`, `${componentName}.css`];
+    if (localized)
+        componentFiles.push(`${componentName}.ftl`);
+    let plan = `Would create files in components/custom/${componentName}/:\n` +
+        componentFiles.map((f) => `  ${f}`).join('\n');
+    plan += formatTestSection({ testStyle, componentName, binaryName });
+    plan += `\n\nWould add custom entry to furnace.json:`;
+    plan += `\n  name: ${componentName}`;
+    plan += `\n  description: ${description || '(empty)'}`;
+    plan += `\n  register: ${register}`;
+    plan += `\n  localized: ${localized}`;
+    if (composes && composes.length > 0) {
+        plan += `\n  composes: ${composes.join(', ')}`;
+    }
+    return plan;
+}
+//# sourceMappingURL=create-dry-run.js.map

package/dist/src/commands/furnace/create-templates.js

@@ -103,6 +103,20 @@ export function generateXpcshellTestContent(name, header) {
 
 "use strict";
 
+// Chrome-URI access from xpcshell:
+//   Toolkit chrome (chrome://global/*) IS registered and resolvable from
+//   this harness — that is what the smoke assertion below uses.
+//
+//   Browser chrome (chrome://browser/*) is NOT registered unless the
+//   xpcshell.toml sets firefox-appdir = "browser" AND the built app bundle
+//   has landed every packaged chrome manifest. Even then, the set of
+//   manifests xpcshell loads lags what the real browser loads, so
+//   NetUtil.asyncFetch("chrome://browser/content/…") can still fail with
+//   NS_ERROR_FILE_NOT_FOUND against an artifact that IS present in
+//   obj-*/dist/. Assertions that need browser chrome URIs belong in a
+//   browser-chrome mochitest (fireforge furnace create --test-style=browser-chrome),
+//   not xpcshell.
+
 add_task(async function test_${name.replace(/-/g, '_')}_module_loads() {
   // Module-load smoke check: resolves the ESM at its registered chrome URI.
   // Replace or extend with storage-layer assertions as the component grows

package/dist/src/commands/furnace/create.js

@@ -15,6 +15,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
+import { formatDryRunPlan, formatSuccessNote } from './create-dry-run.js';
 import { scaffoldMochikitTestFiles } from './create-mochikit.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
 import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
@@ -374,7 +375,8 @@ function validateComposesTargets(config, componentName, composes) {
  */
 export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
-    intro('Furnace Create');
+    const isDryRun = options.dryRun ?? false;
+    intro(isDryRun ? 'Furnace Create (dry run)' : 'Furnace Create');
     // --- Resolve component name ---
     // Validation runs before we load/create any persisted furnace config so a
     // failed authoring command never auto-creates furnace.json in a fresh
@@ -453,6 +455,24 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // does not strand component files behind.
     const composes = options.compose;
     validateComposesTargets(config, componentName, composes);
+    // Dry-run exits here — every validation that does not need a write has
+    // already run, so the plan we render reflects exactly what the real
+    // command would do. The mutation phase and its rollback journal are
+    // intentionally skipped so no furnace.json/engine state is touched.
+    if (isDryRun) {
+        const plan = formatDryRunPlan({
+            componentName,
+            localized,
+            register,
+            composes,
+            testStyle,
+            description,
+            binaryName: forgeConfig.binaryName,
+        });
+        note(plan, componentName);
+        outro('Dry run complete (no files modified)');
+        return;
+    }
     // All validation is done. Hand off to the transactional mutation helper
     // so any failure restores the workspace and engine to their pre-command
     // state via the shared rollback journal. The mutation runs under the
@@ -480,29 +500,13 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         ftlChromeSubPath,
         operationContext: ctx,
     }));
-    // --- Success ---
-    let noteParts = `Files created in components/custom/${componentName}/:\n` +
-        files.map((f) => `  ${f}`).join('\n');
-    if (testFiles.length > 0) {
-        let testRoot;
-        if (testStyle === 'xpcshell') {
-            testRoot = `engine/browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${componentName}/`;
-        }
-        else if (testStyle === 'mochikit') {
-            testRoot = 'engine/toolkit/content/tests/widgets/';
-        }
-        else {
-            testRoot = `engine/browser/base/content/test/${forgeConfig.binaryName}/`;
-        }
-        noteParts += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
-    }
-    noteParts +=
-        '\n\n' +
-            'Next steps:\n' +
-            `  1. Edit component files in components/custom/${componentName}/\n` +
-            '  2. Run "fireforge furnace preview" to see it\n' +
-            '  3. Run "fireforge build" to apply and build';
-    note(noteParts, componentName);
+    note(formatSuccessNote({
+        componentName,
+        files,
+        testFiles,
+        testStyle,
+        binaryName: forgeConfig.binaryName,
+    }), componentName);
     outro('Component created');
 }
 //# sourceMappingURL=create.js.map

package/dist/src/commands/furnace/index.js

@@ -73,7 +73,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('--localized', 'Include Fluent l10n support')
         .option('--no-register', 'Skip customElements.js registration')
         .option('--with-tests', 'Scaffold a test harness (defaults to MochiKit; see --test-style)')
-        .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser); equivalent to --test-style=xpcshell')
+        .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser); equivalent to --test-style=xpcshell. Note: xpcshell resolves chrome://global/* URIs but not chrome://browser/* — use --test-style=browser-chrome for browser-chrome-dependent tests.')
         .option('--test-style <style>', "Override the harness written by --with-tests: mochikit (default, runs against non-tabbrowser chrome), browser-chrome (today's scaffold, needs tabbrowser), or xpcshell (headless)", (value) => {
         if (value !== 'mochikit' && value !== 'browser-chrome' && value !== 'xpcshell') {
             throw new Error(`--test-style must be one of: mochikit, browser-chrome, xpcshell. Got: "${value}".`);
@@ -81,6 +81,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         return value;
     })
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
+        .option('--dry-run', 'Show the planned file set and furnace.json changes without writing')
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);
     }));
@@ -91,6 +92,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         .command('create <name>')
         .description('Scaffold a new top-level chrome document')
         .option('--no-titlebar', 'Frameless overlay-style document (omits titlebar-buttonbox)')
+        .option('--with-tests', 'Scaffold an xpcshell packaging-verification test that probes XCurProcD/chrome/browser/... directly (bypasses the xpcshell chrome:// URI limitation).')
         .action(withErrorHandling(async (name, options) => {
         await furnaceChromeDocCreateCommand(getProjectRoot(), name, pickDefined(options));
     }));

package/dist/src/commands/lint.d.ts

@@ -6,10 +6,25 @@ export interface LintCommandOptions {
      * When set, tag each issue as `introduced` or `cumulative` based on
      * whether its file changed since this git revision (e.g. `HEAD`, a
      * branch name, or a SHA). Issues are not filtered — the full set still
-     * prints and the exit code is unchanged — but a diff-scoped summary
-     * makes it trivial to see which errors the current task introduced.
+     * prints — but a diff-scoped summary makes it trivial to see which
+     * errors the current task introduced.
      */
     since?: string;
+    /**
+     * When set together with {@link since}, scope the exit code to issues
+     * tagged `introduced`. Cumulative pre-existing errors still print (so
+     * the operator can still see the full queue state) but do not fail
+     * lint. Motivating case: a branch whose diff is clean but whose repo
+     * already carries unrelated `raw-color` / license-header errors from
+     * older patches. Without this flag, CI treats the clean branch as
+     * failing; with it, a branch "breaks the build" only when its own diff
+     * introduced a new error.
+     *
+     * Requires {@link since}: without a revision to diff against there is
+     * no distinction between introduced and cumulative, so the flag is
+     * rejected up-front rather than silently ignored.
+     */
+    onlyIntroduced?: boolean;
 }
 /**
  * Runs the lint command to check engine changes against patch quality rules.

package/dist/src/commands/lint.js

@@ -19,6 +19,14 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
  */
 export async function lintCommand(projectRoot, files, options = {}) {
     intro('FireForge Lint');
+    // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
+    // without a revision to anchor the diff there is no "introduced" subset
+    // to scope to — reject the combination up-front so a misconfigured CI
+    // invocation fails loud instead of silently treating every error as
+    // cumulative and passing.
+    if (options.onlyIntroduced && !options.since) {
+        throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
+    }
     const paths = getProjectPaths(projectRoot);
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
@@ -139,9 +147,20 @@ export async function lintCommand(projectRoot, files, options = {}) {
     else {
         info(`\nLint: ${errors.length} error(s), ${warnings.length} warning(s)`);
     }
-    if (errors.length > 0) {
+    // Exit-code scope: `--only-introduced` narrows the failure criterion to
+    // issues tagged `introduced`. Cumulative errors still print so the
+    // operator sees the full queue state, but do not fail lint — the
+    // motivating case is a branch whose own diff is clean but whose repo
+    // already carries pre-existing queue errors from older patches.
+    const failingErrors = options.onlyIntroduced
+        ? errors.filter((i) => i.tag === 'introduced')
+        : errors;
+    if (failingErrors.length > 0) {
         outro('Lint failed');
-        throw new GeneralError(`Patch lint found ${errors.length} error(s). Fix these before exporting.`);
+        const cumulativeSuppressed = options.onlyIntroduced && errors.length > failingErrors.length
+            ? ` (${errors.length - failingErrors.length} cumulative error(s) suppressed by --only-introduced)`
+            : '';
+        throw new GeneralError(`Patch lint found ${failingErrors.length} ${options.onlyIntroduced ? 'introduced ' : ''}error(s). Fix these before exporting.${cumulativeSuppressed}`);
     }
     outro('Lint passed with warnings');
 }
@@ -151,11 +170,15 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .command('lint [paths...]')
         .description('Lint engine changes against patch quality rules')
         .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
+        .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
             lintOptions.since = options.since;
         }
+        if (options.onlyIntroduced !== undefined) {
+            lintOptions.onlyIntroduced = options.onlyIntroduced;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
 }

package/dist/src/commands/register.d.ts

@@ -5,7 +5,7 @@ import type { RegisterOptions } from '../types/commands/index.js';
  * Registers a file in the appropriate build manifest.
  *
  * @param projectRoot - Root directory of the project
- * @param filePath - Path relative to engine/
+ * @param filePath - Path relative to engine/ (a leading `engine/` segment is stripped)
  * @param options - Command options
  */
 export declare function registerCommand(projectRoot: string, filePath: string, options?: RegisterOptions): Promise<void>;

package/dist/src/commands/register.js

@@ -6,11 +6,28 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+/**
+ * Strips a leading `engine/` segment (either separator flavour) from a
+ * user-supplied path so operators can pass either a repo-root-relative
+ * path (`engine/browser/base/content/foo.xhtml`) or an engine-relative
+ * path (`browser/base/content/foo.xhtml`). The engine-relative form is
+ * what the manifest writers expect; without this normalisation, the
+ * former failed with a misleading "File not found in engine" pointing
+ * at a doubled path like `engine/engine/browser/...` that operators
+ * had no way to spot from the error message alone.
+ */
+function normalizeEngineRelativePath(filePath) {
+    if (filePath.startsWith('engine/'))
+        return filePath.slice('engine/'.length);
+    if (filePath.startsWith('engine\\'))
+        return filePath.slice('engine\\'.length);
+    return filePath;
+}
 /**
  * Registers a file in the appropriate build manifest.
  *
  * @param projectRoot - Root directory of the project
- * @param filePath - Path relative to engine/
+ * @param filePath - Path relative to engine/ (a leading `engine/` segment is stripped)
  * @param options - Command options
  */
 export async function registerCommand(projectRoot, filePath, options = {}) {
@@ -28,17 +45,23 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
             throw new InvalidArgumentError('--after must be a non-empty substring without control characters or line terminators.', 'after');
         }
     }
+    // Accept either repo-root-relative (`engine/browser/...`) or
+    // engine-relative (`browser/...`) inputs — operators frequently paste
+    // the former from the output of tab completion or `git status`, and
+    // the mismatch used to produce a "File not found" error that named
+    // the original path with no hint that dropping `engine/` would fix it.
+    const engineRelativePath = normalizeEngineRelativePath(filePath);
     // Verify the file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);
-        const fullPath = join(paths.engine, filePath);
+        const fullPath = join(paths.engine, engineRelativePath);
         if (!(await pathExists(fullPath))) {
-            throw new InvalidArgumentError(`File not found in engine: ${filePath}`, 'path');
+            throw new InvalidArgumentError(`File not found in engine: ${engineRelativePath}`, 'path');
         }
     }
-    const result = await registerFile(projectRoot, filePath, options.dryRun, options.after);
+    const result = await registerFile(projectRoot, engineRelativePath, options.dryRun, options.after);
     if (options.dryRun) {
-        info(`[dry-run] Would register ${filePath}`);
+        info(`[dry-run] Would register ${engineRelativePath}`);
         info(`  manifest: ${result.manifest}`);
         info(`  entry: ${result.entry}`);
         if (result.previousEntry) {
@@ -54,14 +77,14 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
         return;
     }
     if (result.skipped) {
-        info(`Already registered: ${filePath} in ${result.manifest}`);
+        info(`Already registered: ${engineRelativePath} in ${result.manifest}`);
     }
     else {
         if (result.afterFallback) {
             warn(`--after target "${options.after}" not found, falling back to alphabetical order`);
         }
         const position = result.previousEntry ? ` (after ${result.previousEntry})` : '';
-        success(`Registered ${filePath} in ${result.manifest}${position}`);
+        success(`Registered ${engineRelativePath} in ${result.manifest}${position}`);
         info("hint: Run 'fireforge build --ui' to make the new module available at runtime");
     }
     outro('Done');

package/dist/src/commands/test.js

@@ -4,10 +4,11 @@ import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
 import { reportMarionettePreflight, runMarionettePreflight } from '../core/marionette-preflight.js';
+import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, spinner } from '../utils/logger.js';
+import { info, intro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
  * Strips a leading "engine/" or "engine\\" prefix from a path if present.
@@ -118,6 +119,20 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         s.stop('Build complete');
         info('');
     }
+    else {
+        // Stale-build preflight — when --build was NOT requested, detect
+        // packageable engine edits since the last successful `fireforge build`
+        // and warn UP-FRONT. Without this, edits to chrome / packaged resources
+        // surface only as a cryptic `NS_ERROR_FILE_NOT_FOUND` inside xpcshell
+        // after mach test has already launched (see motivating case in
+        // `core/test-stale-check.ts`). The check is warn-only so a fork that
+        // rebuilt out-of-band (no FireForge-recorded baseline update) is not
+        // blocked from running tests.
+        const stale = await checkStaleBuildForTest(projectRoot, paths.engine);
+        if (stale.stale) {
+            warn(formatStaleBuildWarning(stale));
+        }
+    }
     // `--doctor` runs a short marionette handshake probe. When test paths are
     // supplied the probe gates the mach test invocation (a FAIL bails out). When
     // no paths are supplied this is the only step — it's the fastest way to tell

package/dist/src/core/build-audit-platform.d.ts

@@ -24,7 +24,9 @@ export interface PlatformGateResult {
 export declare function findEnclosingGate(content: string, basename: string): string | undefined;
 /**
  * Determines whether the given source file is gated off on the current
- * host by an enclosing `if CONFIG[...]:` block in its owning moz.build.
+ * host by an enclosing `if CONFIG[...]:` block in its owning moz.build,
+ * OR by a path-convention rule for installer-tree subdirectories that
+ * are packaged via Makefile.in recipes the audit does not parse.
  * Returns `gatedOff: false` and no expression when no gate is found —
  * the file is not platform-restricted, so the caller should audit it
  * normally.