@hominis/fireforge 0.18.2 → 0.18.5

package/dist/src/commands/status.js

@@ -7,7 +7,8 @@ import { buildOwnershipTable, renderOwnershipTable } from '../core/ownership-tab
 import { buildPatchQueueContext, collectNewFileCreatorsByPath } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { classifyFiles, } from '../core/status-classify.js';
-import { GeneralError } from '../errors/base.js';
+import { CommandError, GeneralError } from '../errors/base.js';
+import { ExitCode } from '../errors/codes.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, outro, warn } from '../utils/logger.js';
 /**
@@ -260,6 +261,14 @@ async function assertEngineHasBaselineCommit(engineDir, options) {
             warn(guidance);
             outro('Engine baseline missing — re-run download --force');
         }
+        if (options.json) {
+            // Mirror `--json`'s contract: errors must be machine-parseable too.
+            // Without this branch the human guidance above is suppressed but the
+            // throw still falls through to the styled error renderer in
+            // withErrorHandling, leaving JSON consumers with non-JSON output on
+            // exactly the failure mode they care about catching.
+            process.stdout.write(JSON.stringify({ error: guidance, code: 'engine-baseline-missing' }) + '\n');
+        }
         throw new GeneralError(guidance);
     }
 }
@@ -278,6 +287,29 @@ export async function statusCommand(projectRoot, options = {}) {
     }
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
+    // `--json` mode contracts to machine-parseable output on every code path,
+    // including failure modes. Before this guard, errors raised below
+    // ("Firefox source not found", "engine is not a git repository") flowed
+    // through the normal styled error renderer in `withErrorHandling`, so
+    // scripts piping `status --json | jq` broke precisely when the engine was
+    // missing. Surface a structured `{ "error": ..., "code": ... }` payload
+    // and exit non-zero via GeneralError so the exit code still reflects the
+    // failure but stdout remains valid JSON. The same guard runs for
+    // ownership mode below because that path also throws on missing engine.
+    // 2026-04-26 eval Finding 1: throw `CommandError` rather than
+    // `GeneralError` after the JSON line lands on stdout. `GeneralError`
+    // is a `FireForgeError`, so the `withErrorHandling` wrapper in cli.ts
+    // calls `logError(error.userMessage)` on it, which routes the styled
+    // human banner through clack to stdout — `status --json` therefore
+    // emitted both the JSON object AND the `■ Firefox source not found …`
+    // line on stdout, breaking every script that pipes the command into
+    // a JSON parser. `CommandError` is the bin-only sentinel that
+    // `withErrorHandling` does not log: bin/fireforge.ts catches it,
+    // exits with the carried code, and stdout stays a single JSON line.
+    const emitJsonError = (code, message) => {
+        process.stdout.write(JSON.stringify({ error: message, code }) + '\n');
+        throw new CommandError(ExitCode.GENERAL_ERROR);
+    };
     // Ownership mode is a flat file→patch table; sources are the manifest's
     // filesAffected, any worktree drift, and the cross-patch
     // duplicate-new-file-creation map produced by walking each patch
@@ -326,10 +358,16 @@ export async function statusCommand(projectRoot, options = {}) {
     }
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
+        if (options.json) {
+            emitJsonError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
+        }
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
     // Check if it's a git repository
     if (!(await isGitRepository(paths.engine))) {
+        if (options.json) {
+            emitJsonError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
+        }
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     await assertEngineHasBaselineCommit(paths.engine, options);

package/dist/src/commands/test.js

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, } from '../core/mach.js';
 import { assertMarionettePortAvailable } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
@@ -193,6 +193,25 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // probe have access to `binaryName` (the port probe uses it to
     // recognise a fork-branded browser holding the Marionette port).
     const projectConfig = await loadConfig(projectRoot);
+    // `hasBuildArtifacts` only confirms `obj-*/dist/` exists; a partial
+    // build (linker failed, packaging step interrupted, etc.) can satisfy
+    // that check without ever writing the launchable binary the marionette
+    // preflight needs to spawn. `fireforge run` already uses
+    // `hasRunnableBundle` to fail fast with a precise message; mirror that
+    // here so `test --doctor` against an incomplete build surfaces the
+    // missing-bundle path instead of a cryptic `Browser process exited
+    // during spawn (exit code 1, signal none). stderr tail: (empty)`.
+    if (buildCheck.objDir) {
+        const bundleCheck = await hasRunnableBundle(paths.engine, projectConfig.binaryName, buildCheck.objDir);
+        if (!bundleCheck.runnable) {
+            const expectedSuffix = bundleCheck.expectedPath
+                ? ` (expected at engine/${bundleCheck.expectedPath})`
+                : '';
+            throw new GeneralError(`Tests require a complete launchable build${expectedSuffix}. ` +
+                'The obj-*/dist/ tree exists but the launchable binary is missing — typically the result of an interrupted or partially failed `fireforge build`.\n\n' +
+                'Run "fireforge build" again and let it finish before retrying "fireforge test".');
+        }
+    }
     // Run incremental build if requested
     if (options.build) {
         await prepareBuildEnvironment(projectRoot, paths, projectConfig);

package/dist/src/commands/token.js

@@ -120,7 +120,7 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
     });
     token
         .command('add <token-name> <value>')
-        .description('Add a design token to CSS and documentation')
+        .description('Add a design token to CSS and documentation. The token name is a positional argument, but most tokens start with `--` (CSS custom property syntax), which Commander reads as an option flag. Use the standard `--` separator to mark the end of options before the token name, e.g. `fireforge token add --mode static --category Colors -- --my-token "#fff"`. Bare names without `--` are accepted directly and prefixed using the configured Furnace `tokenPrefix`.')
         .requiredOption('--category <cat>', 'Token category (e.g., "Colors — Canvas", "Spacing")')
         .addOption(
     // Use Commander's .choices() so invalid --mode values are rejected with

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

@@ -9,6 +9,7 @@ import { applyCustomComponent, applyOverrideComponent, computeComponentChecksums
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from './furnace-constants.js';
 import { topologicalSortCustom } from './furnace-graph-utils.js';
+import { resolveFurnaceMarkerComment } from './furnace-marker.js';
 import { recordFurnaceRollbackFailure } from './furnace-operation.js';
 import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
@@ -304,9 +305,16 @@ export async function applyAllComponents(root, dryRun = false, options) {
     const { engine: engineDir } = getProjectPaths(root);
     const furnacePaths = getFurnacePaths(root);
     const ftlDir = resolveFtlDir(config.ftlBasePath);
-    const markerComment = await loadConfig(root)
-        .then((forgeConfig) => forgeConfig.markerComment)
-        .catch(() => undefined);
+    // 2026-04-26 eval Finding 6: when `markerComment` is unset in
+    // fireforge.json, default it to `binaryName.toUpperCase()` so the
+    // furnace-emitted edits to upstream files (e.g. customElements.js)
+    // carry a marker that satisfies `lintModificationComments` — that
+    // rule keys on `${binaryName.toUpperCase()}:` and was firing
+    // `[missing-modification-comment]` on every furnace-applied
+    // upstream edit because the implicit default was `undefined`. An
+    // explicit `markerComment` in fireforge.json still wins.
+    const forgeConfig = await loadConfig(root).catch(() => undefined);
+    const markerComment = resolveFurnaceMarkerComment(forgeConfig);
     if (!(await pathExists(engineDir))) {
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
     }

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

@@ -541,6 +541,20 @@ export async function updateFurnaceState(root, updates) {
         await writeJson(paths.furnaceState, validateFurnaceState(nextState));
     });
 }
+/**
+ * Engine-relative path of the directory `furnace preview` writes its
+ * generated Storybook story files into. Treated as Furnace-managed so
+ * `status` does not flag them as unmanaged and `lint` does not fail on
+ * their (intentionally bare) license headers.
+ *
+ * 2026-04-25 eval Finding 19: a successful `furnace preview` run synced
+ * 23 stories under this prefix; afterwards `status` showed all 23 as
+ * untracked unmanaged changes and aggregate `lint` failed with 23
+ * `missing-license-header` errors. The files are tool output — operators
+ * are not expected to commit or hand-edit them — so the right shape is
+ * to bucket them with the rest of Furnace's managed material.
+ */
+const FURNACE_STORYBOOK_STORIES_PREFIX = 'browser/components/storybook/stories/furnace/';
 /**
  * Collects engine-relative path prefixes that are managed by the Furnace
  * component system (overrides, custom components, and their Fluent l10n
@@ -571,6 +585,11 @@ export async function collectFurnaceManagedPrefixes(root) {
             prefixes.add(ftlDir.endsWith('/') ? ftlDir : ftlDir + '/');
         }
     }
+    // Always include the preview-generated stories prefix when furnace is
+    // initialised. The directory may not exist yet (no preview ever ran),
+    // but classifying it as furnace-managed is safe even when empty —
+    // status simply has nothing to bucket.
+    prefixes.add(FURNACE_STORYBOOK_STORIES_PREFIX);
     return prefixes;
 }
 //# sourceMappingURL=furnace-config.js.map

package/dist/src/core/furnace-marker.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Marker-comment resolution shared between furnace apply and deploy.
+ *
+ * 2026-04-26 eval Finding 6: when `markerComment` is unset in
+ * fireforge.json, fall back to `binaryName.toUpperCase()` so the
+ * patch-lint rule `lintModificationComments` (which keys on
+ * `${binaryName.toUpperCase()}:`) accepts furnace-emitted edits on the
+ * next `lint`/`export` round-trip. The helper tolerates the
+ * undefined-config case (a project that hasn't run `fireforge setup`
+ * yet) and the missing-binaryName case (test fixtures that mock
+ * `loadConfig` with a partial shape).
+ */
+export declare function resolveFurnaceMarkerComment(forgeConfig: {
+    markerComment?: string;
+    binaryName?: string;
+} | undefined): string | undefined;

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

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Marker-comment resolution shared between furnace apply and deploy.
+ *
+ * 2026-04-26 eval Finding 6: when `markerComment` is unset in
+ * fireforge.json, fall back to `binaryName.toUpperCase()` so the
+ * patch-lint rule `lintModificationComments` (which keys on
+ * `${binaryName.toUpperCase()}:`) accepts furnace-emitted edits on the
+ * next `lint`/`export` round-trip. The helper tolerates the
+ * undefined-config case (a project that hasn't run `fireforge setup`
+ * yet) and the missing-binaryName case (test fixtures that mock
+ * `loadConfig` with a partial shape).
+ */
+export function resolveFurnaceMarkerComment(forgeConfig) {
+    if (!forgeConfig)
+        return undefined;
+    if (forgeConfig.markerComment !== undefined)
+        return forgeConfig.markerComment;
+    if (forgeConfig.binaryName)
+        return forgeConfig.binaryName.toUpperCase();
+    return undefined;
+}
+//# sourceMappingURL=furnace-marker.js.map

package/dist/src/core/git.js

@@ -65,6 +65,35 @@ async function cleanupIndexLock(dir) {
         verbose('Cleaned up stale .git/index.lock after timeout');
     }
 }
+/**
+ * Returns true when {@link relativePath} is ignored by `.gitignore` (or
+ * any other exclusion mechanism git considers, e.g. `.git/info/exclude`,
+ * core.excludesFile). Used by the chunked staging fallback to skip
+ * entries that would otherwise fail `git add -- <path>` with the fatal
+ * "The following paths are ignored by one of your .gitignore files"
+ * error — a state the monolithic `git add -A` path silently handles.
+ *
+ * Implementation: `git check-ignore -q -- <path>` exits 0 when the path
+ * is ignored, 1 when it isn't, and >=128 on real failures. Treat
+ * anything other than 0/1 as "unknown" and conservatively return false
+ * so the chunk runs and any real underlying failure surfaces normally.
+ *
+ * 2026-04-26 eval Finding 4: a Firefox checkout's top-level `.vscode/`
+ * is gitignored by the source tree's own `.gitignore`. Pre-fix, the
+ * chunked `git add -- .vscode` invocation aborted the entire fallback
+ * and turned a recoverable monolithic timeout into a hard setup
+ * failure that required `fireforge download --force`.
+ */
+async function isPathIgnored(dir, relativePath) {
+    const result = await exec('git', ['check-ignore', '-q', '--', relativePath], { cwd: dir });
+    if (result.exitCode === 0)
+        return true;
+    if (result.exitCode === 1)
+        return false;
+    // Any other shape is "we don't know" — let the caller proceed and
+    // surface the real error if `git add` rejects the path.
+    return false;
+}
 /**
  * Stages every file by walking top-level directories one at a time.
  * This avoids a single monolithic `git add -A` that may time out on
@@ -98,11 +127,26 @@ async function stageAllFilesChunked(dir, options = {}) {
         }
     }
     for (const dirName of directories) {
+        if (await isPathIgnored(dir, dirName)) {
+            options.onProgress?.(`Skipping gitignored: ${dirName}/`);
+            continue;
+        }
         options.onProgress?.(`Staging directory: ${dirName}/...`);
         await runChunk(['add', '--', dirName], dirName);
     }
-    // Stage any top-level files
-    const topLevelFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
+    // Stage any top-level files (excluding gitignored ones — `git add`
+    // on an explicit ignored path errors out, which would otherwise
+    // abort the chunked fallback after the monolithic path has already
+    // timed out).
+    const topLevelCandidates = entries.filter((e) => e.isFile()).map((e) => e.name);
+    const topLevelFiles = [];
+    for (const name of topLevelCandidates) {
+        if (await isPathIgnored(dir, name)) {
+            options.onProgress?.(`Skipping gitignored: ${name}`);
+            continue;
+        }
+        topLevelFiles.push(name);
+    }
     if (topLevelFiles.length > 0) {
         options.onProgress?.('Staging top-level files...');
         await runChunk(['add', '--', ...topLevelFiles], 'top-level files');
@@ -125,16 +169,23 @@ const GIT_ADD_HEARTBEAT_MS = 15_000;
 export async function stageAllFiles(dir, options = {}) {
     const timeout = options.timeout ?? GIT_ADD_TIMEOUT_MS;
     const reportProgress = options.onProgress;
-    const heartbeatStartedAt = Date.now();
-    // Periodic heartbeat so non-TTY log scrapers (CI, tail -f) AND operators
-    // watching a spinner both see that the add is still making progress
-    // rather than a dead process. Each tick reports elapsed seconds so the
-    // expected 1–3 minute window (see `download.ts`' info banner) is
-    // observable as it unfolds.
+    // 2026-04-26 eval Finding 5: the pre-fix heartbeat used a single
+    // `heartbeatStartedAt` set at function entry and reported cumulative
+    // elapsed for the whole `stageAllFiles` invocation. After a
+    // monolithic timeout, the chunked-phase ticks therefore named
+    // numbers that already included the entire monolithic budget plus
+    // any host-sleep time, with no way for an operator watching the log
+    // to tell where the monolithic attempt ended and the chunked pass
+    // began. The heartbeat now tracks a per-phase start timestamp and
+    // labels each tick with the phase, so the chunked pass reports its
+    // own elapsed window and the monolithic→chunked handoff is visible.
+    let phase = 'monolithic';
+    let phaseStartedAt = Date.now();
     const heartbeatTimer = reportProgress
         ? setInterval(() => {
-            const elapsedS = Math.round((Date.now() - heartbeatStartedAt) / 1000);
-            reportProgress(`Indexing Firefox source (still staging, ${elapsedS}s elapsed)`);
+            const elapsedS = Math.round((Date.now() - phaseStartedAt) / 1000);
+            const label = phase === 'monolithic' ? 'monolithic' : 'chunked staging';
+            reportProgress(`Indexing Firefox source (${label}, ${elapsedS}s elapsed)`);
         }, GIT_ADD_HEARTBEAT_MS)
         : null;
     heartbeatTimer?.unref();
@@ -158,6 +209,11 @@ export async function stageAllFiles(dir, options = {}) {
         }
         // The killed process may have left an index lock
         await cleanupIndexLock(dir);
+        // Reset elapsed accounting for the chunked phase so its heartbeat
+        // names a believable per-phase number rather than rolling the
+        // monolithic budget forward.
+        phase = 'chunked';
+        phaseStartedAt = Date.now();
         try {
             await stageAllFilesChunked(dir, options);
         }

package/dist/src/core/license-headers.d.ts

@@ -21,6 +21,14 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  * Returns true if `content` starts with any known license header for the
  * given comment style.
  *
+ * For `js` files, MPL-2.0 is also accepted in the upstream Mozilla block-
+ * comment form (`/* ... *\/`) used by the Firefox source tree, not just the
+ * `// ` line-comment form `getLicenseHeader` emits. Without that, a new JS
+ * file copied from upstream Firefox (or written to match the surrounding
+ * code's convention) hit `missing-license-header` even with a verbatim
+ * standard MPL header — operators were forced to `--skip-lint` over a real
+ * false positive.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */

package/dist/src/core/license-headers.js

@@ -57,12 +57,26 @@ export function getLicenseHeader(license, style) {
  * Returns true if `content` starts with any known license header for the
  * given comment style.
  *
+ * For `js` files, MPL-2.0 is also accepted in the upstream Mozilla block-
+ * comment form (`/* ... *\/`) used by the Firefox source tree, not just the
+ * `// ` line-comment form `getLicenseHeader` emits. Without that, a new JS
+ * file copied from upstream Firefox (or written to match the surrounding
+ * code's convention) hit `missing-license-header` even with a verbatim
+ * standard MPL header — operators were forced to `--skip-lint` over a real
+ * false positive.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
 export function hasAnyLicenseHeader(content, style) {
     const licenses = Object.keys(HEADER_LINES);
-    return licenses.some((license) => content.startsWith(getLicenseHeader(license, style)));
+    if (licenses.some((license) => content.startsWith(getLicenseHeader(license, style)))) {
+        return true;
+    }
+    if (style === 'js' && content.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
+        return true;
+    }
+    return false;
 }
 /**
  * Returns true if `content` starts with any known license header in any

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

@@ -65,7 +65,15 @@ async function isSharedCSSRegistered(engineDir, fileName) {
     }
     const name = basename(fileName, '.css');
     const content = await readText(manifestPath);
-    return content.includes(`skin/classic/browser/${name}.css`);
+    // `register` writes the canonical `skin/classic/browser/<name>.css` form;
+    // `furnace chrome-doc create` writes a `content/browser/<name>.css` entry
+    // because the CSS is loaded by a chrome document via a `chrome://browser/
+    // content/<name>.css` URI. Match either prefix so paths registered by the
+    // chrome-doc scaffolder are not flagged as "potentially unregistered" by
+    // `status` and so a re-run of `register` against the same file recognises
+    // the existing entry instead of proposing a duplicate.
+    return (content.includes(`skin/classic/browser/${name}.css`) ||
+        content.includes(`content/browser/${name}.css`));
 }
 async function isBrowserContentRegistered(engineDir, fileName) {
     const manifestPath = join(engineDir, 'browser/base/jar.mn');

package/dist/src/core/patch-identifier-suggest.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Builds a concise "patch not found" error message with did-you-mean
+ * suggestions in place of the full queue enumeration.
+ *
+ * 2026-04-26 eval Finding 12: pre-fix every `patch` subcommand
+ * (`delete`, `reorder`, `tier`, `lint-ignore`) caught a missing
+ * identifier by joining every queued patch's filename and (optional)
+ * manifest name into a single comma-separated `Available: ...` tail.
+ * On a 29-patch queue the resulting line ran ~1500 characters and
+ * buried the actual error under noise that was almost never useful in
+ * CI. The new shape ranks each known identifier (ordinal,
+ * filename-with-and-without-`.patch`, manifest name) by Levenshtein
+ * distance from the operator's input, surfaces up to three suggestions
+ * close enough to be plausibly the intended target, and falls back to
+ * a count-only summary that points at `fireforge patch list` when no
+ * close match exists. The full enumeration is no longer ever inlined.
+ */
+import type { PatchMetadata } from '../types/commands/index.js';
+/**
+ * Formats the user-facing "patch not found" error message used by
+ * `patch delete`, `patch reorder`, `patch tier`, and
+ * `patch lint-ignore`. Returns a single string suitable for the
+ * `InvalidArgumentError` body — never the full queue enumeration.
+ */
+export declare function formatPatchNotFoundError(identifier: string, patches: readonly PatchMetadata[]): string;

package/dist/src/core/patch-identifier-suggest.js

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Builds a concise "patch not found" error message with did-you-mean
+ * suggestions in place of the full queue enumeration.
+ *
+ * 2026-04-26 eval Finding 12: pre-fix every `patch` subcommand
+ * (`delete`, `reorder`, `tier`, `lint-ignore`) caught a missing
+ * identifier by joining every queued patch's filename and (optional)
+ * manifest name into a single comma-separated `Available: ...` tail.
+ * On a 29-patch queue the resulting line ran ~1500 characters and
+ * buried the actual error under noise that was almost never useful in
+ * CI. The new shape ranks each known identifier (ordinal,
+ * filename-with-and-without-`.patch`, manifest name) by Levenshtein
+ * distance from the operator's input, surfaces up to three suggestions
+ * close enough to be plausibly the intended target, and falls back to
+ * a count-only summary that points at `fireforge patch list` when no
+ * close match exists. The full enumeration is no longer ever inlined.
+ */
+/** Maximum Levenshtein distance accepted as a "did you mean" suggestion. */
+const SUGGESTION_DISTANCE_THRESHOLD = 3;
+/** Maximum number of suggestions to surface in the error message. */
+const SUGGESTION_LIMIT = 3;
+/**
+ * Computes the Levenshtein edit distance between two strings. Used by
+ * `formatPatchNotFoundError` to rank candidate identifiers; the small
+ * upper bound on input lengths (filenames, ordinals, names) makes the
+ * O(m*n) implementation trivially fast.
+ */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Allocate the row buffers up-front and fill with zero so every index in
+    // [0, b.length] is populated before any read. Using `Array.fill(0)` keeps
+    // the type as `number[]` (not `(number | undefined)[]`) so subsequent
+    // index reads compose without optional-chaining noise.
+    const prev = new Array(b.length + 1).fill(0);
+    const curr = new Array(b.length + 1).fill(0);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const left = curr[j - 1] ?? 0;
+            const up = prev[j] ?? 0;
+            const diag = prev[j - 1] ?? 0;
+            curr[j] = Math.min(left + 1, up + 1, diag + cost);
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j] ?? 0;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * Collects every identifier shape FireForge accepts for a queue entry:
+ *   - the ordinal (string form), e.g. `"2"`
+ *   - the filename, e.g. `"002-ui-foo.patch"`
+ *   - the filename without the `.patch` suffix, e.g. `"002-ui-foo"`
+ *   - the manifest `name` field, when distinct from the filename
+ * Returned as a flat list so the suggestion ranking can compare each
+ * candidate independently.
+ */
+function collectAcceptedIdentifiers(patches) {
+    const set = new Set();
+    for (const patch of patches) {
+        set.add(String(patch.order));
+        set.add(patch.filename);
+        if (patch.filename.endsWith('.patch')) {
+            set.add(patch.filename.slice(0, -'.patch'.length));
+        }
+        if (patch.name && patch.name !== patch.filename)
+            set.add(patch.name);
+    }
+    return Array.from(set);
+}
+/**
+ * Returns up to {@link SUGGESTION_LIMIT} accepted identifiers ordered
+ * by closest Levenshtein distance to {@link identifier}, dropping any
+ * candidate whose distance exceeds {@link SUGGESTION_DISTANCE_THRESHOLD}.
+ */
+function rankSuggestions(identifier, candidates) {
+    return candidates
+        .map((candidate) => ({ candidate, distance: levenshtein(identifier, candidate) }))
+        .filter((entry) => entry.distance <= SUGGESTION_DISTANCE_THRESHOLD)
+        .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate))
+        .slice(0, SUGGESTION_LIMIT)
+        .map((entry) => entry.candidate);
+}
+/**
+ * Formats the user-facing "patch not found" error message used by
+ * `patch delete`, `patch reorder`, `patch tier`, and
+ * `patch lint-ignore`. Returns a single string suitable for the
+ * `InvalidArgumentError` body — never the full queue enumeration.
+ */
+export function formatPatchNotFoundError(identifier, patches) {
+    const accepted = collectAcceptedIdentifiers(patches);
+    const suggestions = rankSuggestions(identifier, accepted);
+    const lead = `Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo).`;
+    if (suggestions.length > 0) {
+        return `${lead} Did you mean: ${suggestions.join(', ')}? (${patches.length} patches in queue — run "fireforge patch list" for the full list.)`;
+    }
+    return `${lead} No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
+}
+//# sourceMappingURL=patch-identifier-suggest.js.map

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

@@ -359,6 +359,14 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
             continue;
         if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
             continue;
+        // Accept the MPL-2.0 block-comment form (`/* ... */` with leading `*`)
+        // for any JS file — that is the canonical upstream Firefox header
+        // shape, and `hasAnyLicenseHeader` above also recognises it. The
+        // explicit guard mirrors the branding carve-out so operators using the
+        // standard Mozilla header on a JS file (e.g. one copied from upstream
+        // browser/base/content) do not need `--skip-lint` to land it.
+        if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
+            continue;
         issues.push({
             file,
             check: 'missing-license-header',

package/dist/src/core/register-shared-css.d.ts

@@ -2,10 +2,38 @@
  * CSS registration in browser/themes/shared/jar.inc.mn.
  */
 import type { RegisterResult } from './manifest-register.js';
+/**
+ * Measures the column at which the `(source)` parenthesis opens in
+ * adjacent `skin/classic/browser/<x>.css (...)` entries inside an
+ * existing jar.inc.mn body, and returns the maximum so a newly inserted
+ * entry can align its source column to match.
+ *
+ * 2026-04-26 eval Finding 3: pre-fix `registerSharedCSS` always emitted
+ * a four-space gap between the target path and the parenthesis,
+ * regardless of how the rest of the file was aligned. Adjacent Firefox
+ * entries are typically padded to a wider column, so a freshly
+ * registered file landed at the wrong column and produced avoidable
+ * formatting churn. Returns `undefined` when no existing entries
+ * provide an alignment signal — callers fall back to the four-space
+ * default in that case.
+ */
+export declare function measureSourceColumn(content: string): number | undefined;
+/**
+ * Builds a `skin/classic/browser/<name>.css   (../shared/<name>.css)`
+ * line padded so the parenthesis lands at {@link sourceColumn} (when
+ * supplied) or at the default four-space gap (when {@link sourceColumn}
+ * is `undefined` or would force the parenthesis closer to the target
+ * than {@link MIN_SOURCE_GAP}).
+ */
+export declare function buildEntry(name: string, sourceColumn: number | undefined): string;
 /**
  * Registers a CSS file in browser/themes/shared/jar.inc.mn.
  *
  * Entry format:
  *   skin/classic/browser/{name}.css    (../shared/{name}.css)
+ *
+ * The gap between target and source is sized to align with adjacent
+ * entries when the manifest already uses a wider column; falls back to
+ * a four-space minimum otherwise.
  */
 export declare function registerSharedCSS(engineDir: string, fileName: string, after?: string, dryRun?: boolean): Promise<RegisterResult>;