@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,299 +0,0 @@
-// 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=`mybrowser`) the
- * harness looks for `mybrowser-appdir`, so 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 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
- *    there is nothing to inject.
- * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
- *    first. If present, the harness already finds it. 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, refuse injection
- *    and return null. The operator can drop down to `--mach-arg`.
- *
- * Operator escape hatch: `--mach-arg=--app-path=…` always wins (handled in
- * test.ts, which skips injection when `--app-path=` already appears in the
- * forwarded args).
- */
-import { readdir, stat } from 'node:fs/promises';
-import { dirname, join, resolve, sep } from 'node:path';
-import { pathExists, readJson, readText } from '../utils/fs.js';
-import { escapeRegex } from '../utils/regex.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 (const [i, line] of lines.entries()) {
-        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 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`, since operators sometimes pass a manifest path directly.
- *
- * When `startPath` is a directory, the walk starts at the directory itself
- * (checking `<dir>/xpcshell.toml` first) rather than at its parent.
- * Starting at the parent misses a directory's own manifest, so
- * `fireforge test <dir>` classifies it non-xpcshell and dispatches to the
- * mochitest runner, which finds no mochitests.
- */
-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 startIsDirectory = await stat(absStart).then((stats) => stats.isDirectory(), () => false);
-    const engineAbs = resolve(engineDir);
-    let current = absStart;
-    // First iteration resolves the starting directory (the path itself for a
-    // directory argument, its parent for a file). 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 ? (startIsDirectory ? absStart : 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 is 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 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 does not exist, which fails with a different
- * error than the original symptom and confuses triage.
- *
- * Probe order differs by host platform:
- *
- * - macOS (`darwin`): prefer
- *   `<objDir>/dist/<App>.app/Contents/Resources/<value>` first, then fall
- *   back to `<objDir>/dist/bin/<value>`. On macOS `dist/bin` is symlinked to
- *   `dist/<App>.app/Contents/MacOS/` (the binaries directory), so
- *   `dist/bin/browser` resolves to `<App>.app/Contents/MacOS/browser/`,
- *   which is not where `resource:///modules/` is rooted. Injecting that path
- *   looks successful in the log but points at a directory with no modules
- *   tree, so every `resource:///modules/…` import still throws.
- * - non-macOS: `dist/bin/<value>` first,
- *   `.app/Contents/Resources/<value>` as fallback.
- *
- * On both platforms the final `.app` fallback iterates every `*.app` entry
- * because a rebranded fork may pick an arbitrary app name.
- */
-export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
-    const distBinCandidate = join(objDirAbs, 'dist', 'bin', relativeAppdir);
-    const distDir = join(objDirAbs, 'dist');
-    const isMacos = process.platform === 'darwin';
-    async function probeMacAppBundle() {
-        if (!(await pathExists(distDir)))
-            return null;
-        let entries;
-        try {
-            entries = await readdir(distDir);
-        }
-        catch {
-            // No readable dist directory means no appdir candidate can be resolved.
-            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;
-    }
-    if (isMacos) {
-        const appBundle = await probeMacAppBundle();
-        if (appBundle)
-            return appBundle;
-        if (await pathExists(distBinCandidate))
-            return distBinCandidate;
-        return null;
-    }
-    if (await pathExists(distBinCandidate))
-        return distBinCandidate;
-    return probeMacAppBundle();
-}
-/**
- * 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 {
-            // An unreadable manifest cannot declare an appdir. Skip it and keep
-            // walking the remaining candidates.
-            continue;
-        }
-        // Operator already migrated. The 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 (const [i, arg] of extraArgs.entries()) {
-        if (arg === '--app-path' && i + 1 < extraArgs.length)
-            return true;
-        if (arg.startsWith('--app-path='))
-            return true;
-    }
-    return false;
-}

package/dist/src/core/xpcshell-profile-dir.d.ts

@@ -1,12 +0,0 @@
-export declare const XPCSHELL_PROFILE_ENV_VAR = "XPCSHELL_TEST_PROFILE_DIR";
-/**
- * Runs `fn` with a fresh per-invocation xpcshell profile directory
- * injected into the environment, removing the directory afterwards
- * (best-effort: a failure to clean up warns and leaves the mkdtemp dir
- * for the OS tmp reaper, and the harness may still hold files briefly).
- *
- * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
- * process environment) is respected verbatim: no directory is minted and
- * nothing is deleted, because we never remove a directory we did not create.
- */
-export declare function withXpcshellProfileDir<T>(baseEnv: Record<string, string> | undefined, fn: (env: Record<string, string>) => Promise<T>): Promise<T>;

package/dist/src/core/xpcshell-profile-dir.js

@@ -1,45 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Per-invocation xpcshell profile directory.
- *
- * Firefox's xpcshell harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a
- * fixed path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping
- * harness invocations (concurrent `fireforge test` processes, or future
- * verification-tree shards) corrupt each other's profiles. FireForge
- * never set the variable. This helper mints a fresh `mkdtemp` directory
- * per harness invocation and exports it through the mach env channel.
- */
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { warn } from '../utils/logger.js';
-export const XPCSHELL_PROFILE_ENV_VAR = 'XPCSHELL_TEST_PROFILE_DIR';
-/**
- * Runs `fn` with a fresh per-invocation xpcshell profile directory
- * injected into the environment, removing the directory afterwards
- * (best-effort: a failure to clean up warns and leaves the mkdtemp dir
- * for the OS tmp reaper, and the harness may still hold files briefly).
- *
- * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
- * process environment) is respected verbatim: no directory is minted and
- * nothing is deleted, because we never remove a directory we did not create.
- */
-export async function withXpcshellProfileDir(baseEnv, fn) {
-    const operatorProvided = baseEnv?.[XPCSHELL_PROFILE_ENV_VAR] ?? process.env[XPCSHELL_PROFILE_ENV_VAR];
-    if (operatorProvided !== undefined && operatorProvided !== '') {
-        return fn({ ...baseEnv, [XPCSHELL_PROFILE_ENV_VAR]: operatorProvided });
-    }
-    const profileDir = await mkdtemp(join(tmpdir(), 'fireforge-xpcshell-profile-'));
-    try {
-        return await fn({ ...baseEnv, [XPCSHELL_PROFILE_ENV_VAR]: profileDir });
-    }
-    finally {
-        try {
-            await rm(profileDir, { recursive: true, force: true });
-        }
-        catch (error) {
-            warn(`Could not clean up xpcshell profile dir ${profileDir}: ${toError(error).message}`);
-        }
-    }
-}

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

@@ -1,217 +0,0 @@
-import { ExitCode } from './codes.js';
-/**
- * Base error class for all FireForge errors.
- * Provides structured error information with exit codes and user-friendly messages.
- */
-export declare abstract class FireForgeError extends Error {
-    /** Exit code to use when this error causes process termination */
-    abstract readonly code: ExitCode;
-    /**
-     * Creates a new FireForgeError.
-     * @param message - Technical error message for logging
-     * @param cause - The underlying error that caused this error
-     */
-    readonly cause?: unknown;
-    constructor(message: string, cause?: unknown);
-    /**
-     * User-friendly error message with context and suggested fixes.
-     * Override in subclasses to provide specific guidance.
-     */
-    get userMessage(): string;
-}
-/**
- * Renders the trailing "To fix this:" block shared by every FireForge error
- * that offers remedies.
- *
- * Numbering is derived from the array rather than written into each string.
- * Several classes vary their advice by context (`FurnaceError` drops the
- * validate step, `ChecksumMismatchError` adds a Developer Edition note), and
- * hand-numbered branches had to renumber every later step by hand, one
- * conditional away from printing "2." twice.
- *
- * @param steps - The remedy lines, in order, without their numbers
- * @returns The block, starting with the blank-line separator
- */
-export declare function remedies(steps: readonly string[]): string;
-/**
- * General error for unexpected failures.
- */
-export declare class GeneralError extends FireForgeError {
-    readonly code: 1;
-}
-/**
- * A `fireforge test` preflight gate that refused before any harness ran.
- *
- * Exists to carry a `note`, not to change behaviour: it keeps
- * {@link ExitCode.GENERAL_ERROR}, so `docs/exit-codes.md` and every CI
- * consumer keying on the exit status are untouched. The note is a stable
- * kebab-case refusal class that the `FIREFORGE-VERDICT:` line reports as an
- * additive `note=` key. Without it every preflight refusal reached an
- * unattended reader as the single token `reason=preflight`, which covers
- * everything from a missing build to a peer's packaging record, so the one
- * line that survives a truncating pipe could not say which gate fired.
- */
-export declare class PreflightRefusalError extends GeneralError {
-    /** Stable refusal class, e.g. `stale-browser`. */
-    readonly note: string;
-    constructor(message: string, 
-    /** Stable refusal class, e.g. `stale-browser`. */
-    note: string);
-}
-/**
- * Raised when one of FireForge's own internal invariants did not hold:
- * the failure of a runtime assertion from `src/utils/assert.ts`.
- *
- * Dedicated subclass (rather than raw GeneralError) because an invariant
- * failure is categorically different from every other error the CLI
- * raises: it is a bug in FireForge, not something the operator did or can
- * fix. That difference is worth carrying all the way to the exit status
- * (see {@link ExitCode.INTERNAL_ERROR}) so a CI job can escalate it
- * instead of retrying it, and it is the one error class the CLI boundary
- * prints a stack trace for, since the stack is the report.
- *
- * Assertions exist so that a violated invariant stops the run at the
- * first inconsistency instead of continuing to write. In the mutating
- * paths that means the surrounding rollback journal restores the engine
- * before this reaches the operator. See `docs/lifecycle-invariants.md`.
- */
-export declare class InternalInvariantError extends FireForgeError {
-    readonly code: 11;
-    get userMessage(): string;
-}
-/**
- * Raised when a regex/brace-depth fallback parser decides it
- * cannot safely perform its mutation, e.g. because a block it expected
- * to walk never closes, because the inserted result fails a round-trip
- * brace balance check, or because an expected pattern is missing.
- *
- * Dedicated subclass (rather than raw GeneralError) so callers and tests
- * can distinguish "the fallback refused to corrupt this file" from other
- * failure modes, and so {@link withParserFallback} callers can opt into
- * re-throwing fallback refusals instead of silently swallowing them.
- */
-export declare class ParserFallbackError extends FireForgeError {
-    /** Filename or logical context where the fallback ran (e.g. `browser-init.js`). */
-    readonly context?: string | undefined;
-    readonly code: 1;
-    constructor(message: string, 
-    /** Filename or logical context where the fallback ran (e.g. `browser-init.js`). */
-    context?: string | undefined, cause?: unknown);
-    get userMessage(): string;
-}
-/**
- * Error thrown when a command-line argument is invalid.
- */
-export declare class InvalidArgumentError extends FireForgeError {
-    readonly argument?: string | undefined;
-    readonly code: 8;
-    constructor(message: string, argument?: string | undefined, cause?: Error);
-    get userMessage(): string;
-}
-/**
- * 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`, which
- * carries no command name, no elapsed time, and no hint that a timeout
- * (rather than 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]). */
-    readonly command: string;
-    /** Arguments the executable was spawned with. */
-    readonly args: readonly string[];
-    /** Timeout that elapsed, in milliseconds. */
-    readonly timeoutMs: number;
-    readonly code: 1;
-    /** Standard output captured before the deadline fired (empty when the exec path does not capture). */
-    readonly stdout: string;
-    /** Standard error captured before the deadline fired (empty when the exec path does not capture). */
-    readonly stderr: string;
-    /** True when either captured stream was cut off at the exec layer's collector cap. */
-    readonly outputTruncated: boolean;
-    constructor(
-    /** Executable that was spawned (argv[0]). */
-    command: string, 
-    /** Arguments the executable was spawned with. */
-    args: readonly string[], 
-    /** Timeout that elapsed, in milliseconds. */
-    timeoutMs: number, cause?: unknown, output?: ExecTimeoutOutput);
-    get userMessage(): string;
-    /**
-     * The last few lines the command printed before it was killed, so an
-     * operator can see what it was doing (a `git add -A` stuck on one path,
-     * a build step that hung) instead of a bare budget number. It prefers
-     * stderr and falls back to stdout when stderr is silent.
-     */
-    private outputTailForUser;
-}
-/** Output captured before an exec timeout fired. See {@link ExecTimeoutError}. */
-export interface ExecTimeoutOutput {
-    stdout: string;
-    stderr: string;
-    truncated: boolean;
-}
-/**
- * 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. 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, because the fact is the same whichever lock was contended.
- */
-export declare class LockContentionError extends FireForgeError {
-    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 interrupts an interactive prompt: Esc or
- * Ctrl+C, i.e. `isCancel(...)`.
- *
- * Not for a prompt the operator 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: 130;
-    constructor();
-}
-/**
- * Error thrown when patch resolution fails.
- */
-export declare class ResolutionError extends FireForgeError {
-    readonly code: 10;
-}
-/**
- * Sentinel error used to propagate an exit code to the CLI entrypoint
- * without calling process.exit() from shared library code.
- *
- * The user-visible error message has already been logged by the time this
- * is thrown. The entrypoint only needs to read `.exitCode` and terminate.
- */
-export declare class CommandError extends Error {
-    readonly exitCode: ExitCode;
-    constructor(exitCode: ExitCode);
-}