@hominis/fireforge 0.37.0 → 0.39.0

package/dist/src/core/token-variant.js

@@ -107,6 +107,15 @@ function findVariantBlockInsertionPoint(lines) {
     }
     return lines.length;
 }
+/**
+ * True when a top-level `:root<variant>` block exists in `lines`. Used by
+ * the override path to write theme-attribute blocks only when the scaffold
+ * already declares them — `insertVariantDeclaration` would otherwise create
+ * the block, which is only wanted for the explicit `--variant` flow.
+ */
+export function variantBlockExists(lines, variant) {
+    return findVariantBlock(lines, variant) !== null;
+}
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export function variantBlockHasToken(lines, variant, tokenName) {
     const block = findVariantBlock(lines, variant);

package/dist/src/core/typecheck-shim.d.ts

@@ -24,6 +24,19 @@ export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
  * reason the operator couldn't infer from the docs.
  */
 export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
+/**
+ * Undefined-free-identifier codes, split out of
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES} (FORGE F12). Unconditional
+ * suppression let a module reference a name with no import or declaration
+ * anywhere and still typecheck with 0 errors — the failure then surfaced
+ * as a runtime `ReferenceError`. Both flows now report these at a
+ * configurable severity (default `'warning'`: visible without breaking
+ * gates; genuine shim gaps are silenced by adding the global to
+ * `extraShim`, or per-run via the `'off'` setting).
+ */
+export declare const UNDEFINED_IDENTIFIER_CODES: ReadonlySet<number>;
+/** Hint appended to reported undefined-identifier diagnostics. */
+export declare const UNDEFINED_IDENTIFIER_HINT: string;
 /**
  * Result of {@link composeShimSource}: the source body to feed into
  * the TS host plus a flag indicating whether the user-supplied extra

package/dist/src/core/typecheck-shim.js

@@ -146,11 +146,26 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
     2306, // File '{0}' is not a module.
     2305, // Module '{0}' has no exported member '{1}'.
     2792, // Cannot find module '{0}'. Did you mean to set the 'moduleResolution' option...
-    2304, // Cannot find name '{0}'. (for globals we missed in the shim)
-    2552, // Cannot find name '{0}'. Did you mean '{1}'?
     2580, // Cannot find name '{0}'. Do you need to install type definitions...
     7016, // Could not find a declaration file for module '{0}'.
 ]);
+/**
+ * Undefined-free-identifier codes, split out of
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES} (FORGE F12). Unconditional
+ * suppression let a module reference a name with no import or declaration
+ * anywhere and still typecheck with 0 errors — the failure then surfaced
+ * as a runtime `ReferenceError`. Both flows now report these at a
+ * configurable severity (default `'warning'`: visible without breaking
+ * gates; genuine shim gaps are silenced by adding the global to
+ * `extraShim`, or per-run via the `'off'` setting).
+ */
+export const UNDEFINED_IDENTIFIER_CODES = new Set([
+    2304, // Cannot find name '{0}'.
+    2552, // Cannot find name '{0}'. Did you mean '{1}'?
+]);
+/** Hint appended to reported undefined-identifier diagnostics. */
+export const UNDEFINED_IDENTIFIER_HINT = '(undefined identifier — import or declare it, add the global to the extra shim, ' +
+    'or tune the "undefinedIdentifiers" setting)';
 /** Matches a lone triple-slash `/// <reference path="…" />` directive line. */
 const TRIPLE_SLASH_REFERENCE = /^\s*\/\/\/\s*<reference\s+path\s*=\s*["']([^"']+)["']\s*\/?>\s*$/;
 /**

package/dist/src/core/typecheck.js

@@ -21,7 +21,7 @@
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES } from './typecheck-shim.js';
+import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
  * project's jsconfig sets `checkJs: false`. Exported so tests can
@@ -131,7 +131,7 @@ export async function runTypecheck(projectRoot, cfg) {
             });
             continue;
         }
-        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource));
+        results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource, cfg.undefinedIdentifiers ?? 'warning'));
     }
     return results;
 }
@@ -149,7 +149,7 @@ function resolveProjectExtraShim(cfg, projectPath) {
     return cfg.extraShim;
 }
 /** Runs typecheck for a single jsconfig path, isolating its failures. */
-async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource) {
+async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource, undefinedIdentifiers = 'warning') {
     const absConfig = resolve(projectRoot, projectPath);
     if (!(await pathExists(absConfig))) {
         return {
@@ -268,6 +268,17 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource)
         // can't act on them and they would clutter CI logs.
         if (diag.file?.fileName === shimPath)
             continue;
+        if (UNDEFINED_IDENTIFIER_CODES.has(diag.code)) {
+            if (undefinedIdentifiers === 'off')
+                continue;
+            const issue = diagnosticToIssue(ts, diag, absConfig, projectPath);
+            issues.push({
+                ...issue,
+                category: undefinedIdentifiers,
+                message: `${issue.message} ${UNDEFINED_IDENTIFIER_HINT}`,
+            });
+            continue;
+        }
         issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
     }
     verbose(`typecheck: ${projectPath} — analyzed ${String(parsed.fileNames.length)} file(s), found ${String(issues.length)} issue(s)`);

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.
@@ -112,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
@@ -144,6 +160,12 @@ export interface ResetOptions {
  * Options for the discard command.
  */
 export interface DiscardOptions {
+    /**
+     * Restore to pristine upstream (HEAD) instead of the patch-applied
+     * baseline; deletes patch-created files (the pre-0.39.0 semantics —
+     * FORGE F1).
+     */
+    toUpstream?: boolean;
     /** Show what would be discarded without doing it */
     dryRun?: boolean;
     /** Skip confirmation prompt */
@@ -251,6 +273,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
@@ -350,13 +378,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.
@@ -457,6 +503,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;
     /**
@@ -487,6 +541,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.
@@ -741,6 +801,12 @@ export interface StatusOptions {
      * patch as an ownership conflict.
      */
     ownership?: boolean;
+    /**
+     * Print the recorded test-packaging coverage of the last build baseline
+     * (scope, timestamp, recording invocation) and exit. Read-only — the
+     * counterpart to the out-of-coverage test refusal (FORGE F11).
+     */
+    testCoverage?: boolean;
     /** Output machine-readable JSON instead of human-readable text. */
     json?: boolean;
 }

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.
@@ -174,6 +181,14 @@ export interface TypecheckConfig {
      * mismatch). A narrowed project sets `null` here to stay clean.
      */
     projectOverrides?: Record<string, string | null>;
+    /**
+     * How to report undefined free identifiers (TS2304/TS2552). These were
+     * historically suppressed as shim-gap noise, which also hid genuine
+     * missing imports until they crashed at runtime (FORGE F12). Default
+     * `'warning'`: visible without failing the gate. `'error'` makes them
+     * blocking; `'off'` restores the historical suppression.
+     */
+    undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * Wire command configuration.
@@ -255,6 +270,13 @@ export interface PatchLintConfig {
      * 'off'.
      */
     chromeScriptJsDoc?: PatchLintSeverityGate;
+    /**
+     * How the checkJs pass reports undefined free identifiers
+     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`
+     * (FORGE F12); the two flows share the suppression policy so a patch
+     * cannot pass one and fail the other. Default: 'warning'.
+     */
+    undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * Build mode for mach.

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)));
+}

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

@@ -57,6 +57,11 @@ export declare function isArray(value: unknown): value is unknown[];
  * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
  */
 export declare function isValidFirefoxVersion(version: string): boolean;
+/**
+ * Validates a release-candidate build directory name.
+ * Accepts formats like "build1", "build2", "build12" (no leading zero).
+ */
+export declare function isValidFirefoxCandidate(candidate: string): boolean;
 /**
  * Validates a Firefox product string.
  * Accepts: firefox, firefox-esr, firefox-beta, firefox-devedition

package/dist/src/utils/validation.js

@@ -87,6 +87,13 @@ export function isValidFirefoxVersion(version) {
     // Beta: 147.0b1, 147.0b2
     return /^[1-9]\d{0,2}\.\d+(?:b[1-9]\d*|\.\d+(?:esr)?|esr)?$/.test(version);
 }
+/**
+ * Validates a release-candidate build directory name.
+ * Accepts formats like "build1", "build2", "build12" (no leading zero).
+ */
+export function isValidFirefoxCandidate(candidate) {
+    return /^build[1-9]\d{0,3}$/.test(candidate);
+}
 /**
  * Validates a Firefox product string.
  * Accepts: firefox, firefox-esr, firefox-beta, firefox-devedition

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -73,9 +73,9 @@
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.25.0",
+    "knip": "6.26.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.4",
+    "prettier": "3.9.5",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",