@hominis/fireforge 0.34.2 → 0.36.0

package/dist/src/errors/build.js

@@ -111,4 +111,3 @@ export class AmbiguousBuildArtifactsError extends BuildError {
             '  3. Run the command again');
     }
 }
-//# sourceMappingURL=build.js.map

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

@@ -38,5 +38,11 @@ export declare const ExitCode: {
      * missing profile, etc.).
      */
     readonly SMOKE_LAUNCH_FAILURE: 13;
+    /**
+     * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
+     * conventional "interrupted by the user" code — scripts and CI can tell
+     * a deliberate cancellation apart from a real failure (GENERAL_ERROR).
+     */
+    readonly USER_CANCELLED: 130;
 };
 export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/src/errors/codes.js

@@ -39,5 +39,10 @@ export const ExitCode = {
      * missing profile, etc.).
      */
     SMOKE_LAUNCH_FAILURE: 13,
+    /**
+     * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
+     * conventional "interrupted by the user" code — scripts and CI can tell
+     * a deliberate cancellation apart from a real failure (GENERAL_ERROR).
+     */
+    USER_CANCELLED: 130,
 };
-//# sourceMappingURL=codes.js.map

package/dist/src/errors/config.js

@@ -58,4 +58,3 @@ export class InvalidFieldError extends ConfigError {
         this.actualValue = actualValue;
     }
 }
-//# sourceMappingURL=config.js.map

package/dist/src/errors/download.js

@@ -65,8 +65,10 @@ export class ExtractionError extends DownloadError {
         this.archivePath = archivePath;
     }
     get userMessage() {
+        const reason = this.cause instanceof Error ? `Reason: ${this.cause.message}\n\n` : '';
         return (`Extraction Error: Failed to extract Firefox source archive.\n\n` +
             `Archive: ${this.archivePath}\n\n` +
+            reason +
             'To fix this:\n' +
             '  1. Delete the corrupted archive and try again\n' +
             '  2. Ensure you have enough disk space\n' +
@@ -127,4 +129,3 @@ export class PartialEngineExistsError extends DownloadError {
             '  3. Re-run with --verbose for the full underlying error and stack trace');
     }
 }
-//# sourceMappingURL=download.js.map

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

@@ -5,6 +5,16 @@ import { FireForgeError } from './base.js';
 export declare class FurnaceError extends FireForgeError {
     readonly component?: string | undefined;
     readonly code: 9;
-    constructor(message: string, component?: string | undefined, cause?: Error);
+    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.
+         */
+        omitValidateAdvice?: boolean;
+    });
+    private readonly omitValidateAdvice;
     get userMessage(): string;
 }

package/dist/src/errors/furnace.js

@@ -7,22 +7,23 @@ import { ExitCode } from './codes.js';
 export class FurnaceError extends FireForgeError {
     component;
     code = ExitCode.FURNACE_ERROR;
-    constructor(message, component, cause) {
+    constructor(message, component, cause, options) {
         super(message, cause);
         this.component = component;
+        this.omitValidateAdvice =
+            options?.omitValidateAdvice ?? message.includes('Run "fireforge furnace validate"');
     }
+    omitValidateAdvice;
     get userMessage() {
         let msg = this.component
             ? `Furnace Error (${this.component}): ${this.message}`
             : `Furnace Error: ${this.message}`;
         msg += '\n\nTo fix this:\n';
         msg += '  1. Check the error message above for specifics\n';
-        // Avoid circular advice when the error is thrown during validation itself.
-        if (!this.message.includes('furnace validate')) {
+        if (!this.omitValidateAdvice) {
             msg += '  2. Run "fireforge furnace validate" to diagnose issues\n';
         }
-        msg += `  ${this.message.includes('furnace validate') ? '2' : '3'}. Use "fireforge doctor --repair-furnace" if state is inconsistent`;
+        msg += `  ${this.omitValidateAdvice ? '2' : '3'}. Use "fireforge doctor --repair-furnace" if state is inconsistent`;
         return msg;
     }
 }
-//# sourceMappingURL=furnace.js.map

package/dist/src/errors/git.js

@@ -135,4 +135,3 @@ export class GitIndexingTimeoutError extends GitError {
             '  3. If the problem persists, check disk throughput and free space; Firefox source indexing on a cold SSD typically completes in 1–3 minutes.');
     }
 }
-//# sourceMappingURL=git.js.map

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

@@ -1,4 +1,21 @@
 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).
+ */
+export declare class PatchManifestCorruptError extends FireForgeError {
+    readonly manifestPath: string;
+    readonly code: 6;
+    constructor(manifestPath: string, cause?: Error);
+    get userMessage(): string;
+}
 /**
  * Error thrown when patch operations fail.
  */

package/dist/src/errors/patch.js

@@ -1,6 +1,35 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { FireForgeError } from './base.js';
 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).
+ */
+export class PatchManifestCorruptError extends FireForgeError {
+    manifestPath;
+    code = ExitCode.PATCH_ERROR;
+    constructor(manifestPath, cause) {
+        super(`patches.json exists but could not be parsed: ${cause?.message ?? 'unknown parse error'}`, cause);
+        this.manifestPath = manifestPath;
+    }
+    get userMessage() {
+        return (`Patch Manifest Error: ${this.message}\n\n` +
+            `Manifest: ${this.manifestPath}\n\n` +
+            'FireForge refuses to modify the patch queue while patches.json is unreadable — ' +
+            'rewriting it now would silently discard the metadata of every patch it lists.\n\n' +
+            'To fix this:\n' +
+            '  1. Open patches.json and repair the syntax error (a recent hand-edit is the usual cause)\n' +
+            '  2. Or restore patches.json from version control\n' +
+            '  3. Then re-run the command');
+    }
+}
 /**
  * Error thrown when patch operations fail.
  */
@@ -23,4 +52,3 @@ export class PatchError extends FireForgeError {
         return msg;
     }
 }
-//# sourceMappingURL=patch.js.map

package/dist/src/errors/rebase.js

@@ -32,4 +32,3 @@ export class NoRebaseSessionError extends RebaseError {
         super('No rebase session in progress. Start one with "fireforge rebase".');
     }
 }
-//# sourceMappingURL=rebase.js.map

package/dist/src/errors/run.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { FireForgeError } from './base.js';
+import { ExitCode } from './codes.js';
 /**
  * Error raised by `fireforge run --smoke-exit` when the captured console
  * stream produced one or more error lines that did NOT match the
@@ -19,4 +20,3 @@ export class SmokeRunError extends FireForgeError {
         return `Smoke run failed: ${this.message}`;
     }
 }
-//# sourceMappingURL=run.js.map

package/dist/src/index.js

@@ -18,4 +18,3 @@ export { validateAllComponents, validateComponent } from './core/furnace-validat
 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';
-//# sourceMappingURL=index.js.map

package/dist/src/types/cli.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=cli.js.map

package/dist/src/types/commands/index.js

@@ -3,4 +3,3 @@
  * Re-exports all command-related types from focused sub-modules.
  */
 export {};
-//# sourceMappingURL=index.js.map

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

@@ -299,11 +299,6 @@ export interface PatchStagedDependencyOptions {
     /** Skip the confirmation prompt (required for non-TTY). */
     yes?: 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 `patch split` command.
  */
@@ -331,6 +326,11 @@ export interface PatchSplitOptions {
     /** Skip per-patch lint of the projected bodies. */
     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.
+ */
 export interface PatchMoveFilesOptions {
     /** File paths relative to engine/ to move from the source patch to the target patch. */
     file?: string[];
@@ -389,6 +389,13 @@ export interface RunOptions {
      * inspect the raw stream after smoke-exit returns.
      */
     captureConsole?: string;
+    /**
+     * Launch the browser with `--headless` (forwarded to the binary via
+     * `mach run`). Primarily for smoke mode on shared desktops: a headed
+     * smoke window absorbs live keyboard/mouse input, and the resulting
+     * console errors contaminate the capture and can fail the run.
+     */
+    headless?: boolean;
 }
 /**
  * Options for the test command.
@@ -398,6 +405,8 @@ export interface TestOptions {
     headless?: boolean;
     /** Run incremental UI build before testing */
     build?: boolean;
+    /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
+    auto?: boolean;
     /**
      * Run a marionette preflight before tests. Reports PASS/FAIL in under a
      * minute. When test paths are supplied, a FAIL aborts before mach test is
@@ -421,6 +430,12 @@ export interface TestOptions {
      * stale process holds the default port or CI uses another port.
      */
     marionettePort?: number;
+    /** Kill a recognized stale browser process holding the Marionette port, then continue. */
+    killStaleMarionette?: boolean;
+    /** Permit tests against packageable engine edits newer than the last successful build. */
+    allowStaleBuild?: boolean;
+    /** Run the configured short harness canary. `true` means use `fireforge.json`'s test.canaryPath. */
+    canary?: string | boolean;
     /**
      * Retry budget for recognized harness crashes (resource-monitor
      * tracebacks, pre-test no-output hangs, post-green shutdown re-entry).

package/dist/src/types/commands/options.js

@@ -3,4 +3,3 @@
  * Command option types for CLI commands.
  */
 export {};
-//# sourceMappingURL=options.js.map

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

@@ -31,6 +31,14 @@ export interface PatchResult {
     conflictingFiles?: string[];
     /** Whether the patch was auto-resolved (new file vs existing file conflict) */
     autoResolved?: boolean;
+    /**
+     * Pre-existing content of files the auto-resolve overwrote, keyed by
+     * engine-relative path. Kept for the RUN's duration (not just the retry):
+     * if a later patch fails and `rollbackPatches` reverse-applies this one,
+     * reversing a new-file patch DELETES the file — these snapshots are the
+     * only way to restore what was there before the auto-resolve.
+     */
+    autoResolvedOriginals?: Map<string, string>;
 }
 /**
  * Extended patch information with metadata.

package/dist/src/types/commands/patches.js

@@ -3,4 +3,3 @@
  * Types for the patch system: patch metadata, manifests, lint, and import results.
  */
 export {};
-//# sourceMappingURL=patches.js.map

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

@@ -3,19 +3,28 @@
  */
 /**
  * Result of a doctor check.
+ *
+ * Field precedence (consumers and producers must agree):
+ *   1. `severity`, when present, is authoritative — `'error'` counts as a
+ *      failure and `'warning'` as a warning REGARDLESS of `passed`.
+ *   2. Without `severity`, `passed: false` is a failure unless
+ *      `warning: true` downgrades it to a warning.
+ * Producers should prefer setting `severity` explicitly; `warning` exists
+ * for older checks that predate the field. Do not emit contradictory
+ * combinations like `passed: true, severity: 'error'`.
  */
 export interface DoctorCheck {
     /** Name of the check */
     name: string;
     /** Whether the check passed */
     passed: boolean;
-    /** Severity of the result */
+    /** Severity of the result (authoritative when present — see above) */
     severity?: 'ok' | 'warning' | 'error';
     /** Description of the result */
     message: string;
     /** Suggested fix if check failed */
     fix?: string;
-    /** Whether this check passed with a warning */
+    /** Legacy warning flag for checks that predate `severity` */
     warning?: boolean;
 }
 /**

package/dist/src/types/commands/project.js

@@ -3,4 +3,3 @@
  * Project diagnostics, status, and token coverage types.
  */
 export {};
-//# sourceMappingURL=project.js.map

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

@@ -24,6 +24,34 @@ export interface BuildConfig {
     /** Number of parallel jobs for mach build */
     jobs?: number;
 }
+/** Test command defaults stored in fireforge.json. */
+export interface TestConfig {
+    /**
+     * Engine-relative browser-chrome canary file used by `fireforge test --canary`
+     * when the command does not receive an explicit canary path.
+     */
+    canaryPath?: string;
+    /** Short no-output ceiling for `fireforge test --canary`, in seconds. */
+    canaryTimeoutSeconds?: number;
+}
+/** A single external executable required by a project-specific toolchain. */
+export interface ExternalToolRequirement {
+    /** Tool name as shown in doctor output, and PATH/xcrun lookup key when no path is set. */
+    name: string;
+    /** Absolute or project-relative executable path. */
+    path?: string;
+    /** Resolve the tool with `xcrun -find <name>` instead of PATH. */
+    xcrun?: boolean;
+    /** Missing tool is an error by default; set false for advisory probes. */
+    required?: boolean;
+}
+/** Named group of project-specific external asset/build tools. */
+export interface ExternalToolchainConfig {
+    /** Human-readable toolchain name, e.g. "seasonal-branding". */
+    name: string;
+    /** Tools this toolchain needs. */
+    tools: ExternalToolRequirement[];
+}
 /** Enforcement mode for patch policy violations during mutating commands. */
 export type PatchPolicyMutationMode = 'error' | 'warn' | 'force';
 /** A category-owned numeric range in the patch queue. */
@@ -89,6 +117,10 @@ export interface FireForgeConfig {
     firefox: FirefoxConfig;
     /** Build settings */
     build?: BuildConfig;
+    /** Test command defaults */
+    test?: TestConfig;
+    /** Optional project-specific external toolchains checked by doctor. */
+    externalToolchains?: ExternalToolchainConfig[];
     /** Project license SPDX identifier */
     license?: ProjectLicense;
     /** Wire command configuration */

package/dist/src/types/config.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=config.js.map

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

@@ -208,6 +208,16 @@ export interface FurnaceState {
 export interface StepError {
     step: string;
     error: string;
+    /**
+     * Advisory step errors are reported as warnings and never trigger
+     * rollback or a non-zero exit. Used by the `.ftl` helpers, whose module
+     * contract is graceful degradation: a missing locale jar.mn on a fork
+     * without a locale package must not block a working `.mjs`/`.css` from
+     * shipping. Before this flag existed the contract was contradicted in
+     * practice — any FTL step error rolled back the entire apply, so a
+     * localized component on such a fork could never be applied at all.
+     */
+    advisory?: boolean;
 }
 /**
  * Result of applying all components to the engine source tree.

package/dist/src/types/furnace.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=furnace.js.map

package/dist/src/types/index.js

@@ -3,4 +3,3 @@
  * Re-exports all type definitions.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/src/types/typecheck.js

@@ -12,4 +12,3 @@
  * code fields that have no meaning for patch-hygiene rules.
  */
 export {};
-//# sourceMappingURL=typecheck.js.map

package/dist/src/utils/elapsed.js

@@ -12,4 +12,3 @@ function formatElapsed(ms) {
 export function elapsedSince(startedAt) {
     return formatElapsed(Date.now() - startedAt);
 }
-//# sourceMappingURL=elapsed.js.map

package/dist/src/utils/errors.js

@@ -12,4 +12,3 @@ export function toError(error) {
     }
     return new Error(typeof error === 'string' ? error : String(error), { cause: error });
 }
-//# sourceMappingURL=errors.js.map

package/dist/src/utils/fs.js

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
 import { access, chmod, copyFile as fsCopyFile, lstat, mkdir, open, readdir, readFile, rename, rm, stat, statfs, } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
+const RETRIABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
 function sleep(ms) {
     return new Promise((resolve) => {
         setTimeout(resolve, ms);
@@ -199,7 +200,7 @@ export async function writeFileAtomic(path, content) {
         if (existingMode !== undefined) {
             await chmod(tempPath, existingMode);
         }
-        await rename(tempPath, path);
+        await renameWithRetries(tempPath, path);
         await syncParentDir(path);
     }
     catch (error) {
@@ -207,6 +208,31 @@ export async function writeFileAtomic(path, content) {
         throw error;
     }
 }
+/**
+ * Renames the temp file over its destination, retrying transient sharing
+ * violations. On Windows, a rename onto a target that another writer is
+ * concurrently replacing — or that an antivirus/indexer briefly holds open —
+ * fails with EPERM/EACCES/EBUSY even though the same rename succeeds a moment
+ * later; POSIX renames never hit this. Non-retriable codes and exhausted
+ * budgets rethrow, so a genuine permission problem still surfaces.
+ */
+async function renameWithRetries(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rename(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
+                ? error.code
+                : undefined;
+            if (!code || !RETRIABLE_RENAME_ERRORS.has(code) || attempt === 4) {
+                throw error;
+            }
+            await sleep(25 * (attempt + 1));
+        }
+    }
+}
 async function syncParentDir(path) {
     let directoryHandle;
     try {
@@ -270,7 +296,10 @@ export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9
  */
 function createAtomicTempPath(path) {
     const directory = dirname(path);
-    const filename = path.slice(directory.length + 1);
+    // basename, not slice(dirname.length + 1): when dirname ends with the
+    // separator (filesystem/drive roots, e.g. dirname('/foo') === '/'), the
+    // slice arithmetic chopped the first filename character ('/foo' → 'oo').
+    const filename = basename(path);
     return join(directory, `.${filename}.fireforge-tmp-${process.pid}-${randomUUID()}`);
 }
 /**
@@ -287,7 +316,11 @@ function createAtomicTempPath(path) {
 export async function checkDiskSpace(path, minBytes, onLowSpace) {
     try {
         const stats = await statfs(path);
-        const availableBytes = stats.bfree * stats.bsize;
+        // bavail = blocks available to UNPRIVILEGED users; bfree includes the
+        // root-reserved blocks (typically 5% on ext4), so it over-reported free
+        // space and silently suppressed the low-space warning exactly when it
+        // mattered.
+        const availableBytes = stats.bavail * stats.bsize;
         if (availableBytes < minBytes) {
             const availableGB = (availableBytes / (1024 * 1024 * 1024)).toFixed(1);
             const requiredGB = (minBytes / (1024 * 1024 * 1024)).toFixed(1);
@@ -302,4 +335,3 @@ export async function checkDiskSpace(path, minBytes, onLowSpace) {
         return undefined;
     }
 }
-//# sourceMappingURL=fs.js.map

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

@@ -3,6 +3,13 @@
  * @param enabled - Whether to enable verbose output
  */
 export declare function setVerbose(enabled: boolean): void;
+/**
+ * Switches the logger into (or out of) machine-output mode. Commands with
+ * `--json`/`--raw` flags call this before producing any output.
+ */
+export declare function setMachineOutputMode(enabled: boolean): void;
+/** True when machine-output mode is active. */
+export declare function isMachineOutputMode(): boolean;
 /**
  * Displays a verbose/debug message (only shown if verbose mode is enabled).
  * @param message - Message to display