@hominis/fireforge 0.15.6 → 0.15.8

package/dist/src/core/xpcshell-appdir.js

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Auto-injects `--app-path=<abs>` into `mach test` invocations whose nearest
+ * xpcshell.toml sets `firefox-appdir = "browser"` (or `<appname>-appdir = …`)
+ * but whose `appname` is not `firefox`.
+ *
+ * ## Why this exists
+ *
+ * The upstream xpcshell harness computes the manifest key for the appdir
+ * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
+ * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
+ * directive is honoured. On a rebranded fork (appname=`hominis`,
+ * `mybrowser`, …) the harness looks for `hominis-appdir` / `mybrowser-appdir`
+ * — the literal `firefox-appdir` line is silently ignored, `appPath` falls
+ * back to `xrePath`, and every `resource:///modules/…` import throws
+ * `Failed to load resource:///modules/<name>.sys.mjs` because xpcshell now
+ * resolves the `resource:///` prefix one level above the real app root.
+ *
+ * ## Strategy
+ *
+ * 1. For each test path the operator handed us, find the nearest
+ *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
+ *    nothing to inject.
+ * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
+ *    first — if present, the harness already finds it and there's nothing to
+ *    do. Fall back to `firefox-appdir`. This ordering matches upstream
+ *    precedence and avoids overriding an operator who already migrated.
+ * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
+ *    the absolute app dir path against the active `obj-X/dist` tree
+ *    (probing `dist/bin/<value>` first, then any `dist/<bundle>.app/Contents/
+ *    Resources/<value>` for the macOS packaged layout) and return it as
+ *    the value to pass to `--app-path`.
+ * 4. If multiple test paths disagree on the resolved value (e.g. one
+ *    manifest sets `browser`, another sets `xulrunner`), refuse injection
+ *    and return null — the operator can drop down to `--mach-arg`.
+ *
+ * Operator escape hatches: `--mach-arg=--app-path=…` always wins (handled in
+ * test.ts; we skip injection when `--app-path=` already appears in the
+ * forwarded args).
+ */
+import { readdir } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { pathExists, readJson, readText } from '../utils/fs.js';
+import { isObject, isString } from '../utils/validation.js';
+/**
+ * `[DEFAULT]` section parser shaped to the narrow case we need: pull a
+ * single key/value out without depending on a real TOML parser. Avoids
+ * pulling a TOML dep into the test path for a one-shot lookup.
+ *
+ * Accepts:
+ *  - Single- or double-quoted values
+ *  - Whitespace either side of `=`
+ *  - Continuation comments (`#` or `;`) at the end of the line
+ *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`) — some
+ *    operators omit the quotes and the harness honours either form.
+ *
+ * Returns `undefined` when the key is absent or sits outside `[DEFAULT]`.
+ */
+export function parseAppdirFromToml(tomlText, key) {
+    const lines = tomlText.split(/\r?\n/);
+    let inDefault = false;
+    let sectionSeen = false;
+    // Anchored on the start of the line so a `# firefox-appdir = "…"`-style
+    // comment further along the file is not mistaken for the directive.
+    const escapedKey = escapeRegex(key);
+    const keyPattern = new RegExp('^\\s*' + escapedKey + '\\s*=\\s*(.+?)\\s*(?:[#;].*)?$');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        const sectionMatch = /^\s*\[([^\]]+)\]\s*$/.exec(line);
+        if (sectionMatch) {
+            sectionSeen = true;
+            inDefault = sectionMatch[1]?.trim().toUpperCase() === 'DEFAULT';
+            continue;
+        }
+        // The implicit pre-section region of an xpcshell.toml is treated as
+        // [DEFAULT] by the upstream parser, so we honour the same convention.
+        const inImplicitDefault = !sectionSeen;
+        if (!inDefault && !inImplicitDefault)
+            continue;
+        const match = keyPattern.exec(line);
+        if (!match)
+            continue;
+        const raw = (match[1] ?? '').trim();
+        const value = stripQuotes(raw);
+        if (value === undefined)
+            continue;
+        return { value, lineIndex: i };
+    }
+    return undefined;
+}
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function stripQuotes(raw) {
+    if (raw.length === 0)
+        return undefined;
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    // Bareword: must not contain whitespace; otherwise we are looking at
+    // commentary that the regex's optional comment tail did not strip.
+    if (/\s/.test(raw))
+        return undefined;
+    return raw;
+}
+/**
+ * Walks up from `startPath` (a file or directory under `engineDir`) and
+ * returns the absolute path of the first sibling `xpcshell.toml` found.
+ * Stops at `engineDir` (inclusive) and returns null on miss.
+ *
+ * Special-cases `startPath` itself when it already ends with
+ * `xpcshell.toml` — operators sometimes pass a manifest path directly.
+ */
+export async function findNearestXpcshellManifest(engineDir, startPath) {
+    const absStart = resolve(engineDir, startPath);
+    if (absStart.toLowerCase().endsWith(`${sep}xpcshell.toml`)) {
+        return (await pathExists(absStart)) ? absStart : null;
+    }
+    const engineAbs = resolve(engineDir);
+    let current = absStart;
+    // First iteration walks down to a directory; subsequent ones walk up.
+    // Cap iterations defensively — a pathological symlink loop would
+    // otherwise spin until the call stack overflows.
+    for (let i = 0; i < 64; i += 1) {
+        const dir = i === 0 ? dirname(absStart) : dirname(current);
+        const candidate = join(dir, 'xpcshell.toml');
+        if (await pathExists(candidate))
+            return candidate;
+        if (dir === engineAbs || dir === dirname(dir))
+            return null;
+        current = dir;
+    }
+    return null;
+}
+/**
+ * Reads `<objDir>/mozinfo.json` for the active app name. Returns
+ * `"firefox"` when mozinfo cannot be read or the field is missing — that
+ * is the safe default because it matches stock Firefox behaviour and
+ * means the resolver will not inject anything (the manifest's
+ * `firefox-appdir` value WILL be honoured by the upstream harness when
+ * appname is firefox).
+ */
+export async function readMozinfoAppname(objDirPath) {
+    const mozinfoPath = join(objDirPath, 'mozinfo.json');
+    if (!(await pathExists(mozinfoPath)))
+        return 'firefox';
+    try {
+        const data = await readJson(mozinfoPath);
+        if (isObject(data) && isString(data['appname'])) {
+            return data['appname'];
+        }
+    }
+    catch {
+        // Malformed mozinfo is a build-system problem out of scope for the
+        // appdir resolver; treat as if appname were missing.
+    }
+    return 'firefox';
+}
+/**
+ * Probes the obj-dir's `dist/` subtree for the absolute path that the
+ * harness would have computed if the manifest key had been honoured.
+ * Returns null when no candidate exists — better to skip injection
+ * silently than to point the harness at a path that doesn't exist
+ * (which fails with a different error than the original `firefox-appdir`
+ * symptom and confuses triage).
+ *
+ * Probe order matches the on-disk layouts FireForge supports today:
+ *  1. `<objDir>/dist/bin/<value>` — Linux primary, also macOS via the
+ *     `dist/bin -> dist/<App>.app/Contents/MacOS/` symlink.
+ *  2. `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` — macOS
+ *     packaged layout, where `dist/bin/` may not exist as a directory.
+ */
+export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
+    const distBinCandidate = join(objDirAbs, 'dist', 'bin', relativeAppdir);
+    if (await pathExists(distBinCandidate))
+        return distBinCandidate;
+    const distDir = join(objDirAbs, 'dist');
+    if (!(await pathExists(distDir)))
+        return null;
+    let entries;
+    try {
+        entries = await readdir(distDir);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith('.app'))
+            continue;
+        const candidate = join(distDir, entry, 'Contents', 'Resources', relativeAppdir);
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Top-level resolver. Walks every test path, reads the nearest
+ * xpcshell.toml, and returns the single absolute path to inject (or a
+ * structured "no injection" outcome). Never throws — every fs / parse
+ * error is folded into a `none` outcome so the test command always falls
+ * through to the diagnostic hint instead of dying inside a helper.
+ */
+export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName) {
+    if (testPaths.length === 0)
+        return { kind: 'none' };
+    const objDirAbs = resolve(engineDir, objDirName);
+    const appname = await readMozinfoAppname(objDirAbs);
+    // When appname IS "firefox" the upstream harness reads `firefox-appdir`
+    // natively. Injecting in that case would be a no-op at best and an
+    // override at worst, so bail out before doing any IO per-path.
+    if (appname === 'firefox')
+        return { kind: 'none' };
+    const appnameKey = `${appname}-appdir`;
+    const seenInjections = new Map();
+    for (const testPath of testPaths) {
+        const manifestPath = await findNearestXpcshellManifest(engineDir, testPath);
+        if (!manifestPath)
+            continue;
+        let body;
+        try {
+            body = await readText(manifestPath);
+        }
+        catch {
+            continue;
+        }
+        // Operator already migrated — harness will read the appname-keyed
+        // value directly. Nothing to do.
+        if (parseAppdirFromToml(body, appnameKey) !== undefined)
+            continue;
+        const fallback = parseAppdirFromToml(body, 'firefox-appdir');
+        if (fallback === undefined)
+            continue;
+        const absolute = await resolveAbsoluteAppPath(objDirAbs, fallback.value);
+        if (!absolute) {
+            return {
+                kind: 'unresolved',
+                relativeAppdir: fallback.value,
+                manifestPath,
+            };
+        }
+        seenInjections.set(absolute, {
+            appPath: absolute,
+            manifestPath,
+            key: 'firefox-appdir',
+            relativeAppdir: fallback.value,
+        });
+    }
+    if (seenInjections.size === 0)
+        return { kind: 'none' };
+    if (seenInjections.size > 1) {
+        return { kind: 'mismatch', values: Array.from(seenInjections.keys()) };
+    }
+    const [result] = seenInjections.values();
+    // Map.size === 1 was just checked, so result is defined.
+    return { kind: 'injected', result: result };
+}
+/**
+ * Returns true when the operator already passed `--app-path=` (or its
+ * `--app-path <value>` two-token form) through `--mach-arg`. Used by the
+ * test command to skip auto-injection so the operator override always
+ * wins.
+ */
+export function operatorAlreadySetAppPath(extraArgs) {
+    for (let i = 0; i < extraArgs.length; i += 1) {
+        const arg = extraArgs[i] ?? '';
+        if (arg === '--app-path' && i + 1 < extraArgs.length)
+            return true;
+        if (arg.startsWith('--app-path='))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=xpcshell-appdir.js.map

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

@@ -25,5 +25,18 @@ export declare const ExitCode: {
     readonly FURNACE_ERROR: 9;
     /** Patch conflict resolution error */
     readonly RESOLUTION_ERROR: 10;
+    /**
+     * `fireforge run --smoke-exit` observed one or more unallowed console
+     * error lines inside the smoke window. Distinct from BUILD_ERROR so CI
+     * can route smoke regressions separately from compile/config failures.
+     */
+    readonly SMOKE_EXIT_FAILURE: 12;
+    /**
+     * `fireforge run --smoke-exit` saw the browser exit with a non-clean
+     * status before the smoke window elapsed — a launch-side failure that
+     * did NOT surface as a console error line (crash before console wiring,
+     * missing profile, etc.).
+     */
+    readonly SMOKE_LAUNCH_FAILURE: 13;
 };
 export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode];

package/dist/src/errors/codes.js

@@ -26,5 +26,18 @@ export const ExitCode = {
     FURNACE_ERROR: 9,
     /** Patch conflict resolution error */
     RESOLUTION_ERROR: 10,
+    /**
+     * `fireforge run --smoke-exit` observed one or more unallowed console
+     * error lines inside the smoke window. Distinct from BUILD_ERROR so CI
+     * can route smoke regressions separately from compile/config failures.
+     */
+    SMOKE_EXIT_FAILURE: 12,
+    /**
+     * `fireforge run --smoke-exit` saw the browser exit with a non-clean
+     * status before the smoke window elapsed — a launch-side failure that
+     * did NOT surface as a console error line (crash before console wiring,
+     * missing profile, etc.).
+     */
+    SMOKE_LAUNCH_FAILURE: 13,
 };
 //# sourceMappingURL=codes.js.map

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

@@ -0,0 +1,16 @@
+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
+ * configured allowlist.
+ *
+ * Distinct from `BuildError` so CI pipelines can route smoke failures
+ * differently from build failures and so the exit code is the smoke-run
+ * contract's `SMOKE_EXIT_FAILURE` rather than the generic `BUILD_ERROR`.
+ */
+export declare class SmokeRunError extends FireForgeError {
+    readonly code: ExitCode;
+    constructor(message: string, exitCode: ExitCode, cause?: Error);
+    get userMessage(): string;
+}

package/dist/src/errors/run.js

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { FireForgeError } from './base.js';
+/**
+ * Error raised by `fireforge run --smoke-exit` when the captured console
+ * stream produced one or more error lines that did NOT match the
+ * configured allowlist.
+ *
+ * Distinct from `BuildError` so CI pipelines can route smoke failures
+ * differently from build failures and so the exit code is the smoke-run
+ * contract's `SMOKE_EXIT_FAILURE` rather than the generic `BUILD_ERROR`.
+ */
+export class SmokeRunError extends FireForgeError {
+    code;
+    constructor(message, exitCode, cause) {
+        super(message, cause);
+        this.code = exitCode;
+    }
+    get userMessage() {
+        return `Smoke run failed: ${this.message}`;
+    }
+}
+//# sourceMappingURL=run.js.map

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

@@ -41,6 +41,14 @@ export interface BuildOptions {
     jobs?: number;
     /** Brand to build (stable, esr, etc.) */
     brand?: string;
+    /**
+     * When a mozinfo mismatch is detected that looks like a safe path
+     * relocation (same structure, different prefix), patch mozinfo paths
+     * in place and run `mach configure` rather than aborting with a
+     * full-rebuild instruction. Falls back to the original abort message
+     * for any mismatch the rewriter cannot prove safe.
+     */
+    rewriteMozinfo?: boolean;
 }
 /**
  * Options for the export command.
@@ -169,6 +177,39 @@ export interface RebaseOptions {
 export interface RunOptions {
     /** Additional arguments to pass to the browser */
     args?: string[];
+    /**
+     * Enable smoke-run mode. Launches the browser, streams the console,
+     * sends SIGTERM to the whole process group after `smokeExit` seconds,
+     * and applies the smoke exit contract:
+     *  - `0` — clean window (no unallowed error lines).
+     *  - `ExitCode.SMOKE_EXIT_FAILURE` (12) — one or more console lines
+     *    matched the error heuristic and were not covered by the allowlist.
+     *  - `ExitCode.SMOKE_LAUNCH_FAILURE` (13) — the browser exited with a
+     *    non-clean status before the smoke window elapsed (launch-side
+     *    failure we cannot observe as a console line — crash before console
+     *    wiring, missing profile, etc.).
+     *
+     * POSIX only (process-group semantics do not map cleanly onto Windows);
+     * `runSmokeExit` rejects the flag up front on `win32`.
+     */
+    smokeExit?: number;
+    /**
+     * Repeatable regex patterns that mark a matching console line as
+     * benign. Matches are still counted for the summary but do not drive
+     * the smoke-run exit code.
+     */
+    consoleAllow?: string[];
+    /**
+     * Path to a newline-delimited allowlist regex file. Blank lines and
+     * `#` comments are ignored; each remaining line is compiled as a
+     * regex and appended to the active allowlist.
+     */
+    consoleAllowFile?: string;
+    /**
+     * Mirror the captured console output to this file path so agents can
+     * inspect the raw stream after smoke-exit returns.
+     */
+    captureConsole?: string;
 }
 /**
  * Options for the test command.
@@ -184,6 +225,13 @@ export interface TestOptions {
      * spawned. When no paths are supplied, runs the preflight only and exits.
      */
     doctor?: boolean;
+    /**
+     * Extra arguments forwarded verbatim to `mach test` (repeatable). Escape
+     * valve for upstream xpcshell/mochitest flags that FireForge does not
+     * model directly. Order relative to other flags is preserved; passthrough
+     * values appear after `--headless` if both are set.
+     */
+    machArg?: string[];
 }
 /**
  * Options for the furnace apply command.
@@ -298,6 +346,22 @@ export interface FurnaceCreateOptions {
     testStyle?: 'mochikit' | 'browser-chrome' | 'xpcshell';
     /** Stock component tag names composed internally by this component */
     compose?: string[];
+    /**
+     * Participate in a pre-existing feature-scoped Fluent bundle at this
+     * path (as used by `insertFTLIfNeeded`, e.g. `browser/hominis-dock.ftl`)
+     * instead of scaffolding a per-component `.ftl`. Implies `localized`.
+     * Persists onto the furnace.json entry so validation and apply skip the
+     * per-component paths.
+     */
+    sharedFtl?: string;
+    /**
+     * Show the planned file set and furnace.json changes without writing
+     * anything. All validation that does not require disk writes (tag name
+     * shape, name conflicts, engine pre-existence, `--compose` targets, cycle
+     * detection, prefix warning) runs before the plan is emitted, so a
+     * dry-run faithfully previews the real command's outcome.
+     */
+    dryRun?: boolean;
 }
 /**
  * Options for the wire command.

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

@@ -50,6 +50,45 @@ export interface CustomComponentConfig {
     localized: boolean;
     /** Stock component tag names composed internally by this component */
     composes?: string[];
+    /**
+     * Opts the component out of the `no-keyboard-handler` accessibility check
+     * when it wraps a native-interactive inner element that is not tracked in
+     * `composes` (for example a hand-authored `<button>` or a non-stock
+     * `moz-*` widget). When `true`, the check is skipped even if the template
+     * appears to attach `@click` to synthetic markup.
+     *
+     * Leave unset for the default behavior: the validator still silences the
+     * check automatically when any entry in `composes` matches its native-
+     * interactive allowlist (e.g. `moz-button`, `moz-toggle`). This flag is
+     * only needed when `composes` does not capture the inner element.
+     *
+     * Operator-asserted: setting this to `true` does not re-check the
+     * component, so it can be used to silence genuine findings. Prefer adding
+     * the wrapped element to `composes` when that field applies.
+     */
+    keyboardCovered?: boolean;
+    /**
+     * Path of a pre-existing feature-scoped Fluent bundle this component
+     * participates in, in the same form used by `insertFTLIfNeeded` (for
+     * example `browser/hominis-dock.ftl`). When set:
+     *
+     *   - `furnace create --localized` does NOT scaffold a per-component
+     *     `.ftl` stub — the component shares the feature bundle.
+     *   - The generated `.mjs` calls `insertFTLIfNeeded("<sharedFtl>")` at
+     *     the shared path instead of the per-component one.
+     *   - `furnace validate`'s `missing-ftl` structural rule is skipped for
+     *     the component (there is no `<tag>.ftl` to require).
+     *   - `furnace apply` does NOT copy a per-component `.ftl` into the FTL
+     *     tree nor register a new entry in the locale `jar.mn` — the shared
+     *     file is owned by whoever authored the feature bundle.
+     *
+     * Requires `localized: true`. Mutually exclusive with the per-component
+     * `.ftl` scaffold. Does NOT auto-migrate previous per-component FTL
+     * state: flipping an existing component onto `sharedFtl` leaves the
+     * prior per-component entry in the engine tree and the locale `jar.mn`
+     * until explicitly cleaned up.
+     */
+    sharedFtl?: string;
 }
 /**
  * The furnace.json schema.

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

@@ -79,6 +79,69 @@ export declare function execInherit(command: string, args: string[], options?: E
 export declare function execInheritCapture(command: string, args: string[], options?: ExecOptions & {
     shutdownGraceMs?: number;
 }): Promise<ExecResult>;
+/** Per-line callback for smoke-run stream dispatch. */
+export type SmokeLineCallback = (line: string) => void;
+/** Options for {@link execSmokeRun}. */
+export interface SmokeRunOptions extends ExecOptions {
+    /**
+     * Hard deadline in milliseconds. When it elapses the child process
+     * group is sent SIGTERM and, after `killGraceMs`, SIGKILL. The returned
+     * {@link SmokeRunResult.timedOut} is `true` when the deadline fires —
+     * callers treat that as a clean smoke window (no child-driven error),
+     * not a failure.
+     */
+    smokeTimeoutMs: number;
+    /**
+     * Grace period between SIGTERM and SIGKILL when the deadline fires.
+     * Defaults to 10000 ms because Firefox's AsyncShutdown and
+     * profileBeforeChange blockers can take ~5–10 s to flush in-memory
+     * state. A shorter grace risks corrupting the dev profile mid-quit.
+     */
+    killGraceMs?: number;
+    /** Invoked once per complete line of stdout. Final partial line is flushed on close. */
+    onStdoutLine?: SmokeLineCallback;
+    /** Invoked once per complete line of stderr. Final partial line is flushed on close. */
+    onStderrLine?: SmokeLineCallback;
+    /**
+     * Optional writable stream to mirror captured output to (e.g. an
+     * operator-supplied `--capture-console` file). Writes happen inline
+     * with line dispatch and the stream is NOT closed here — the caller
+     * owns its lifecycle.
+     */
+    mirror?: {
+        stdout?: NodeJS.WritableStream;
+        stderr?: NodeJS.WritableStream;
+    };
+}
+/** Result of {@link execSmokeRun}. */
+export interface SmokeRunResult extends ExecResult {
+    /**
+     * `true` when the smoke deadline fired and we SIGTERMed the child
+     * ourselves. Callers that want to distinguish "smoke window elapsed
+     * cleanly" from "child exited on its own" check this flag — the
+     * `exitCode` in the timedOut path is almost always 143 (SIGTERM) and
+     * should NOT be treated as a child-driven failure.
+     */
+    timedOut: boolean;
+}
+/**
+ * Spawns `command` with `args` in its own process group (POSIX), streams
+ * stdout/stderr line-by-line to the caller, enforces a deadline by
+ * SIGTERMing the whole group when it elapses, and returns the captured
+ * output alongside a `timedOut` flag.
+ *
+ * Process-group semantics matter here because `mach run` execs a Python
+ * wrapper that then forks Firefox, which itself spawns content processes.
+ * Sending SIGTERM only to the Python PID leaves an orphan Firefox tree
+ * behind. Running the child as a process-group leader (`detached: true`
+ * on POSIX) and signalling `-pid` routes the kill to every descendant
+ * that inherited the group.
+ *
+ * Windows fallback: `detached: true` does not create an equivalent group
+ * there, so we degrade to `child.kill()` and log a best-effort warning
+ * via the `onStderrLine` callback if the caller wired one.
+ */
+export declare function execSmokeRun(command: string, args: string[], options: SmokeRunOptions): Promise<SmokeRunResult>;
 /**
  * Finds an executable in the system PATH.
  * @param name - Name of the executable