@hominis/fireforge 0.37.0 → 0.38.0

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
@@ -251,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
@@ -350,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.
@@ -457,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;
     /**
@@ -487,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/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/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.38.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",