@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -1,11 +1,36 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { createIssue } from './furnace-validate-helpers.js';
+import { countUnlabelledIconButtons } from './furnace-validate-icon-button.js';
 import { collectLitTemplateRegions, parseTemplateAttributes } from './lit-template-regions.js';
 /**
- * Validates accessibility patterns in a component's .mjs file.
- * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ * Reads the composed component: `<tagName>.mjs` followed by its companion
+ * modules (`<tagName>-*.mjs`, tests and stories left out), so a template's
+ * findings do not depend on which of the component's modules it lives in.
+ * Returns undefined when the host module is missing.
+ */
+async function readComposedComponentSource(componentDir, tagName) {
+    const hostPath = join(componentDir, `${tagName}.mjs`);
+    if (!(await pathExists(hostPath)))
+        return undefined;
+    const entries = await readdir(componentDir).catch(() => []);
+    const companions = entries
+        .filter((name) => name.startsWith(`${tagName}-`) &&
+        name.endsWith('.mjs') &&
+        !/\.(test|spec|stories)\./.test(name))
+        .sort();
+    const sources = [await readText(hostPath)];
+    for (const name of companions)
+        sources.push(await readText(join(componentDir, name)));
+    return sources.join('\n');
+}
+/**
+ * Validates accessibility patterns in a component's composed source: its
+ * host module and every companion module (see
+ * {@link readComposedComponentSource}). Checks for ARIA roles, keyboard
+ * handlers, l10n, and focus delegation.
  *
  * @param componentDir - Directory holding the component's sources
  * @param tagName - Custom element tag name, used to locate `<tagName>.mjs`
@@ -15,12 +40,13 @@ import { collectLitTemplateRegions, parseTemplateAttributes } from './lit-templa
  *   (`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.
+ * @param optInChecks - `furnace.json#optInChecks`. `icon-button-label`
+ *   adds the icon-only `<moz-button>` naming check.
  */
-export async function validateAccessibility(componentDir, tagName, customConfig) {
-    const mjsPath = join(componentDir, `${tagName}.mjs`);
-    if (!(await pathExists(mjsPath)))
+export async function validateAccessibility(componentDir, tagName, customConfig, optInChecks = []) {
+    const content = await readComposedComponentSource(componentDir, tagName);
+    if (content === undefined)
         return [];
-    const content = await readText(mjsPath);
     const issues = [];
     if (!hasAriaRole(content) && hasGenericInteractiveElement(content)) {
         issues.push(createIssue(tagName, 'warning', 'no-aria-role', 'Generic interactive markup has no native semantics. Prefer native elements, or add role= when native markup cannot provide the semantics.'));
@@ -38,10 +64,13 @@ export async function validateAccessibility(componentDir, tagName, customConfig)
     // 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);
+    const syntheticTags = syntheticClickTags(content);
     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 (syntheticTags.length > 0 && !hasKeyboardHandler && !keyboardCovered) {
+        issues.push({
+            ...createIssue(tagName, 'warning', 'no-keyboard-handler', `Interactive element has @click but no keyboard event handler (@keydown/@keypress/@keyup), on ${syntheticTags.map((tag) => `<${tag}>`).join(', ')}.`),
+            tags: syntheticTags,
+        });
     }
     if (containsHardcodedTemplateText(content)) {
         issues.push(createIssue(tagName, 'warning', 'hardcoded-text', 'Possible hardcoded string found. Use data-l10n-id for localization.'));
@@ -56,6 +85,12 @@ export async function validateAccessibility(componentDir, tagName, customConfig)
     if (hasUnlabelledFormInput(content)) {
         issues.push(createIssue(tagName, 'warning', 'unlabelled-form-input', 'Form input without an accessible label. Add aria-label, aria-labelledby, or an associated <label> element.'));
     }
+    if (optInChecks.includes('icon-button-label')) {
+        const unlabelled = countUnlabelledIconButtons(content);
+        if (unlabelled > 0) {
+            issues.push(createIssue(tagName, 'warning', 'icon-button-label', `${unlabelled} icon-only <moz-button> without an accessible name. Add data-l10n-id (with the label in its Fluent message) or aria-label.`));
+        }
+    }
     return issues;
 }
 /** Detects whether template or script content assigns an ARIA role. */
@@ -155,6 +190,9 @@ const NATIVE_CLICK_INTERACTIVE_TAGS = new Set([
     'moz-radio',
     'moz-radio-group',
     'moz-menulist',
+    // Toolkit's panel-list row renders a button that takes Enter and Space
+    // and dispatches click.
+    'panel-item',
 ]);
 /**
  * Returns true when `customConfig` declares that the component's keyboard
@@ -176,28 +214,33 @@ function isKeyboardCoveredByComposition(customConfig) {
     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
- * keyboard activation and therefore needs an explicit key handler for
- * Enter/Space. Returns false when every `@click` handler sits on a native
- * interactive element. Those already fire `click` on keyboard activation.
+ * Returns the tags (in first-seen order) of every *synthetic* interactive
+ * element carrying an `@click=${...}` handler (e.g. `<div @click>`), which
+ * lacks native keyboard activation and therefore needs an explicit key
+ * handler for Enter/Space. Empty when every `@click` handler sits on a
+ * native interactive element. Those already fire `click` on keyboard
+ * activation.
  */
-function hasTemplateClickOnSyntheticInteractive(content) {
+function syntheticClickTags(content) {
     const pattern = /@click\s*=\s*\$\{/g;
+    const tags = [];
     let match;
     while ((match = pattern.exec(content)) !== null) {
-        if (isClickOnSyntheticInteractive(content, match.index)) {
-            return true;
-        }
+        const tag = syntheticClickTag(content, match.index);
+        if (tag !== undefined && !tags.includes(tag))
+            tags.push(tag);
     }
-    return false;
+    return tags;
 }
+/** The tag a synthetic-element `@click` sits on, `?` when it cannot be told. */
+const UNKNOWN_TAG = '?';
 /**
  * Given the offset of an `@click=${...}` occurrence, walks backwards to find
- * the opening `<tag` that owns it and decides whether that tag is a native
- * interactive element (no warning needed) or a synthetic one (warning needed).
+ * the opening `<tag` that owns it and returns that tag when it is a
+ * synthetic interactive element (warning needed), or undefined when it is a
+ * native one (no warning needed).
  */
-function isClickOnSyntheticInteractive(content, clickIndex) {
+function syntheticClickTag(content, clickIndex) {
     // Find the nearest preceding `<` that starts a tag (skip `</` closers).
     let i = clickIndex - 1;
     let tagOpenIndex = -1;
@@ -210,15 +253,15 @@ function isClickOnSyntheticInteractive(content, clickIndex) {
         // which shouldn't happen for a well-formed template but we defensively
         // treat it as synthetic to preserve the prior-behaviour warning.
         if (content[i] === '>') {
-            return true;
+            return UNKNOWN_TAG;
         }
         i--;
     }
     if (tagOpenIndex < 0)
-        return true;
+        return UNKNOWN_TAG;
     const tagMatch = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(content.slice(tagOpenIndex));
     if (!tagMatch?.[1])
-        return true;
+        return UNKNOWN_TAG;
     const tagName = tagMatch[1].toLowerCase();
     if (tagName === 'a') {
         // Bare <a> (no href) is non-interactive, so require a keyboard handler.
@@ -226,11 +269,11 @@ function isClickOnSyntheticInteractive(content, clickIndex) {
         // attribute text in between for an href attribute.
         const tagEnd = content.indexOf('>', tagOpenIndex);
         if (tagEnd < 0)
-            return true;
+            return 'a';
         const attrs = content.slice(tagOpenIndex, tagEnd);
-        return !/\shref\s*=/.test(attrs);
+        return /\shref\s*=/.test(attrs) ? undefined : 'a';
     }
-    return !NATIVE_CLICK_INTERACTIVE_TAGS.has(tagName);
+    return NATIVE_CLICK_INTERACTIVE_TAGS.has(tagName) ? undefined : tagName;
 }
 /** ASCII punctuation that reads as decoration rather than localizable text. */
 const SYMBOL_ONLY_ASCII = '+-*=<>|/\\^~@#&!?%';

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

@@ -0,0 +1,48 @@
+/**
+ * Applies `furnace.json#validationExceptions[]` to a `furnace validate`
+ * result. An exception suppresses every finding of its check on its
+ * component, or with `tag`, a finding whose element tags it (and its
+ * sibling tag entries) cover. One that suppresses nothing is stale: the
+ * finding was fixed (or renamed) and the review record outlived it, so it
+ * is reported as a warning naming the entry to delete, which keeps the
+ * list honest under `--max-warnings 0`.
+ *
+ * An exception never suppresses an error: an error blocks apply, and a
+ * review record cannot make a broken component deployable. The error stays
+ * counted and the matching entry is reported as
+ * `validation-exception-on-error`.
+ */
+import type { FurnaceValidationException, ValidationIssue } from '../types/furnace.js';
+/** The check name of the warning a stale exception produces. */
+export declare const STALE_VALIDATION_EXCEPTION_CHECK = "stale-validation-exception";
+/** The check name of the error an exception matching an error produces. */
+export declare const EXCEPTION_ON_ERROR_CHECK = "validation-exception-on-error";
+/** A finding an exception suppressed, with the exception's reason. */
+export interface ExceptedValidationIssue extends ValidationIssue {
+    reason: string;
+}
+/** {@link applyValidationExceptions}'s result. */
+export interface ValidationExceptionOutcome {
+    /** Findings that still count, stale-exception warnings included. */
+    issues: ValidationIssue[];
+    /** Findings an exception suppressed. */
+    excepted: ExceptedValidationIssue[];
+    /** Exceptions that matched no finding of a component this run judged. */
+    stale: FurnaceValidationException[];
+}
+/**
+ * Splits findings into counted and excepted, and reports stale exceptions.
+ *
+ * @param issues - Every finding of the run
+ * @param exceptions - `furnace.json#validationExceptions`
+ * @param judged - Whether the run judged an exception's component. A run
+ *   scoped to one component cannot call another component's exception
+ *   stale, while the full run judges them all (including components
+ *   furnace.json no longer declares)
+ */
+export declare function applyValidationExceptions(issues: readonly ValidationIssue[], exceptions: readonly FurnaceValidationException[] | undefined, judged: (component: string) => boolean): ValidationExceptionOutcome;
+/** Counts error- and warning-severity findings. */
+export declare function countValidationSeverities(issues: readonly ValidationIssue[]): {
+    errors: number;
+    warnings: number;
+};

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

@@ -0,0 +1,80 @@
+import { createIssue } from './furnace-validate-helpers.js';
+/** The check name of the warning a stale exception produces. */
+export const STALE_VALIDATION_EXCEPTION_CHECK = 'stale-validation-exception';
+/** The check name of the error an exception matching an error produces. */
+export const EXCEPTION_ON_ERROR_CHECK = 'validation-exception-on-error';
+function matches(exception, issue) {
+    return exception.component === issue.component && exception.check === issue.check;
+}
+/**
+ * The exceptions that suppress a warning: an untagged one alone, or tagged
+ * ones that together cover every tag the finding names.
+ */
+function coveringExceptions(issue, candidates) {
+    const untagged = candidates.find((entry) => entry.tag === undefined);
+    if (untagged !== undefined)
+        return [untagged];
+    const tags = issue.tags ?? [];
+    if (tags.length === 0)
+        return [];
+    const covering = tags.map((tag) => candidates.find((entry) => entry.tag === tag));
+    return covering.every((entry) => entry !== undefined) ? [...new Set(covering)] : [];
+}
+/**
+ * Splits findings into counted and excepted, and reports stale exceptions.
+ *
+ * @param issues - Every finding of the run
+ * @param exceptions - `furnace.json#validationExceptions`
+ * @param judged - Whether the run judged an exception's component. A run
+ *   scoped to one component cannot call another component's exception
+ *   stale, while the full run judges them all (including components
+ *   furnace.json no longer declares)
+ */
+export function applyValidationExceptions(issues, exceptions, judged) {
+    const outcome = { issues: [], excepted: [], stale: [] };
+    const list = exceptions ?? [];
+    const used = new Set();
+    const onError = new Set();
+    for (const issue of issues) {
+        const candidates = list.filter((entry) => matches(entry, issue));
+        if (issue.severity === 'error') {
+            for (const entry of candidates) {
+                used.add(entry);
+                onError.add(entry);
+            }
+            outcome.issues.push(issue);
+            continue;
+        }
+        const covering = coveringExceptions(issue, candidates);
+        if (covering.length === 0) {
+            // A tagged exception that covers some of the tags is not stale: its
+            // element still carries the finding, beside one it does not cover.
+            for (const entry of candidates) {
+                if (entry.tag !== undefined && issue.tags?.includes(entry.tag) === true)
+                    used.add(entry);
+            }
+            outcome.issues.push(issue);
+            continue;
+        }
+        for (const entry of covering)
+            used.add(entry);
+        outcome.excepted.push({ ...issue, reason: covering.map((entry) => entry.reason).join('; ') });
+    }
+    for (const exception of onError) {
+        outcome.issues.push(createIssue(exception.component, 'error', EXCEPTION_ON_ERROR_CHECK, `furnace.json validationExceptions entry for [${exception.check}] matches an error, ` +
+            'which an exception cannot suppress. Fix the error, then delete the entry.'));
+    }
+    for (const exception of list) {
+        if (used.has(exception) || !judged(exception.component))
+            continue;
+        outcome.stale.push(exception);
+        outcome.issues.push(createIssue(exception.component, 'warning', STALE_VALIDATION_EXCEPTION_CHECK, `furnace.json validationExceptions entry for [${exception.check}] matches no finding. ` +
+            'Delete the entry: the finding it records is gone.'));
+    }
+    return outcome;
+}
+/** Counts error- and warning-severity findings. */
+export function countValidationSeverities(issues) {
+    const errors = issues.filter((issue) => issue.severity === 'error').length;
+    return { errors, warnings: issues.length - errors };
+}

package/dist/src/core/furnace-validate-icon-button.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Counts icon-only `<moz-button>` elements in the module's Lit templates
+ * that carry neither `data-l10n-id` nor `aria-label`.
+ *
+ * @param content - The component module's source
+ */
+export declare function countUnlabelledIconButtons(content: string): number;

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

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The opt-in `icon-button-label` check (`furnace.json#optInChecks`): an
+ * icon-only `<moz-button>` has no visible text, so its accessible name has
+ * to come from `data-l10n-id` (whose FTL message carries the label or
+ * `.aria-label`) or from `aria-label`. Without one, screen readers announce
+ * just "button".
+ *
+ * Scans the Lit `html` templates of the component module only. A button
+ * built with `document.createElement` is not seen.
+ */
+import { collectLitTemplateRegions, parseTemplateAttributes } from './lit-template-regions.js';
+/**
+ * Attributes (and their Lit property-binding spellings) that give the
+ * button an accessible name. `parseTemplateAttributes` lowercases names,
+ * so `.ariaLabel=${…}` arrives as `.arialabel`.
+ */
+const NAMING_ATTRIBUTES = ['data-l10n-id', 'aria-label', '.arialabel'];
+/** Attributes that give the button a visible label, so it is not icon-only. */
+const LABEL_ATTRIBUTES = ['label', '.label'];
+/**
+ * Whether the button's content has a non-blank character outside tags.
+ * Scans instead of stripping tags, so nested or unbalanced markup cannot
+ * leave a fragment behind that reads as text, and a `>` inside a quoted
+ * attribute value does not end its tag.
+ */
+function hasVisibleText(markup) {
+    let inTag = false;
+    let quote;
+    for (const char of markup) {
+        if (quote !== undefined) {
+            if (char === quote)
+                quote = undefined;
+        }
+        else if (inTag) {
+            if (char === '"' || char === "'")
+                quote = char;
+            else if (char === '>')
+                inTag = false;
+        }
+        else if (char === '<') {
+            inTag = true;
+        }
+        else if (char.trim() !== '') {
+            return true;
+        }
+    }
+    return false;
+}
+function isIconOnly(attrs, innerText) {
+    if (LABEL_ATTRIBUTES.some((name) => attrs.has(name)))
+        return false;
+    if (hasVisibleText(innerText))
+        return false;
+    const type = attrs.get('type') ?? '';
+    return attrs.has('iconsrc') || attrs.has('.iconsrc') || /(^|\s)icon(\s|$)/.test(type);
+}
+/**
+ * Counts icon-only `<moz-button>` elements in the module's Lit templates
+ * that carry neither `data-l10n-id` nor `aria-label`.
+ *
+ * @param content - The component module's source
+ */
+export function countUnlabelledIconButtons(content) {
+    let count = 0;
+    for (const region of collectLitTemplateRegions(content)) {
+        const pattern = /<moz-button\b((?:"[^"]*"|'[^']*'|[^'">])*)>([\s\S]*?)<\/moz-button>/gi;
+        for (const match of region.matchAll(pattern)) {
+            const attrs = parseTemplateAttributes(match[1] ?? '');
+            if (!isIconOnly(attrs, match[2] ?? ''))
+                continue;
+            if (NAMING_ATTRIBUTES.some((name) => attrs.has(name)))
+                continue;
+            count++;
+        }
+    }
+    return count;
+}

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

@@ -49,7 +49,7 @@ export async function validateComponent(componentDir, tagName, type, config, roo
     // parameter, so this is a no-op for stock and override components.
     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 validateAccessibility(componentDir, tagName, customConfigForTag, config?.optInChecks)));
     issues.push(...(await validateCompatibility(componentDir, tagName, type, config, root)));
     if (root && config && type === 'override') {
         const forgeConfig = await loadConfig(root);

package/dist/src/core/harness-port-fallback.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `fireforge test --auto-ports` (or `test.mochitestPorts: "auto"`): let two
+ * checkouts run browser suites at the same time.
+ *
+ * Desktop `mach mochitest` has no `--http-port`/`--ssl-port` options; those
+ * exist only in the Android and iOS argument sets. What recent engines do
+ * have is a fallback inside `testing/mochitest/runtests.py`: before starting
+ * its servers the harness bind-probes the HTTP server, ssltunnel and
+ * WebSocket ports, and before launching the browser the Marionette port,
+ * and moves any that is busy to a free port, routing `mochi.test:8888`
+ * through its proxy to wherever the server actually landed. FireForge's
+ * own preflight refused before that fallback could run. In auto mode it
+ * steps aside for a holder that is not this checkout's own (a sibling
+ * checkout's live suite, or an unrelated listener), and keeps refusing for
+ * this checkout's own leftovers, exactly as in the default mode.
+ *
+ * Auto mode is opt-in, and it only takes effect when the engine's harness
+ * is seen to carry the fallback: on an engine without it, a busy port would
+ * still collide, so the default refusal stays in force there.
+ */
+import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type MarionettePortHolder } from './marionette-port.js';
+/** Which busy-port fallbacks the engine's mochitest harness carries. */
+export interface HarnessPortFallback {
+    /** HTTP server, ssltunnel and WebSocket ports (`startServers`). */
+    serverPorts: boolean;
+    /** The Marionette port (before the browser launch). */
+    marionettePort: boolean;
+}
+/**
+ * Reads the engine's `runtests.py` for the busy-port fallbacks. An
+ * unreadable file reports neither, which keeps the default refusal.
+ */
+export declare function detectHarnessPortFallback(engineDir: string): Promise<HarnessPortFallback>;
+/** True when the operator asked for auto ports, by flag or by config. */
+export declare function autoPortsRequested(options: TestOptions, config: FireForgeConfig): boolean;
+/**
+ * True when the holder's command line points into THIS checkout's engine
+ * directory: our own leftover, which auto mode never steps aside for.
+ */
+export declare function isThisCheckoutsHolder(holder: MarionettePortHolder, engineDir: string): boolean;
+/**
+ * Resolves the effective auto-ports posture for a browser run: what the
+ * engine's harness can fall back from, or `undefined` when auto mode is
+ * off or the engine cannot honour it (in which case the default refusal
+ * stays, and an explicit request says why).
+ */
+export declare function resolveAutoPorts(engineDir: string, options: TestOptions, config: FireForgeConfig): Promise<HarnessPortFallback | undefined>;
+/**
+ * Steps aside for a busy port the harness will fall back from. Returns true
+ * (after a notice naming the holder) when the port is held by anything that
+ * is not this checkout's own process, false when the port is free or the
+ * holder is ours, so the caller's normal preflight runs.
+ *
+ * @param port - The default port the harness would use
+ * @param label - Human name of the port for the notice
+ * @param engineDir - This checkout's engine directory
+ */
+export declare function deferBusyPortToHarness(port: number, label: string, engineDir: string): Promise<boolean>;

package/dist/src/core/harness-port-fallback.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge test --auto-ports` (or `test.mochitestPorts: "auto"`): let two
+ * checkouts run browser suites at the same time.
+ *
+ * Desktop `mach mochitest` has no `--http-port`/`--ssl-port` options; those
+ * exist only in the Android and iOS argument sets. What recent engines do
+ * have is a fallback inside `testing/mochitest/runtests.py`: before starting
+ * its servers the harness bind-probes the HTTP server, ssltunnel and
+ * WebSocket ports, and before launching the browser the Marionette port,
+ * and moves any that is busy to a free port, routing `mochi.test:8888`
+ * through its proxy to wherever the server actually landed. FireForge's
+ * own preflight refused before that fallback could run. In auto mode it
+ * steps aside for a holder that is not this checkout's own (a sibling
+ * checkout's live suite, or an unrelated listener), and keeps refusing for
+ * this checkout's own leftovers, exactly as in the default mode.
+ *
+ * Auto mode is opt-in, and it only takes effect when the engine's harness
+ * is seen to carry the fallback: on an engine without it, a busy port would
+ * still collide, so the default refusal stays in force there.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { notice } from '../utils/logger.js';
+import { isExplicitAbsolutePath, isPathInsideRoot } from '../utils/paths.js';
+import { probeMarionettePort } from './marionette-port.js';
+const RUNTESTS_PATH = 'testing/mochitest/runtests.py';
+/**
+ * Reads the engine's `runtests.py` for the busy-port fallbacks. An
+ * unreadable file reports neither, which keeps the default refusal.
+ */
+export async function detectHarnessPortFallback(engineDir) {
+    let source;
+    try {
+        source = await readFile(join(engineDir, RUNTESTS_PATH), 'utf8');
+    }
+    catch {
+        return { serverPorts: false, marionettePort: false };
+    }
+    const fallsBack = /falling back to port/.test(source);
+    return {
+        serverPorts: fallsBack && /\("httpPort",/.test(source) && /_port_in_use\(port\)/.test(source),
+        marionettePort: fallsBack && /_port_in_use\(marionette_port\)/.test(source),
+    };
+}
+/** True when the operator asked for auto ports, by flag or by config. */
+export function autoPortsRequested(options, config) {
+    return options.autoPorts === true || config.test?.mochitestPorts === 'auto';
+}
+/**
+ * True when the holder's command line points into THIS checkout's engine
+ * directory: our own leftover, which auto mode never steps aside for.
+ */
+export function isThisCheckoutsHolder(holder, engineDir) {
+    return holder.commandLine
+        .split(/\s+/)
+        .filter(isExplicitAbsolutePath)
+        .some((token) => isPathInsideRoot(engineDir, token));
+}
+/**
+ * Resolves the effective auto-ports posture for a browser run: what the
+ * engine's harness can fall back from, or `undefined` when auto mode is
+ * off or the engine cannot honour it (in which case the default refusal
+ * stays, and an explicit request says why).
+ */
+export async function resolveAutoPorts(engineDir, options, config) {
+    if (!autoPortsRequested(options, config))
+        return undefined;
+    const fallback = await detectHarnessPortFallback(engineDir);
+    if (!fallback.serverPorts && !fallback.marionettePort) {
+        notice(`Auto ports requested, but engine/${RUNTESTS_PATH} has no busy-port fallback, so a busy ` +
+            'mochitest or Marionette port is still refused as in the default mode.');
+        return undefined;
+    }
+    return fallback;
+}
+/**
+ * Steps aside for a busy port the harness will fall back from. Returns true
+ * (after a notice naming the holder) when the port is held by anything that
+ * is not this checkout's own process, false when the port is free or the
+ * holder is ours, so the caller's normal preflight runs.
+ *
+ * @param port - The default port the harness would use
+ * @param label - Human name of the port for the notice
+ * @param engineDir - This checkout's engine directory
+ */
+export async function deferBusyPortToHarness(port, label, engineDir) {
+    const probe = await probeMarionettePort(port);
+    if (!probe.inUse || !probe.holder)
+        return false;
+    if (isThisCheckoutsHolder(probe.holder, engineDir))
+        return false;
+    notice(`${label} port ${port} is held by ${probe.holder.command} (PID ${probe.holder.pid}), which is ` +
+        "not this checkout's. Auto ports: the harness moves this run to a free port instead.");
+    return true;
+}

package/dist/src/core/history-log-file.d.ts

@@ -0,0 +1,61 @@
+/** Filename of the history log at its pre-0.50 location, inside `patches/`. */
+export declare const LEGACY_HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
+/** Default history log location, relative to the project root. */
+export declare const DEFAULT_HISTORY_LOG_PATH: string;
+/** Environment variable a caller sets to tag every record of its session. */
+export declare const HISTORY_SESSION_ENV = "FIREFORGE_SESSION_ID";
+/** Who wrote a history record. */
+export interface HistoryRecordIdentity {
+    /** One id per FireForge process: every record one command writes shares it. */
+    invocationId: string;
+    /** The caller's `FIREFORGE_SESSION_ID`, when set. */
+    sessionId?: string;
+    pid: number;
+    ppid: number;
+}
+/**
+ * Identity fields stamped on every history record: one id per FireForge
+ * process (every record one command writes shares it), the process and its
+ * parent, and the caller's `FIREFORGE_SESSION_ID` when set. The parent PID
+ * is a weak hint (usually the shell); the environment variable is the
+ * reliable way for a session to tag its own lines.
+ */
+export declare function historyRecordIdentity(): HistoryRecordIdentity;
+/**
+ * Resolves the history log path for a project.
+ *
+ * @param projectRoot - Project root containing `fireforge.json`
+ * @returns Absolute path of the history log
+ */
+export declare function resolveHistoryLogPath(projectRoot: string): Promise<string>;
+/**
+ * Moves a history log left at the legacy `patches/` path to `target`.
+ *
+ * Records are never dropped, whatever else is happening:
+ * - The legacy file is first claimed by renaming it aside, so of two
+ *   commands migrating at once exactly one does the work and neither
+ *   duplicates it.
+ * - When `target` does not exist yet (the first run), the claimed file is
+ *   hard-linked into place, which cannot overwrite a log another command
+ *   created in the meantime, and keeps a large log a constant-time move.
+ * - When both exist (an older FireForge appended to the legacy path after
+ *   a migration, or `history.path` changed), the legacy records are
+ *   appended to the target in one write. They then follow newer records;
+ *   every record carries its own `ts`.
+ *
+ * A crash between the claim and the move leaves the records in a
+ * `.migrating-*` file next to the legacy path, never deleted.
+ *
+ * @param patchesDir - The patches directory that may hold a legacy log
+ * @param target - Absolute path of the history log
+ */
+export declare function migrateLegacyHistoryLog(patchesDir: string, target: string): Promise<void>;
+/**
+ * Appends one serialized record to the project's history log, migrating a
+ * legacy log first.
+ *
+ * @param patchesDir - The project's `patches/` directory; the project root is
+ *   its parent, as every caller derives it from `getProjectPaths`
+ * @param line - One JSON record, without the trailing newline
+ */
+export declare function appendHistoryLine(patchesDir: string, line: string): Promise<void>;