@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/errors/base.d.ts

@@ -79,13 +79,10 @@ export declare class InvalidArgumentError extends FireForgeError {
  * Error thrown when a spawned command exceeds its `timeout` option.
  *
  * Every `exec*` helper in `src/utils/process.ts` rejects with this type
- * (instead of Node's bare `AbortError: The operation was aborted`) when the
- * caller-supplied timeout fires. The bare AbortError bit an operator during
- * the 2026-04-24 eval (see {@link GitIndexingTimeoutError} in errors/git.ts):
- * an 854 s git indexing pass died with no command name, no elapsed time, and
- * no hint that a timeout — not git — was responsible. The git path gained a
- * site-local typed error then; this class extends the same courtesy to every
- * other `timeout` caller.
+ * instead of Node's bare `AbortError: The operation was aborted`, which
+ * carries no command name, no elapsed time, and no hint that a timeout —
+ * not the command — was responsible. See {@link GitIndexingTimeoutError} in
+ * errors/git.ts for the git-specific variant.
  */
 export declare class ExecTimeoutError extends FireForgeError {
     /** Executable that was spawned (argv[0]). */
@@ -105,23 +102,47 @@ export declare class ExecTimeoutError extends FireForgeError {
     get userMessage(): string;
 }
 /**
- * Error thrown when a file-lock wait times out because another process
- * holds the lock.
+ * Error thrown when a file-lock wait times out because another process holds
+ * the lock.
  *
  * Dedicated subclass so the CLI boundary renders lock contention as the
- * one-line reason-first/remedy-second refusal it is — before this, the
- * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
- * as an internal failure and prints with a five-frame stack. The refusal
- * was always correct; the presentation made it look like a crash.
+ * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
+ * is treated by `withErrorHandling` as an internal failure and printed with
+ * a five-frame stack — a correct refusal that looks like a crash.
+ *
+ * Exit code 15, not 1: the run never started. A script that retries on
+ * failure wants to re-queue this one, not treat it as a failure of the work
+ * it asked for. Every lock in FireForge shares the class and therefore the
+ * code — the fact is the same whichever lock was contended.
  */
 export declare class LockContentionError extends FireForgeError {
-    readonly code: 1;
+    readonly code: 15;
+}
+/**
+ * Error thrown when a test run completed but its verdict cannot be trusted,
+ * because `engine/` changed (or stopped being probeable) while the harness
+ * was running.
+ *
+ * Dedicated subclass for its exit code alone: as a `GeneralError` this
+ * refusal exited 1 beside real test failures' 5, and a summary line reading
+ * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
+ * kind of fact. They are opposites — one suite failed, the other's result
+ * was discarded — and only a distinct code makes "unknown, re-run"
+ * mechanically separable from "red".
+ */
+export declare class InconclusiveVerdictError extends FireForgeError {
+    readonly code: 14;
 }
 /**
- * Error thrown when the user cancels an interactive prompt.
+ * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Ctrl+C, i.e. `isCancel(...)`.
+ *
+ * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * 128+SIGINT, which claims an interrupt. A declined confirmation is a
+ * successful run that chose not to proceed, and exits 0.
  */
 export declare class CancellationError extends FireForgeError {
-    readonly code: 1;
+    readonly code: 130;
     constructor();
 }
 /**

package/dist/src/errors/base.js

@@ -113,13 +113,10 @@ export class InvalidArgumentError extends FireForgeError {
  * Error thrown when a spawned command exceeds its `timeout` option.
  *
  * Every `exec*` helper in `src/utils/process.ts` rejects with this type
- * (instead of Node's bare `AbortError: The operation was aborted`) when the
- * caller-supplied timeout fires. The bare AbortError bit an operator during
- * the 2026-04-24 eval (see {@link GitIndexingTimeoutError} in errors/git.ts):
- * an 854 s git indexing pass died with no command name, no elapsed time, and
- * no hint that a timeout — not git — was responsible. The git path gained a
- * site-local typed error then; this class extends the same courtesy to every
- * other `timeout` caller.
+ * instead of Node's bare `AbortError: The operation was aborted`, which
+ * carries no command name, no elapsed time, and no hint that a timeout —
+ * not the command — was responsible. See {@link GitIndexingTimeoutError} in
+ * errors/git.ts for the git-specific variant.
  */
 export class ExecTimeoutError extends FireForgeError {
     command;
@@ -145,23 +142,47 @@ export class ExecTimeoutError extends FireForgeError {
     }
 }
 /**
- * Error thrown when a file-lock wait times out because another process
- * holds the lock.
+ * Error thrown when a file-lock wait times out because another process holds
+ * the lock.
  *
  * Dedicated subclass so the CLI boundary renders lock contention as the
- * one-line reason-first/remedy-second refusal it is — before this, the
- * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
- * as an internal failure and prints with a five-frame stack. The refusal
- * was always correct; the presentation made it look like a crash.
+ * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
+ * is treated by `withErrorHandling` as an internal failure and printed with
+ * a five-frame stack — a correct refusal that looks like a crash.
+ *
+ * Exit code 15, not 1: the run never started. A script that retries on
+ * failure wants to re-queue this one, not treat it as a failure of the work
+ * it asked for. Every lock in FireForge shares the class and therefore the
+ * code — the fact is the same whichever lock was contended.
  */
 export class LockContentionError extends FireForgeError {
-    code = ExitCode.GENERAL_ERROR;
+    code = ExitCode.LOCK_TIMEOUT;
+}
+/**
+ * Error thrown when a test run completed but its verdict cannot be trusted,
+ * because `engine/` changed (or stopped being probeable) while the harness
+ * was running.
+ *
+ * Dedicated subclass for its exit code alone: as a `GeneralError` this
+ * refusal exited 1 beside real test failures' 5, and a summary line reading
+ * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
+ * kind of fact. They are opposites — one suite failed, the other's result
+ * was discarded — and only a distinct code makes "unknown, re-run"
+ * mechanically separable from "red".
+ */
+export class InconclusiveVerdictError extends FireForgeError {
+    code = ExitCode.INCONCLUSIVE;
 }
 /**
- * Error thrown when the user cancels an interactive prompt.
+ * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Ctrl+C, i.e. `isCancel(...)`.
+ *
+ * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * 128+SIGINT, which claims an interrupt. A declined confirmation is a
+ * successful run that chose not to proceed, and exits 0.
  */
 export class CancellationError extends FireForgeError {
-    code = ExitCode.GENERAL_ERROR;
+    code = ExitCode.USER_CANCELLED;
     constructor() {
         super('cancelled');
     }

package/dist/src/errors/build.d.ts

@@ -47,6 +47,18 @@ export declare class MozconfigError extends BuildError {
  */
 export declare class AmbiguousBuildArtifactsError extends BuildError {
     readonly objDirs: string[];
-    constructor(objDirs: string[]);
+    /**
+     * Objdir the active mozconfig declared, when one was declared and did
+     * not resolve to exactly one candidate. Reported because a declaration
+     * that names something the scan cannot see is the diagnosis, not noise.
+     */
+    readonly declaredObjDir?: string | undefined;
+    constructor(objDirs: string[], 
+    /**
+     * Objdir the active mozconfig declared, when one was declared and did
+     * not resolve to exactly one candidate. Reported because a declaration
+     * that names something the scan cannot see is the diagnosis, not noise.
+     */
+    declaredObjDir?: string | undefined);
     get userMessage(): string;
 }

package/dist/src/errors/build.js

@@ -97,17 +97,29 @@ export class MozconfigError extends BuildError {
  */
 export class AmbiguousBuildArtifactsError extends BuildError {
     objDirs;
-    constructor(objDirs) {
+    declaredObjDir;
+    constructor(objDirs, 
+    /**
+     * Objdir the active mozconfig declared, when one was declared and did
+     * not resolve to exactly one candidate. Reported because a declaration
+     * that names something the scan cannot see is the diagnosis, not noise.
+     */
+    declaredObjDir) {
         super(`Multiple build artifact directories found: ${objDirs.join(', ')}`);
         this.objDirs = objDirs;
+        this.declaredObjDir = declaredObjDir;
     }
     get userMessage() {
+        const declared = this.declaredObjDir !== undefined
+            ? `The mozconfig declares MOZ_OBJDIR=${this.declaredObjDir}, which does not match exactly one of these candidates — so it could not settle the choice.\n\n`
+            : '';
         return ('Build Error: Multiple build artifact directories were found.\n\n' +
             `Candidates: ${this.objDirs.join(', ')}\n\n` +
+            declared +
             'FireForge will not guess which build output to use.\n\n' +
             'To fix this:\n' +
             '  1. Remove stale obj-* directories you no longer need\n' +
-            '  2. Keep only the active build output directory\n' +
+            '  2. Keep only the active build output directory, or name it with MOZ_OBJDIR in the mozconfig\n' +
             '  3. Run the command again');
     }
 }

package/dist/src/errors/codes.d.ts

@@ -48,6 +48,22 @@ export declare const ExitCode: {
      * missing profile, etc.).
      */
     readonly SMOKE_LAUNCH_FAILURE: 13;
+    /**
+     * A `fireforge test` run produced a harness result that cannot be trusted
+     * — `engine/` moved (or became unprobeable) while the tests ran. Distinct
+     * from BUILD_ERROR because the two are opposites: a 5 is a suite that
+     * FAILED, a 14 is a suite whose result was THROWN AWAY. A consumer should
+     * re-run a 14 (after settling the writers) and must not report it as red.
+     */
+    readonly INCONCLUSIVE: 14;
+    /**
+     * A lock wait expired: the run never started, because another FireForge
+     * process held the lock for the whole budget. Distinct from GENERAL_ERROR
+     * because nothing about the request was wrong — a consumer should re-queue
+     * it, with a larger `--wait-lock` budget, rather than treat it as a
+     * failure of the work it asked for.
+     */
+    readonly LOCK_TIMEOUT: 15;
     /**
      * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
      * conventional "interrupted by the user" code — scripts and CI can tell

package/dist/src/errors/codes.js

@@ -49,6 +49,22 @@ export const ExitCode = {
      * missing profile, etc.).
      */
     SMOKE_LAUNCH_FAILURE: 13,
+    /**
+     * A `fireforge test` run produced a harness result that cannot be trusted
+     * — `engine/` moved (or became unprobeable) while the tests ran. Distinct
+     * from BUILD_ERROR because the two are opposites: a 5 is a suite that
+     * FAILED, a 14 is a suite whose result was THROWN AWAY. A consumer should
+     * re-run a 14 (after settling the writers) and must not report it as red.
+     */
+    INCONCLUSIVE: 14,
+    /**
+     * A lock wait expired: the run never started, because another FireForge
+     * process held the lock for the whole budget. Distinct from GENERAL_ERROR
+     * because nothing about the request was wrong — a consumer should re-queue
+     * it, with a larger `--wait-lock` budget, rather than treat it as a
+     * failure of the work it asked for.
+     */
+    LOCK_TIMEOUT: 15,
     /**
      * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
      * conventional "interrupted by the user" code — scripts and CI can tell

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

@@ -8,10 +8,10 @@ export declare class FurnaceError extends FireForgeError {
     constructor(message: string, component?: string | undefined, cause?: Error, options?: {
         /**
          * Suppresses the "run furnace validate" advice line. Set by callers
-         * whose message already tells the user to run validate (or that ARE
-         * the validate command) — an explicit flag, because the previous
-         * `message.includes('furnace validate')` sniffing dropped the advice
-         * from any error that merely MENTIONED the command.
+         * whose message already tells the user to run validate, or that ARE
+         * the validate command. An explicit flag rather than sniffing the
+         * message for `furnace validate`, which drops the advice from any
+         * error that merely MENTIONS the command.
          */
         omitValidateAdvice?: boolean;
     });

package/dist/src/errors/git.d.ts

@@ -48,17 +48,13 @@ export declare class GitIndexLockError extends GitError {
  */
 export declare function isGitIndexLockConflict(error: unknown): boolean;
 /**
- * Error thrown when `git add` (monolithic or chunked) exceeds the
- * configured timeout while indexing the Firefox source tree.
+ * Error thrown when `git add` (monolithic or chunked) exceeds the configured
+ * timeout while indexing the Firefox source tree.
  *
- * 2026-04-24 eval Finding 10: a 140.10.0esr bump on a previously-working
- * 140.9.0esr workspace aborted after ~854s with a generic
- * `AbortError: The operation was aborted`. The root cause was the
- * `git add` timeout firing, but the surfaced error was indistinguishable
- * from any other AbortError and gave the operator no actionable
- * direction. This typed error carries the elapsed budget and the
- * environment-variable override so the recovery path is
- * self-documenting.
+ * A bare `AbortError: The operation was aborted` after ~15 minutes is
+ * indistinguishable from any other AbortError and gives the operator no
+ * actionable direction. This typed error carries the elapsed budget and the
+ * environment-variable override so the recovery path is self-documenting.
  */
 export declare class GitIndexingTimeoutError extends GitError {
     readonly phase: 'monolithic' | 'chunked';

package/dist/src/errors/git.js

@@ -114,17 +114,13 @@ export function isGitIndexLockConflict(error) {
         /(unable to create|another git process seems to be running|file exists|locked)/i.test(error.message));
 }
 /**
- * Error thrown when `git add` (monolithic or chunked) exceeds the
- * configured timeout while indexing the Firefox source tree.
+ * Error thrown when `git add` (monolithic or chunked) exceeds the configured
+ * timeout while indexing the Firefox source tree.
  *
- * 2026-04-24 eval Finding 10: a 140.10.0esr bump on a previously-working
- * 140.9.0esr workspace aborted after ~854s with a generic
- * `AbortError: The operation was aborted`. The root cause was the
- * `git add` timeout firing, but the surfaced error was indistinguishable
- * from any other AbortError and gave the operator no actionable
- * direction. This typed error carries the elapsed budget and the
- * environment-variable override so the recovery path is
- * self-documenting.
+ * A bare `AbortError: The operation was aborted` after ~15 minutes is
+ * indistinguishable from any other AbortError and gives the operator no
+ * actionable direction. This typed error carries the elapsed budget and the
+ * environment-variable override so the recovery path is self-documenting.
  */
 export class GitIndexingTimeoutError extends GitError {
     phase;

package/dist/src/errors/patch.d.ts

@@ -2,13 +2,13 @@ import { FireForgeError } from './base.js';
 /**
  * Error thrown when `patches.json` exists but cannot be parsed or validated.
  *
- * This must be a HARD error on every mutating path. The historical behavior
- * collapsed "corrupt" into "absent" (`loadPatchesManifest` returned null for
- * both), so the next `fireforge export` would rebuild the manifest containing
- * only the new patch — silently destroying every other patch's metadata
- * (tiers, descriptions, lintIgnore, staged dependencies) — and a failed
- * export's rollback would then delete `patches.json` outright because the
- * "before" state looked absent (2026-07-05 review, finding H2).
+ * This must be a HARD error on every mutating path. Collapsing "corrupt"
+ * into "absent" — a `loadPatchesManifest` that returns null for both — makes
+ * the next `fireforge export` rebuild the manifest containing only the new
+ * patch, silently destroying every other patch's metadata (tiers,
+ * descriptions, lintIgnore, staged dependencies); a failed export's rollback
+ * then deletes `patches.json` outright, because the "before" state looked
+ * absent.
  */
 export declare class PatchManifestCorruptError extends FireForgeError {
     readonly manifestPath: string;

package/dist/src/errors/patch.js

@@ -4,13 +4,13 @@ import { ExitCode } from './codes.js';
 /**
  * Error thrown when `patches.json` exists but cannot be parsed or validated.
  *
- * This must be a HARD error on every mutating path. The historical behavior
- * collapsed "corrupt" into "absent" (`loadPatchesManifest` returned null for
- * both), so the next `fireforge export` would rebuild the manifest containing
- * only the new patch — silently destroying every other patch's metadata
- * (tiers, descriptions, lintIgnore, staged dependencies) — and a failed
- * export's rollback would then delete `patches.json` outright because the
- * "before" state looked absent (2026-07-05 review, finding H2).
+ * This must be a HARD error on every mutating path. Collapsing "corrupt"
+ * into "absent" — a `loadPatchesManifest` that returns null for both — makes
+ * the next `fireforge export` rebuild the manifest containing only the new
+ * patch, silently destroying every other patch's metadata (tiers,
+ * descriptions, lintIgnore, staged dependencies); a failed export's rollback
+ * then deletes `patches.json` outright, because the "before" state looked
+ * absent.
  */
 export class PatchManifestCorruptError extends FireForgeError {
     manifestPath;

package/dist/src/errors/rebase.d.ts

@@ -21,11 +21,11 @@ export declare class NoRebaseSessionError extends RebaseError {
 /**
  * Thrown when the session file exists but cannot be used.
  *
- * This case had no error of its own before 0.41.0 and was reported as
+ * Without an error of its own, this case is reported as
  * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
- * reported {@link RebaseSessionExistsError} — a closed cycle in which each
- * command pointed at the other two. The message names the file so an operator
- * always has a way out, and `--abort` now clears a corrupt session rather than
+ * reports {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command points at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` clears a corrupt session rather than
  * refusing to run against one.
  */
 export declare class CorruptRebaseSessionError extends RebaseError {

package/dist/src/errors/rebase.js

@@ -35,11 +35,11 @@ export class NoRebaseSessionError extends RebaseError {
 /**
  * Thrown when the session file exists but cannot be used.
  *
- * This case had no error of its own before 0.41.0 and was reported as
+ * Without an error of its own, this case is reported as
  * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
- * reported {@link RebaseSessionExistsError} — a closed cycle in which each
- * command pointed at the other two. The message names the file so an operator
- * always has a way out, and `--abort` now clears a corrupt session rather than
+ * reports {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command points at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` clears a corrupt session rather than
  * refusing to run against one.
  */
 export class CorruptRebaseSessionError extends RebaseError {

package/dist/src/index.d.ts

@@ -8,9 +8,15 @@
  * but may change between minor versions until 1.0 is released. Pin to an
  * exact version if you depend on the programmatic API.
  *
+ * **What belongs here:** a type earns a place on this surface only if it is
+ * reachable from the signature of an exported VALUE — i.e. a consumer needs
+ * it to name an argument or a return. Everything else stays internal to
+ * `src/types/`.
+ *
  * @packageDocumentation
  */
 export { loadConfig, validateConfig } from './core/config.js';
+export type { ApplyAllComponentsResult } from './core/furnace-apply.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
@@ -20,4 +26,4 @@ export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-ma
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';
-export type { ApplyResult, BuildConfig, BuildMode, BuildOptions, ComponentType, CustomComponentConfig, DiscardOptions, DoctorCheck, DownloadOptions, DryRunAction, ExportOptions, FireForgeConfig, FireForgeState, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceCreateOptions, FurnaceOverrideOptions, FurnaceRemoveOptions, FurnaceState, GlobalOptions, ImportOptions, ImportSummary, OverrideComponentConfig, OverrideType, PackageOptions, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, ProjectLicense, ProjectPaths, ProjectStatus, ReExportOptions, RegistrationStatus, ResetOptions, RunOptions, ScannedComponent, SetupOptions, StepError, SyncResult, TestOptions, TokenCoverageFileEntry, TokenCoverageReport, ValidationIssue, WireConfig, } from './types/index.js';
+export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';

package/dist/src/index.js

@@ -9,6 +9,11 @@
  * but may change between minor versions until 1.0 is released. Pin to an
  * exact version if you depend on the programmatic API.
  *
+ * **What belongs here:** a type earns a place on this surface only if it is
+ * reachable from the signature of an exported VALUE — i.e. a consumer needs
+ * it to name an argument or a return. Everything else stays internal to
+ * `src/types/`.
+ *
  * @packageDocumentation
  */
 export { loadConfig, validateConfig } from './core/config.js';

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

@@ -1,6 +1,6 @@
 /**
  * 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 { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, 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, PatchStagedRegistration, } from './patches.js';
-export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';
+export type { DoctorCheck, TokenCoverageFileEntry, TokenCoverageReport } from './project.js';