@hominis/fireforge 0.51.0 → 0.53.0

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

@@ -11,7 +11,7 @@
 import { FurnaceError } from '../errors/furnace.js';
 import { FURNACE_OPT_IN_CHECKS, } from '../types/furnace.js';
 import { isArray, isObject, isString } from '../utils/validation.js';
-const EXCEPTION_KEYS = new Set(['component', 'check', 'tag', 'reason']);
+const EXCEPTION_KEYS = new Set(['component', 'check', 'tag', 'file', 'reason']);
 function requireNonEmptyString(entry, key, field) {
     const value = entry[key];
     if (!isString(value) || value.trim().length === 0) {
@@ -20,9 +20,10 @@ function requireNonEmptyString(entry, key, field) {
     return value;
 }
 /**
- * Parses `validationExceptions[]`: `{ component, check, tag?, reason }`
- * objects, no other keys, every field a non-empty string, and no two
- * entries for the same component, check and tag.
+ * Parses `validationExceptions[]`: `{ component, check, tag?, file?, reason }`
+ * objects, no other keys, every field a non-empty string, at most one of
+ * `tag` and `file` (a bare file name of the component), and no two entries
+ * for the same component, check and scope.
  */
 export function parseValidationExceptions(raw) {
     if (!isArray(raw)) {
@@ -46,9 +47,28 @@ export function parseValidationExceptions(raw) {
         };
         if (entry['tag'] !== undefined)
             exception.tag = requireNonEmptyString(entry, 'tag', field);
-        const identity = `${exception.component}\u0000${exception.check}\u0000${exception.tag ?? ''}`;
+        if (entry['file'] !== undefined) {
+            if (exception.tag !== undefined) {
+                throw new FurnaceError(`Furnace config: "${field}" may name a "tag" or a "file", not both`);
+            }
+            const file = requireNonEmptyString(entry, 'file', field);
+            if (/[\\/]/.test(file) || file === '.' || file === '..') {
+                throw new FurnaceError(`Furnace config: "${field}.file" must be a file name in the component's directory, not a path`);
+            }
+            exception.file = file;
+        }
+        const scope = exception.tag !== undefined
+            ? `tag:${exception.tag}`
+            : exception.file !== undefined
+                ? `file:${exception.file}`
+                : '';
+        const identity = `${exception.component}\u0000${exception.check}\u0000${scope}`;
         if (seen.has(identity)) {
-            const on = exception.tag !== undefined ? ` on <${exception.tag}>` : '';
+            const on = exception.tag !== undefined
+                ? ` on <${exception.tag}>`
+                : exception.file !== undefined
+                    ? ` in ${exception.file}`
+                    : '';
             throw new FurnaceError(`Furnace config: "${field}" repeats the exception for ${exception.component} [${exception.check}]${on}`);
         }
         seen.add(identity);

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

@@ -305,11 +305,11 @@ export async function completeJournalRollback(ctx, journal, error, options) {
 export async function forceReleaseFurnaceLocksForActiveOperations() {
     const paths = new Set([...activeOperations.values()].map((op) => getFurnaceLockPath(op.root)));
     for (const lockPath of paths) {
-        // Ownership-checked, like every other release path. The bare `rm` this
-        // replaced would delete a lock a different process had acquired in the
-        // window between our operation dying and this sweep running. That is the
-        // exact race `releaseLock`'s PID verification was added to close, reopened
-        // here because the sweeper has no acquisition token to check.
+        // Ownership-checked, like every other release path. A bare `rm` would
+        // delete a lock a different process had acquired in the window between
+        // our operation dying and this sweep running. That is the exact race
+        // `releaseLock`'s PID verification closes, and the sweeper has no
+        // acquisition token to check.
         const removed = await releaseLockIfOwned(lockPath);
         verbose(removed
             ? `Removed furnace lock at ${lockPath} during signal teardown`

package/dist/src/core/furnace-registration-jar-inplace.js

@@ -2,10 +2,9 @@
 /**
  * In-place edits to a widget's `toolkit/content/jar.mn` block.
  *
- * Undeploying one file and renaming a component used to drop every line of
- * the widget and re-add the live ones, which re-sorted the whole block and
- * left the owning patch carrying reorder hunks. These helpers touch only
- * the lines that change: a deleted file's line goes, a renamed component's
+ * Dropping every line of the widget and re-adding the live ones would
+ * re-sort the whole block and leave the owning patch carrying reorder
+ * hunks. These helpers touch only the lines that change: a deleted file's line goes, a renamed component's
  * lines are rewritten where they stand, and anything still missing is left
  * for `addJarMnEntries` to insert.
  */
@@ -15,8 +14,8 @@ import { escapeRegex } from '../utils/regex.js';
 import { JAR_MN } from './furnace-constants.js';
 /**
  * The file a widget jar.mn line registers: the `(widgets/<tag>/<file>)`
- * source mapping, or the legacy `content/global/elements/<tag>.<ext>`
- * target written before the mapping existed. Undefined when the line is
+ * source mapping, or the `content/global/elements/<tag>.<ext>` target of a
+ * line that carries no source mapping. Undefined when the line is
  * not one of this tag's.
  */
 function registeredFile(line, tagName) {

package/dist/src/core/furnace-registration-rename.d.ts

@@ -1,11 +1,11 @@
 /**
  * In-place rename of a custom element registration in customElements.js.
  *
- * `furnace rename` used to remove the old entry and add a new one. On a
- * registration list the remove path could not see, that left the old entry
- * beside the new one, and the new entry was written without the project
- * marker every sibling line carries (`// <MARKER>:`), so the next lint
- * flagged it as an unmarked engine edit. Rewriting the tag and module
+ * Removing the old entry and adding a new one would, on a registration
+ * list the remove path cannot see, leave the old entry beside the new one,
+ * and the new entry would lack the project marker every sibling line
+ * carries (`// <MARKER>:`), so the next lint would flag it as an unmarked
+ * engine edit. Rewriting the tag and module
  * literals inside the existing entry keeps the entry's position, layout and
  * trailing marker comments exactly as they were.
  */

package/dist/src/core/furnace-registration-rename.js

@@ -2,11 +2,11 @@
 /**
  * In-place rename of a custom element registration in customElements.js.
  *
- * `furnace rename` used to remove the old entry and add a new one. On a
- * registration list the remove path could not see, that left the old entry
- * beside the new one, and the new entry was written without the project
- * marker every sibling line carries (`// <MARKER>:`), so the next lint
- * flagged it as an unmarked engine edit. Rewriting the tag and module
+ * Removing the old entry and adding a new one would, on a registration
+ * list the remove path cannot see, leave the old entry beside the new one,
+ * and the new entry would lack the project marker every sibling line
+ * carries (`// <MARKER>:`), so the next lint would flag it as an unmarked
+ * engine edit. Rewriting the tag and module
  * literals inside the existing entry keeps the entry's position, layout and
  * trailing marker comments exactly as they were.
  */

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

@@ -1,6 +1,7 @@
 /**
  * Shared validation for furnace custom element registration placement.
- * Used after both AST and legacy code paths to avoid duplicating logic.
+ * Shared by the AST registration editor and the registration validator to
+ * avoid duplicating logic.
  */
 /**
  * Regex for valid custom element tag names. A valid name is lowercase, starts

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

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Shared validation for furnace custom element registration placement.
- * Used after both AST and legacy code paths to avoid duplicating logic.
+ * Shared by the AST registration editor and the registration validator to
+ * avoid duplicating logic.
  */
 import { FurnaceError } from '../errors/furnace.js';
 import { escapeRegex, stripJsComments } from '../utils/regex.js';

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

@@ -252,8 +252,8 @@ export async function removeJarMnEntries(engineDir, tagName) {
     // line the component registered is removed regardless of the target
     // basename. A helper `.mjs` whose name does not start with the tag (e.g.
     // a renamed `foo-utils.mjs`) otherwise survives the remove pass and leaves
-    // a stale registration that breaks packaging. The legacy target-path match
-    // is kept as an OR for lines written before the source mapping existed.
+    // a stale registration that breaks packaging. The target-path match is
+    // kept as an OR for lines that carry no source mapping.
     // Word boundaries keep "moz-card" from matching "moz-card-group".
     const sourcePattern = new RegExp(`\\(widgets/${escapeRegex(tagName)}/`);
     const legacyTargetPattern = new RegExp(`content/global/elements/${escapeRegex(tagName)}\\.`);

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

@@ -34,6 +34,6 @@ export declare function validateAccessibility(componentDir: string, tagName: str
  *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
  *
  * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
- * findings (matches the pre-existing escape hatch).
+ * findings in that file (matches the pre-existing escape hatch).
  */
 export declare function containsHardcodedTemplateText(content: string): boolean;

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

@@ -11,8 +11,9 @@ import { collectLitTemplateRegions, parseTemplateAttributes } from './lit-templa
  * 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`);
+async function readComposedComponentModules(componentDir, tagName) {
+    const hostName = `${tagName}.mjs`;
+    const hostPath = join(componentDir, hostName);
     if (!(await pathExists(hostPath)))
         return undefined;
     const entries = await readdir(componentDir).catch(() => []);
@@ -21,10 +22,11 @@ async function readComposedComponentSource(componentDir, 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');
+    const modules = [{ name: hostName, content: await readText(hostPath) }];
+    for (const name of companions) {
+        modules.push({ name, content: await readText(join(componentDir, name)) });
+    }
+    return modules;
 }
 /**
  * Validates accessibility patterns in a component's composed source: its
@@ -44,9 +46,10 @@ async function readComposedComponentSource(componentDir, tagName) {
  *   adds the icon-only `<moz-button>` naming check.
  */
 export async function validateAccessibility(componentDir, tagName, customConfig, optInChecks = []) {
-    const content = await readComposedComponentSource(componentDir, tagName);
-    if (content === undefined)
+    const modules = await readComposedComponentModules(componentDir, tagName);
+    if (modules === undefined)
         return [];
+    const content = modules.map((module) => module.content).join('\n');
     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.'));
@@ -72,8 +75,16 @@ export async function validateAccessibility(componentDir, tagName, customConfig,
             tags: syntheticTags,
         });
     }
-    if (containsHardcodedTemplateText(content)) {
-        issues.push(createIssue(tagName, 'warning', 'hardcoded-text', 'Possible hardcoded string found. Use data-l10n-id for localization.'));
+    // Judged per module, so the finding names its files and an exception can
+    // accept one module (a vendored bundle) without muting the others.
+    const textFiles = modules
+        .filter((module) => containsHardcodedTemplateText(module.content))
+        .map((module) => module.name);
+    if (textFiles.length > 0) {
+        issues.push({
+            ...createIssue(tagName, 'warning', 'hardcoded-text', `Possible hardcoded string found in ${textFiles.join(', ')}. Use data-l10n-id for localization.`),
+            files: textFiles,
+        });
     }
     const isInteractive = hasClick || hasKeyboardHandler;
     if (isInteractive && !hasDelegatesFocusEnabled(content)) {
@@ -337,7 +348,7 @@ function isWithinLocalizedElement(content, matchIndex) {
  *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
  *
  * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
- * findings (matches the pre-existing escape hatch).
+ * findings in that file (matches the pre-existing escape hatch).
  */
 export function containsHardcodedTemplateText(content) {
     if (/furnace-ignore:\s*hardcoded-text/.test(content)) {

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

@@ -2,7 +2,8 @@
  * 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
+ * sibling tag entries) cover, or with `file`, a finding whose module files
+ * it (and its sibling file 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`.

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

@@ -6,19 +6,34 @@ export const EXCEPTION_ON_ERROR_CHECK = 'validation-exception-on-error';
 function matches(exception, issue) {
     return exception.component === issue.component && exception.check === issue.check;
 }
+/** An exception's narrowing: the finding field it reads and its value. */
+function scopeOf(entry) {
+    if (entry.tag !== undefined)
+        return { key: 'tags', value: entry.tag };
+    if (entry.file !== undefined)
+        return { key: 'files', value: entry.file };
+    return undefined;
+}
 /**
- * The exceptions that suppress a warning: an untagged one alone, or tagged
- * ones that together cover every tag the finding names.
+ * The exceptions that suppress a warning: an unscoped one alone, or scoped
+ * ones that together cover every tag (or every file) 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)] : [];
+    const unscoped = candidates.find((entry) => scopeOf(entry) === undefined);
+    if (unscoped !== undefined)
+        return [unscoped];
+    for (const key of ['tags', 'files']) {
+        const named = issue[key] ?? [];
+        if (named.length === 0)
+            continue;
+        const covering = named.map((value) => candidates.find((entry) => {
+            const scope = scopeOf(entry);
+            return scope?.key === key && scope.value === value;
+        }));
+        if (covering.every((entry) => entry !== undefined))
+            return [...new Set(covering)];
+    }
+    return [];
 }
 /**
  * Splits findings into counted and excepted, and reports stale exceptions.
@@ -47,11 +62,14 @@ export function applyValidationExceptions(issues, exceptions, judged) {
         }
         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.
+            // A scoped exception that covers some of the tags (or files) 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)
+                const scope = scopeOf(entry);
+                if (scope !== undefined && issue[scope.key]?.includes(scope.value) === true) {
                     used.add(entry);
+                }
             }
             outcome.issues.push(issue);
             continue;

package/dist/src/core/git-base.js

@@ -45,9 +45,10 @@ export const GIT_ADD_CHUNK_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_CHUNK_TIME
 /**
  * In-flight or settled successful `git` availability probe.
  *
- * The probe spawns `which git` (or `where` on Windows), and every git wrapper
- * in this layer used to run it before each command, which meant dozens of
- * extra spawns per `fireforge export`. Only success is cached: a rejection
+ * The probe spawns `which git` (or `where` on Windows); running it before
+ * every command would mean dozens of extra spawns per `fireforge export`, so
+ * the result is shared by every git wrapper in this layer. Only success is
+ * cached: a rejection
  * clears the slot so a run that installs git mid-flight (or a test that flips
  * the probe) sees the new answer instead of a sticky refusal.
  */

package/dist/src/core/git-diff.js

@@ -521,7 +521,7 @@ async function generateBinaryFilePatchWithConfig(repoDir, filePath, gitConfigArg
  * "absent", and this branch only runs for files untracked in HEAD). A prior
  * stage-0 entry is re-pointed at its recorded mode and blob. Unmerged entries
  * (stages 1 to 3) cannot be rebuilt through `--cacheinfo`. That degenerate
- * state keeps the legacy reset-to-HEAD behavior rather than corrupting the
+ * state falls back to the reset-to-HEAD restore rather than corrupting the
  * conflict.
  * @param repoDir - Repository directory
  * @param filePath - File path (relative to repo root)

package/dist/src/core/git.js

@@ -46,7 +46,7 @@ const GIT_ADD_ENV = { GIT_INDEX_THREADS: '0' };
  * AbortError when the signal fires, so both shapes have to be recognised.
  */
 function isTimeoutError(error) {
-    // `exec` now rejects with a typed ExecTimeoutError when its `timeout`
+    // `exec` rejects with a typed ExecTimeoutError when its `timeout`
     // option fires (the raw AbortError check below is kept for defence in
     // depth against other abort paths).
     if (error instanceof ExecTimeoutError)

package/dist/src/core/harness-orphans.d.ts

@@ -45,12 +45,12 @@ export interface OrphanedHarnessProcess {
  * True when `command` IS a harness helper: its executable is a helper
  * binary, or an interpreter whose first argument is a helper script.
  *
- * Structural on purpose. An earlier version matched the helper names
- * anywhere in the command line, which is right for the httpd (`xpcshell -g
- * … -f …/server.js`) and wrong for everything that merely mentions such a
- * path: an editor opened on `server.js`, a shell whose command text quotes
- * it, a `grep` over the objdir. Report-only, that printed a misleading
- * `kill`; under the reap posture it terminated the operator's shell.
+ * Structural on purpose. Matching the helper names anywhere in the command
+ * line is right for the httpd (`xpcshell -g … -f …/server.js`) and wrong for
+ * everything that merely mentions such a path: an editor opened on
+ * `server.js`, a shell whose command text quotes it, a `grep` over the
+ * objdir. Report-only, that would print a misleading `kill`; under the reap
+ * posture it would terminate the operator's shell.
  */
 export declare function matchesHarnessHelper(command: string): boolean;
 /** Objdir provenance: an explicit objdir path, a `obj-…` path segment, or `_tests/`. */

package/dist/src/core/harness-orphans.js

@@ -55,12 +55,12 @@ function basename(token) {
  * True when `command` IS a harness helper: its executable is a helper
  * binary, or an interpreter whose first argument is a helper script.
  *
- * Structural on purpose. An earlier version matched the helper names
- * anywhere in the command line, which is right for the httpd (`xpcshell -g
- * … -f …/server.js`) and wrong for everything that merely mentions such a
- * path: an editor opened on `server.js`, a shell whose command text quotes
- * it, a `grep` over the objdir. Report-only, that printed a misleading
- * `kill`; under the reap posture it terminated the operator's shell.
+ * Structural on purpose. Matching the helper names anywhere in the command
+ * line is right for the httpd (`xpcshell -g … -f …/server.js`) and wrong for
+ * everything that merely mentions such a path: an editor opened on
+ * `server.js`, a shell whose command text quotes it, a `grep` over the
+ * objdir. Report-only, that would print a misleading `kill`; under the reap
+ * posture it would terminate the operator's shell.
  */
 export function matchesHarnessHelper(command) {
     const [exe, first] = command.trim().split(/\s+/);

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

@@ -0,0 +1,60 @@
+/**
+ * Mochitest server ports for `fireforge test --jobs <n>`: placeholder
+ * listeners that push every parallel harness instance onto its own ports,
+ * and the parse of the ports each instance actually took.
+ *
+ * Desktop `mach mochitest` has no `--http-port`, `--ssl-port` or
+ * `--websocket-port`. Its `startServers` (`testing/mochitest/runtests.py`)
+ * bind-probes the HTTP server, ssltunnel and WebSocket ports (8888, 4443,
+ * 9988) and moves only a busy one to a free port; see
+ * `harness-port-fallback.ts`. Instances started at the same moment all
+ * pass that probe on a free 8888, then race to bind it: the losers die with
+ * `could not start server on port 8888` before any test runs. Holding the
+ * three ports for the whole parallel run makes every instance's probe fail,
+ * so each one falls back to an OS-assigned port of its own.
+ */
+/** Which mochitest server a port belongs to, as the verdict line names it. */
+export type HarnessServerPortKey = 'http' | 'ssl' | 'ws';
+/** Placeholder listeners held for a parallel run. */
+export interface HarnessPortReservation {
+    /** Ports this process now holds. A port that was already busy is not listed. */
+    held: number[];
+    /** Closes every placeholder. Safe to call more than once. */
+    release(): Promise<void>;
+}
+/**
+ * Holds a placeholder listener on `127.0.0.1` on each mochitest server
+ * port, so the harness's busy-port probe moves every instance elsewhere.
+ * A port that cannot be bound is skipped, not refused: whatever holds it
+ * already makes the probe fail, which is all the placeholder is for (the
+ * preflight has already ruled out this checkout's own stale httpd).
+ *
+ * @param ports - Ports to hold (default: {@link HARNESS_SERVER_PORTS})
+ */
+export declare function reserveHarnessServerPorts(ports?: readonly number[]): Promise<HarnessPortReservation>;
+/** The server ports one harness invocation reported, by server. */
+export type HarnessServerPorts = Partial<Record<HarnessServerPortKey, number>>;
+/**
+ * Records the port one output line reports, if it reports one: the
+ * fallback port of a "falling back" line, or the port itself otherwise.
+ *
+ * @param line - One line of harness output
+ * @param into - Collected ports; a later line for the same server wins
+ */
+export declare function recordHarnessServerPortLine(line: string, into: HarnessServerPorts): void;
+/** Collects server ports from streamed output chunks. */
+export interface HarnessPortTracker {
+    onChunk(stream: 'stdout' | 'stderr', chunk: string): void;
+    /** The ports seen so far, including an unterminated last line. */
+    ports(): HarnessServerPorts;
+}
+/**
+ * A tracker over the full output stream. The ports are printed at harness
+ * start, so the capped capture tail a long run keeps would lose them.
+ */
+export declare function createHarnessPortTracker(): HarnessPortTracker;
+/**
+ * The `http:N,ssl:N,ws:N` value of a `ports=` key, in probe order, or
+ * undefined when no port is known.
+ */
+export declare function formatHarnessServerPorts(ports: HarnessServerPorts | undefined): string | undefined;

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

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Mochitest server ports for `fireforge test --jobs <n>`: placeholder
+ * listeners that push every parallel harness instance onto its own ports,
+ * and the parse of the ports each instance actually took.
+ *
+ * Desktop `mach mochitest` has no `--http-port`, `--ssl-port` or
+ * `--websocket-port`. Its `startServers` (`testing/mochitest/runtests.py`)
+ * bind-probes the HTTP server, ssltunnel and WebSocket ports (8888, 4443,
+ * 9988) and moves only a busy one to a free port; see
+ * `harness-port-fallback.ts`. Instances started at the same moment all
+ * pass that probe on a free 8888, then race to bind it: the losers die with
+ * `could not start server on port 8888` before any test runs. Holding the
+ * three ports for the whole parallel run makes every instance's probe fail,
+ * so each one falls back to an OS-assigned port of its own.
+ */
+import { createServer } from 'node:net';
+/**
+ * The ports `startServers` probes, in the order it probes them. Desktop
+ * mochitest cannot configure them, so the engine defaults are the ports.
+ */
+const HARNESS_SERVER_PORTS = [
+    { key: 'http', port: 8888, label: 'HTTP test server' },
+    { key: 'ssl', port: 4443, label: 'ssltunnel' },
+    { key: 'ws', port: 9988, label: 'WebSocket server' },
+];
+/** Listens on `127.0.0.1:port`, or resolves undefined when the bind fails. */
+async function holdPort(port) {
+    return new Promise((resolve) => {
+        const server = createServer((socket) => {
+            // Nothing should connect: the harness only probes with a bind. Anyone
+            // who does gets a closed socket instead of a hang.
+            socket.destroy();
+        });
+        server.once('error', () => {
+            resolve(undefined);
+        });
+        server.listen({ port, host: '127.0.0.1', exclusive: true }, () => {
+            server.unref();
+            resolve(server);
+        });
+    });
+}
+/**
+ * Holds a placeholder listener on `127.0.0.1` on each mochitest server
+ * port, so the harness's busy-port probe moves every instance elsewhere.
+ * A port that cannot be bound is skipped, not refused: whatever holds it
+ * already makes the probe fail, which is all the placeholder is for (the
+ * preflight has already ruled out this checkout's own stale httpd).
+ *
+ * @param ports - Ports to hold (default: {@link HARNESS_SERVER_PORTS})
+ */
+export async function reserveHarnessServerPorts(ports = HARNESS_SERVER_PORTS.map((spec) => spec.port)) {
+    const servers = (await Promise.all(ports.map(holdPort))).filter((server) => server !== undefined);
+    const held = servers.map((server) => {
+        const address = server.address();
+        return typeof address === 'object' && address !== null ? address.port : 0;
+    });
+    let released = false;
+    return {
+        held,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await Promise.all(servers.map((server) => new Promise((resolve) => {
+                server.close(() => {
+                    resolve();
+                });
+            })));
+        },
+    };
+}
+const PORT_LINE_PATTERN = /\b(HTTP test server|ssltunnel|WebSocket server) port (\d+)(?: already in use, falling back to port (\d+))?/;
+/**
+ * Records the port one output line reports, if it reports one: the
+ * fallback port of a "falling back" line, or the port itself otherwise.
+ *
+ * @param line - One line of harness output
+ * @param into - Collected ports; a later line for the same server wins
+ */
+export function recordHarnessServerPortLine(line, into) {
+    const match = PORT_LINE_PATTERN.exec(line);
+    if (match === null)
+        return;
+    const spec = HARNESS_SERVER_PORTS.find((entry) => entry.label === match[1]);
+    const port = Number.parseInt(match[3] ?? match[2] ?? '', 10);
+    if (spec !== undefined && Number.isInteger(port))
+        into[spec.key] = port;
+}
+/**
+ * A tracker over the full output stream. The ports are printed at harness
+ * start, so the capped capture tail a long run keeps would lose them.
+ */
+export function createHarnessPortTracker() {
+    const collected = {};
+    const pending = { stdout: '', stderr: '' };
+    return {
+        onChunk(stream, chunk) {
+            const lines = `${pending[stream]}${chunk}`.split(/\r?\n/);
+            pending[stream] = lines.pop() ?? '';
+            for (const line of lines)
+                recordHarnessServerPortLine(line, collected);
+        },
+        ports() {
+            const result = { ...collected };
+            recordHarnessServerPortLine(pending.stdout, result);
+            recordHarnessServerPortLine(pending.stderr, result);
+            return result;
+        },
+    };
+}
+/**
+ * The `http:N,ssl:N,ws:N` value of a `ports=` key, in probe order, or
+ * undefined when no port is known.
+ */
+export function formatHarnessServerPorts(ports) {
+    if (ports === undefined)
+        return undefined;
+    const parts = HARNESS_SERVER_PORTS.flatMap(({ key }) => ports[key] === undefined ? [] : [`${key}:${ports[key]}`]);
+    return parts.length > 0 ? parts.join(',') : undefined;
+}

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

@@ -1,4 +1,4 @@
-/** Filename of the history log at its pre-0.50 location, inside `patches/`. */
+/** Filename of a history log inside `patches/`, which is moved out of the queue. */
 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;
@@ -29,30 +29,30 @@ export declare function historyRecordIdentity(): HistoryRecordIdentity;
  */
 export declare function resolveHistoryLogPath(projectRoot: string): Promise<string>;
 /**
- * Moves a history log left at the legacy `patches/` path to `target`.
+ * Moves a history log found at the `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
+ * - The in-queue 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
+ * - When both exist (a log reappeared at the `patches/` path after a
+ *   migration, or `history.path` changed), the in-queue 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.
+ * `.migrating-*` file next to the in-queue path, never deleted.
  *
- * @param patchesDir - The patches directory that may hold a legacy log
+ * @param patchesDir - The patches directory that may hold an in-queue 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.
+ * Appends one serialized record to the project's history log, first moving
+ * a log found inside `patches/`.
  *
  * @param patchesDir - The project's `patches/` directory; the project root is
  *   its parent, as every caller derives it from `getProjectPaths`