@hominis/fireforge 0.35.0 → 0.36.0

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[];
@@ -405,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
@@ -428,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

package/dist/src/utils/logger.js

@@ -3,6 +3,19 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 /** Whether verbose mode is enabled */
 let verboseMode = false;
+/**
+ * Whether machine-output mode is active (`--json` / `--raw`).
+ *
+ * In machine mode, stdout belongs EXCLUSIVELY to the machine-readable
+ * payload: all human-facing diagnostics (intro/outro banners, info, warn,
+ * error, steps, notes) are routed to stderr as plain unstyled lines.
+ * Before this mode existed, clack's log helpers wrote styled warnings to
+ * stdout *before* the JSON body — a truncated-directory warning during
+ * `status --json` broke every `JSON.parse(stdout)` consumer, and error
+ * objects on the machine contract were followed by a styled duplicate on
+ * the same stream.
+ */
+let machineOutputMode = false;
 /**
  * Enables or disables verbose mode.
  * @param enabled - Whether to enable verbose output
@@ -10,6 +23,21 @@ let verboseMode = false;
 export function setVerbose(enabled) {
     verboseMode = enabled;
 }
+/**
+ * Switches the logger into (or out of) machine-output mode. Commands with
+ * `--json`/`--raw` flags call this before producing any output.
+ */
+export function setMachineOutputMode(enabled) {
+    machineOutputMode = enabled;
+}
+/** True when machine-output mode is active. */
+export function isMachineOutputMode() {
+    return machineOutputMode;
+}
+/** Writes a plain diagnostic line to stderr (machine-mode side channel). */
+function writeDiagnostic(prefix, message) {
+    process.stderr.write(`${prefix}${message}\n`);
+}
 /**
  * Checks if verbose mode is enabled.
  * @returns True if verbose mode is enabled
@@ -22,43 +50,75 @@ function isVerbose() {
  * @param message - Message to display
  */
 export function verbose(message) {
-    if (isVerbose()) {
-        p.log.info(`[debug] ${message}`);
+    if (!isVerbose())
+        return;
+    if (machineOutputMode) {
+        writeDiagnostic('[debug] ', message);
+        return;
     }
+    p.log.info(`[debug] ${message}`);
 }
 function supportsInteractiveSpinner() {
     return process.stdout.isTTY && process.stderr.isTTY;
 }
 /** Displays the top-level intro banner for a command. */
 export function intro(message) {
+    if (machineOutputMode)
+        return;
     p.intro(message);
 }
 /** Displays the closing outro banner for a command. */
 export function outro(message) {
+    if (machineOutputMode)
+        return;
     p.outro(message);
 }
 /** Logs an informational message. */
 export function info(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.info(message);
 }
 /** Logs a success message. */
 export function success(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.success(message);
 }
 /** Logs a warning message. */
 export function warn(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('warning: ', message);
+        return;
+    }
     p.log.warn(message);
 }
 /** Logs an error message. */
 export function error(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('error: ', message);
+        return;
+    }
     p.log.error(message);
 }
 /** Logs an in-progress step message. */
 export function step(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.step(message);
 }
 /** Logs a plain message without a status prefix. */
 export function message(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('', message);
+        return;
+    }
     p.log.message(message);
 }
 /** Formats text using the success color without logging it. */
@@ -75,6 +135,21 @@ export function formatErrorText(message) {
  * @returns Spinner handle with message(), stop(), and error() methods
  */
 export function spinner(initialMessage) {
+    if (machineOutputMode) {
+        // Spinner progress is diagnostics; keep stdout clean for the payload.
+        return {
+            message: (msg) => {
+                writeDiagnostic('', msg);
+            },
+            stop: (msg) => {
+                if (msg)
+                    writeDiagnostic('', msg);
+            },
+            error: (msg) => {
+                writeDiagnostic('error: ', msg ?? 'Failed');
+            },
+        };
+    }
     if (!supportsInteractiveSpinner()) {
         let latestMessage = initialMessage;
         return {
@@ -107,6 +182,10 @@ export function spinner(initialMessage) {
 }
 /** Emits a cancellation message. */
 export function cancel(message) {
+    if (machineOutputMode) {
+        writeDiagnostic('cancelled: ', message);
+        return;
+    }
     p.cancel(message);
 }
 /** Checks whether a prompt result represents a user cancellation. */
@@ -115,6 +194,9 @@ export function isCancel(value) {
 }
 /** Displays a titled note block for follow-up details. */
 export function note(message, title) {
+    if (machineOutputMode) {
+        writeDiagnostic('', title ? `${title}: ${message}` : message);
+        return;
+    }
     p.note(message, title);
 }
-//# sourceMappingURL=logger.js.map

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

@@ -6,3 +6,18 @@
 export declare function pickDefined<T extends Record<string, unknown>>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
+/**
+ * Wraps an option-argument parser so its failures surface through
+ * commander's own invalid-argument channel.
+ *
+ * Commander only treats errors whose `code` is `'commander.invalidArgument'`
+ * as argument-validation failures; anything else re-throws out of
+ * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
+ * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
+ * That was the observed behavior for `run --smoke-exit abc` (plain Error),
+ * `test --harness-retries 99` (GeneralError), and `export --order 0`
+ * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
+ * Every `.argParser()`/option-parser callback must be wrapped with this
+ * helper (or throw commander's InvalidArgumentError directly).
+ */
+export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw: string) => T;

package/dist/src/utils/options.js

@@ -13,4 +13,28 @@ export function pickDefined(obj) {
     }
     return result;
 }
-//# sourceMappingURL=options.js.map
+import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
+/**
+ * Wraps an option-argument parser so its failures surface through
+ * commander's own invalid-argument channel.
+ *
+ * Commander only treats errors whose `code` is `'commander.invalidArgument'`
+ * as argument-validation failures; anything else re-throws out of
+ * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
+ * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
+ * That was the observed behavior for `run --smoke-exit abc` (plain Error),
+ * `test --harness-retries 99` (GeneralError), and `export --order 0`
+ * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
+ * Every `.argParser()`/option-parser callback must be wrapped with this
+ * helper (or throw commander's InvalidArgumentError directly).
+ */
+export function commanderArgParser(parse) {
+    return (raw) => {
+        try {
+            return parse(raw);
+        }
+        catch (error) {
+            throw new CommanderInvalidArgumentError(error instanceof Error ? error.message : String(error));
+        }
+    };
+}

package/dist/src/utils/package-root.js

@@ -34,8 +34,8 @@ export function getPackageRoot() {
     }
     let current = dirname(fileURLToPath(import.meta.url));
     for (;;) {
+        const packagePath = join(current, 'package.json');
         try {
-            const packagePath = join(current, 'package.json');
             const pkg = readPackageMetadata(packagePath);
             if (isFireForgePackageMetadata(pkg)) {
                 cachedPackageRoot = current;
@@ -43,8 +43,16 @@ export function getPackageRoot() {
             }
         }
         catch (error) {
-            void error;
-            // no package.json here — keep walking
+            // Absent package.json: keep walking. A package.json that EXISTS but
+            // fails to parse is a different animal — walking past it could bind
+            // to a wrong ancestor package (any parent exposing bin.fireforge) or
+            // end in the unhelpful generic "could not locate" error, hiding the
+            // actual syntax problem.
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw new Error(`Found ${packagePath} but could not parse it: ` +
+                    (error instanceof Error ? error.message : String(error)), { cause: error });
+            }
         }
         const parent = dirname(current);
         if (parent === current) {
@@ -66,4 +74,3 @@ export function getPackageVersion() {
     const packageRoot = getPackageRoot();
     return readPackageMetadata(join(packageRoot, 'package.json')).version;
 }
-//# sourceMappingURL=package-root.js.map

package/dist/src/utils/parse.js

@@ -212,4 +212,3 @@ export function parseObject(data, label) {
     }
     return new ParsedRecord(data, label);
 }
-//# sourceMappingURL=parse.js.map

package/dist/src/utils/paths.js

@@ -75,4 +75,3 @@ export function toRootRelativePath(root, candidate) {
     }
     return normalizePathSlashes(relative(resolvedRoot, resolvedCandidate));
 }
-//# sourceMappingURL=paths.js.map

package/dist/src/utils/platform.js

@@ -53,4 +53,3 @@ export function isWindows() {
 export function getExecutableExtension() {
     return isWindows() ? '.exe' : '';
 }
-//# sourceMappingURL=platform.js.map