@hominis/fireforge 0.18.1 → 0.18.3

package/dist/src/commands/re-export-files.js

@@ -11,6 +11,85 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, outro, success, warn } from '../utils/logger.js';
 import { runPatchLint } from './export-shared.js';
+/**
+ * Computes the effective `tier` and `lintIgnore` carrying both the
+ * patch's existing values and the CLI flag overrides. Pure helper —
+ * extracted from {@link reExportFilesInPlace} both to share with the
+ * standard re-export path conceptually and to keep the orchestrator
+ * function under the per-file LOC budget.
+ *
+ * Tier resolution: the CLI flag takes precedence; the patch's existing
+ * tier is the fallback. Lint-ignore resolution: union of the patch's
+ * existing list and the CLI flag values, de-duplicated; an empty
+ * result returns `undefined` so the caller can drop the field rather
+ * than write an empty array.
+ */
+function resolveEffectiveTierAndLintIgnore(target, options) {
+    const existingIgnoreSet = new Set(target.lintIgnore ?? []);
+    const flagIgnoreSet = new Set(options.lintIgnore ?? []);
+    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
+    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const effectiveTier = options.tier ?? target.tier;
+    return { effectiveTier, effectiveLintIgnore, flagIgnoreSet };
+}
+/**
+ * Projects the cross-patch context (replace the target entry with its
+ * shrunken self), runs the patch-queue lint against the projection,
+ * and returns a conflict report only for regressions introduced *by*
+ * this shrink. Pre-existing cross-patch errors are surfaced as a
+ * non-blocking warning so the user does not walk away thinking the
+ * queue is clean. Extracted from {@link reExportFilesInPlace} to keep
+ * the orchestrator function under the per-file LOC budget.
+ */
+async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedDiff) {
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const projectedNewFiles = new Map();
+    for (const path of detectNewFilesInDiff(projectedDiff)) {
+        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
+    }
+    const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
+    const projectedEntries = baseCtx.entries.map((entry) => {
+        if (entry.filename !== targetFilename)
+            return entry;
+        return {
+            ...entry,
+            diff: projectedDiff,
+            newFiles: projectedNewFiles,
+            modifiedFileAdditions: projectedModifiedFileAdditions,
+        };
+    });
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
+    if (baselineIssues.length > 0 && regressions.length === 0) {
+        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing ` +
+            `cross-patch error(s) unrelated to this shrink. Run "fireforge verify" to list them.`);
+    }
+    if (regressions.length === 0)
+        return null;
+    return {
+        reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
+        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+    };
+}
+/**
+ * Builds the `Partial<PatchMetadata>` payload for the `--files` write,
+ * folding in the CLI flag overrides for `tier` and `lintIgnore` only
+ * when the operator actually asked for them. Extracted to keep
+ * {@link reExportFilesInPlace} under the per-file LOC budget.
+ */
+function buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet) {
+    const updates = {
+        filesAffected: actualProjectedFiles,
+    };
+    if (options.tier !== undefined) {
+        updates.tier = options.tier;
+    }
+    if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
+        updates.lintIgnore = effectiveLintIgnore;
+    }
+    return updates;
+}
 /**
  * Handles `re-export --files` end-to-end: computes the projected diff,
  * runs the per-patch and cross-patch lint against a context in which the
@@ -77,50 +156,13 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // have to choose between `--skip-lint` (blunt) and the full rebase path.
     // `target.tier` threads the explicit branding-threshold opt-in for
     // the branding patch that also touches a non-allowlisted sibling.
-    const ignoreChecks = target.lintIgnore?.length ? new Set(target.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks, target.tier);
-    // Project the cross-patch context: replace the target entry with its
-    // would-be shrunken self (new diff + new newFiles + new
-    // modifiedFileAdditions). The projected entry must repopulate both
-    // source-site maps so the forward-import rule sees imports the
-    // shrunken diff would add — or stop adding — consistently with how a
-    // real rebuild would see them.
-    const baseCtx = await buildPatchQueueContext(paths.patches);
-    const projectedNewFiles = new Map();
-    for (const path of detectNewFilesInDiff(projectedDiff)) {
-        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
-    }
-    const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
-    const projectedEntries = baseCtx.entries.map((entry) => {
-        if (entry.filename !== target.filename)
-            return entry;
-        return {
-            ...entry,
-            diff: projectedDiff,
-            newFiles: projectedNewFiles,
-            modifiedFileAdditions: projectedModifiedFileAdditions,
-        };
-    });
-    // Baseline-vs-projected diffing: only regressions introduced *by* this
-    // shrink should block. A pre-existing cross-patch error elsewhere in
-    // the queue must not prevent the user from shrinking an unrelated
-    // patch (which is often exactly the tool they reach for to repair
-    // such a queue).
-    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
-    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
-    const conflicts = regressions.length > 0
-        ? {
-            reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
-            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
-        }
-        : null;
-    // Surface pre-existing errors as a non-blocking warning so the user
-    // doesn't walk away thinking the queue is clean.
-    if (baselineIssues.length > 0 && regressions.length === 0) {
-        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing ` +
-            `cross-patch error(s) unrelated to this shrink. Run "fireforge verify" to list them.`);
-    }
+    // CLI flags `--tier` and `--lint-ignore` participate too, with
+    // append/union semantics on the lint-ignore list (matching the
+    // standard re-export path).
+    const { effectiveTier, effectiveLintIgnore, flagIgnoreSet } = resolveEffectiveTierAndLintIgnore(target, options);
+    const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
+    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
+    const conflicts = await runProjectedCrossPatchLint(paths.patches, target.filename, projectedDiff);
     // Shrinks are destructive (previously-owned files become unmanaged).
     // Additive-only changes still deserve a prompt because --files asserts
     // an authoritative file set.
@@ -163,7 +205,8 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // directory lock as the mutation (via the onCommitted hook) so two
     // concurrent re-exports cannot interleave records and a crash between
     // mutation and append cannot orphan the audit trail.
-    await updatePatchAndMetadata(paths.patches, target.filename, projectedDiff, { filesAffected: actualProjectedFiles }, async () => {
+    const filesUpdates = buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet);
+    await updatePatchAndMetadata(paths.patches, target.filename, projectedDiff, filesUpdates, async () => {
         await appendHistory(paths.patches, {
             operation: 're-export-files',
             args: {

package/dist/src/commands/re-export.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
 import { confirm, multiselect } from '@clack/prompts';
+import { Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
@@ -204,10 +205,29 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     // The paired `patch.tier` threads the explicit branding-threshold
     // opt-in the same way, for the branding patch that also touches a
     // non-allowlisted registration sibling.
-    const ignoreChecks = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, patch.tier);
+    //
+    // The CLI flags `--tier` and `--lint-ignore` participate too, with
+    // append/union semantics on the lint-ignore list (the operator's
+    // intuition for "I want this patch to also suppress X" — explicit
+    // removal lives on the `fireforge patch lint-ignore` subcommand).
+    // Computed before the lint pass so the new intent takes effect on
+    // this invocation, not the next one.
+    const existingIgnoreSet = new Set(patch.lintIgnore ?? []);
+    const flagIgnoreSet = new Set(options.lintIgnore ?? []);
+    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
+    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
+    const effectiveTier = options.tier ?? patch.tier;
+    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
     if (isDryRun) {
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
+        if (effectiveTier !== undefined && effectiveTier !== patch.tier) {
+            info(`[dry-run] ${patch.filename}: tier would become ${effectiveTier}`);
+        }
+        const addedIgnores = [...flagIgnoreSet].filter((id) => !existingIgnoreSet.has(id));
+        if (addedIgnores.length > 0) {
+            info(`[dry-run] ${patch.filename}: lintIgnore would gain ${addedIgnores.join(', ')}`);
+        }
     }
     else {
         // Atomic body + manifest update under a single patch-directory lock.
@@ -215,9 +235,16 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         // sequence allows a concurrent `resolve` / `rebase --continue` / `patch
         // compact` / `patch reorder` to rewrite the manifest between the two
         // writes and leave patch body and `filesAffected` disagreeing.
-        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, {
+        const updates = {
             filesAffected: currentFilesAffected,
-        });
+        };
+        if (options.tier !== undefined) {
+            updates.tier = options.tier;
+        }
+        if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
+            updates.lintIgnore = effectiveLintIgnore;
+        }
+        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, updates);
         // Keep the in-memory manifest in sync so subsequent iterations (notably
         // `--all --scan`, where `getClaimedFiles` reads from this manifest) see
         // the just-written `filesAffected`. The on-disk write above is the
@@ -228,7 +255,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             if (existingEntry) {
                 manifest.patches[patchIndex] = {
                     ...existingEntry,
-                    filesAffected: currentFilesAffected,
+                    ...updates,
                 };
             }
         }
@@ -291,6 +318,15 @@ export async function reExportCommand(projectRoot, patches, options) {
             throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier.', '--files');
         }
     }
+    // --tier and --lint-ignore are per-patch metadata edits; combining them
+    // with --all silently rewrites every patch's tier/ignore list, which is
+    // virtually always wrong (different patches have different shapes).
+    // Refuse the combination so the operator must enumerate the targets.
+    const usingTierFlag = options.tier !== undefined;
+    const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
+    if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {
+        throw new InvalidArgumentError('--tier and --lint-ignore require explicit patch identifiers and cannot be combined with --all (different patches typically need different metadata).', '--all');
+    }
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
@@ -396,8 +432,15 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('-y, --yes', 'Skip confirmation when --files shrinks a patch (required for non-TTY)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
         .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceEsrVersion in patches.json to firefox.version from fireforge.json. No effect on a partial run.")
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], [])
         .action(withErrorHandling(async (patches, options) => {
-        await reExportCommand(getProjectRoot(), patches, pickDefined(options));
+        const { tier, lintIgnore, ...rest } = options;
+        await reExportCommand(getProjectRoot(), patches, {
+            ...pickDefined(rest),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
+        });
     }));
 }
 //# sourceMappingURL=re-export.js.map

package/dist/src/commands/status.js

@@ -260,6 +260,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 +286,19 @@ 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.
+    const emitJsonError = (code, message) => {
+        process.stdout.write(JSON.stringify({ error: message, code }) + '\n');
+        throw new GeneralError(message);
+    };
     // 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 +347,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-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/git-diff.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { GitError } from '../errors/git.js';
@@ -35,6 +35,16 @@ export async function getFileDiff(repoDir, filePath) {
  */
 export async function generateNewFileDiff(repoDir, filePath) {
     const fullPath = join(repoDir, filePath);
+    // Defensive check: a directory here means a caller bypassed the
+    // expansion layers and handed the leaf reader a path it cannot
+    // read. Surface it with an actionable message naming the offending
+    // path rather than the raw `EISDIR` that `readText` would throw —
+    // recurring bug class (see the belt-and-suspenders note in
+    // `getDiffForFilesAgainstHead`).
+    const fileStat = await stat(fullPath);
+    if (fileStat.isDirectory()) {
+        throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
+    }
     const content = await readText(fullPath);
     // Compute the abbreviated git blob hash for the index line
     let blobHash = '0000000000';
@@ -212,7 +222,29 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
             }
             continue;
         }
-        if (!(await pathExists(join(repoDir, file)))) {
+        const fullPath = join(repoDir, file);
+        if (!(await pathExists(fullPath))) {
+            continue;
+        }
+        // Second defence against the EISDIR regression: a non-HEAD path
+        // that exists on disk is usually a new file, but can also be a
+        // directory that arrived without the trailing slash
+        // `expandUntrackedDirectoryEntries` would have produced (caller
+        // stripped it, submodule entry, tracked-file-replaced-by-dir).
+        // Expand it via the same helper used by the slash branch and
+        // recurse so each contained file is diffed individually; fail
+        // loud when the directory has no readable content rather than
+        // silently skipping it.
+        const fileStat = await stat(fullPath);
+        if (fileStat.isDirectory()) {
+            const innerFiles = await getUntrackedFilesInDir(repoDir, file);
+            if (innerFiles.length === 0) {
+                throw new GitError(`'${file}' is a directory with no untracked content (submodule or gitignored?) — cannot diff as a file`, `ls-files --others -- ${file}`);
+            }
+            const innerDiff = await getDiffForFilesAgainstHead(repoDir, innerFiles);
+            if (innerDiff.trim()) {
+                diffs.push(innerDiff);
+            }
             continue;
         }
         const diff = await generateNewFileDiff(repoDir, file);

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-export.d.ts

@@ -21,6 +21,10 @@ export interface CommitExportedPatchInput {
     diff: string;
     filesAffected: string[];
     sourceEsrVersion: string;
+    /** Optional `PatchMetadata.tier` opt-in (only `"branding"` recognised). */
+    tier?: 'branding';
+    /** Optional `PatchMetadata.lintIgnore` (empty array treated as absent). */
+    lintIgnore?: string[];
 }
 export interface CommitExportedPatchResult {
     patchFilename: string;
@@ -88,13 +92,71 @@ export type UpdatePatchCommittedHook = () => Promise<void>;
  *   the mutation succeeds. See {@link UpdatePatchCommittedHook}.
  */
 export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook): Promise<void>;
+/**
+ * Optional `PatchMetadata` keys safe to clear via the helpers below.
+ * Required keys (filename, order, etc.) are excluded by construction so
+ * an over-eager `unsetFields: ['filename']` cannot delete a field the
+ * manifest validator requires. Add new keys here only when they become
+ * optional on the type.
+ */
+export type ClearablePatchMetadataField = 'tier' | 'lintIgnore';
 /**
  * Updates metadata for a patch in the manifest.
+ *
+ * Required-field updates go through the `updates` partial. Clearing an
+ * optional field (e.g. removing the `tier` override) goes through
+ * `unsetFields` because TypeScript's `exactOptionalPropertyTypes` does
+ * not let `Partial<PatchMetadata>` carry an explicit `undefined` value
+ * for fields whose declared type does not include `undefined`. The
+ * implementation deletes the listed keys from the merged record before
+ * writing, so the on-disk JSON omits them and the validator's
+ * "preserve only when present" contract is preserved.
+ *
  * @param patchesDir - Path to the patches directory
  * @param filename - Patch filename
- * @param updates - Partial metadata updates
+ * @param updates - Field values to set. Pass an empty object when only
+ *   clearing fields.
+ * @param unsetFields - Optional fields to remove from the entry (so
+ *   serialization drops them).
+ */
+export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>, unsetFields?: ReadonlyArray<ClearablePatchMetadataField>): Promise<void>;
+/**
+ * Return shape from a {@link mutatePatchMetadata} mutator.
+ */
+export interface PatchMetadataMutation {
+    /** Field values to set on the entry. */
+    set?: Partial<PatchMetadata>;
+    /** Optional fields to remove from the entry entirely. */
+    unset?: ReadonlyArray<ClearablePatchMetadataField>;
+}
+/**
+ * Result of a successful {@link mutatePatchMetadata} call.
  */
-export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>): Promise<void>;
+export interface PatchMetadataMutationResult {
+    /** Pre-mutation snapshot of the patch's metadata. */
+    before: PatchMetadata;
+    /** Post-mutation state of the patch's metadata. */
+    after: PatchMetadata;
+}
+/**
+ * Reads a patch's metadata under the directory lock, applies a mutator
+ * function to compute the update, and writes the result back — all
+ * under a single lock so a concurrent writer cannot interleave a
+ * read-modify-write cycle. Useful for operations that need to compute
+ * the new value from the old (e.g. unioning a `lintIgnore` list,
+ * removing a specific entry), which {@link updatePatchMetadata}'s flat
+ * merge cannot express on its own.
+ *
+ * The mutator returns `{ set, unset }` so it can both write fields
+ * and drop optional ones. `set` and `unset` are merged before write:
+ * `set` runs first via spread, then `unset` deletes the listed keys.
+ *
+ * @returns The pre/post metadata pair when the patch is found and the
+ *   write succeeds; `null` when the manifest is missing or the named
+ *   patch is not in it. Callers should treat `null` as "no-op, nothing
+ *   to log".
+ */
+export declare function mutatePatchMetadata(patchesDir: string, filename: string, mutator: (existing: PatchMetadata) => PatchMetadataMutation): Promise<PatchMetadataMutationResult | null>;
 /**
  * Finds patches that are completely superseded by newer patches.
  * A patch is superseded if all its affected files are covered by newer patches.
@@ -196,6 +258,19 @@ export interface PlanExportInput {
     description: string;
     filesAffected: string[];
     sourceEsrVersion: string;
+    /**
+     * Optional `PatchMetadata.tier` opt-in carried from the CLI flag.
+     * Only `"branding"` is currently recognised. When provided the field
+     * is written into the new patch's metadata; when absent the field
+     * stays unset and tier resolution falls back to auto-detection.
+     */
+    tier?: 'branding';
+    /**
+     * Optional `PatchMetadata.lintIgnore` carried from the CLI flag.
+     * Empty arrays are treated as "field absent" — the validator only
+     * preserves the field when it has at least one entry.
+     */
+    lintIgnore?: string[];
 }
 /**
  * Read-only planning function — computes everything a real export would