@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/wire-utils.d.ts

@@ -1,149 +0,0 @@
-import type * as estree from 'estree';
-import { type AcornESTreeNode } from './ast-utils.js';
-/**
- * Validates a name for safe interpolation into generated JavaScript string literals.
- * Rejects strings containing characters that could break out of JS strings or inject code.
- */
-export declare function validateWireName(value: string, label: string): void;
-/**
- * Coerces an init/destroy expression into a function call by appending `()`
- * when the caller passed a bare property chain. Idempotent: an expression
- * already ending in `()` is returned unchanged, so operators can pass either
- * `Startup.init` or `Startup.init()` and get the same wired output.
- *
- * `validateWireName` accepts both shapes, but the generated block
- * interpolates the expression verbatim inside `${expression};`, so a bare
- * `Startup.init` emits `Startup.init;`, a plain property reference that
- * never invokes the lifecycle hook. The symptom is silent: `wire` reports
- * success and the browser-init block looks plausible, but the hook never
- * fires at runtime.
- */
-export declare function coerceToCall(expression: string): string;
-/**
- * Counts net brace depth change in a single line, ignoring braces inside
- * string literals (single, double, template), line comments (`//`), and
- * block comments.
- *
- * Tracks multi-line block comment state across calls via the `inBlockComment`
- * parameter, allowing callers to iterate over lines while preserving context.
- *
- * Regex literal heuristic: when a `/` follows an operator or keyword-boundary
- * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
- * as a regex literal opener and characters are skipped until the closing `/`.
- * This heuristic can misfire on:
- *   - Division operators where the left operand is an identifier (`x / y / z`
- *     would incorrectly treat ` y ` as regex content).
- *   - Tagged template literals or unusual formatting.
- *
- * For Firefox source files this heuristic is sufficient because the AST-based
- * parser (via `withParserFallback`) is tried first. This function is only
- * used in the regex-based fallback path.
- *
- * @param line - A single line of source text
- * @param inBlockComment - Whether the previous line ended inside a block comment
- * @returns The net brace depth change and updated block comment state
- */
-export declare function countBraceDepth(line: string, inBlockComment: boolean): {
-    depth: number;
-    inBlockComment: boolean;
-};
-/**
- * Extracts the class/object name from an expression like "MyComponent.init()".
- */
-export declare function extractNameFromExpression(expression: string): string;
-/** Token types for XHTML/preprocessor files */
-export interface XhtmlToken {
-    type: 'xml' | 'macro' | 'empty';
-    raw: string;
-}
-/**
- * Tokenize an XHTML file with Mozilla preprocessor `#include` directives
- * into a structured array.
- */
-export declare function tokenizeXhtml(lines: string[]): XhtmlToken[];
-/**
- * Finds the line index of a method signature matching `pattern`, then
- * advances to the line containing the opening brace.
- *
- * By default this helper is tolerant: when no `{` is found anywhere after
- * the signature, it still returns `braceIndex: methodLine`, which is the
- * correct answer when the signature and body brace live on the same line,
- * but is ambiguous when the method is abstract or truncated. Opt into
- * stricter behaviour by passing `requireBrace: true`. The function will
- * return `null` instead of guessing, letting the caller surface a clean
- * {@link ParserFallbackError} rather than inserting into a wrong offset.
- *
- * @returns `{ methodLine, braceIndex }`, or `null` if the pattern is not
- *   found (or, under `requireBrace`, no brace follows the signature).
- */
-export declare function findMethodBraceIndex(lines: string[], pattern: RegExp, options?: {
-    requireBrace?: boolean;
-}): {
-    methodLine: number;
-    braceIndex: number;
-} | null;
-/**
- * Starting from `startLine`, walks lines using {@link countBraceDepth}
- * until the brace depth returns to zero (i.e., the enclosing block closes).
- *
- * Default behaviour is defensive: if the block never closes, the helper
- * returns `startLine + 1` so a single malformed file does not stop the
- * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
- * with a {@link ParserFallbackError} instead. New callers should prefer
- * strict mode so silent mis-insertions surface as the fallback refusing
- * to touch the file.
- *
- * @param lines - The full file split by newline
- * @param startLine - Line index of the `try {` (or other block opener) to walk
- * @param options - Pass `{ strict: true }` to throw when the block never closes
- * @returns The line index *after* the closing brace
- */
-export declare function walkToTryBlockEnd(lines: string[], startLine: number, options?: {
-    strict?: boolean;
-    context?: string;
-}): number;
-/**
- * Scans the entire file and returns the net brace balance so callers can
- * assert that a line-based fallback mutation did not silently introduce or
- * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
- * comments, and regex literals are handled consistently with the walker.
- *
- * @param content - Full file contents (will be split by newline)
- * @returns The net depth across the file (`opens - closes`) and a
- *   convenience `balanced` flag equal to `depth === 0`.
- */
-export declare function computeFileBraceBalance(content: string): {
-    depth: number;
-    balanced: boolean;
-};
-/**
- * Round-trip guard used after a line-based fallback mutation: if the file's
- * net brace balance drifts between `before` and `after`, something went
- * wrong and the fallback is refusing to write a corrupted file. Expects
- * the delta to be exactly zero, since wire fallbacks only insert whole
- * try/catch blocks, which always contribute equal opens and closes.
- *
- * @throws {@link ParserFallbackError} when the balance delta is non-zero.
- */
-export declare function assertBraceBalancePreserved(before: string, after: string, context: string): void;
-/**
- * Looks backward from `fromLine` (exclusive) to find the nearest `try {`
- * line.  If nothing is found searching backward, also searches forward.
- *
- * @returns The line index of `try {`, or -1 if not found.
- */
-export declare function findNearestTryLine(lines: string[], fromLine: number, lowerBound: number): number;
-/**
- * Scans lines starting from `startLine` for consecutive fireforge try-catch
- * blocks (identified by init comments or typeof guards) and returns the
- * line index just after the last such block, i.e. where a new block should
- * be inserted.
- *
- * Non-fireforge, non-blank, non-comment lines terminate the scan.
- */
-export declare function findInsertionAfterFireforgeBlocks(lines: string[], startLine: number, lowerBound: number): number;
-/**
- * Find the `Property` node for a method name like `onLoad` or `onUnload`
- * inside the AST. Returns the function body's `BlockStatement`.
- */
-export declare function findMethodBody(ast: AcornESTreeNode<estree.Program>, methodName: string | string[]): AcornESTreeNode<estree.BlockStatement> | null;

package/dist/src/core/wire-utils.js

@@ -1,338 +0,0 @@
-import { GeneralError, ParserFallbackError } from '../errors/base.js';
-import { asEstree, walkAST } from './ast-utils.js';
-/**
- * Validates a name for safe interpolation into generated JavaScript string literals.
- * Rejects strings containing characters that could break out of JS strings or inject code.
- */
-export function validateWireName(value, label) {
-    if (!/^[a-zA-Z0-9_$][\w$.-]*(?:\(\))?$/.test(value)) {
-        throw new GeneralError(`Invalid ${label} "${value}": must contain only letters, digits, hyphens, underscores, dots, and $ signs`);
-    }
-    // Reject property chains that could reach dangerous built-in properties
-    const segments = value.replace(/\(\)$/, '').split('.');
-    const dangerous = new Set(['__proto__', 'constructor', 'prototype']);
-    for (const seg of segments) {
-        if (dangerous.has(seg)) {
-            throw new GeneralError(`Invalid ${label} "${value}": must not contain "${seg}" as a property segment`);
-        }
-    }
-}
-/**
- * Coerces an init/destroy expression into a function call by appending `()`
- * when the caller passed a bare property chain. Idempotent: an expression
- * already ending in `()` is returned unchanged, so operators can pass either
- * `Startup.init` or `Startup.init()` and get the same wired output.
- *
- * `validateWireName` accepts both shapes, but the generated block
- * interpolates the expression verbatim inside `${expression};`, so a bare
- * `Startup.init` emits `Startup.init;`, a plain property reference that
- * never invokes the lifecycle hook. The symptom is silent: `wire` reports
- * success and the browser-init block looks plausible, but the hook never
- * fires at runtime.
- */
-export function coerceToCall(expression) {
-    return expression.endsWith('()') ? expression : `${expression}()`;
-}
-/**
- * Counts net brace depth change in a single line, ignoring braces inside
- * string literals (single, double, template), line comments (`//`), and
- * block comments.
- *
- * Tracks multi-line block comment state across calls via the `inBlockComment`
- * parameter, allowing callers to iterate over lines while preserving context.
- *
- * Regex literal heuristic: when a `/` follows an operator or keyword-boundary
- * character (one of `= ( : , ! | & ? ; ~ ^ { [ \n + - * % < >`), it is treated
- * as a regex literal opener and characters are skipped until the closing `/`.
- * This heuristic can misfire on:
- *   - Division operators where the left operand is an identifier (`x / y / z`
- *     would incorrectly treat ` y ` as regex content).
- *   - Tagged template literals or unusual formatting.
- *
- * For Firefox source files this heuristic is sufficient because the AST-based
- * parser (via `withParserFallback`) is tried first. This function is only
- * used in the regex-based fallback path.
- *
- * @param line - A single line of source text
- * @param inBlockComment - Whether the previous line ended inside a block comment
- * @returns The net brace depth change and updated block comment state
- */
-export function countBraceDepth(line, inBlockComment) {
-    let depth = 0;
-    let quote = null;
-    let inLine = false;
-    let inBlock = inBlockComment;
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-        const next = line[i + 1];
-        if (inLine)
-            continue;
-        if (inBlock) {
-            if (ch === '*' && next === '/') {
-                inBlock = false;
-                i++;
-            }
-            continue;
-        }
-        if (ch === '\\' && quote !== null) {
-            i++;
-            continue;
-        }
-        if (quote !== null) {
-            if (ch === quote)
-                quote = null;
-            continue;
-        }
-        if (ch === '/' && next === '/') {
-            inLine = true;
-            continue;
-        }
-        if (ch === '/' && next === '*') {
-            inBlock = true;
-            i++;
-            continue;
-        }
-        if (ch === '/' && next !== undefined && isRegexLiteralStart(line, i)) {
-            i = scanToRegexLiteralEnd(line, i);
-            continue;
-        }
-        if (ch === "'" || ch === '"' || ch === '`') {
-            quote = ch;
-            continue;
-        }
-        if (ch === '{')
-            depth++;
-        if (ch === '}')
-            depth--;
-    }
-    return { depth, inBlockComment: inBlock };
-}
-/**
- * Regex-literal opener heuristic for the fallback scanner: a `/` is
- * treated as starting a regex when it follows an operator or
- * keyword-boundary character (or starts the line). See the misfire notes
- * on {@link countBraceDepth}.
- */
-function isRegexLiteralStart(line, i) {
-    const prev = i > 0 ? line[i - 1] : undefined;
-    return prev === undefined || /[=(:,!|&?;~^{[\n+\-*%<>]/.test(prev);
-}
-/**
- * Scans from the opening `/` of a regex literal to its closing `/`
- * (honouring escapes), returning the index of the closing slash, or the
- * end of the line when the literal never closes.
- */
-function scanToRegexLiteralEnd(line, start) {
-    let i = start + 1;
-    while (i < line.length) {
-        if (line[i] === '\\') {
-            i++; // skip escaped character
-        }
-        else if (line[i] === '/') {
-            break;
-        }
-        i++;
-    }
-    return i;
-}
-/**
- * Extracts the class/object name from an expression like "MyComponent.init()".
- */
-export function extractNameFromExpression(expression) {
-    const match = /^(\w+)/.exec(expression);
-    return match?.[1] ?? expression;
-}
-/**
- * Tokenize an XHTML file with Mozilla preprocessor `#include` directives
- * into a structured array.
- */
-export function tokenizeXhtml(lines) {
-    return lines.map((raw) => {
-        const trimmed = raw.trim();
-        if (trimmed === '') {
-            return { type: 'empty', raw };
-        }
-        if (trimmed.startsWith('#include ')) {
-            return { type: 'macro', raw };
-        }
-        return { type: 'xml', raw };
-    });
-}
-// ---------------------------------------------------------------------------
-// Line-based helpers, shared by fallback implementations in
-// the wire target modules.  Extracted to reduce duplication and make the brace-
-// walking logic independently testable.
-// ---------------------------------------------------------------------------
-/**
- * Finds the line index of a method signature matching `pattern`, then
- * advances to the line containing the opening brace.
- *
- * By default this helper is tolerant: when no `{` is found anywhere after
- * the signature, it still returns `braceIndex: methodLine`, which is the
- * correct answer when the signature and body brace live on the same line,
- * but is ambiguous when the method is abstract or truncated. Opt into
- * stricter behaviour by passing `requireBrace: true`. The function will
- * return `null` instead of guessing, letting the caller surface a clean
- * {@link ParserFallbackError} rather than inserting into a wrong offset.
- *
- * @returns `{ methodLine, braceIndex }`, or `null` if the pattern is not
- *   found (or, under `requireBrace`, no brace follows the signature).
- */
-export function findMethodBraceIndex(lines, pattern, options) {
-    const methodLine = lines.findIndex((line) => pattern.test(line));
-    if (methodLine === -1)
-        return null;
-    const braceOffset = lines.slice(methodLine).findIndex((line) => line.includes('{'));
-    const braceFound = braceOffset !== -1;
-    const braceIndex = braceFound ? methodLine + braceOffset : methodLine;
-    if (!braceFound && options?.requireBrace) {
-        return null;
-    }
-    return { methodLine, braceIndex };
-}
-/**
- * Starting from `startLine`, walks lines using {@link countBraceDepth}
- * until the brace depth returns to zero (i.e., the enclosing block closes).
- *
- * Default behaviour is defensive: if the block never closes, the helper
- * returns `startLine + 1` so a single malformed file does not stop the
- * entire fallback path. Pass `{ strict: true }` to opt into failing loudly
- * with a {@link ParserFallbackError} instead. New callers should prefer
- * strict mode so silent mis-insertions surface as the fallback refusing
- * to touch the file.
- *
- * @param lines - The full file split by newline
- * @param startLine - Line index of the `try {` (or other block opener) to walk
- * @param options - Pass `{ strict: true }` to throw when the block never closes
- * @returns The line index *after* the closing brace
- */
-export function walkToTryBlockEnd(lines, startLine, options) {
-    let depth = 0;
-    let inBlock = false;
-    for (let j = startLine; j < lines.length; j++) {
-        const r = countBraceDepth(lines[j] ?? '', inBlock);
-        depth += r.depth;
-        inBlock = r.inBlockComment;
-        if (depth <= 0 && j > startLine) {
-            return j + 1;
-        }
-    }
-    if (options?.strict) {
-        throw new ParserFallbackError(`Block starting at line ${startLine + 1} never closes — fallback parser refuses to insert`, options.context);
-    }
-    return startLine + 1;
-}
-/**
- * Scans the entire file and returns the net brace balance so callers can
- * assert that a line-based fallback mutation did not silently introduce or
- * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
- * comments, and regex literals are handled consistently with the walker.
- *
- * @param content - Full file contents (will be split by newline)
- * @returns The net depth across the file (`opens - closes`) and a
- *   convenience `balanced` flag equal to `depth === 0`.
- */
-export function computeFileBraceBalance(content) {
-    const lines = content.split('\n');
-    let depth = 0;
-    let inBlock = false;
-    for (const line of lines) {
-        const r = countBraceDepth(line, inBlock);
-        depth += r.depth;
-        inBlock = r.inBlockComment;
-    }
-    return { depth, balanced: depth === 0 };
-}
-/**
- * Round-trip guard used after a line-based fallback mutation: if the file's
- * net brace balance drifts between `before` and `after`, something went
- * wrong and the fallback is refusing to write a corrupted file. Expects
- * the delta to be exactly zero, since wire fallbacks only insert whole
- * try/catch blocks, which always contribute equal opens and closes.
- *
- * @throws {@link ParserFallbackError} when the balance delta is non-zero.
- */
-export function assertBraceBalancePreserved(before, after, context) {
-    const beforeDepth = computeFileBraceBalance(before).depth;
-    const afterDepth = computeFileBraceBalance(after).depth;
-    if (beforeDepth !== afterDepth) {
-        throw new ParserFallbackError(`Brace balance drifted from ${beforeDepth} to ${afterDepth} after fallback mutation; refusing to write`, context);
-    }
-}
-/**
- * Looks backward from `fromLine` (exclusive) to find the nearest `try {`
- * line.  If nothing is found searching backward, also searches forward.
- *
- * @returns The line index of `try {`, or -1 if not found.
- */
-export function findNearestTryLine(lines, fromLine, lowerBound) {
-    // Backward search
-    for (let k = fromLine; k > lowerBound; k--) {
-        if (/\btry\s*\{/.test(lines[k] ?? ''))
-            return k;
-    }
-    // Forward search
-    for (let k = fromLine; k < lines.length; k++) {
-        if (/\btry\s*\{/.test(lines[k] ?? ''))
-            return k;
-    }
-    return -1;
-}
-/** Patterns that identify a fireforge init/destroy try-catch block. */
-const FIREFORGE_BLOCK_PATTERN = /\/\/\s*.*init\s*—|typeof\s+\w+\s*!==\s*"undefined"/;
-/**
- * Scans lines starting from `startLine` for consecutive fireforge try-catch
- * blocks (identified by init comments or typeof guards) and returns the
- * line index just after the last such block, i.e. where a new block should
- * be inserted.
- *
- * Non-fireforge, non-blank, non-comment lines terminate the scan.
- */
-export function findInsertionAfterFireforgeBlocks(lines, startLine, lowerBound) {
-    let insertIndex = startLine;
-    for (let i = startLine; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (FIREFORGE_BLOCK_PATTERN.test(line)) {
-            const tryLine = findNearestTryLine(lines, i, lowerBound);
-            if (tryLine !== -1) {
-                const end = walkToTryBlockEnd(lines, tryLine);
-                insertIndex = end;
-                i = end - 1; // continue after this block
-            }
-            continue;
-        }
-        if (line.trim() && !line.trim().startsWith('//')) {
-            insertIndex = i;
-            break;
-        }
-    }
-    return insertIndex;
-}
-// ---------------------------------------------------------------------------
-// AST-based helpers
-// ---------------------------------------------------------------------------
-/**
- * Find the `Property` node for a method name like `onLoad` or `onUnload`
- * inside the AST. Returns the function body's `BlockStatement`.
- */
-export function findMethodBody(ast, methodName) {
-    const names = Array.isArray(methodName) ? methodName : [methodName];
-    let found = null;
-    walkAST(ast, {
-        enter(node) {
-            if (found)
-                return;
-            if (node.type === 'Property') {
-                const prop = asEstree(node);
-                if (prop.key.type === 'Identifier' &&
-                    names.includes(prop.key.name) &&
-                    (prop.value.type === 'FunctionExpression' ||
-                        prop.value.type === 'ArrowFunctionExpression')) {
-                    const fn = asEstree(prop.value);
-                    found = asEstree(fn.body);
-                }
-            }
-        },
-    });
-    return found;
-}

package/dist/src/core/xpcshell-appdir.d.ts

@@ -1,157 +0,0 @@
-/**
- * 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).
- */
-/**
- * Result of attempting to resolve the auto-injected `--app-path` value.
- * Carries enough context for the caller to log a useful info line and for
- * the diagnostic hint to know whether an injection was attempted.
- */
-export interface AppdirResolveResult {
-    /** Absolute path to the app dir. Pass as `--app-path=<value>`. */
-    appPath: string;
-    /** Manifest the value was sourced from. Used for the info log. */
-    manifestPath: string;
-    /** Manifest key (e.g. `firefox-appdir`) that triggered the injection. */
-    key: string;
-    /** Relative appdir from the manifest (e.g. `browser`). */
-    relativeAppdir: string;
-}
-/**
- * `[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 declare function parseAppdirFromToml(tomlText: string, key: string): {
-    value: string;
-    lineIndex: number;
-} | undefined;
-/**
- * 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 declare function findNearestXpcshellManifest(engineDir: string, startPath: string): Promise<string | 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 declare function readMozinfoAppname(objDirPath: string): Promise<string>;
-/**
- * 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 declare function resolveAbsoluteAppPath(objDirAbs: string, relativeAppdir: string): Promise<string | null>;
-/**
- * Outcome carrier for {@link resolveXpcshellAppdirArg}. Distinguishes the
- * three "did nothing" cases so callers can shape diagnostics:
- *  - `none`: no manifest under any test path needs injection.
- *  - `mismatch`: at least two manifests resolved to different values. We
- *    refuse to guess which one the operator meant.
- *  - `unresolved`: the manifest asks for `firefox-appdir = "<value>"` but
- *    no `dist/` candidate exists for that value.
- *  - `injected`: the absolute path to pass via `--app-path=`.
- */
-export type XpcshellAppdirOutcome = {
-    kind: 'none';
-} | {
-    kind: 'mismatch';
-    values: string[];
-} | {
-    kind: 'unresolved';
-    relativeAppdir: string;
-    manifestPath: string;
-} | {
-    kind: 'injected';
-    result: AppdirResolveResult;
-};
-/**
- * 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 declare function resolveXpcshellAppdirArg(engineDir: string, testPaths: readonly string[], objDirName: string): Promise<XpcshellAppdirOutcome>;
-/**
- * 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 declare function operatorAlreadySetAppPath(extraArgs: readonly string[]): boolean;