@hominis/fireforge 0.51.0 → 0.53.0

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

@@ -2,14 +2,12 @@
 /**
  * Optional Prettier pass over patch-owned `.sys.mjs` modules.
  *
- * Until 0.45.0 no tier of the chain ran Prettier on `.sys.mjs` at all, so
- * module formatting drift was caught by nothing and survived to a human
- * reviewer. Worse, the obvious manual check was misleading in the same
- * direction: a fork's root `.prettierignore` typically excludes `engine/`,
+ * Without this pass no tier of the chain runs Prettier on `.sys.mjs`, so
+ * module formatting drift survives to a human reviewer. The obvious manual
+ * check is misleading in the same direction: a fork's root `.prettierignore` typically excludes `engine/`,
  * so `prettier --check --config engine/.prettierrc.js <engine files>` run
  * from the repo root reports "all files use Prettier code style" for files
- * that fail the identical check run from inside `engine/`. A root-level
- * spot-check falsely refuted a correct reviewer finding on exactly this.
+ * that fail the identical check run from inside `engine/`.
  *
  * This pass therefore runs prettier with `cwd` set to the engine directory,
  * so the engine's own `.prettierrc*` and `.prettierignore` resolve the way

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

@@ -8,7 +8,7 @@ import type { PatchLintIssue } from '../types/commands/index.js';
  * whose message text can drift between otherwise-equivalent runs (for
  * example because the message embeds later-owner filenames or positional
  * detail). Falling back to the full tuple keeps the helper conservative
- * for older/non-fingerprinted rules: if their message changes, we would
+ * for non-fingerprinted rules: if their message changes, we would
  * rather surface a potential regression than silently swallow it.
  *
  * Consumption order within the projected list is stable (the input

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

@@ -7,7 +7,7 @@
  * whose message text can drift between otherwise-equivalent runs (for
  * example because the message embeds later-owner filenames or positional
  * detail). Falling back to the full tuple keeps the helper conservative
- * for older/non-fingerprinted rules: if their message changes, we would
+ * for non-fingerprinted rules: if their message changes, we would
  * rather surface a potential regression than silently swallow it.
  *
  * Consumption order within the projected list is stable (the input

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

@@ -3,8 +3,8 @@
  *
  * A leaf module by design: it imports nothing, so the individual rule
  * modules can describe the slice of `PatchQueueContext` they read without
- * importing `patch-lint-cross.ts` (which imports them back). Previously each
- * rule re-declared its own private `{ entries }` interface. Sharing them here
+ * importing `patch-lint-cross.ts` (which imports them back). Sharing them
+ * here instead of re-declaring a private `{ entries }` interface per rule
  * keeps the dependency edge one-way and `dpdm` clean while stating the shape
  * once.
  */

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

@@ -4,8 +4,8 @@
  *
  * A leaf module by design: it imports nothing, so the individual rule
  * modules can describe the slice of `PatchQueueContext` they read without
- * importing `patch-lint-cross.ts` (which imports them back). Previously each
- * rule re-declared its own private `{ entries }` interface. Sharing them here
+ * importing `patch-lint-cross.ts` (which imports them back). Sharing them
+ * here instead of re-declaring a private `{ entries }` interface per rule
  * keeps the dependency edge one-way and `dpdm` clean while stating the shape
  * once.
  */

package/dist/src/core/patch-manifest-consistency.d.ts

@@ -20,7 +20,7 @@ export declare function validatePatchesManifestConsistency(patchesDir: string):
  *
  * Drift that is only in `filesAffected` is a derived value disagreeing with
  * the diff it describes, and the narrow repair fixes exactly that. Naming the
- * whole-manifest rebuild for it (as this hint used to, unconditionally) puts
+ * whole-manifest rebuild for it puts
  * an operator one keystroke from rewriting every row in the manifest to
  * correct one list.
  */
@@ -80,7 +80,7 @@ export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions
  * becomes a whole-manifest reinvention. Pass `allowMetadataLoss` to accept it.
  *
  * @param patchesDir - Path to the patches directory
- * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
+ * @param fallbackSourceEsrVersion - source version to use for recovered entries that carry none
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
  * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows

package/dist/src/core/patch-manifest-consistency.js

@@ -87,7 +87,7 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  *
  * Drift that is only in `filesAffected` is a derived value disagreeing with
  * the diff it describes, and the narrow repair fixes exactly that. Naming the
- * whole-manifest rebuild for it (as this hint used to, unconditionally) puts
+ * whole-manifest rebuild for it puts
  * an operator one keystroke from rewriting every row in the manifest to
  * correct one list.
  */
@@ -115,7 +115,7 @@ export function recommendManifestRepair(issues) {
  * becomes a whole-manifest reinvention. Pass `allowMetadataLoss` to accept it.
  *
  * @param patchesDir - Path to the patches directory
- * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
+ * @param fallbackSourceEsrVersion - source version to use for recovered entries that carry none
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
  * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows

package/dist/src/core/patch-manifest-io.d.ts

@@ -65,10 +65,14 @@ export declare function loadPatchesManifestForWrite(patchesDir: string): Promise
  */
 export declare function savePatchesManifest(patchesDir: string, manifest: PatchesManifest): Promise<void>;
 /**
- * Mutates selected manifest rows while preserving the raw JSON shape of every
+ * Mutates selected manifest rows while preserving the raw JSON fields of every
  * untouched row. This avoids serializing reader-only fallback fields, such as
  * `sourceVersion` derived from legacy `sourceEsrVersion`, into unrelated patch
  * entries during partial metadata updates.
+ *
+ * Every row's keys (and the manifest's own) are written in canonical order,
+ * not only the changed rows', so the working copy matches what `patch stage`
+ * and full saves write and no commit flips untouched rows' key order.
  */
 export declare function mutatePatchRowsInManifest(patchesDir: string, filenames: readonly string[], mutator: (existing: PatchMetadata, rawExisting: Readonly<JsonObject>) => PatchManifestRowMutation | null): Promise<PatchManifestRowMutationResult[] | null>;
 /**

package/dist/src/core/patch-manifest-io.js

@@ -19,7 +19,7 @@ import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.j
 import { warn } from '../utils/logger.js';
 import { isArray, isObject } from '../utils/validation.js';
 import { assertPatchDirectoryLockHeld } from './patch-lock.js';
-import { canonicalizeManifest, canonicalizePatchRow } from './patch-manifest-key-order.js';
+import { canonicalizeManifest } from './patch-manifest-key-order.js';
 import { validatePatchesManifest } from './patch-manifest-validate.js';
 import { manifestWithRetiredSlots } from './patch-retired.js';
 /** Filename for the patches manifest */
@@ -90,10 +90,14 @@ export async function savePatchesManifest(patchesDir, manifest) {
     await writeJson(manifestPath, canonicalizeManifest(manifest));
 }
 /**
- * Mutates selected manifest rows while preserving the raw JSON shape of every
+ * Mutates selected manifest rows while preserving the raw JSON fields of every
  * untouched row. This avoids serializing reader-only fallback fields, such as
  * `sourceVersion` derived from legacy `sourceEsrVersion`, into unrelated patch
  * entries during partial metadata updates.
+ *
+ * Every row's keys (and the manifest's own) are written in canonical order,
+ * not only the changed rows', so the working copy matches what `patch stage`
+ * and full saves write and no commit flips untouched rows' key order.
  */
 export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator) {
     const manifestPath = join(patchesDir, PATCHES_MANIFEST);
@@ -140,16 +144,14 @@ export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator)
     }
     if (changedIndexes.length === 0)
         return [];
-    // Only the rows this call changed are put in canonical order, so a key
-    // it sets lands where every other writer puts it; untouched rows keep
-    // their raw shape.
-    for (const index of changedIndexes) {
-        rawPatches[index] = canonicalizePatchRow(rawPatches[index]);
-    }
-    const nextRawManifest = {
+    // Every row is put in canonical key order, not only the changed ones:
+    // `patch stage` and full saves canonicalize the whole manifest, so a
+    // row left in any other order flips back and forth between the
+    // working copy and the index. Reordering keys adds no field.
+    const nextRawManifest = canonicalizeManifest({
         ...rawManifest,
         patches: rawPatches,
-    };
+    });
     const afterManifest = validatePatchesManifest(nextRawManifest);
     await writeJson(manifestPath, nextRawManifest);
     return changedIndexes.map((index) => ({

package/dist/src/core/patch-manifest-key-order.d.ts

@@ -1,9 +1,8 @@
 /**
  * The one key order every `patches.json` writer uses for a patch row and
- * for the manifest itself. Writers used to disagree: `export` spread
- * `sourceProduct` before `sourceVersion` while a full-manifest save put it
- * after `filesAffected`, so a no-op rewrite left a key-order-only hunk in
- * the manifest.
+ * for the manifest itself, so that every writer (`export`, full-manifest
+ * saves, `patch stage`) agrees and a no-op rewrite leaves no key-order-only
+ * hunk in the manifest.
  */
 /**
  * Returns a copy of a patch row with its keys in canonical order.

package/dist/src/core/patch-manifest-key-order.js

@@ -1,10 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * The one key order every `patches.json` writer uses for a patch row and
- * for the manifest itself. Writers used to disagree: `export` spread
- * `sourceProduct` before `sourceVersion` while a full-manifest save put it
- * after `filesAffected`, so a no-op rewrite left a key-order-only hunk in
- * the manifest.
+ * for the manifest itself, so that every writer (`export`, full-manifest
+ * saves, `patch stage`) agrees and a no-op rewrite leaves no key-order-only
+ * hunk in the manifest.
  */
 /** Patch-row keys in the order of the `PatchMetadata` interface. */
 const PATCH_ROW_KEY_ORDER = [

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

@@ -34,10 +34,10 @@ export declare function extractOrder(filename: string): number;
  * The write-side counterpart to {@link extractOrder}. That one answers
  * `Infinity` for a prefix-less filename, which sorts such a patch last and
  * is the right answer for a read: an unparseable name should not crash a
- * status listing. Persisting `Infinity` (or the `0` some call sites used to
- * fall back to) is a different matter: it puts an order in the manifest
+ * status listing. Persisting `Infinity` (or a fallback `0`) is a different
+ * matter: it puts an order in the manifest
  * that no filename on disk agrees with, and the queue then applies in an
- * order the operator cannot see. Callers here have always just built or
+ * order the operator cannot see. Callers here have just built or
  * looked up a real prefixed filename, so absence is a bug, not input.
  *
  * @param filename - Patch filename carrying a numeric order prefix

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

@@ -56,10 +56,10 @@ export function extractOrder(filename) {
  * The write-side counterpart to {@link extractOrder}. That one answers
  * `Infinity` for a prefix-less filename, which sorts such a patch last and
  * is the right answer for a read: an unparseable name should not crash a
- * status listing. Persisting `Infinity` (or the `0` some call sites used to
- * fall back to) is a different matter: it puts an order in the manifest
+ * status listing. Persisting `Infinity` (or a fallback `0`) is a different
+ * matter: it puts an order in the manifest
  * that no filename on disk agrees with, and the queue then applies in an
- * order the operator cannot see. Callers here have always just built or
+ * order the operator cannot see. Callers here have just built or
  * looked up a real prefixed filename, so absence is a bug, not input.
  *
  * @param filename - Patch filename carrying a numeric order prefix

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

@@ -42,7 +42,7 @@ export interface PatchPolicyEnforcementInput {
 }
 /** Returns valid categories for prompts and CLI validation under the config. */
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
-/** Checks whether a category is accepted by legacy defaults or the policy ranges. */
+/** Checks whether a category is accepted by the built-in defaults or the policy ranges. */
 export declare function isCategoryAllowedByConfig(config: FireForgeConfig, category: string): boolean;
 /**
  * Human-readable label for a category's configured ranges, e.g. `300-399`.

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

@@ -28,7 +28,7 @@ export function getPatchPolicyCategories(config) {
         return [...PATCH_CATEGORIES];
     return Array.from(new Set(cfg.ranges.map((range) => range.category))).sort((a, b) => a.localeCompare(b));
 }
-/** Checks whether a category is accepted by legacy defaults or the policy ranges. */
+/** Checks whether a category is accepted by the built-in defaults or the policy ranges. */
 export function isCategoryAllowedByConfig(config, category) {
     if (!/^[a-z][a-z0-9-]*$/.test(category))
         return false;

package/dist/src/core/patch-source-metadata.d.ts

@@ -2,5 +2,5 @@ import type { PatchMetadata } from '../types/commands/index.js';
 import type { FirefoxConfig } from '../types/config.js';
 /** Metadata fields stamped on new or refreshed patch entries. */
 export declare function buildPatchSourceMetadata(firefox: Pick<FirefoxConfig, 'product' | 'version'>): Pick<PatchMetadata, 'sourceEsrVersion' | 'sourceProduct' | 'sourceVersion'>;
-/** Backward-compatible source version reader for legacy manifests. */
+/** Source version reader that also accepts rows carrying only `sourceEsrVersion`. */
 export declare function getPatchSourceVersion(patch: Pick<PatchMetadata, 'sourceEsrVersion' | 'sourceVersion'>): string;

package/dist/src/core/patch-source-metadata.js

@@ -6,7 +6,7 @@ export function buildPatchSourceMetadata(firefox) {
         sourceVersion: firefox.version,
     };
 }
-/** Backward-compatible source version reader for legacy manifests. */
+/** Source version reader that also accepts rows carrying only `sourceEsrVersion`. */
 export function getPatchSourceVersion(patch) {
     return patch.sourceVersion ?? patch.sourceEsrVersion;
 }

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

@@ -3,12 +3,14 @@ import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js'
  * Resolves a `--patches <name…>` subset against the manifest, matching each
  * requested name tolerantly (exact filename, filename ± `.patch`, the bare
  * order number, the manifest `name` field, or the slug). Accepts repeated
- * values and comma lists. Throws listing the available patches when a
+ * values and lists separated by commas or whitespace, so a list passed as
+ * one shell word (`--patches "$P"` under zsh) still splits. Throws when a
  * requested name matches none, so a typo fails loud rather than silently
- * judging nothing.
+ * judging nothing; the refusal names that name and its nearest matches,
+ * not the whole queue.
  *
  * @param manifest - The loaded patch manifest
- * @param requested - Raw `--patches` values (each may be a comma list)
+ * @param requested - Raw `--patches` values (each may be a comma or whitespace list)
  * @param refusalHint - Sentence inserted into the no-match refusal, naming
  *   what the caller's flag selects
  * @returns The matching manifest rows, de-duplicated, in request order

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

@@ -5,6 +5,7 @@
  * one gate selects the same patch in the others.
  */
 import { GeneralError } from '../errors/base.js';
+import { formatPatchSuggestions } from './patch-identifier-suggest.js';
 /** Every spelling an operator may use for one patch. */
 function patchAliases(p) {
     const aliases = new Set([p.filename, p.filename.replace(/\.patch$/, ''), p.name]);
@@ -31,29 +32,29 @@ function matchesPatch(p, name) {
  * Resolves a `--patches <name…>` subset against the manifest, matching each
  * requested name tolerantly (exact filename, filename ± `.patch`, the bare
  * order number, the manifest `name` field, or the slug). Accepts repeated
- * values and comma lists. Throws listing the available patches when a
+ * values and lists separated by commas or whitespace, so a list passed as
+ * one shell word (`--patches "$P"` under zsh) still splits. Throws when a
  * requested name matches none, so a typo fails loud rather than silently
- * judging nothing.
+ * judging nothing; the refusal names that name and its nearest matches,
+ * not the whole queue.
  *
  * @param manifest - The loaded patch manifest
- * @param requested - Raw `--patches` values (each may be a comma list)
+ * @param requested - Raw `--patches` values (each may be a comma or whitespace list)
  * @param refusalHint - Sentence inserted into the no-match refusal, naming
  *   what the caller's flag selects
  * @returns The matching manifest rows, de-duplicated, in request order
  */
 export function selectPatchSubset(manifest, requested, refusalHint = '') {
     const normalizedRequests = requested
-        .flatMap((entry) => entry.split(','))
-        .map((entry) => entry.trim())
+        .flatMap((entry) => entry.split(/[\s,]+/))
         .filter((entry) => entry.length > 0);
     const selected = [];
     const seen = new Set();
     for (const name of normalizedRequests) {
         const found = manifest.patches.filter((p) => matchesPatch(p, name));
         if (found.length === 0) {
-            const available = manifest.patches.map((p) => p.filename).join(', ');
             throw new GeneralError(`No patch in the queue matches "${name}".${refusalHint ? ` ${refusalHint}` : ''} ` +
-                `Available patches: ${available}`);
+                formatPatchSuggestions(name, manifest.patches));
         }
         for (const p of found) {
             if (!seen.has(p.filename)) {

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

@@ -45,8 +45,8 @@ export declare function extractNewFileContentsFromDiff(diff: string, targetFiles
  * `binary-body-not-reconstructable` queue lint, and
  * `buildPatchQueueContext` already tolerates them for real queue entries.
  *
- * One parse for the whole diff, rather than one per new file as the five
- * call sites previously did.
+ * One parse for the whole diff, rather than one per new file, shared by
+ * every call site.
  */
 export declare function buildNewFileTextProjection(diff: string): Map<string, string>;
 /**

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

@@ -101,8 +101,8 @@ function contentFromSections(sections) {
  * `binary-body-not-reconstructable` queue lint, and
  * `buildPatchQueueContext` already tolerates them for real queue entries.
  *
- * One parse for the whole diff, rather than one per new file as the five
- * call sites previously did.
+ * One parse for the whole diff, rather than one per new file, shared by
+ * every call site.
  */
 export function buildNewFileTextProjection(diff) {
     const newFiles = new Map();

package/dist/src/core/rebase-session.js

@@ -29,9 +29,8 @@ const REBASE_PATCH_STATUSES = [
 /**
  * Drops payload that does not belong to an entry's status.
  *
- * Applied on read so a session written by an older FireForge, where
- * `rebase --continue` left `error`/`conflictingFiles` on a now-`resolved`
- * entry, loads cleanly and is corrected, instead of being refused by a
+ * Applied on read so a session whose `resolved` entry still carries
+ * `error`/`conflictingFiles` loads cleanly and is corrected, instead of being refused by a
  * stricter validator mid-rebase.
  *
  * @param entry - A structurally valid entry, possibly carrying stale payload
@@ -145,11 +144,10 @@ export async function readRebaseSession(projectRoot) {
     if (!isValidSession(data)) {
         return { present: true, valid: false, reason: 'the file is not a valid rebase session' };
     }
-    // Normalize on read: an older session can carry a failure's
+    // Normalize on read: a session can carry a failure's
     // `error`/`conflictingFiles` on an entry whose status has since been
     // flipped to `resolved`. Correcting it here is what lets the validator
-    // stay permissive, so an in-flight rebase from an older FireForge still
-    // loads.
+    // stay permissive, so such an in-flight rebase still loads.
     return {
         present: true,
         valid: true,

package/dist/src/core/register-xpcshell-test.d.ts

@@ -2,7 +2,8 @@
  * xpcshell test-file registration. Without it, xpcshell test files (e.g.
  * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
  * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
- * into the directory's `xpcshell.toml` (alphabetically, idempotently). With
+ * into the directory's `xpcshell.toml` (alphabetically or after the
+ * `--after` entry, idempotently). With
  * `--create-manifest` it also creates the manifest and wires
  * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
@@ -14,16 +15,36 @@ import type { RegisterResult } from './register-result.js';
  * missing rather than the file as unregistered).
  */
 export declare function isXpcshellTestRegistered(engineDir: string, dirRel: string, fileName: string): Promise<boolean>;
+/** Where a new section goes and what placed it there. */
+export interface XpcshellSectionPlacement {
+    /** The manifest content with the section inserted. */
+    content: string;
+    /** The `["…"]` header of the `--after` entry the section follows. */
+    previousEntry?: string | undefined;
+    /** `--after` named no entry, so the section went in sort order. */
+    afterFallback?: boolean | undefined;
+}
 /**
- * Inserts the `["<fileName>"]` section into the manifest content in
- * mozbuild's case-insensitive sort order relative to the other test
- * sections, keeping one blank line between sections. Exported for direct
- * unit testing.
+ * Places the `["<fileName>"]` section in the manifest content.
+ *
+ * Without `after`, the section goes in mozbuild's case-insensitive sort
+ * order relative to the other test sections. With `after`, it goes right
+ * after the named entry's whole block (its keys included). Either way it
+ * is inserted ahead of the `#` comment lines that introduce the next
+ * entry, never between a comment and its entry, keeping one
+ * blank line between sections.
  */
-export declare function insertXpcshellManifestSection(content: string, fileName: string): string;
+export declare function placeXpcshellManifestSection(content: string, fileName: string, after?: string): XpcshellSectionPlacement;
+/**
+ * Inserts the `["<fileName>"]` section into the manifest content; see
+ * {@link placeXpcshellManifestSection}. Exported for direct unit testing.
+ *
+ * @internal
+ */
+export declare function insertXpcshellManifestSection(content: string, fileName: string, after?: string): string;
 /**
  * Registers an xpcshell test file in its directory's `xpcshell.toml`.
  * With `createManifest`, a missing manifest is scaffolded and wired into
  * the nearest moz.build via `XPCSHELL_TESTS_MANIFESTS`.
  */
-export declare function registerXpcshellTest(engineDir: string, dirRel: string, fileName: string, dryRun?: boolean, createManifest?: boolean): Promise<RegisterResult>;
+export declare function registerXpcshellTest(engineDir: string, dirRel: string, fileName: string, dryRun?: boolean, createManifest?: boolean, after?: string): Promise<RegisterResult>;

package/dist/src/core/register-xpcshell-test.js

@@ -3,7 +3,8 @@
  * xpcshell test-file registration. Without it, xpcshell test files (e.g.
  * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
  * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
- * into the directory's `xpcshell.toml` (alphabetically, idempotently). With
+ * into the directory's `xpcshell.toml` (alphabetically or after the
+ * `--after` entry, idempotently). With
  * `--create-manifest` it also creates the manifest and wires
  * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
@@ -32,40 +33,82 @@ export async function isXpcshellTestRegistered(engineDir, dirRel, fileName) {
     const content = await readText(manifestPath);
     return content.includes(`["${fileName}"]`);
 }
+const SECTION_HEADER = /^\["([^"]+)"\]\s*$/;
 /**
- * Inserts the `["<fileName>"]` section into the manifest content in
- * mozbuild's case-insensitive sort order relative to the other test
- * sections, keeping one blank line between sections. Exported for direct
- * unit testing.
+ * The line where the block headed at `headerIndex` starts: the header
+ * itself, or the first of the `#` comment lines directly above it. A
+ * comment describes the entry below it, so nothing is inserted between
+ * them.
  */
-export function insertXpcshellManifestSection(content, fileName) {
+function blockStart(lines, headerIndex) {
+    let start = headerIndex;
+    while (start > 0 && (lines[start - 1] ?? '').trimStart().startsWith('#'))
+        start -= 1;
+    return start;
+}
+/** Index of the section header `after` names: exact name first, then a substring. */
+function findAfterHeader(lines, after) {
+    const headers = lines
+        .map((line, index) => ({ index, line, name: SECTION_HEADER.exec(line)?.[1] }))
+        .filter((header) => header.name !== undefined);
+    const exact = headers.find((header) => header.name === after || header.line.trim() === after);
+    return (exact ?? headers.find((header) => header.line.includes(after)))?.index ?? -1;
+}
+function spliceSection(lines, index, fileName) {
+    if (index === -1) {
+        // Append after the last section (or at end of file when there are no
+        // sections yet), keeping exactly one trailing newline.
+        while (lines.length > 0 && (lines.at(-1) ?? '').trim() === '')
+            lines.pop();
+        return [...lines, '', `["${fileName}"]`, ''].join('\n');
+    }
+    lines.splice(index, 0, `["${fileName}"]`, '');
+    return lines.join('\n');
+}
+/**
+ * Places the `["<fileName>"]` section in the manifest content.
+ *
+ * Without `after`, the section goes in mozbuild's case-insensitive sort
+ * order relative to the other test sections. With `after`, it goes right
+ * after the named entry's whole block (its keys included). Either way it
+ * is inserted ahead of the `#` comment lines that introduce the next
+ * entry, never between a comment and its entry, keeping one
+ * blank line between sections.
+ */
+export function placeXpcshellManifestSection(content, fileName, after) {
     const lines = content.split('\n');
-    const sectionHeaderPattern = /^\["([^"]+)"\]\s*$/;
-    let insertIndex = -1;
-    for (let i = 0; i < lines.length; i += 1) {
-        const match = sectionHeaderPattern.exec(lines[i] ?? '');
-        if (!match)
-            continue;
-        if (insertIndex === -1 && mozbuildSortCompare(fileName, match[1] ?? '') < 0) {
-            insertIndex = i;
+    const headerIndexes = lines.flatMap((line, index) => (SECTION_HEADER.test(line) ? [index] : []));
+    if (after !== undefined) {
+        const afterIndex = findAfterHeader(lines, after);
+        if (afterIndex !== -1) {
+            const next = headerIndexes.find((index) => index > afterIndex);
+            return {
+                content: spliceSection(lines, next === undefined ? -1 : blockStart(lines, next), fileName),
+                previousEntry: (lines[afterIndex] ?? '').trim(),
+            };
         }
     }
-    if (insertIndex !== -1) {
-        lines.splice(insertIndex, 0, `["${fileName}"]`, '');
-        return lines.join('\n');
-    }
-    // Append after the last section (or at end of file when there are no
-    // sections yet), keeping exactly one trailing newline.
-    while (lines.length > 0 && (lines.at(-1) ?? '').trim() === '')
-        lines.pop();
-    return [...lines, '', `["${fileName}"]`, ''].join('\n');
+    const before = headerIndexes.find((index) => mozbuildSortCompare(fileName, SECTION_HEADER.exec(lines[index] ?? '')?.[1] ?? '') < 0);
+    return {
+        content: spliceSection(lines, before === undefined ? -1 : blockStart(lines, before), fileName),
+        ...(after !== undefined ? { afterFallback: true } : {}),
+    };
+}
+/**
+ * Inserts the `["<fileName>"]` section into the manifest content; see
+ * {@link placeXpcshellManifestSection}. Exported for direct unit testing.
+ *
+ * @internal
+ */
+export function insertXpcshellManifestSection(content, fileName, after) {
+    return placeXpcshellManifestSection(content, fileName, after).content;
 }
 /**
  * Registers an xpcshell test file in its directory's `xpcshell.toml`.
  * With `createManifest`, a missing manifest is scaffolded and wired into
  * the nearest moz.build via `XPCSHELL_TESTS_MANIFESTS`.
  */
-export async function registerXpcshellTest(engineDir, dirRel, fileName, dryRun = false, createManifest = false) {
+export async function registerXpcshellTest(engineDir, dirRel, fileName, dryRun = false, createManifest = false, after) {
     const manifestRel = `${dirRel}/xpcshell.toml`;
     const manifestPath = join(engineDir, manifestRel);
     const entry = `["${fileName}"]`;
@@ -86,9 +129,15 @@ export async function registerXpcshellTest(engineDir, dirRel, fileName, dryRun =
     if (content.includes(entry)) {
         return { manifest: manifestRel, entry, skipped: true };
     }
-    const updated = insertXpcshellManifestSection(content, fileName);
+    const placement = placeXpcshellManifestSection(content, fileName, after);
     if (!dryRun) {
-        await writeText(manifestPath, updated);
+        await writeText(manifestPath, placement.content);
     }
-    return { manifest: manifestRel, entry, skipped: false };
+    return {
+        manifest: manifestRel,
+        entry,
+        skipped: false,
+        previousEntry: placement.previousEntry,
+        afterFallback: placement.afterFallback,
+    };
 }

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

@@ -1,13 +1,13 @@
 /**
  * Per-run output logs under `.fireforge/logs/`.
  *
- * A run's diagnosis used to exist in exactly one place: the terminal. Piping
- * through `tail`/`grep`, the ergonomic default when output is long, keeps
- * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say what
- * broke, and it launders the exit code besides. The operator rule ("never
- * pipe a run") was written down three times downstream and broken after each
- * writing, so this is not an operator problem: the tool is the only party
- * that can make the log survive the mistake.
+ * Without a log, a run's diagnosis exists in exactly one place: the terminal.
+ * Piping through `tail`/`grep`, the ergonomic default when output is long,
+ * keeps the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say
+ * what broke, and it launders the exit code besides. An operator rule
+ * ("never pipe a run") does not hold in practice, so this is not an operator
+ * problem: the tool is the only party that can make the log survive the
+ * mistake.
  *
  * So `test` and `build` write their own complete copy as they stream, and the
  * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
@@ -16,7 +16,7 @@
  * Everything here is best-effort. A log is a diagnostic aid, and a run must
  * never fail because one could not be opened, written, or pruned.
  * Every entry point swallows its errors and degrades to "no log", which is
- * exactly the behaviour that existed before this module.
+ * exactly the behaviour of a run without this module.
  */
 /** A run log sink. `write` never throws. */
 export interface RunLog {