@hominis/fireforge 0.36.0 → 0.38.0

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

@@ -294,6 +294,58 @@ function realUnexpectedFailureLines(output) {
     }
     return [...new Set(matches.map((line) => line.trim()))].filter((line) => !SHUTDOWN_REENTRY_PATTERN.test(line));
 }
+/**
+ * Non-global copies of the unexpected/assertion patterns for per-line use —
+ * the `g`-flagged module patterns carry `lastIndex` state across `.test()`
+ * calls and must never be reused line-by-line.
+ */
+const UNEXPECTED_LINE_SINGLE = /\bTEST-UNEXPECTED-[A-Z-]+\b/;
+/**
+ * Context lines the chrome/xpcshell harnesses print directly under a
+ * TEST-UNEXPECTED line: `Got …` / `Expected …` / `Actual …`, Assert
+ * messages, diff markers, stack-trace heads, and indented continuation
+ * lines.
+ */
+const FAILURE_CONTEXT_LINE_PATTERN = /^(?:\s*(?:Got\b|Expected\b|Actual\b|Assert\w*\b|Stack trace:|[-+]\s)|\s{2,}\S)/;
+/** Cap on context lines echoed under a single TEST-UNEXPECTED line. */
+const FAILURE_BLOCK_CONTEXT_LIMIT = 6;
+/**
+ * Collects the first `limit` TEST-UNEXPECTED-* lines with their trailing
+ * assertion/diff context, one string per block. The shutdown-reentry
+ * artifact is excluded (it is harness noise, not a test result). When more
+ * than `limit` blocks exist, a final `…(+N more …)` note is appended so the
+ * operator knows the echo was truncated. Pure; exported for unit tests.
+ */
+export function collectUnexpectedFailureBlocks(output, limit = 5) {
+    const lines = output.split(/\r?\n/);
+    const blocks = [];
+    let skipped = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (!UNEXPECTED_LINE_SINGLE.test(line) || SHUTDOWN_REENTRY_PATTERN.test(line))
+            continue;
+        if (blocks.length >= limit) {
+            skipped++;
+            continue;
+        }
+        const block = [line.trim()];
+        let contextCount = 0;
+        for (let j = i + 1; j < lines.length && contextCount < FAILURE_BLOCK_CONTEXT_LIMIT; j++) {
+            const next = lines[j] ?? '';
+            if (UNEXPECTED_LINE_SINGLE.test(next))
+                break;
+            if (!FAILURE_CONTEXT_LINE_PATTERN.test(next))
+                break;
+            block.push(next.trimEnd());
+            contextCount++;
+        }
+        blocks.push(block.join('\n'));
+    }
+    if (skipped > 0) {
+        blocks.push(`…(+${skipped} more TEST-UNEXPECTED line${skipped === 1 ? '' : 's'} not shown)`);
+    }
+    return blocks;
+}
 function detectSecondaryHarnessNoise(output) {
     const evidence = stripNonSignalNoise(output);
     if (TRACEBACK_PATTERN.test(evidence)) {
@@ -397,6 +449,7 @@ export function detectHarnessCrashSignature(output) {
 export function classifyHarnessRun(exitCode, output, requestedPaths) {
     const realFailures = realUnexpectedFailureLines(output);
     const firstRealFailure = realFailures[0];
+    const failureBlocks = collectUnexpectedFailureBlocks(output);
     const secondaryHarnessSignature = firstRealFailure !== undefined ? detectSecondaryHarnessNoise(output) : undefined;
     const signature = detectHarnessCrashSignature(output);
     if (signature) {
@@ -431,6 +484,7 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
             return {
                 kind: 'test-failures',
                 ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
+                ...(failureBlocks.length > 0 ? { realFailureBlocks: failureBlocks } : {}),
                 ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
                 greenSummaryRejected: {
                     ...(crashLine !== undefined ? { crashLine } : {}),
@@ -444,6 +498,7 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     return {
         kind: 'test-failures',
         ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
+        ...(failureBlocks.length > 0 ? { realFailureBlocks: failureBlocks } : {}),
         ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
     };
 }

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

@@ -1,4 +1,6 @@
-import type { BuildBaseline } from './build-baseline-types.js';
+import { isXpcomManifestPath } from './build-audit.js';
+import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
+export { isXpcomManifestPath };
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -40,3 +42,69 @@ export declare function checkStaleBuildForTest(projectRoot: string, engineDir: s
  * result without matching the rendered copy.
  */
 export declare function formatStaleBuildWarning(result: StaleBuildResult): string;
+/**
+ * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
+ * request (no paths) is checked against a scoped coverage record.
+ */
+export declare const FULL_SUITE_REQUEST = "(entire suite)";
+/**
+ * Compares the requested test paths against the packaged runtime's coverage
+ * claim recorded in the baseline. Returns the requested paths the recorded
+ * packaging does NOT cover — the runs that would dispatch against missing
+ * `_tests/` support fixtures and hang rather than fail.
+ *
+ * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
+ * everything. A scoped list covers a request path when the request equals a
+ * covered entry, sits beneath a covered directory entry, or shares a
+ * manifest granule with a covered entry ({@link toManifestGranule} — a
+ * scoped `test --build` packages the whole manifest directory, so a
+ * same-manifest sibling of a covered file is packaged too). Both sides are
+ * normalized to forward slashes so Windows-style CLI input cannot defeat
+ * the prefix rule (baseline paths are POSIX by convention). A request with
+ * no paths is a full-suite run and is never covered by a scoped list — the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ */
+export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
+/**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include —
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ */
+export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[]): string;
+/** Result of the compiled-StaticComponents staleness probe. */
+export interface StaticComponentsStaleResult {
+    /** True when at least one `components.conf` genuinely diverged from the anchor. */
+    stale: boolean;
+    /**
+     * Engine-relative `components.conf` paths changed since the last FULL
+     * build. Sorted; NOT capped — {@link formatStaticComponentsRefusal}
+     * applies the render cap.
+     */
+    changedManifests: string[];
+}
+/**
+ * Probes whether any `components.conf` changed since the last FULL
+ * `fireforge build` — i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code; a
+ * scoped `test --build` packages the file but the child process resolves
+ * the OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a
+ * test bug.
+ *
+ * The diff anchors to the baseline's `staticComponentsBaseline` (the last
+ * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`
+ * which a scoped `test --build` advances. Dirty candidates are hash-checked
+ * against the anchor's fingerprints so only genuine content divergence
+ * counts. No baseline / no anchor (pre-0.38.0 marker) → fresh. Never
+ * throws — the probes it composes degrade to verbose lines and empty
+ * results on git failure, matching {@link checkStaleBuildForTest}.
+ */
+export declare function checkStaticComponentsStale(engineDir: string, baseline: BuildBaseline | undefined): Promise<StaticComponentsStaleResult>;
+/**
+ * Formats the refusal shown when a run would dispatch against a stale
+ * compiled StaticComponents table. Same probe/copy split as
+ * {@link formatStaleBuildWarning} so tests can pin structure and wording
+ * independently.
+ */
+export declare function formatStaticComponentsRefusal(changedManifests: string[]): string;

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

@@ -28,9 +28,10 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
-import { isPackageablePath } from './build-audit.js';
+import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
+export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
 /**
@@ -112,3 +113,135 @@ export function formatStaleBuildWarning(result) {
         'packaged chrome / jar.mn resources, rerun with "fireforge test --build" (or ' +
         '"fireforge build --ui") first. Passing --build skips this check.');
 }
+/**
+ * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
+ * request (no paths) is checked against a scoped coverage record.
+ */
+export const FULL_SUITE_REQUEST = '(entire suite)';
+/**
+ * Compares the requested test paths against the packaged runtime's coverage
+ * claim recorded in the baseline. Returns the requested paths the recorded
+ * packaging does NOT cover — the runs that would dispatch against missing
+ * `_tests/` support fixtures and hang rather than fail.
+ *
+ * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
+ * everything. A scoped list covers a request path when the request equals a
+ * covered entry, sits beneath a covered directory entry, or shares a
+ * manifest granule with a covered entry ({@link toManifestGranule} — a
+ * scoped `test --build` packages the whole manifest directory, so a
+ * same-manifest sibling of a covered file is packaged too). Both sides are
+ * normalized to forward slashes so Windows-style CLI input cannot defeat
+ * the prefix rule (baseline paths are POSIX by convention). A request with
+ * no paths is a full-suite run and is never covered by a scoped list — the
+ * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ */
+export function findUncoveredRequestPaths(coverage, requestedPaths) {
+    if (coverage === undefined || coverage === 'full') {
+        return [];
+    }
+    const covered = coverage.map(normalizeCoveragePath).filter((p) => p.length > 0);
+    if (requestedPaths.length === 0) {
+        return [FULL_SUITE_REQUEST];
+    }
+    return requestedPaths.filter((requested) => {
+        const path = normalizeCoveragePath(requested);
+        const granule = toManifestGranule(path);
+        return !covered.some((c) => path === c || path.startsWith(`${c}/`) || granule === toManifestGranule(c));
+    });
+}
+/**
+ * Maps a normalized request/coverage path to the "manifest granule" the
+ * packaged runtime actually staged: an extension-bearing basename (a test
+ * FILE) maps to its containing directory, a directory (no dot in the
+ * basename) maps to itself. Purely lexical — the directory-as-manifest
+ * approximation holds because xpcshell/mochitest manifests live next to
+ * their test files and a scoped `test --build` stages the whole manifest
+ * directory into `obj-*`/`_tests/`, not single files. Caveat: a DIRECTORY
+ * whose basename contains a dot is misread as a file and mapped to its
+ * parent, which widens (never narrows) the covered granule.
+ */
+function toManifestGranule(path) {
+    const slash = path.lastIndexOf('/');
+    const base = slash === -1 ? path : path.slice(slash + 1);
+    if (!base.includes('.')) {
+        return path;
+    }
+    return slash === -1 ? '' : path.slice(0, slash);
+}
+/** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
+function normalizeCoveragePath(path) {
+    return path.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+}
+/**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include —
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ */
+export function formatTestCoverageRefusal(uncovered, coverage) {
+    const cap = (paths) => {
+        const head = paths.slice(0, STALE_PATHS_LIMIT);
+        const truncated = paths.length - head.length;
+        return head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    };
+    const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
+    const rebuildHint = rebuildTargets.length > 0
+        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.`
+        : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
+    return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
+        `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
+        'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
+        `rather than fail. ${rebuildHint} ` +
+        '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
+}
+/**
+ * Probes whether any `components.conf` changed since the last FULL
+ * `fireforge build` — i.e. since the compiled StaticComponents table was
+ * last regenerated. `components.conf` entries bake into compiled code; a
+ * scoped `test --build` packages the file but the child process resolves
+ * the OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a
+ * test bug.
+ *
+ * The diff anchors to the baseline's `staticComponentsBaseline` (the last
+ * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`
+ * which a scoped `test --build` advances. Dirty candidates are hash-checked
+ * against the anchor's fingerprints so only genuine content divergence
+ * counts. No baseline / no anchor (pre-0.38.0 marker) → fresh. Never
+ * throws — the probes it composes degrade to verbose lines and empty
+ * results on git failure, matching {@link checkStaleBuildForTest}.
+ */
+export async function checkStaticComponentsStale(engineDir, baseline) {
+    const anchor = baseline?.staticComponentsBaseline;
+    if (baseline === undefined || anchor === undefined) {
+        return { stale: false, changedManifests: [] };
+    }
+    const changed = await collectChangedEnginePaths(engineDir, { ...baseline, engineHeadSha: anchor.engineHeadSha }, 'Static-components preflight');
+    const changedManifests = [];
+    for (const path of changed.filter((p) => isXpcomManifestPath(p))) {
+        const recorded = anchor.fingerprints[path];
+        const live = await hashEngineFile(engineDir, path);
+        if (recorded === undefined || live === undefined || recorded !== live) {
+            changedManifests.push(path);
+        }
+    }
+    return { stale: changedManifests.length > 0, changedManifests };
+}
+/**
+ * Formats the refusal shown when a run would dispatch against a stale
+ * compiled StaticComponents table. Same probe/copy split as
+ * {@link formatStaleBuildWarning} so tests can pin structure and wording
+ * independently.
+ */
+export function formatStaticComponentsRefusal(changedManifests) {
+    const head = changedManifests.slice(0, STALE_PATHS_LIMIT);
+    const truncated = changedManifests.length - head.length;
+    const list = head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
+    return (`The compiled StaticComponents table is stale: ${list} changed since the last full "fireforge build".\n` +
+        'components.conf registrations are baked into compiled code that only a FULL build ' +
+        'regenerates — a scoped "fireforge test --build" repackages files but the child process ' +
+        'resolves the old component table and fails with NS_ERROR_MALFORMED_URI that reads as a ' +
+        'test bug. Run "fireforge build" first. (--allow-stale-build does not bypass this check — ' +
+        'it accepts stale packaged content, not a stale compiled registration. Pass ' +
+        '--allow-stale-components only if you rebuilt out-of-band and accept the risk.)');
+}

package/dist/src/types/commands/index.d.ts

@@ -2,5 +2,5 @@
  * Re-exports all command-related types from focused sub-modules.
  */
 export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
-export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, } from './patches.js';
+export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';

package/dist/src/types/commands/options.d.ts

@@ -43,6 +43,10 @@ export interface SourceSetOptions {
     sha256?: string;
     /** Clear any existing pinned SHA-256 */
     clearSha256?: boolean;
+    /** Optional release-candidate build directory (e.g. "build2") */
+    candidate?: string;
+    /** Clear any existing release-candidate build directory */
+    clearCandidate?: boolean;
 }
 /**
  * Options for the build command.
@@ -62,6 +66,12 @@ export interface BuildOptions {
      * for any mismatch the rewriter cannot prove safe.
      */
     rewriteMozinfo?: boolean;
+    /**
+     * Parsed `--wait-lock [seconds]` value (`true` for the bare flag, meaning
+     * 60). Consumed at the CLI layer to bound the engine-session-lock wait;
+     * the command implementation ignores it.
+     */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the export command.
@@ -99,6 +109,12 @@ export interface ExportOptions {
     forceUnsafe?: boolean;
     /** Exclude furnace-managed file paths from the export. */
     excludeFurnace?: boolean;
+    /**
+     * Export the deployed engine copy even when the `components/` source
+     * changed since the last furnace apply. Without this flag the export is
+     * refused so a stale deployed copy cannot silently land in the patch.
+     */
+    allowStaleFurnace?: boolean;
     /**
      * Acknowledge that the export will create cross-patch ownership overlap
      * with existing non-superseded patches. Without this flag, `export`
@@ -106,6 +122,12 @@ export interface ExportOptions {
      * another patch, because the resulting queue fails `verify` immediately.
      */
     allowOverlap?: boolean;
+    /**
+     * Parsed `--wait-lock [seconds]` value (`true` for the bare flag, meaning
+     * 60). Consumed at the CLI layer to bound the engine-session-lock wait;
+     * the command implementation ignores it.
+     */
+    waitLock?: number | boolean;
     /**
      * Force a tier override on the new patch's `PatchMetadata.tier`. Only
      * `"branding"` is currently recognised — Commander rejects other values
@@ -210,6 +232,12 @@ export interface ReExportOptions {
      * before the interactive/`--yes` confirmation path.
      */
     allowShrink?: boolean;
+    /**
+     * Export the deployed engine copy even when the `components/` source
+     * changed since the last furnace apply. Without this flag the re-export
+     * is refused so a stale deployed copy cannot silently land in the patch.
+     */
+    allowStaleFurnace?: boolean;
     /** Bypass cross-patch lint refusal on projected shrink state */
     forceUnsafe?: boolean;
     /**
@@ -239,6 +267,12 @@ export interface ReExportOptions {
      * patch to also suppress X").
      */
     lintIgnore?: string[];
+    /**
+     * Parsed `--wait-lock [seconds]` value (`true` for the bare flag, meaning
+     * 60). Consumed at the CLI layer to bound the engine-session-lock wait;
+     * the command implementation ignores it.
+     */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -278,16 +312,27 @@ export interface PatchLintIgnoreOptions {
  * declarations, or clear all staged dependencies from the patch.
  */
 export interface PatchStagedDependencyOptions {
-    /** Add a forward-import staged dependency. */
+    /** Add a staged dependency declaration. */
     add?: boolean;
-    /** Remove matching forward-import staged dependency declarations. */
+    /** Remove matching staged dependency declarations. */
     remove?: boolean;
     /** Drop the stagedDependencies field entirely. */
     clear?: boolean;
-    /** Importing file path relative to engine/. */
+    /**
+     * Declaration shape: `import` (forward import, the default when unset) or
+     * `registration` (jar.mn packaging line, customElements or actor
+     * registration). Registration entries use `line` instead of `specifier`.
+     */
+    kind?: string;
+    /** Declaring file path relative to engine/. */
     file?: string;
-    /** Exact import specifier as it appears in source. */
+    /** Exact import specifier as it appears in source (`kind: import`). */
     specifier?: string;
+    /**
+     * Registration/packaging line as the patch adds it, compared
+     * whitespace-trimmed (`kind: registration`).
+     */
+    line?: string;
     /** Later-created file path relative to engine/. */
     creates?: string;
     /** Optional exact patch filename expected to create `creates`. */
@@ -327,13 +372,31 @@ export interface PatchSplitOptions {
     skipLint?: boolean;
 }
 /**
- * Options for the preview-only `fireforge patch move-files` subcommand.
- * It validates an ownership transfer and prints the explicit
- * `re-export --files` commands needed to perform it.
+ * Options for the `fireforge patch move-files` subcommand. Without
+ * `--create` it is preview-only: it validates an ownership transfer and
+ * prints the explicit `re-export --files` commands needed to perform it.
+ * With `--create --order <n>` the target patch is created at that order
+ * and the files move into it as one split-style transaction.
  */
 export interface PatchMoveFilesOptions {
     /** File paths relative to engine/ to move from the source patch to the target patch. */
     file?: string[];
+    /** Create the target patch (transactional bootstrap of a split). Requires `order`. */
+    create?: boolean;
+    /** Exact sparse order for the created patch. Only valid with `create`. */
+    order?: number;
+    /** Category for the created patch; defaults to the source patch's. */
+    category?: string;
+    /** Description for the created patch. */
+    description?: string;
+    /** Preview the create+move without writing. */
+    dryRun?: boolean;
+    /** Skip interactive confirmation (required for non-TTY). */
+    yes?: boolean;
+    /** Bypass projected-lint refusals. */
+    forceUnsafe?: boolean;
+    /** Skip per-patch lint of the projected bodies. */
+    skipLint?: boolean;
 }
 /**
  * Options for the rebase command.
@@ -434,6 +497,14 @@ export interface TestOptions {
     killStaleMarionette?: boolean;
     /** Permit tests against packageable engine edits newer than the last successful build. */
     allowStaleBuild?: boolean;
+    /**
+     * Permit tests despite `components.conf` changes that only a full
+     * `fireforge build` compiles into the StaticComponents table — the
+     * packaged child process will resolve the OLD table. For operators who
+     * rebuilt out-of-band and accept the risk; distinct from
+     * `allowStaleBuild`, which only accepts stale packaged content.
+     */
+    allowStaleComponents?: boolean;
     /** Run the configured short harness canary. `true` means use `fireforge.json`'s test.canaryPath. */
     canary?: string | boolean;
     /**
@@ -464,6 +535,12 @@ export interface TestOptions {
      * checkers that consume a sample artifact after the run.
      */
     perfSamples?: string;
+    /**
+     * Parsed `--wait-lock [seconds]` value (`true` for the bare flag, meaning
+     * 60). Consumed at the CLI layer to bound the engine-session-lock wait;
+     * the command implementation ignores it.
+     */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the furnace apply command.

package/dist/src/types/commands/patches.d.ts

@@ -127,6 +127,15 @@ export interface PatchMetadata {
 export interface PatchStagedDependencies {
     /** Exact forward-import declarations allowed for this patch. */
     forwardImports?: PatchStagedForwardImport[];
+    /**
+     * Registration-shaped forward dependencies: packaging or registration
+     * LINES (a jar.mn entry, a customElements registration, an actor
+     * registration) this patch adds that reference a file a later patch
+     * creates. Unlike `forwardImports`, these are validated by matching the
+     * declared line against the patch's added content, not by finding an
+     * import specifier — packaging lines have no import to match.
+     */
+    registrations?: PatchStagedRegistration[];
 }
 /** A single intentional forward import to a later-created file. */
 export interface PatchStagedForwardImport {
@@ -141,6 +150,26 @@ export interface PatchStagedForwardImport {
     /** Optional human-readable rationale for the staged dependency. */
     reason?: string;
 }
+/**
+ * A single intentional registration/packaging line referencing a
+ * later-created file.
+ */
+export interface PatchStagedRegistration {
+    /** Declaring file path relative to engine/ (e.g. `toolkit/content/jar.mn`). */
+    file: string;
+    /**
+     * The registration/packaging line exactly as the patch adds it. Compared
+     * whitespace-trimmed against the patch's added lines in `file`, so
+     * indentation differences do not break the match.
+     */
+    line: string;
+    /** Later-created file path relative to engine/. */
+    creates: string;
+    /** Optional exact patch filename expected to create `creates`. */
+    owner?: string;
+    /** Optional human-readable rationale for the staged dependency. */
+    reason?: string;
+}
 /**
  * Schema for patches/patches.json file.
  */

package/dist/src/types/config.d.ts

@@ -12,6 +12,13 @@ export interface FirefoxConfig {
     product: FirefoxProduct;
     /** Optional pinned SHA-256 for the resolved source archive */
     sha256?: string;
+    /**
+     * Optional release-candidate build directory (e.g. "build2"). When set,
+     * the source archive resolves under
+     * `pub/<product>/candidates/<version>-candidates/<candidate>/` instead of
+     * `pub/<product>/releases/<version>/`, for pre-release verification.
+     */
+    candidate?: string;
 }
 /**
  * Supported project license SPDX identifiers.

package/dist/src/types/furnace.d.ts

@@ -46,6 +46,19 @@ export interface CustomComponentConfig {
     targetPath: string;
     /** Whether to register in customElements.js */
     register: boolean;
+    /**
+     * What the component IS. `'element'` (the default when unset) is a custom
+     * element with its own tag. `'library'` is a base class + helpers module
+     * that defines no element of its own (e.g. a shared MozLitElement
+     * subclass other components extend): `furnace validate` skips the
+     * `no-custom-element-define` / `not-moz-lit-element` compatibility checks
+     * and the `missing-css` structural advisory for it, while headers, module
+     * shape, `relative-import`, and (when a `.css` exists) the CSS
+     * compatibility rules still apply. A library exports no element, so
+     * `kind: "library"` requires `register: false` — the combination with
+     * `register: true` is rejected at config parse time.
+     */
+    kind?: 'element' | 'library';
     /** Whether this component uses Fluent l10n */
     localized: boolean;
     /** Stock component tag names composed internally by this component */

package/dist/src/utils/options.d.ts

@@ -6,6 +6,7 @@
 export declare function pickDefined<T extends Record<string, unknown>>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
+import type { Command } from 'commander';
 /**
  * Wraps an option-argument parser so its failures surface through
  * commander's own invalid-argument channel.
@@ -21,3 +22,22 @@ export declare function pickDefined<T extends Record<string, unknown>>(obj: T):
  * helper (or throw commander's InvalidArgumentError directly).
  */
 export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw: string) => T;
+/**
+ * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
+ * in seconds for `withEngineSessionLock`:
+ * - absent (`undefined`) → `undefined` (legacy ~1 s fail-fast),
+ * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
+ * - explicit value → integer validated into 1..3600.
+ *
+ * Accepts the raw string too, so it doubles as the option's arg parser (wrap
+ * with {@link commanderArgParser} so failures surface through commander's
+ * invalid-argument channel).
+ */
+export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
+/**
+ * Registers the shared `--wait-lock [seconds]` flag on an engine-mutating
+ * command. The parsed option value is `true` for the bare flag or a validated
+ * integer; feed it through {@link resolveWaitLockSeconds} at the call site to
+ * obtain the `waitLockSeconds` for `withEngineSessionLock`.
+ */
+export declare function addWaitLockOption(command: Command): Command;

package/dist/src/utils/options.js

@@ -14,6 +14,7 @@ export function pickDefined(obj) {
     return result;
 }
 import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
+import { GeneralError } from '../errors/base.js';
 /**
  * Wraps an option-argument parser so its failures surface through
  * commander's own invalid-argument channel.
@@ -38,3 +39,41 @@ export function commanderArgParser(parse) {
         }
     };
 }
+/** Wait budget applied when `--wait-lock` is passed without a value. */
+const DEFAULT_WAIT_LOCK_SECONDS = 60;
+/**
+ * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
+ * in seconds for `withEngineSessionLock`:
+ * - absent (`undefined`) → `undefined` (legacy ~1 s fail-fast),
+ * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
+ * - explicit value → integer validated into 1..3600.
+ *
+ * Accepts the raw string too, so it doubles as the option's arg parser (wrap
+ * with {@link commanderArgParser} so failures surface through commander's
+ * invalid-argument channel).
+ */
+export function resolveWaitLockSeconds(value) {
+    if (value === undefined || value === false) {
+        return undefined;
+    }
+    if (value === true) {
+        return DEFAULT_WAIT_LOCK_SECONDS;
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    const n = Number.parseInt(value, 10);
+    if (!Number.isFinite(n) || n < 1 || n > 3600) {
+        throw new GeneralError(`--wait-lock must be an integer in 1..3600 (got "${value}")`);
+    }
+    return n;
+}
+/**
+ * Registers the shared `--wait-lock [seconds]` flag on an engine-mutating
+ * command. The parsed option value is `true` for the bare flag or a validated
+ * integer; feed it through {@link resolveWaitLockSeconds} at the call site to
+ * obtain the `waitLockSeconds` for `withEngineSessionLock`.
+ */
+export function addWaitLockOption(command) {
+    return command.option('--wait-lock [seconds]', 'Wait up to this many seconds (default 60) for another FireForge engine-mutating command to release the engine lock, instead of failing immediately', commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
+}