@hominis/fireforge 0.15.7 → 0.15.9

package/dist/src/core/furnace-validate-accessibility.js

@@ -1,12 +1,19 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasPositiveTabindex, hasTemplateClickHandler, hasTemplateClickOnSyntheticInteractive, hasTemplateKeyboardHandler, hasUnlabelledFormInput, } from './furnace-validate-helpers.js';
+import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasPositiveTabindex, hasTemplateClickHandler, hasTemplateClickOnSyntheticInteractive, hasTemplateKeyboardHandler, hasUnlabelledFormInput, isKeyboardCoveredByComposition, } from './furnace-validate-helpers.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
  * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ *
+ * @param customConfig - When the component is custom, its matching entry
+ *   from `furnace.json`. Used to skip the `no-keyboard-handler` warning
+ *   when the component declares keyboard coverage either explicitly
+ *   (`keyboardCovered: true`) or via `composes` naming a native-interactive
+ *   inner element. Optional so stock/override callers and test fixtures
+ *   without config in scope can continue to call without changes.
  */
-export async function validateAccessibility(componentDir, tagName) {
+export async function validateAccessibility(componentDir, tagName, customConfig) {
     const mjsPath = join(componentDir, `${tagName}.mjs`);
     if (!(await pathExists(mjsPath)))
         return [];
@@ -22,8 +29,15 @@ export async function validateAccessibility(componentDir, tagName) {
     // platform, so a duplicate keyboard handler would usually double-fire.
     // Only flag synthetic markup (e.g. `<div @click>`) where the activation
     // path has to be wired manually.
+    //
+    // A wrapper component whose `composes` entry lists a native-interactive
+    // tag (or that sets `keyboardCovered: true`) is treated the same way:
+    // activation flows through the inner element and a duplicate handler on
+    // the wrapper would either no-op or fire twice alongside the child's
+    // built-in keyboard path.
     const hasClickOnSynthetic = hasTemplateClickOnSyntheticInteractive(content);
-    if (hasClickOnSynthetic && !hasKeyboardHandler) {
+    const keyboardCovered = isKeyboardCoveredByComposition(customConfig);
+    if (hasClickOnSynthetic && !hasKeyboardHandler && !keyboardCovered) {
         issues.push(createIssue(tagName, 'warning', 'no-keyboard-handler', 'Interactive element has @click but no keyboard event handler (@keydown/@keypress/@keyup).'));
     }
     if (containsHardcodedTemplateText(content)) {

package/dist/src/core/furnace-validate-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
+import type { ComponentType, CustomComponentConfig, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
 /** Creates a normalized validation issue object. */
 export declare function createIssue(component: string, severity: ValidationIssue['severity'], check: ValidationIssue['check'], message: string): ValidationIssue;
 /** Detects whether template or script content assigns an ARIA role. */
@@ -13,6 +13,18 @@ export declare function hasUnlabelledFormInput(content: string): boolean;
 export declare function hasTemplateClickHandler(content: string): boolean;
 /** Detects Lit-style template keyboard handlers. */
 export declare function hasTemplateKeyboardHandler(content: string): boolean;
+/**
+ * Returns true when `customConfig` declares that the component's keyboard
+ * activation path is covered by a wrapped native-interactive inner element,
+ * either through an explicit opt-out (`keyboardCovered: true`) or by
+ * composing a tag that lives in {@link NATIVE_CLICK_INTERACTIVE_TAGS}.
+ *
+ * Uses `.some` rather than `.every` so that a wrapper composing e.g.
+ * `['moz-button', 'my-tooltip']` still skips the warning: the keyboard
+ * activation path flows through the button, even if other composed
+ * children are synthetic.
+ */
+export declare function isKeyboardCoveredByComposition(customConfig: CustomComponentConfig | undefined): boolean;
 /**
  * Returns true when `content` has at least one `@click=${...}` handler on a
  * *synthetic* interactive element (e.g. `<div @click>`), which lacks native

package/dist/src/core/furnace-validate-helpers.js

@@ -76,6 +76,25 @@ const NATIVE_CLICK_INTERACTIVE_TAGS = new Set([
     'moz-radio-group',
     'moz-menulist',
 ]);
+/**
+ * Returns true when `customConfig` declares that the component's keyboard
+ * activation path is covered by a wrapped native-interactive inner element,
+ * either through an explicit opt-out (`keyboardCovered: true`) or by
+ * composing a tag that lives in {@link NATIVE_CLICK_INTERACTIVE_TAGS}.
+ *
+ * Uses `.some` rather than `.every` so that a wrapper composing e.g.
+ * `['moz-button', 'my-tooltip']` still skips the warning: the keyboard
+ * activation path flows through the button, even if other composed
+ * children are synthetic.
+ */
+export function isKeyboardCoveredByComposition(customConfig) {
+    if (!customConfig)
+        return false;
+    if (customConfig.keyboardCovered === true)
+        return true;
+    const composes = customConfig.composes ?? [];
+    return composes.some((tag) => NATIVE_CLICK_INTERACTIVE_TAGS.has(tag));
+}
 /**
  * Returns true when `content` has at least one `@click=${...}` handler on a
  * *synthetic* interactive element (e.g. `<div @click>`), which lacks native

package/dist/src/core/furnace-validate-structure.js

@@ -39,14 +39,18 @@ export async function validateStructure(componentDir, tagName, type, customConfi
     // Localized custom components must have a {tag}.ftl file. Without one,
     // apply silently deploys nothing for the locale and the runtime
     // localization payload is empty, which is hard to spot in review.
-    if (type === 'custom' && customConfig?.localized) {
+    //
+    // Components that declare `sharedFtl` participate in a pre-existing
+    // feature-scoped bundle, so there is no per-component .ftl to require —
+    // the shared file is owned by whoever authored the feature bundle.
+    if (type === 'custom' && customConfig?.localized && !customConfig.sharedFtl) {
         const ftlPath = join(componentDir, `${tagName}.ftl`);
         if (!(await pathExists(ftlPath))) {
             issues.push({
                 component: tagName,
                 severity: 'error',
                 check: 'missing-ftl',
-                message: `Component is marked localized: true but ${tagName}.ftl is missing. Create the file or set localized: false in furnace.json.`,
+                message: `Component is marked localized: true but ${tagName}.ftl is missing. Create the file, set localized: false in furnace.json, or switch to sharedFtl.`,
             });
         }
     }

package/dist/src/core/furnace-validate.js

@@ -37,10 +37,13 @@ function buildOverrideVersionDriftIssues(config, currentVersion, tagName) {
 export async function validateComponent(componentDir, tagName, type, config, root, options) {
     const issues = [];
     // Pass the matching custom config so structure validation can enforce
-    // the .ftl-when-localized invariant. Non-custom validations ignore the
+    // the .ftl-when-localized invariant and accessibility validation can
+    // recognize wrapper-over-native components (via `composes` or an
+    // explicit `keyboardCovered` opt-out). Non-custom validations ignore the
     // parameter, so this is a no-op for stock and override components.
-    issues.push(...(await validateStructure(componentDir, tagName, type, type === 'custom' ? config?.custom[tagName] : undefined)));
-    issues.push(...(await validateAccessibility(componentDir, tagName)));
+    const customConfigForTag = type === 'custom' ? config?.custom[tagName] : undefined;
+    issues.push(...(await validateStructure(componentDir, tagName, type, customConfigForTag)));
+    issues.push(...(await validateAccessibility(componentDir, tagName, customConfigForTag)));
     issues.push(...(await validateCompatibility(componentDir, tagName, type, config, root)));
     if (root && config && type === 'override') {
         const forgeConfig = await loadConfig(root);

package/dist/src/core/mach.d.ts

@@ -1,3 +1,4 @@
+import { type SmokeLineCallback, type SmokeRunResult } from '../utils/process.js';
 export { attemptMozinfoRewrite, type BuildArtifactCheck, buildArtifactMismatchMessage, hasBuildArtifacts, type MozinfoRewriteResult, } from './mach-build-artifacts.js';
 export { generateMozconfig, type MozconfigVariables } from './mach-mozconfig.js';
 export { ensurePython, resetResolvedPython } from './mach-python.js';
@@ -79,6 +80,31 @@ export declare function buildUI(engineDir: string): Promise<number>;
  * @returns Exit code
  */
 export declare function run(engineDir: string, args?: string[]): Promise<number>;
+/**
+ * Options for {@link runMachSmoke}.
+ */
+export interface RunMachSmokeOptions {
+    env?: Record<string, string>;
+    smokeTimeoutMs: number;
+    killGraceMs?: number;
+    onStdoutLine?: SmokeLineCallback;
+    onStderrLine?: SmokeLineCallback;
+    mirror?: {
+        stdout?: NodeJS.WritableStream;
+        stderr?: NodeJS.WritableStream;
+    };
+}
+/**
+ * Launches `mach run` under the smoke-run wrapper: streams line-by-line,
+ * enforces a deadline by SIGTERMing the whole process group, and returns
+ * the captured output alongside a `timedOut` flag.
+ *
+ * Unlike {@link run}, this variant does NOT inherit stdio. The child
+ * stdout/stderr are piped back through the line callbacks so the caller
+ * can scan for `JavaScript error:` / `console.error:` without coupling
+ * the runner to chrome-specific pattern logic.
+ */
+export declare function runMachSmoke(args: string[], engineDir: string, options: RunMachSmokeOptions): Promise<SmokeRunResult>;
 /**
  * Creates a distribution package.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
-import { exec, execInherit, execInheritCapture, execStream } from '../utils/process.js';
+import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
@@ -165,6 +165,30 @@ export async function buildUI(engineDir) {
 export async function run(engineDir, args = []) {
     return runMach(['run', ...args], engineDir, { inherit: true });
 }
+/**
+ * Launches `mach run` under the smoke-run wrapper: streams line-by-line,
+ * enforces a deadline by SIGTERMing the whole process group, and returns
+ * the captured output alongside a `timedOut` flag.
+ *
+ * Unlike {@link run}, this variant does NOT inherit stdio. The child
+ * stdout/stderr are piped back through the line callbacks so the caller
+ * can scan for `JavaScript error:` / `console.error:` without coupling
+ * the runner to chrome-specific pattern logic.
+ */
+export async function runMachSmoke(args, engineDir, options) {
+    const python = await getPython(engineDir);
+    await ensureMach(engineDir);
+    const machPath = join(engineDir, 'mach');
+    return execSmokeRun(python, [machPath, ...args], {
+        cwd: engineDir,
+        ...(options.env ? { env: options.env } : {}),
+        smokeTimeoutMs: options.smokeTimeoutMs,
+        ...(options.killGraceMs !== undefined ? { killGraceMs: options.killGraceMs } : {}),
+        ...(options.onStdoutLine ? { onStdoutLine: options.onStdoutLine } : {}),
+        ...(options.onStderrLine ? { onStderrLine: options.onStderrLine } : {}),
+        ...(options.mirror ? { mirror: options.mirror } : {}),
+    });
+}
 /**
  * Creates a distribution package.
  * @param engineDir - Path to the engine directory

package/dist/src/core/patch-lint.d.ts

@@ -89,6 +89,11 @@ export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles:
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional set of per-patch `check` IDs to drop from the
+ *   returned issues. Threaded from `PatchMetadata.lintIgnore` so a patch that
+ *   is advisory-noisy by nature (a cohesive branding bundle, auto-generated
+ *   manifest, etc.) can opt out of a specific rule without reaching for the
+ *   blunt `--skip-lint` hammer. Not mutated by this function.
  * @returns Array of all lint issues found
  */
-export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext): Promise<PatchLintIssue[]>;
+export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>): Promise<PatchLintIssue[]>;

package/dist/src/core/patch-lint.js

@@ -455,9 +455,14 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional set of per-patch `check` IDs to drop from the
+ *   returned issues. Threaded from `PatchMetadata.lintIgnore` so a patch that
+ *   is advisory-noisy by nature (a cohesive branding bundle, auto-generated
+ *   manifest, etc.) can opt out of a specific rule without reaching for the
+ *   blunt `--skip-lint` hammer. Not mutated by this function.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks) {
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
@@ -482,6 +487,14 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         const checkJsIssues = await runCheckJs(repoDir, patchOwnedFiles);
         issues.push(...checkJsIssues);
     }
+    // Filter out ignored checks last so every rule still runs (keeps the
+    // implementation uniform) but suppressed rules do not surface. We do not
+    // reclassify severities — an ignored error simply drops, mirroring how
+    // inline `fireforge-ignore: <check>` markers work in the CSS and
+    // forward-import rules.
+    if (ignoreChecks && ignoreChecks.size > 0) {
+        return issues.filter((issue) => !ignoreChecks.has(issue.check));
+    }
     return issues;
 }
 //# sourceMappingURL=patch-lint.js.map

package/dist/src/core/shared-ftl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Structural rules for the `sharedFtl` field on a custom component.
+ *
+ * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
+ * furnace.json parser apply the same rules — extracting them here
+ * avoids drift between the two entry points and lets the `.mjs`
+ * template generator assume the value is safe to interpolate verbatim.
+ */
+/**
+ * Outcome of {@link validateSharedFtl}. `ok: true` carries the trimmed
+ * (operator-safe) value; `ok: false` carries a human-readable message
+ * suitable for throwing as a `FurnaceError` or `InvalidArgumentError`.
+ */
+export type SharedFtlValidation = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a candidate `sharedFtl` value. Returns the trimmed value
+ * when well-formed, or a structured reason when not. Callers throw the
+ * error type appropriate to their context (CLI vs config parser).
+ */
+export declare function validateSharedFtl(raw: unknown, context: {
+    localized: boolean;
+}): SharedFtlValidation;

package/dist/src/core/shared-ftl.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Structural rules for the `sharedFtl` field on a custom component.
+ *
+ * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
+ * furnace.json parser apply the same rules — extracting them here
+ * avoids drift between the two entry points and lets the `.mjs`
+ * template generator assume the value is safe to interpolate verbatim.
+ */
+/**
+ * Characters that must not appear in `sharedFtl`:
+ *  - Backticks close the MJS template literal the scaffold writes.
+ *  - `\` is a path-escape we do not want to interpret.
+ *  - `${` opens a template expression and turns the FTL path into
+ *    executable code.
+ */
+const UNSAFE_CHARS = /[`\\]|\$\{/;
+/**
+ * Validates a candidate `sharedFtl` value. Returns the trimmed value
+ * when well-formed, or a structured reason when not. Callers throw the
+ * error type appropriate to their context (CLI vs config parser).
+ */
+export function validateSharedFtl(raw, context) {
+    if (typeof raw !== 'string') {
+        return { ok: false, reason: 'must be a string when set' };
+    }
+    const value = raw.trim();
+    if (value.length === 0) {
+        return { ok: false, reason: 'must not be empty' };
+    }
+    if (UNSAFE_CHARS.test(value)) {
+        return {
+            ok: false,
+            reason: 'must not contain backticks, backslashes, or ${ (would break the generated .mjs)',
+        };
+    }
+    if (!context.localized) {
+        return { ok: false, reason: 'requires localized to be true' };
+    }
+    return { ok: true, value };
+}
+//# sourceMappingURL=shared-ftl.js.map

package/dist/src/core/smoke-patterns.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared regex library for `fireforge run --smoke-exit`. Used by the smoke
+ * runner to decide whether a console line from the real chrome counts as a
+ * runtime error. Kept separate from the runner so the patterns can be
+ * exercised in isolation and amended without touching process-group logic.
+ *
+ * Matching is anchored at the start of the line (`^`) on purpose: a runtime
+ * error leaves a canonical prefix that Firefox's logging layer prints at
+ * column zero. Embedded mentions of the same string inside an unrelated
+ * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
+ * the prefix and should not trip the scanner.
+ */
+/**
+ * Line prefixes that signal an actual runtime error in a Firefox chrome
+ * process. A hit on any of these patterns is a smoke failure unless the
+ * line also matches the caller-supplied allowlist.
+ *
+ * Additions here should be conservative — false positives turn every
+ * smoke run into noise for operators and every CI run into flake.
+ */
+export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
+/**
+ * Returns `true` when `line` matches any pattern in
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * allowlisted hits separately from raw error matches for its summary.
+ */
+export declare function matchesSmokeError(line: string): boolean;
+/**
+ * Returns `true` when `line` matches any regex in `allow`. Safe to call
+ * with an empty allowlist (always returns `false`).
+ */
+export declare function matchesAllowlist(line: string, allow: readonly RegExp[]): boolean;
+/**
+ * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * lines and `#`-prefixed comments are skipped. Each remaining line is
+ * compiled as a RegExp. A bad pattern throws immediately — better to fail
+ * fast at CLI parse time than to silently let a typo match nothing.
+ */
+export declare function compileAllowlistFromFile(body: string, sourcePath: string): RegExp[];
+/**
+ * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
+ * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.
+ */
+export declare function compileAllowlistFromStrings(sources: readonly string[]): RegExp[];

package/dist/src/core/smoke-patterns.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared regex library for `fireforge run --smoke-exit`. Used by the smoke
+ * runner to decide whether a console line from the real chrome counts as a
+ * runtime error. Kept separate from the runner so the patterns can be
+ * exercised in isolation and amended without touching process-group logic.
+ *
+ * Matching is anchored at the start of the line (`^`) on purpose: a runtime
+ * error leaves a canonical prefix that Firefox's logging layer prints at
+ * column zero. Embedded mentions of the same string inside an unrelated
+ * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
+ * the prefix and should not trip the scanner.
+ */
+/**
+ * Line prefixes that signal an actual runtime error in a Firefox chrome
+ * process. A hit on any of these patterns is a smoke failure unless the
+ * line also matches the caller-supplied allowlist.
+ *
+ * Additions here should be conservative — false positives turn every
+ * smoke run into noise for operators and every CI run into flake.
+ */
+export const SMOKE_ERROR_PATTERNS = [
+    // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
+    /^\s*JavaScript error:/i,
+    // Some log paths prefix browser-console `console.error(...)` with the literal label below.
+    /^\s*console\.error:/i,
+    // Older bracketed-prefix variant still seen in some chrome logs / test runs.
+    /^\s*\[JavaScript (Error|Warning)\]/i,
+    // IPC-layer fatal assertions — Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
+    /^\s*###!!! \[Parent\]/,
+];
+/**
+ * Returns `true` when `line` matches any pattern in
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * allowlisted hits separately from raw error matches for its summary.
+ */
+export function matchesSmokeError(line) {
+    for (const pattern of SMOKE_ERROR_PATTERNS) {
+        if (pattern.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Returns `true` when `line` matches any regex in `allow`. Safe to call
+ * with an empty allowlist (always returns `false`).
+ */
+export function matchesAllowlist(line, allow) {
+    for (const pattern of allow) {
+        if (pattern.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * lines and `#`-prefixed comments are skipped. Each remaining line is
+ * compiled as a RegExp. A bad pattern throws immediately — better to fail
+ * fast at CLI parse time than to silently let a typo match nothing.
+ */
+export function compileAllowlistFromFile(body, sourcePath) {
+    const lines = body.split(/\r?\n/);
+    const compiled = [];
+    lines.forEach((raw, index) => {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            return;
+        try {
+            compiled.push(new RegExp(line));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid allowlist regex at ${sourcePath}:${String(index + 1)}: ${message}`, {
+                cause: error,
+            });
+        }
+    });
+    return compiled;
+}
+/**
+ * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
+ * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.
+ */
+export function compileAllowlistFromStrings(sources) {
+    const compiled = [];
+    sources.forEach((source, index) => {
+        try {
+            compiled.push(new RegExp(source));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid --console-allow regex at position ${String(index + 1)} ("${source}"): ${message}`, { cause: error });
+        }
+    });
+    return compiled;
+}
+//# sourceMappingURL=smoke-patterns.js.map

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

@@ -0,0 +1,143 @@
+/**
+ * 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).
+ */
+/**
+ * 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` — operators sometimes pass a manifest path directly.
+ */
+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 WILL be 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 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 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;