@hominis/fireforge 0.37.0 → 0.38.0

package/dist/src/commands/patch/move-files.js

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch move-files <from> <to>` previews the explicit
- * re-export choreography needed to move file ownership between two patches.
+ * re-export choreography needed to move file ownership between two
+ * patches. With `--create --order <n>` the target patch is created and
+ * the files move into it as one transaction (see move-files-create.ts).
  */
 import { relative } from 'node:path';
 import { Command } from 'commander';
@@ -11,6 +13,8 @@ import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-ma
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, note, outro, warn } from '../../utils/logger.js';
+import { commanderArgParser, pickDefined } from '../../utils/options.js';
+import { patchMoveFilesCreateCommand } from './move-files-create.js';
 function collectOption(value, previous) {
     previous.push(value);
     return previous;
@@ -67,6 +71,19 @@ function computeFileMovePlan(source, target, files) {
  * @param options - Files to move and display mode
  */
 export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdentifier, options = {}) {
+    if (options.create === true && options.order === undefined) {
+        throw new InvalidArgumentError('--create requires --order <n> to place the new patch.', '--create');
+    }
+    if (options.create !== true && options.order !== undefined) {
+        throw new InvalidArgumentError('--order is only valid together with --create.', '--order');
+    }
+    if (options.create === true && options.order !== undefined) {
+        await patchMoveFilesCreateCommand(projectRoot, fromIdentifier, toIdentifier, {
+            ...options,
+            order: options.order,
+        });
+        return;
+    }
     intro('FireForge patch move-files');
     if (fromIdentifier === toIdentifier) {
         throw new InvalidArgumentError('Source and target patch identifiers must be different.', 'patch move-files');
@@ -118,7 +135,8 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     note(`${dryRunSource}\n${dryRunTarget}`, 'Preview commands');
     note(`${applySource}\n${applyTarget}`, 'Apply commands');
     info('Tip: to move files into a brand-new patch in one transaction (including ' +
-        'staged-dependency owner rewrites), use "fireforge patch split" instead.');
+        'staged-dependency owner rewrites), re-run with --create --order <n> to create ' +
+        'the target patch and move the files in one step, or use "fireforge patch split".');
     outro('Move plan complete - no changes made');
 }
 /**
@@ -131,9 +149,36 @@ export function registerPatchMoveFiles(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
     parent
         .command('move-files <from> <to>')
-        .description('Preview the re-export commands needed to move file ownership between patches.')
+        .description('Preview the re-export commands needed to move file ownership between patches, ' +
+        'or create the target patch and move the files in one transaction with --create --order <n>.')
         .option('--file <path>', 'File path relative to engine/ to move (repeatable)', collectOption, [])
+        .option('--create', 'Create <to> as a new patch and move the files into it (requires --order)')
+        .option('--order <n>', 'Exact sparse order for the created patch (only valid with --create)', commanderArgParser((raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new InvalidArgumentError(`--order must be a positive integer, got "${raw}".`, '--order');
+        }
+        return n;
+    }))
+        .option('--category <category>', "Category for the created patch (default: the source patch's)")
+        .option('--description <desc>', 'Description for the created patch')
+        .option('--dry-run', 'Show what would happen without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--force-unsafe', 'Bypass projected-lint refusals')
+        .option('--skip-lint', 'Skip per-patch lint of the projected bodies')
         .action(withErrorHandling(async (from, to, options) => {
-        await patchMoveFilesCommand(getProjectRoot(), from, to, options);
+        await patchMoveFilesCommand(getProjectRoot(), from, to, {
+            ...pickDefined({
+                file: options.file,
+                create: options.create,
+                order: options.order,
+                category: options.category,
+                description: options.description,
+                dryRun: options.dryRun,
+                yes: options.yes,
+                forceUnsafe: options.forceUnsafe,
+                skipLint: options.skipLint,
+            }),
+        });
     }));
 }

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

@@ -18,7 +18,17 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
-import type { PatchSplitOptions } from '../../types/commands/index.js';
+import type { PatchMetadata, PatchSplitOptions } from '../../types/commands/index.js';
+import type { FireForgeConfig } from '../../types/config.js';
+import { type SplitPlan } from './split-plan.js';
+/**
+ * Commits a confirmed split under the patch directory lock: renumber →
+ * write new patch body → write shrunken source body → single manifest
+ * rewrite (new row + shrunken source row + owner rewrites). On any
+ * failure the steps are rolled back in reverse order. Exported for
+ * `patch move-files --create`, which commits the same transaction shape.
+ */
+export declare function commitPatchSplit(patchesDir: string, plan: SplitPlan, newMetadata: PatchMetadata, options: Pick<PatchSplitOptions, 'yes' | 'forceUnsafe'>, config: FireForgeConfig): Promise<void>;
 /**
  * Runs the `patch split` command: plans the split, lints the projection,
  * confirms, and commits transactionally.

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

@@ -38,9 +38,10 @@ import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSpli
  * Commits a confirmed split under the patch directory lock: renumber →
  * write new patch body → write shrunken source body → single manifest
  * rewrite (new row + shrunken source row + owner rewrites). On any
- * failure the steps are rolled back in reverse order.
+ * failure the steps are rolled back in reverse order. Exported for
+ * `patch move-files --create`, which commits the same transaction shape.
  */
-async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
+export async function commitPatchSplit(patchesDir, plan, newMetadata, options, config) {
     await withPatchDirectoryLock(patchesDir, async () => {
         const manifest = await loadPatchesManifest(patchesDir);
         if (!manifest)
@@ -49,7 +50,7 @@ async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
         if (!current || current.filesAffected.join('\n') !== plan.source.filesAffected.join('\n')) {
             throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
         }
-        const currentPlacement = await resolvePlacementPlan(patchesDir, plan.placementOptions, plan.category, plan.name);
+        const currentPlacement = await resolvePlacementPlan(patchesDir, plan.placementOptions, plan.category, plan.name, config);
         if (!placementPlansEqual(currentPlacement, plan.placement)) {
             throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
         }
@@ -193,7 +194,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         after: options.after ??
             (options.order === undefined && options.before === undefined ? source.filename : undefined),
     });
-    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name);
+    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name, config);
     const plan = {
         source,
         movedFiles,
@@ -240,7 +241,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         outro('Split cancelled');
         return;
     }
-    await commitPatchSplit(paths.patches, plan, newMetadata, options);
+    await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     success(`Split ${source.filename}: ${placement.newFilename} now owns ${plan.movedFiles.length} file(s)`);
     if (plan.ownerRewrites.length > 0) {
         info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);

package/dist/src/commands/re-export-scan.d.ts

@@ -28,6 +28,23 @@ export declare function confirmBroadScanAdditions(args: {
     yes: boolean;
     isInteractive: boolean;
 }): Promise<boolean>;
+/**
+ * Refuses scan adoptions whose candidate files import modules created by
+ * LATER patches. Modeled on the `re-export --files` cross-patch
+ * projection: the candidates' diffs are projected into the adopting
+ * patch's queue entry, the queue lint runs baseline vs projection, and
+ * only forward-import regressions attributable to the candidates block.
+ * Staged-dependency declarations and inline lint-ignore markers are
+ * honored automatically because the real lint rule evaluates them.
+ * Covers broad `--scan`, `--scan-file`, and the `--scan-files` bulk flow
+ * (all adopt through the same scan result), including dry-run.
+ */
+export declare function assertScanAdoptionsHaveNoForwardImports(args: {
+    patchesDir: string;
+    engineDir: string;
+    patchFilename: string;
+    added: readonly string[];
+}): Promise<void>;
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export declare function assertScanFileAdditionsHaveDiffHunks(args: {
     diffContent: string;

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

@@ -1,9 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
 import { confirm } from '@clack/prompts';
+import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.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 { getClaimedFiles } from '../core/patch-manifest.js';
+import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
@@ -132,6 +136,53 @@ function scanAdditionsNeedConfirmation(added) {
         return true;
     return new Set(added.map((f) => dirname(f))).size >= SCAN_DIR_COUNT_THRESHOLD;
 }
+/**
+ * Refuses scan adoptions whose candidate files import modules created by
+ * LATER patches. Modeled on the `re-export --files` cross-patch
+ * projection: the candidates' diffs are projected into the adopting
+ * patch's queue entry, the queue lint runs baseline vs projection, and
+ * only forward-import regressions attributable to the candidates block.
+ * Staged-dependency declarations and inline lint-ignore markers are
+ * honored automatically because the real lint rule evaluates them.
+ * Covers broad `--scan`, `--scan-file`, and the `--scan-files` bulk flow
+ * (all adopt through the same scan result), including dry-run.
+ */
+export async function assertScanAdoptionsHaveNoForwardImports(args) {
+    const { patchesDir, engineDir, patchFilename, added } = args;
+    if (added.length === 0)
+        return;
+    const candidateDiff = await getDiffForFilesAgainstHead(engineDir, [...added]);
+    if (!candidateDiff.trim())
+        return;
+    const candidateNewFiles = new Map();
+    for (const path of detectNewFilesInDiff(candidateDiff)) {
+        candidateNewFiles.set(path, extractNewFileContentFromDiff(candidateDiff, path));
+    }
+    const candidateAdditions = buildModifiedFileAdditionsFromDiff(candidateDiff);
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const projectedEntries = baseCtx.entries.map((entry) => {
+        if (entry.filename !== patchFilename)
+            return entry;
+        return {
+            ...entry,
+            diff: `${entry.diff}\n${candidateDiff}`,
+            newFiles: new Map([...entry.newFiles, ...candidateNewFiles]),
+            modifiedFileAdditions: new Map([...entry.modifiedFileAdditions, ...candidateAdditions]),
+        };
+    });
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const addedSet = new Set(added);
+    const offending = computeProjectedLintRegressions(baselineIssues, projectedIssues).filter((issue) => issue.check === 'forward-import' && addedSet.has(issue.file));
+    if (offending.length === 0)
+        return;
+    const details = offending.map((issue) => `  - ${issue.file}: ${issue.message}`).join('\n');
+    throw new GeneralError(`Refusing to adopt ${offending.length} scanned file${offending.length === 1 ? '' : 's'} into ${patchFilename} ` +
+        `because they import modules created by later patches:\n${details}\n` +
+        'Export those files as their own later patch ("fireforge export --order <n>" / ' +
+        '"fireforge patch split --order <n>") or declare the intentional dependency with ' +
+        '"fireforge patch staged-dependency --add" before re-running the scan.');
+}
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export function assertScanFileAdditionsHaveDiffHunks(args) {
     const { diffContent, patchFilename, previousFilesAffected, scanFiles } = args;

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

@@ -18,12 +18,12 @@ import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
 import { loadScanFilesAssignments, withDryRunReExportLock } from './re-export-bulk-scan.js';
 import { reExportFilesInPlace } from './re-export-files.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
-import { assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
+import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
 async function findMissingFiles(engineDir, files) {
     const missingFiles = [];
     for (const file of files) {
@@ -87,6 +87,17 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             isDryRun,
             ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
         });
+        // Forward-import gate at adoption time (runs in dry-run too): refuse
+        // to adopt unmanaged files that import modules created by LATER
+        // patches — the after-the-fact lint failure this leaves behind is the
+        // field-reported footgun. Applies to broad --scan, --scan-file, and
+        // the --scan-files bulk assignments alike.
+        await assertScanAdoptionsHaveNoForwardImports({
+            patchesDir: paths.patches,
+            engineDir: paths.engine,
+            patchFilename: patch.filename,
+            added: scanResult.added,
+        });
         if (options.scanFiles === undefined) {
             const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
             const proceed = await confirmBroadScanAdditions({
@@ -407,7 +418,7 @@ export async function reExportCommand(projectRoot, patches, options) {
 }
 /** Registers the re-export command on the CLI program. */
 export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const reExport = program
         .command('re-export [patches...]')
         .description('Refresh existing patch bodies (and filesAffected with --scan) from the current engine ' +
         'state. Does NOT change sourceVersion/sourceProduct by default — use --stamp or run ' +
@@ -428,8 +439,8 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
         .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceVersion/sourceProduct in patches.json to firefox.version/firefox.product from fireforge.json. No effect on a partial run.")
         .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
-        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], [])
-        .action(withErrorHandling(async (patches, options) => {
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], []);
+    addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
         const { tier, lintIgnore, scanFile, scanFiles, ...rest } = options;
         const projectRoot = getProjectRoot();
         await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
@@ -438,6 +449,6 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
             ...(scanFiles !== undefined ? { scanFilesManifest: scanFiles } : {}),
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
-        }));
+        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

package/dist/src/commands/source.js

@@ -4,7 +4,7 @@ import { configExists, loadRawConfigDocument, validateConfig, withConfigFileLock
 import { resolveArchive } from '../core/firefox-archive.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { info, intro, outro, success } from '../utils/logger.js';
-import { isValidFirefoxProduct } from '../utils/validation.js';
+import { isValidFirefoxCandidate, isValidFirefoxProduct } from '../utils/validation.js';
 const SOURCE_PRODUCTS = [
     'firefox',
     'firefox-esr',
@@ -27,6 +27,12 @@ function parseSourceProduct(product) {
     }
     throw new InvalidArgumentError(`--product must be one of: ${SOURCE_PRODUCTS.join(', ')}`, '--product');
 }
+function parseSourceCandidate(candidate) {
+    if (isValidFirefoxCandidate(candidate)) {
+        return candidate;
+    }
+    throw new InvalidArgumentError(`--candidate must look like "buildN" (e.g. "build2"), got "${candidate}"`, '--candidate');
+}
 /**
  * Atomically updates the Firefox source tuple in fireforge.json.
  */
@@ -38,6 +44,9 @@ export async function sourceSetCommand(projectRoot, options) {
     if (options.sha256 !== undefined && options.clearSha256 === true) {
         throw new InvalidArgumentError('--sha256 cannot be combined with --clear-sha256', '--sha256');
     }
+    if (options.candidate !== undefined && options.clearCandidate === true) {
+        throw new InvalidArgumentError('--candidate cannot be combined with --clear-candidate', '--candidate');
+    }
     const written = await withConfigFileLock(projectRoot, async () => {
         const raw = await loadRawConfigDocument(projectRoot);
         const updated = cloneRawConfig(raw);
@@ -50,6 +59,12 @@ export async function sourceSetCommand(projectRoot, options) {
         else if (options.sha256 !== undefined) {
             firefox['sha256'] = options.sha256;
         }
+        if (options.clearCandidate === true) {
+            delete firefox['candidate'];
+        }
+        else if (options.candidate !== undefined) {
+            firefox['candidate'] = options.candidate;
+        }
         updated['firefox'] = firefox;
         const validated = validateConfig(updated);
         if (validated.firefox.sha256 !== undefined) {
@@ -58,7 +73,7 @@ export async function sourceSetCommand(projectRoot, options) {
         await writeConfigDocument(projectRoot, updated);
         return validated.firefox;
     });
-    const archive = resolveArchive(written.version, written.product);
+    const archive = resolveArchive(written.version, written.product, written.candidate);
     success(`Set firefox.version = ${written.version}`);
     success(`Set firefox.product = ${written.product}`);
     success(`Resolved source URL: ${archive.url}`);
@@ -68,6 +83,12 @@ export async function sourceSetCommand(projectRoot, options) {
     else if (options.clearSha256 === true) {
         info('Cleared firefox.sha256');
     }
+    if (written.candidate !== undefined) {
+        success(`Set firefox.candidate = ${written.candidate}`);
+    }
+    else if (options.clearCandidate === true) {
+        info('Cleared firefox.candidate');
+    }
     outro('');
 }
 /** Registers the source command on the CLI program. */
@@ -82,13 +103,17 @@ export function registerSource(program, { getProjectRoot, withErrorHandling }) {
         .makeOptionMandatory())
         .option('--sha256 <hash>', 'Pinned SHA-256 for the resolved source archive')
         .option('--clear-sha256', 'Clear any existing pinned SHA-256')
+        .option('--candidate <buildN>', 'Release-candidate build directory (e.g. "build2")', parseSourceCandidate)
+        .option('--clear-candidate', 'Clear any existing release-candidate build directory')
         .action(withErrorHandling(async (options) => {
-        const { product, version, sha256, clearSha256 } = options;
+        const { product, version, sha256, clearSha256, candidate, clearCandidate } = options;
         await sourceSetCommand(getProjectRoot(), {
             version,
             product: parseSourceProduct(product),
             ...(sha256 !== undefined ? { sha256 } : {}),
             ...(clearSha256 !== undefined ? { clearSha256 } : {}),
+            ...(candidate !== undefined ? { candidate } : {}),
+            ...(clearCandidate !== undefined ? { clearCandidate } : {}),
         });
     }));
 }

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

@@ -2,18 +2,19 @@
 import { Command } from 'commander';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { GeneralError } from '../errors/base.js';
-import { commanderArgParser, pickDefined } from '../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { testCommand } from './test.js';
 import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const test = program
         .command('test [paths...]')
         .description('Run tests via mach test')
         .option('--headless', 'Run tests in headless mode')
         .option('--build', 'Run incremental UI build before testing')
         .option('--auto', 'Forward mach test --auto. Valid only when no explicit paths are provided.')
         .option('--allow-stale-build', 'Allow tests to run even when packageable engine files changed since the last successful FireForge build')
+        .option('--allow-stale-components', 'Run tests despite components.conf changes that only a full "fireforge build" compiles in (the packaged child process will resolve the OLD StaticComponents table)')
         .option('--kill-stale-marionette', 'Terminate a recognized stale browser process holding the Marionette port before running tests')
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
@@ -56,9 +57,9 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         'runs (one browser instance per argument) by default, which does',
         'not exercise cross-argument state; --no-shard restores the',
         'combined single-instance invocation.',
-    ].join('\n'))
-        .action(withErrorHandling(async (paths, options) => {
+    ].join('\n'));
+    addWaitLockOption(test).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)));
+        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

package/dist/src/commands/test-stale-gate.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pre-dispatch gates for `fireforge test` that stand between the request
+ * and a run against a stale or under-packaged runtime: the packaging
+ * coverage refusal, the stale-content refusal, and the compiled
+ * StaticComponents refusal. Split out of `test.ts` so the command module
+ * stays wiring; the probes and refusal copy live in
+ * `src/core/test-stale-check.ts`.
+ */
+import type { BuildBaseline } from '../core/build-baseline-types.js';
+import type { TestOptions } from '../types/commands/index.js';
+/**
+ * Stale-build preflight — when `--build` was NOT requested, detect
+ * packageable engine edits since the last successful build and fail
+ * UP-FRONT unless the operator explicitly accepts the stale package risk.
+ *
+ * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * regardless of staleness or `--allow-stale-build`: a runtime packaged by
+ * a file-scoped `test --build` can lack support fixtures for OTHER
+ * manifests even when nothing changed since — dispatching such a run
+ * hangs on missing fixtures rather than failing, so the flag (which only
+ * accepts stale CONTENT) must not be the trigger. Field incident: a
+ * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
+ * later run over different files timed out twice at 45s waiting on
+ * `DOMAudioPlaybackStarted`.
+ *
+ * Exception: a path-less `test --doctor` stops at the Marionette health
+ * check (`runDoctorPreflight` returns 'stop' when no test paths were
+ * given) and never dispatches a test, so it needs no packaging coverage —
+ * treating it as a full-suite request would refuse a probe that touches
+ * no fixtures. The stale-content refusal still applies to it unchanged.
+ */
+export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[]): Promise<void>;
+/**
+ * Compiled-StaticComponents gate — refuses runs whose child process would
+ * resolve a stale compiled component table. `components.conf` entries bake
+ * into compiled code that only a FULL build regenerates; a scoped
+ * `test --build` repackages the file but the failure surfaces as
+ * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
+ * (after the coverage refusal) AND to scoped `test --build` runs (before
+ * the pre-test build — that build cannot fix the table). A path-less
+ * `test --build` is exempt: its full build refreshes the anchor itself.
+ * `--allow-stale-components` downgrades the refusal to a warning.
+ */
+export declare function enforceStaticComponentsGate(engineDir: string, baseline: BuildBaseline | undefined, options: TestOptions): Promise<void>;

package/dist/src/commands/test-stale-gate.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pre-dispatch gates for `fireforge test` that stand between the request
+ * and a run against a stale or under-packaged runtime: the packaging
+ * coverage refusal, the stale-content refusal, and the compiled
+ * StaticComponents refusal. Split out of `test.ts` so the command module
+ * stays wiring; the probes and refusal copy live in
+ * `src/core/test-stale-check.ts`.
+ */
+import { checkStaleBuildForTest, checkStaticComponentsStale, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
+import { GeneralError } from '../errors/base.js';
+import { warn } from '../utils/logger.js';
+/**
+ * Stale-build preflight — when `--build` was NOT requested, detect
+ * packageable engine edits since the last successful build and fail
+ * UP-FRONT unless the operator explicitly accepts the stale package risk.
+ *
+ * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * regardless of staleness or `--allow-stale-build`: a runtime packaged by
+ * a file-scoped `test --build` can lack support fixtures for OTHER
+ * manifests even when nothing changed since — dispatching such a run
+ * hangs on missing fixtures rather than failing, so the flag (which only
+ * accepts stale CONTENT) must not be the trigger. Field incident: a
+ * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
+ * later run over different files timed out twice at 45s waiting on
+ * `DOMAudioPlaybackStarted`.
+ *
+ * Exception: a path-less `test --doctor` stops at the Marionette health
+ * check (`runDoctorPreflight` returns 'stop' when no test paths were
+ * given) and never dispatches a test, so it needs no packaging coverage —
+ * treating it as a full-suite request would refuse a probe that touches
+ * no fixtures. The stale-content refusal still applies to it unchanged.
+ */
+export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths) {
+    const stale = await checkStaleBuildForTest(projectRoot, engineDir);
+    const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
+    if (!dispatchesNoTests) {
+        const recordedCoverage = stale.baseline?.testPackagingCoverage;
+        const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
+        if (uncovered.length > 0) {
+            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : []));
+        }
+    }
+    await enforceStaticComponentsGate(engineDir, stale.baseline, options);
+    const staleMessage = stale.stale
+        ? `${formatStaleBuildWarning(stale)}\n\n` +
+            'Run `fireforge test --build` to refresh the packaged runtime first, or pass ' +
+            '`--allow-stale-build` if you intentionally rebuilt out-of-band and accept the risk.'
+        : undefined;
+    if (staleMessage !== undefined) {
+        if (options.allowStaleBuild === true) {
+            warn(staleMessage);
+        }
+        else {
+            throw new GeneralError(staleMessage);
+        }
+    }
+}
+/**
+ * Compiled-StaticComponents gate — refuses runs whose child process would
+ * resolve a stale compiled component table. `components.conf` entries bake
+ * into compiled code that only a FULL build regenerates; a scoped
+ * `test --build` repackages the file but the failure surfaces as
+ * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
+ * (after the coverage refusal) AND to scoped `test --build` runs (before
+ * the pre-test build — that build cannot fix the table). A path-less
+ * `test --build` is exempt: its full build refreshes the anchor itself.
+ * `--allow-stale-components` downgrades the refusal to a warning.
+ */
+export async function enforceStaticComponentsGate(engineDir, baseline, options) {
+    const result = await checkStaticComponentsStale(engineDir, baseline);
+    if (!result.stale) {
+        return;
+    }
+    const message = formatStaticComponentsRefusal(result.changedManifests);
+    if (options.allowStaleComponents === true) {
+        warn(message);
+        return;
+    }
+    throw new GeneralError(message);
+}