@hominis/fireforge 0.18.8 → 0.18.10

package/dist/src/commands/lint.d.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+import type { PatchLintIssue } from '../types/commands/index.js';
 /** Options controlling how the lint command filters and tags its output. */
 export interface LintCommandOptions {
     /**
@@ -46,6 +47,41 @@ export interface LintCommandOptions {
      */
     perPatch?: boolean;
 }
+/**
+ * Result of {@link applyAggregateLintIgnoreSuppression}.
+ */
+export interface AggregateLintIgnoreResult {
+    /** Issues remaining after suppression. */
+    issues: PatchLintIssue[];
+    /** Number of issues dropped because an owning patch listed the check in `lintIgnore`. */
+    dropped: number;
+}
+/**
+ * Filters aggregate-mode lint issues against per-patch `lintIgnore`
+ * lists drawn from the manifest. An issue is dropped when at least one
+ * patch whose `filesAffected` covers `issue.file` lists `issue.check`
+ * in its `lintIgnore`.
+ *
+ * Mirrors the per-patch contract: `--per-patch` mode threads each
+ * patch's `lintIgnore` directly into `lintExportedPatch`, so a check
+ * the operator explicitly waived in `patches.json` does not surface.
+ * Aggregate `--since` mode previously rediscovered the suppressed
+ * warning every CI run because the diff was treated as a single unit
+ * with no patch-level scope. Attributing each issue's file to its
+ * owning patch via `filesAffected` re-establishes the same suppression
+ * semantics. Cross-patch findings (forward-import, duplicate-creation)
+ * still attribute via `issue.file` because the `file` field is the
+ * offending site, which is owned by some patch.
+ *
+ * Multiple owners: an issue is dropped if **any** owning patch waived
+ * the rule. Conservative — never adds new findings, only drops
+ * already-explicitly-waived ones.
+ *
+ * @param issues - Issues collected from the aggregate lint run.
+ * @param ctx - Patch queue context used to attribute file → patch.
+ * @returns Filtered issue list and the count of dropped findings.
+ */
+export declare function applyAggregateLintIgnoreSuppression(issues: PatchLintIssue[], ctx: import('../core/patch-lint.js').PatchQueueContext): AggregateLintIgnoreResult;
 /**
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project

package/dist/src/commands/lint.js

@@ -160,6 +160,53 @@ async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
     }
     return diff;
 }
+/**
+ * Filters aggregate-mode lint issues against per-patch `lintIgnore`
+ * lists drawn from the manifest. An issue is dropped when at least one
+ * patch whose `filesAffected` covers `issue.file` lists `issue.check`
+ * in its `lintIgnore`.
+ *
+ * Mirrors the per-patch contract: `--per-patch` mode threads each
+ * patch's `lintIgnore` directly into `lintExportedPatch`, so a check
+ * the operator explicitly waived in `patches.json` does not surface.
+ * Aggregate `--since` mode previously rediscovered the suppressed
+ * warning every CI run because the diff was treated as a single unit
+ * with no patch-level scope. Attributing each issue's file to its
+ * owning patch via `filesAffected` re-establishes the same suppression
+ * semantics. Cross-patch findings (forward-import, duplicate-creation)
+ * still attribute via `issue.file` because the `file` field is the
+ * offending site, which is owned by some patch.
+ *
+ * Multiple owners: an issue is dropped if **any** owning patch waived
+ * the rule. Conservative — never adds new findings, only drops
+ * already-explicitly-waived ones.
+ *
+ * @param issues - Issues collected from the aggregate lint run.
+ * @param ctx - Patch queue context used to attribute file → patch.
+ * @returns Filtered issue list and the count of dropped findings.
+ */
+export function applyAggregateLintIgnoreSuppression(issues, ctx) {
+    const suppressionsByFile = new Map();
+    for (const entry of ctx.entries) {
+        const ignoreList = entry.metadata?.lintIgnore;
+        if (!ignoreList || ignoreList.length === 0)
+            continue;
+        for (const f of entry.metadata?.filesAffected ?? []) {
+            let bucket = suppressionsByFile.get(f);
+            if (!bucket) {
+                bucket = new Set();
+                suppressionsByFile.set(f, bucket);
+            }
+            for (const id of ignoreList)
+                bucket.add(id);
+        }
+    }
+    if (suppressionsByFile.size === 0) {
+        return { issues, dropped: 0 };
+    }
+    const filtered = issues.filter((issue) => !suppressionsByFile.get(issue.file)?.has(issue.check));
+    return { issues: filtered, dropped: issues.length - filtered.length };
+}
 /**
  * Runs the lint command to check engine changes against patch quality rules.
  * @param projectRoot - Root directory of the project
@@ -217,7 +264,7 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (await pathExists(paths.patches)) {
         ctx = await buildPatchQueueContext(paths.patches);
     }
-    const issues = [
+    let issues = [
         ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx)),
     ];
     // Cross-patch rules operate over the whole queue, so run them whenever a
@@ -226,6 +273,19 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (ctx) {
         issues.push(...lintPatchQueue(ctx));
     }
+    // Honor per-patch `lintIgnore` in aggregate mode by attributing each
+    // issue's file to its owning patches via the manifest's
+    // `filesAffected`. Per-patch mode threads `lintIgnore` directly into
+    // `lintExportedPatch`; aggregate mode previously had no patch-level
+    // scope to consult, so a check an operator had explicitly waived in
+    // `patches.json` re-surfaced on every `--since` run (CI default).
+    if (ctx) {
+        const result = applyAggregateLintIgnoreSuppression(issues, ctx);
+        issues = result.issues;
+        if (result.dropped > 0) {
+            info(`Suppressed ${result.dropped} issue(s) via per-patch lintIgnore (aggregate mode).`);
+        }
+    }
     // When a queue manifest exists AND files were NOT scoped explicitly, the
     // "diff" we just linted is every applied patch summed together. Patch-
     // size rules (`large-patch-lines`, `large-patch-files`) then fire against

package/dist/src/commands/patch/index.d.ts

@@ -1,14 +1,16 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
- * they do not clutter the top-level command list. Queue-level verbs
- * like `lint`, `export`, `verify`, and `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `rename`, `reorder`,
+ * `tier`) so they do not clutter the top-level command list.
+ * Queue-level verbs like `lint`, `export`, `verify`, and `status` stay
+ * flat.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
 export { patchLintIgnoreCommand } from './lint-ignore.js';
+export { patchRenameCommand } from './rename.js';
 export { patchReorderCommand } from './reorder.js';
 export { patchTierCommand } from './tier.js';
 /**

package/dist/src/commands/patch/index.js

@@ -1,18 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
- * they do not clutter the top-level command list. Queue-level verbs
- * like `lint`, `export`, `verify`, and `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `rename`, `reorder`,
+ * `tier`) so they do not clutter the top-level command list.
+ * Queue-level verbs like `lint`, `export`, `verify`, and `status` stay
+ * flat.
  */
 import { registerPatchCompact } from './compact.js';
 import { registerPatchDelete } from './delete.js';
 import { registerPatchLintIgnore } from './lint-ignore.js';
+import { registerPatchRename } from './rename.js';
 import { registerPatchReorder } from './reorder.js';
 import { registerPatchTier } from './tier.js';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
 export { patchLintIgnoreCommand } from './lint-ignore.js';
+export { patchRenameCommand } from './rename.js';
 export { patchReorderCommand } from './reorder.js';
 export { patchTierCommand } from './tier.js';
 /**
@@ -24,7 +27,7 @@ export { patchTierCommand } from './tier.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, lint-ignore, reorder, tier)')
+        .description('Manage individual patches in the queue (compact, delete, lint-ignore, rename, reorder, tier)')
         // Match `fireforge furnace`'s no-args contract: print the group's help and
         // exit 0. Without this default action, commander routes `fireforge patch`
         // (no subcommand) through its own help-then-exit-1 path, so scripts that
@@ -37,6 +40,7 @@ export function registerPatch(program, context) {
     registerPatchCompact(patch, context);
     registerPatchDelete(patch, context);
     registerPatchLintIgnore(patch, context);
+    registerPatchRename(patch, context);
     registerPatchReorder(patch, context);
     registerPatchTier(patch, context);
 }

package/dist/src/commands/patch/lint-ignore.d.ts

@@ -21,6 +21,13 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 import type { PatchLintIgnoreOptions } from '../../types/commands/index.js';
+type LintIgnoreMode = 'add' | 'remove' | 'clear';
+/**
+ * Renders a one-line summary of the planned change for use in
+ * `info()` / dry-run / history args. Exported for unit-testing the
+ * message format directly without mocking the logger transport.
+ */
+export declare function describeChange(before: ReadonlyArray<string>, after: ReadonlyArray<string>, mode: LintIgnoreMode, values: ReadonlyArray<string>): string;
 /**
  * Runs the `patch lint-ignore` command: reads the patch's existing
  * `lintIgnore`, applies the requested mode, and writes the manifest.
@@ -37,3 +44,4 @@ export declare function patchLintIgnoreCommand(projectRoot: string, identifier:
  * @param context - Shared CLI registration context
  */
 export declare function registerPatchLintIgnore(parent: Command, context: CommandContext): void;
+export {};

package/dist/src/commands/patch/lint-ignore.js

@@ -53,9 +53,10 @@ function applyMode(existing, mode, values) {
 }
 /**
  * Renders a one-line summary of the planned change for use in
- * `info()` / dry-run / history args.
+ * `info()` / dry-run / history args. Exported for unit-testing the
+ * message format directly without mocking the logger transport.
  */
-function describeChange(before, after, mode, values) {
+export function describeChange(before, after, mode, values) {
     const beforeSet = new Set(before);
     const afterSet = new Set(after);
     if (mode === 'clear') {
@@ -63,17 +64,20 @@ function describeChange(before, after, mode, values) {
             ? 'lintIgnore was already empty — no change'
             : `lintIgnore cleared (was ${before.join(', ')})`;
     }
+    const currentLabel = before.length > 0 ? `[${before.join(', ')}]` : '(empty)';
     if (mode === 'add') {
         const added = values.filter((v) => !beforeSet.has(v));
         if (added.length === 0) {
-            return 'lintIgnore unchanged (all requested IDs were already present)';
+            // Surface the existing list so a no-op `--add` does not require a
+            // follow-up `patches.json` read to confirm what was already present.
+            return `lintIgnore unchanged (current: ${currentLabel}; all requested IDs already present)`;
         }
         return `lintIgnore += ${added.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
     }
     // mode === 'remove'
     const removed = values.filter((v) => beforeSet.has(v));
     if (removed.length === 0) {
-        return 'lintIgnore unchanged (none of the requested IDs were present)';
+        return `lintIgnore unchanged (current: ${currentLabel}; none of the requested IDs were present)`;
     }
     return `lintIgnore −= ${removed.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
 }

package/dist/src/commands/patch/rename.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `fireforge patch rename <name>` — relabels a patch's filename, manifest
+ * `name`, and (optionally) `description` without rewriting the `.patch`
+ * file body.
+ *
+ * Companion to `re-export --files <subset>`. Re-export shrinks the body
+ * + `filesAffected`, but leaves the patch's identity describing the
+ * pre-shrink scope. Before this verb existed, the only workaround for
+ * that drift was `delete` + re-export, which briefly removed the patch
+ * from the queue (any forward-import dependent would refuse the
+ * re-export until the deleted patch's siblings were rewritten).
+ *
+ * The filename rename and the manifest mutation happen under the patch
+ * directory lock so concurrent exports cannot allocate the new
+ * filename, and a filesystem rename failure rolls back before the
+ * manifest is touched.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchRenameOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch rename` command: relabels filename + manifest entry
+ * for a single patch atomically.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (`--to <new-name>` is required)
+ */
+export declare function patchRenameCommand(projectRoot: string, identifier: string, options?: PatchRenameOptions): Promise<void>;
+/**
+ * Registers the `patch rename` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchRename(parent: Command, context: CommandContext): void;

package/dist/src/commands/patch/rename.js

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch rename <name>` — relabels a patch's filename, manifest
+ * `name`, and (optionally) `description` without rewriting the `.patch`
+ * file body.
+ *
+ * Companion to `re-export --files <subset>`. Re-export shrinks the body
+ * + `filesAffected`, but leaves the patch's identity describing the
+ * pre-shrink scope. Before this verb existed, the only workaround for
+ * that drift was `delete` + re-export, which briefly removed the patch
+ * from the queue (any forward-import dependent would refuse the
+ * re-export until the deleted patch's siblings were rewritten).
+ *
+ * The filename rename and the manifest mutation happen under the patch
+ * directory lock so concurrent exports cannot allocate the new
+ * filename, and a filesystem rename failure rolls back before the
+ * manifest is touched.
+ */
+import { rename as fsRename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { sanitizeName } from '../../core/patch-export.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, resolvePatchIdentifier, savePatchesManifest, } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+import { pickDefined } from '../../utils/options.js';
+/**
+ * Pulls the ordinal-string + category prefix out of a patch filename so
+ * the rename keeps the existing ordinal padding verbatim. Returning the
+ * literal substring (rather than recomputing from the parsed integer)
+ * avoids any chance of the new filename's ordinal differing from the
+ * old by a leading-zero count.
+ */
+function splitPatchFilename(filename) {
+    const m = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(filename);
+    if (!m?.[1] || !m[2] || !m[3])
+        return null;
+    return { ordinalStr: m[1], category: m[2], slug: m[3] };
+}
+/**
+ * Performs the rename's transactional core under the patch directory
+ * lock: re-reads the manifest, re-checks for filename collisions,
+ * renames the `.patch` file on disk (when applicable), writes the
+ * updated manifest, and appends a history entry. Filesystem rename
+ * happens before the manifest save so an interrupted run never leaves
+ * the manifest pointing at a missing file; a manifest-save failure
+ * rolls the filesystem rename back.
+ */
+async function commitRenameUnderLock(input) {
+    const { patchesDir, target, newFilename, newName, newDescription, filenameChanging, nameChanging, descriptionChanging, } = input;
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const fresh = await loadPatchesManifest(patchesDir);
+        if (!fresh) {
+            throw new GeneralError('Manifest disappeared between resolution and rename.');
+        }
+        const idx = fresh.patches.findIndex((p) => p.filename === target.filename);
+        if (idx === -1) {
+            throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename. Re-run after investigating.`);
+        }
+        const before = fresh.patches[idx];
+        if (!before) {
+            throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename.`);
+        }
+        if (filenameChanging) {
+            const collisionInLock = fresh.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
+            if (collisionInLock) {
+                throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch claimed that filename concurrently.`, 'patch rename');
+            }
+            const oldPath = join(patchesDir, target.filename);
+            const newPath = join(patchesDir, newFilename);
+            if (await pathExists(newPath)) {
+                throw new InvalidArgumentError(`Cannot rename: ${newFilename} already exists on disk. Resolve manually before retrying.`, 'patch rename');
+            }
+            await fsRename(oldPath, newPath);
+            fresh.patches[idx] = {
+                ...before,
+                filename: newFilename,
+                name: newName,
+                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
+            };
+            try {
+                await savePatchesManifest(patchesDir, fresh);
+            }
+            catch (saveError) {
+                try {
+                    await fsRename(newPath, oldPath);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore ${target.filename} after manifest write failure: ${toError(rollbackError).message}`);
+                }
+                throw saveError;
+            }
+        }
+        else {
+            fresh.patches[idx] = {
+                ...before,
+                ...(nameChanging ? { name: newName } : {}),
+                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
+            };
+            await savePatchesManifest(patchesDir, fresh);
+        }
+        try {
+            await appendHistory(patchesDir, {
+                operation: 'patch-rename',
+                args: {
+                    oldFilename: target.filename,
+                    newFilename,
+                    oldName: target.name,
+                    newName,
+                    ...(descriptionChanging ? { oldDescription: target.description, newDescription } : {}),
+                },
+                ...(input.yes === true ? { yes: true } : {}),
+                result: 'ok',
+            });
+        }
+        catch (historyError) {
+            warn(`History log append failed after patch rename committed (${newFilename}): ${toError(historyError).message}`);
+        }
+    });
+}
+/**
+ * Runs the `patch rename` command: relabels filename + manifest entry
+ * for a single patch atomically.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (`--to <new-name>` is required)
+ */
+export async function patchRenameCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch rename (dry run)' : 'FireForge patch rename');
+    if (options.to === undefined || options.to.trim() === '') {
+        throw new InvalidArgumentError('Specify --to <new-name>. The new name is sanitised into the filename slug the same way `export --name` is.', 'patch rename');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const target = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!target) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
+    }
+    const split = splitPatchFilename(target.filename);
+    if (!split) {
+        throw new GeneralError(`Cannot rename ${target.filename}: filename does not match the expected {ordinal}-{category}-{slug}.patch convention. Re-export the patch instead.`);
+    }
+    const newSlug = sanitizeName(options.to);
+    if (newSlug === '') {
+        throw new InvalidArgumentError('--to must contain at least one alphanumeric character after sanitisation.', 'patch rename');
+    }
+    const newFilename = `${split.ordinalStr}-${split.category}-${newSlug}.patch`;
+    const filenameChanging = newFilename !== target.filename;
+    const nameChanging = options.to !== target.name;
+    const descriptionChanging = options.description !== undefined && options.description !== target.description;
+    if (!filenameChanging && !nameChanging && !descriptionChanging) {
+        info(`${target.filename}: name and description already match — nothing to change.`);
+        outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch rename (no-op)');
+        return;
+    }
+    // Pre-flight collision check against the manifest snapshot we already
+    // loaded. The authoritative check happens again inside the lock to
+    // close the TOCTOU window — surface a helpful error here when the
+    // collision is obvious so the operator does not get surprised by a
+    // late refusal after a confirmation prompt.
+    if (filenameChanging) {
+        const collision = manifest.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
+        if (collision) {
+            throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch already uses that filename.`, 'patch rename');
+        }
+    }
+    const summary = [];
+    if (filenameChanging) {
+        summary.push(`rename ${target.filename} → ${newFilename}`);
+    }
+    if (nameChanging) {
+        summary.push(`name: "${target.name}" → "${options.to}"`);
+    }
+    if (descriptionChanging) {
+        summary.push(`description: "${target.description || '(none)'}" → "${options.description ?? '(none)'}"`);
+    }
+    const decision = await confirmDestructive({
+        operation: 'patch-rename',
+        title: `Rename ${target.filename}`,
+        summary,
+        yes: options.yes === true,
+        dryRun: isDryRun,
+        conflicts: null,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Rename cancelled');
+        return;
+    }
+    await commitRenameUnderLock({
+        patchesDir: paths.patches,
+        target,
+        newFilename,
+        newName: options.to,
+        ...(options.description !== undefined ? { newDescription: options.description } : {}),
+        filenameChanging,
+        nameChanging,
+        descriptionChanging,
+        ...(options.yes === true ? { yes: true } : {}),
+    });
+    if (filenameChanging) {
+        info(`${target.filename} → ${newFilename}`);
+    }
+    else {
+        info(`${target.filename}: metadata updated.`);
+    }
+    outro('Patch rename complete');
+}
+/**
+ * Registers the `patch rename` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchRename(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('rename <name>')
+        .description('Rename a patch: filename + manifest name (and optional description) update without rewriting the .patch body.')
+        .requiredOption('--to <new-name>', 'New human-readable name (sanitised into the filename slug)')
+        .option('--description <text>', 'Replacement description (omit to leave description unchanged)')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        await patchRenameCommand(getProjectRoot(), name, pickDefined(options));
+    }));
+}
+//# sourceMappingURL=rename.js.map

package/dist/src/commands/test.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, } from '../core/mach.js';
-import { assertMarionettePortAvailable } from '../core/marionette-port.js';
+import { assertMarionettePortAvailable, extractForwardedMarionettePort, isMarionetteFlavor, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
@@ -238,6 +238,20 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             warn(formatStaleBuildWarning(stale));
         }
     }
+    // Resolve the effective Marionette port. Operator precedence:
+    //   1. `--marionette-port` (first-class option, parsed at the CLI layer)
+    //   2. forwarded `--mach-arg --marionette-port=NNNN` /
+    //      `--mach-arg --setpref=marionette.port=NNNN`
+    //   3. fall back to `DEFAULT_MARIONETTE_PORT` semantics inside the probes
+    //      (passed as `undefined`).
+    // Without (2), an operator working around a stale listener via the
+    // documented `--mach-arg --marionette-port=NNNN` workaround would still
+    // hit the wrapper preflight refusing on 2828 before the forwarded arg
+    // ever reached mach.
+    const forwardedPort = options.machArg
+        ? extractForwardedMarionettePort(options.machArg)
+        : undefined;
+    const effectivePort = options.marionettePort ?? forwardedPort;
     // Stale-browser probe: an interrupted earlier test run can leave a
     // Firefox/ForgeFresh/Hominis instance listening on the Marionette
     // control port, which breaks the next mach test launch with a
@@ -246,7 +260,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // generic bind failure. 2026-04-21 eval (Finding #20): a stale
     // `-marionette` process from `fresh/` poisoned a later test run in
     // the sibling `hominis/` workspace.
-    await assertMarionettePortAvailable(undefined, { binaryName: projectConfig.binaryName });
+    await assertMarionettePortAvailable(effectivePort, { binaryName: projectConfig.binaryName });
     // `--doctor` runs a short marionette handshake probe. When test paths are
     // supplied the probe gates the mach test invocation (a FAIL bails out). When
     // no paths are supplied this is the only step — it's the fastest way to tell
@@ -259,7 +273,9 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         // clack box-drawing framing.
         process.stdout.write('Running marionette preflight...\n');
         info('Running marionette preflight...');
-        const preflight = await runMarionettePreflight(paths.engine);
+        const preflight = effectivePort !== undefined
+            ? await runMarionettePreflight(paths.engine, { port: effectivePort })
+            : await runMarionettePreflight(paths.engine);
         // 2026-04-24 eval Finding 7: the pre-0.18.1 code used
         // `success()` + `outro()` + a direct `process.stdout.write` as a
         // belt-and-suspenders but still reproducibly dropped the PASS summary
@@ -303,6 +319,30 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (options.machArg && options.machArg.length > 0) {
         extraArgs.push(...options.machArg);
     }
+    // Auto-forward the Marionette port to mach when `--marionette-port` is
+    // set. We use `--setpref=marionette.port=<n>` because the marionette
+    // listener reads that pref before binding (browser-chrome / mochitest
+    // path); xpcshell never reads it, so the pref is a no-op there.
+    //
+    // Skip forwarding when the operator already supplied an equivalent arg
+    // via `--mach-arg` — duplicates would be confusing without changing
+    // semantics. Skip with a notice for clearly-non-marionette flavours
+    // (xpcshell, or paths that don't look browser-chrome/mochitest) so the
+    // operator knows the preflight took the override but mach was not
+    // auto-configured. Same escape valve applies: any mach arg can still
+    // be supplied via `--mach-arg`.
+    if (options.marionettePort !== undefined) {
+        const operatorAlreadyForwarded = forwardedPort !== undefined;
+        if (operatorAlreadyForwarded) {
+            info(`--marionette-port=${options.marionettePort} set, but the same port is already forwarded via --mach-arg; skipping auto-forward.`);
+        }
+        else if (isMarionetteFlavor(normalizedPaths, options.machArg ?? [])) {
+            extraArgs.push(`--setpref=marionette.port=${options.marionettePort}`);
+        }
+        else {
+            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but the test paths do not look browser-chrome/mochitest — mach is not auto-configured. Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if mach should also use this port.`);
+        }
+    }
     // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
     // full motivation. On rebranded forks (appname != "firefox") the upstream
     // harness silently ignores `firefox-appdir = "browser"` directives in the
@@ -368,6 +408,13 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         acc.push(value);
         return acc;
     }, [])
+        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and the auto-forwarded --setpref=marionette.port=<n> arg passed to mach. Use this when a stale process holds 2828 or a CI runner reserves a different port.', (raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isFinite(n) || n < 1 || n > 65535) {
+            throw new GeneralError(`--marionette-port must be an integer in 1..65535 (got "${raw}")`);
+        }
+        return n;
+    })
         .action(withErrorHandling(async (paths, options) => {
         await testCommand(getProjectRoot(), paths, pickDefined(options));
     }));

package/dist/src/core/ast-utils.d.ts

@@ -15,8 +15,12 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
  * Parse JavaScript source as a **script** (not an ES module).
  * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
+ *
+ * @param content - Source text to parse
+ * @param onComment - Optional array that acorn fills with comment nodes
+ * @returns Parsed program AST with character-offset positions
  */
-export declare function parseScript(content: string): AcornESTreeNode<estree.Program>;
+export declare function parseScript(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
 /**
  * Parse JavaScript source as an **ES module**.
  * Used for `.sys.mjs` files which use static import/export syntax.