@hominis/fireforge 0.52.0 → 0.53.0

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/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`

package/dist/src/core/history-log-file.js

@@ -2,12 +2,12 @@
 /**
  * Where the patch history log lives, and who wrote each record.
  *
- * The log used to be `patches/.fireforge-history.jsonl`, inside the tracked
- * patch queue, so it was committed with every export until consumers
- * gitignored it, and it grew to tens of megabytes. It now defaults to
- * `.fireforge/history.jsonl` (FireForge's own untracked data directory), or
- * `fireforge.json#history.path` when a project sets one. A log left at the
- * old path is moved on the first append.
+ * The log defaults to `.fireforge/history.jsonl` (FireForge's own untracked
+ * data directory), or `fireforge.json#history.path` when a project sets one.
+ * It stays out of the tracked patch queue because it grows to tens of
+ * megabytes and would otherwise be committed with every export. A log found
+ * at `patches/.fireforge-history.jsonl`, inside the queue, is moved on the
+ * first append.
  *
  * Several sessions sharing one checkout all append to the same log, so each
  * record carries the invocation that wrote it, plus a session hint, letting
@@ -21,7 +21,7 @@ import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, verbose } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { isValidHistoryPath } from './config-validate-history.js';
-/** 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 const LEGACY_HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
 /** Default history log location, relative to the project root. */
 export const DEFAULT_HISTORY_LOG_PATH = join(FIREFORGE_DIR, 'history.jsonl');
@@ -87,24 +87,24 @@ export async function resolveHistoryLogPath(projectRoot) {
     return resolve(projectRoot, configured ?? DEFAULT_HISTORY_LOG_PATH);
 }
 /**
- * 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 async function migrateLegacyHistoryLog(patchesDir, target) {
@@ -149,8 +149,8 @@ export async function migrateLegacyHistoryLog(patchesDir, target) {
         'Nothing reads it back; it is an audit trail only.');
 }
 /**
- * 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`

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

@@ -3,13 +3,13 @@ import type { HistoryEntry } from './destructive.js';
  * Appends a history entry for a mutation that has already committed, degrading
  * to a warning when the log cannot be written.
  *
- * Eleven call sites across `export-flow` and the `patch` subcommands had each
- * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * This is the one `try { await appendHistory(...) } catch { warn(...) }`
+ * block for every call site across `export-flow` and the `patch` subcommands.
  * The swallow is intentional: the patch files and the manifest
  * are already on disk by the time this runs, so letting a failed log write
  * reject would report a completed, irreversible mutation as a failure and send
  * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it now lives in one place.
+ * easy to lose in a copy, it lives in one place.
  * @param patchesDir - The project's `patches/` directory (the log itself lives
  *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.

package/dist/src/core/history-log.js

@@ -6,13 +6,13 @@ import { appendHistory } from './destructive.js';
  * Appends a history entry for a mutation that has already committed, degrading
  * to a warning when the log cannot be written.
  *
- * Eleven call sites across `export-flow` and the `patch` subcommands had each
- * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * This is the one `try { await appendHistory(...) } catch { warn(...) }`
+ * block for every call site across `export-flow` and the `patch` subcommands.
  * The swallow is intentional: the patch files and the manifest
  * are already on disk by the time this runs, so letting a failed log write
  * reject would report a completed, irreversible mutation as a failure and send
  * the operator looking for damage that is not there. Because that reasoning is
- * easy to lose in a copy, it now lives in one place.
+ * easy to lose in a copy, it lives in one place.
  * @param patchesDir - The project's `patches/` directory (the log itself lives
  *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.

package/dist/src/core/launchable-build.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Facts about the launchable build a test run will exercise: its build id
+ * and when its compiled code was last linked.
+ *
+ * A green or red against a binary older than the C++ under test reads as a
+ * verdict on that C++ unless the run says which binary it was. The
+ * build id goes on the verdict line (`build-id=`), and the link time anchors
+ * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
+ * `test-stale-check.ts`).
+ */
+/**
+ * The `application.ini` beside a launchable binary: `Contents/Resources`
+ * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
+ * elsewhere.
+ *
+ * @param binaryPath - Absolute launchable binary path
+ */
+export declare function applicationIniPath(binaryPath: string): string;
+/**
+ * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
+ * browser reports). Undefined when the file or the key is missing, so a
+ * caller can simply leave the attribute off.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export declare function readBuildId(engineDir: string, launchablePath: string): Promise<string | undefined>;
+/**
+ * When the launchable build's compiled code was last linked: the newest
+ * mtime of the binary and the `libxul` beside it. Undefined when neither
+ * can be read.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export declare function readLinkedAt(engineDir: string, launchablePath: string): Promise<{
+    mtimeMs: number;
+    path: string;
+} | undefined>;

package/dist/src/core/launchable-build.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Facts about the launchable build a test run will exercise: its build id
+ * and when its compiled code was last linked.
+ *
+ * A green or red against a binary older than the C++ under test reads as a
+ * verdict on that C++ unless the run says which binary it was. The
+ * build id goes on the verdict line (`build-id=`), and the link time anchors
+ * the stale-compiled preflight (`findCompiledSourcesNewerThanBinary` in
+ * `test-stale-check.ts`).
+ */
+import { stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+/**
+ * The compiled libraries a build links next to the launchable binary.
+ * `libxul` carries nearly all compiled engine code (C++, Rust, generated
+ * bindings, prefs), so it, not the small launcher executable, is what a
+ * compiled-source edit relinks.
+ */
+const LINKED_LIBRARY_NAMES = ['XUL', 'libxul.so', 'xul.dll'];
+/**
+ * The `application.ini` beside a launchable binary: `Contents/Resources`
+ * of the `.app` bundle on macOS, the binary's own directory (`dist/bin`)
+ * elsewhere.
+ *
+ * @param binaryPath - Absolute launchable binary path
+ */
+export function applicationIniPath(binaryPath) {
+    const binaryDir = dirname(binaryPath);
+    if (basename(binaryDir) === 'MacOS' && basename(dirname(binaryDir)) === 'Contents') {
+        return join(dirname(binaryDir), 'Resources', 'application.ini');
+    }
+    return join(binaryDir, 'application.ini');
+}
+/**
+ * Reads the `BuildID=` of the launchable build (the `moz:buildID` the
+ * browser reports). Undefined when the file or the key is missing, so a
+ * caller can simply leave the attribute off.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export async function readBuildId(engineDir, launchablePath) {
+    const iniPath = applicationIniPath(join(engineDir, launchablePath));
+    let content;
+    try {
+        content = await readText(iniPath);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) !== 'ENOENT') {
+            verbose(`Build id: could not read ${iniPath} — ${toError(error).message}`);
+        }
+        return undefined;
+    }
+    const match = /^BuildID=(\S+)\s*$/m.exec(content);
+    return match?.[1];
+}
+/**
+ * When the launchable build's compiled code was last linked: the newest
+ * mtime of the binary and the `libxul` beside it. Undefined when neither
+ * can be read.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param launchablePath - Engine-relative launchable binary path
+ */
+export async function readLinkedAt(engineDir, launchablePath) {
+    const binary = join(engineDir, launchablePath);
+    const candidates = [binary, ...LINKED_LIBRARY_NAMES.map((name) => join(dirname(binary), name))];
+    let newest;
+    for (const path of candidates) {
+        try {
+            // stat follows the dist/bin symlinks to the linked objdir file.
+            const { mtimeMs } = await stat(path);
+            if (newest === undefined || mtimeMs > newest.mtimeMs)
+                newest = { mtimeMs, path };
+        }
+        catch {
+            // A platform's other library names are simply absent.
+        }
+    }
+    return newest;
+}

package/dist/src/core/marionette-port.js

@@ -247,9 +247,7 @@ async function probeWithLsof(port) {
     catch {
         // `lsof` missing, or its stdout did not parse. Either way the port state
         // is unknown, and an unknown port is reported as free so the probe never
-        // blocks a run on its own uncertainty. (The errno test that used to sit
-        // here returned the same value as this fallthrough, so it decided
-        // nothing.)
+        // blocks a run on its own uncertainty.
         return { inUse: false };
     }
 }

package/dist/src/core/moz-manifest-rules.js

@@ -77,11 +77,12 @@ export function getRules(binaryName, createManifest = false) {
             // scaffolded and wired via XPCSHELL_TESTS_MANIFESTS.
             pattern: /^(?!browser\/base\/content\/test\/)(.+)\/(test_[^/]+\.js)$/,
             isRegistered: (engineDir, dirRel, fileName) => isXpcshellTestRegistered(engineDir, dirRel, fileName),
-            register: (engineDir, _after, dryRun, dirRel, fileName) => registerXpcshellTest(engineDir, dirRel, fileName, dryRun, createManifest),
+            register: (engineDir, after, dryRun, dirRel, fileName) => registerXpcshellTest(engineDir, dirRel, fileName, dryRun, createManifest, after),
             // Both groups are guaranteed by the pattern, so slice avoids dead
             // fallback branches.
             extractArgs: (m) => m.slice(1, 3),
-            supportsAfter: false,
+            // `--after <entry>` places the section after that entry's block.
+            supportsAfter: true,
         },
     ];
 }