@hominis/fireforge 0.18.2 → 0.18.3

package/README.md

@@ -143,6 +143,9 @@ fireforge re-export --all --scan
 # Preview what an export would do without writing
 fireforge export browser/base/content/browser.js --dry-run
 
+# Same preview surface for the aggregate path
+fireforge export-all --name "all-changes" --category ui --dry-run
+
 # Insert a new patch at a specific position
 fireforge export browser/base/content/browser.js --order 3 --name "inserted" --category ui
 fireforge export browser/base/content/browser.js --before 005-ui-sidebar.patch --name "prelim"
@@ -158,7 +161,7 @@ fireforge re-export --files browser/base/content/browser.js 002-ui-toolbar
 fireforge re-export --all --scan --stamp
 ```
 
-`export` refuses when the new patch's `filesAffected` would overlap with files already claimed by another non-superseded patch. Repartitioning ownership is a deliberate operation: the message points at `fireforge re-export --files <paths> <patch>` as the safe primitive. Pass `--allow-overlap` to acknowledge the conflict and proceed anyway — the resulting queue will fail `fireforge verify` immediately, so this is an intentional escape hatch, not a default.
+`export` refuses when the new patch's `filesAffected` would overlap with files already claimed by another non-superseded patch. Repartitioning ownership is a deliberate operation: the message points at `fireforge re-export --files <paths> <patch>` as the safe primitive. Pass `--allow-overlap` to acknowledge the conflict and proceed anyway — the resulting queue will fail `fireforge verify` immediately, so this is an intentional escape hatch, not a default. The flag covers cross-patch _modification_ overlap, where two patches both edit the same file. It does NOT bypass the new-file creation guard: two patches creating the same path on `/dev/null` cannot coexist in any apply order, so that case stays a hard refusal regardless of `--allow-overlap`.
 
 `re-export --scan` also prompts before broadening a patch with more than a handful of newly discovered files or with files spanning multiple directories. The gate keeps the common refresh case frictionless (small, same-directory additions) while catching the failure mode where `--scan` silently pulls an adjacent feature into the wrong patch. Non-interactive mode requires `--yes` to acknowledge a broad expansion; dry-run previews never require confirmation.
 
@@ -267,16 +270,16 @@ fireforge status --json             # machine-readable classified output
 
 Then fix with the appropriate primitive:
 
-| Problem                                        | Fix                                                                                                          |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files`                                        |
-| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                                                        |
-| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                                                                   |
-| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                                                                    |
-| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                                                               |
-| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                                                                 |
-| Dangling widget / locale registration in patch | Re-run `fireforge export` without `--exclude-furnace` to capture the source files, or revert furnace changes |
-| Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                                                              |
+| Problem                                        | Fix                                                                                                              |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Two patches each creating the same file        | `fireforge patch delete <duplicate>` or `fireforge re-export --files`                                            |
+| A patch imports from a module in a later patch | `fireforge patch reorder <later> --before <importer>`                                                            |
+| Wrong patch ordering                           | `fireforge patch reorder <patch> --to <N>`                                                                       |
+| Ordinal gaps after deletes/splits              | `fireforge patch compact`                                                                                        |
+| A patch claims files that belong elsewhere     | `fireforge re-export --files <subset> <patch>`                                                                   |
+| Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                                                                     |
+| Dangling widget / locale registration in patch | Re-run `fireforge export` without `--exclude-furnace` to capture the source files, or revert furnace changes     |
+| Unmanaged changes you want to discard          | `fireforge discard <file>` (also accepts a directory path to discard everything beneath it) or `fireforge reset` |
 
 Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge — `doctor --repair-patches-manifest` reconstructs missing metadata, and `fireforge re-export <filename> --description "<text>"` overwrites recovered entries with operator-supplied metadata through the tool. `fireforge verify` cross-checks every registration hunk in each patch body against the files the queue and engine supply, so a patch that registers a widget / locale without carrying its source surfaces as a `dangling-registration` error rather than slipping through as "Verify clean"; `fireforge export-all --exclude-furnace` refuses up-front when it would produce that shape.
 
@@ -466,7 +469,11 @@ fireforge package
 fireforge watch
 
 # Add a CSS design token (requires `fireforge furnace init` first; see the Furnace/Tokens section below)
-fireforge token add --category 'Colors — General' -- --my-color 'light-dark(#fff, #000)'
+# The `--` separator is required because the token name itself starts with `--`,
+# which Commander would otherwise read as an option flag. Bare names without `--`
+# are accepted directly and get the configured `tokenPrefix` prepended.
+fireforge token add --category 'Colors — General' --mode static -- --my-color 'light-dark(#fff, #000)'
+fireforge token add --category 'Colors — General' --mode static my-color   '#fff'   # bare-name form
 ```
 
 Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` also registers the tokens CSS path in `patchLint.rawColorAllowlist` so raw color literals inside it are not flagged by `fireforge lint`, and derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init.

package/dist/src/commands/discard.js

@@ -11,6 +11,82 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+/**
+ * Discards every status entry whose path lives under `dirPath`. Used by
+ * `discardCommand` as a directory-recursion fallback when the operator
+ * passed a directory path that contains modified or untracked entries
+ * but is not itself a status entry.
+ *
+ * Mirrors the single-file path's confirmation, dry-run, and Furnace-aware
+ * warning behaviour so the contract stays consistent. Each per-entry
+ * discard runs sequentially under its own try/catch so a failure on one
+ * file is reported but does not block the remaining files in the batch.
+ */
+async function discardDirectoryEntries(projectRoot, engineDir, dirPath, entries, options) {
+    if (!options.yes && !options.dryRun) {
+        const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+        if (!isInteractive) {
+            throw new InvalidArgumentError('Interactive confirmation not available. Use --yes flag to discard without confirmation.', 'Use: fireforge discard <directory> --yes');
+        }
+        const confirmed = await confirm({
+            message: `Discard changes to ${entries.length} file${entries.length === 1 ? '' : 's'} under ${dirPath}/?`,
+            initialValue: false,
+        });
+        if (isCancel(confirmed) || !confirmed) {
+            outro('Discard cancelled');
+            return;
+        }
+    }
+    if (options.dryRun) {
+        info(`Would discard changes to ${entries.length} file(s) under ${dirPath}/:`);
+        for (const entry of entries) {
+            const target = entry.originalPath && entry.originalPath !== entry.file
+                ? `${entry.originalPath} -> ${entry.file}`
+                : entry.file;
+            info(`  ${target}`);
+        }
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    const s = spinner(`Discarding ${entries.length} file(s) under ${dirPath}/...`);
+    let succeeded = 0;
+    const failures = [];
+    try {
+        for (const entry of entries) {
+            try {
+                await discardStatusEntry(engineDir, entry);
+                succeeded += 1;
+            }
+            catch (error) {
+                failures.push(`${entry.file}: ${toError(error).message}`);
+            }
+        }
+        s.stop(`Discarded ${succeeded} of ${entries.length} file(s) under ${dirPath}/${failures.length > 0 ? ` (${failures.length} failed)` : ''}`);
+        for (const failure of failures) {
+            warn(`  ${failure}`);
+        }
+        try {
+            const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+            const dirIsFurnace = [...furnacePrefixes].some((prefix) => `${dirPath}/`.startsWith(prefix) || prefix.startsWith(`${dirPath}/`));
+            if (dirIsFurnace) {
+                warn('These paths are managed by Furnace. Run "fireforge furnace apply" to redeploy components if needed.');
+            }
+        }
+        catch {
+            // Furnace config may not exist — skip silently
+        }
+        if (failures.length > 0) {
+            throw new GeneralError(`Failed to discard ${failures.length} file(s) under ${dirPath}/. See warnings above.`);
+        }
+        outro(`${succeeded} file(s) restored to original state`);
+    }
+    catch (error) {
+        if (!(error instanceof GeneralError)) {
+            s.error('Discard failed');
+        }
+        throw error;
+    }
+}
 /**
  * Runs the discard command to revert changes to a specific file.
  * @param projectRoot - Root directory of the project
@@ -31,7 +107,23 @@ export async function discardCommand(projectRoot, file, options = {}) {
     // Check if the file has changes
     const statusEntries = await expandUntrackedDirectoryEntries(paths.engine, await getWorkingTreeStatus(paths.engine));
     const statusEntry = statusEntries.find((entry) => entry.file === file || entry.originalPath === file);
+    // Directory recursion fallback: when the explicit path does not match a
+    // single status entry but DOES correspond to one or more entries below
+    // it, treat the input as a directory and discard everything inside.
+    // 2026-04-25 eval Finding 20: `discard browser/components/storybook/
+    // stories/furnace --yes` failed with "no changes to discard" even
+    // though `status --unmanaged` listed 23 files under that directory —
+    // operators were forced to discard each file individually or fall
+    // back to non-FireForge cleanup commands. Match against the
+    // directory-with-trailing-slash form so a path like `foo/bar` doesn't
+    // accidentally match `foo/bar2/file`.
     if (!statusEntry) {
+        const dirPrefix = file.endsWith('/') ? file : `${file}/`;
+        const dirEntries = statusEntries.filter((entry) => entry.file.startsWith(dirPrefix) || entry.originalPath?.startsWith(dirPrefix));
+        if (dirEntries.length > 0) {
+            await discardDirectoryEntries(projectRoot, paths.engine, file, dirEntries, options);
+            return;
+        }
         throw new GeneralError(`File "${file}" has no changes to discard.`);
     }
     if (!options.yes && !options.dryRun) {
@@ -91,7 +183,7 @@ export async function discardCommand(projectRoot, file, options = {}) {
 export function registerDiscard(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('discard <file>')
-        .description('Discard changes to a specific file (deletes untracked files)')
+        .description('Discard changes to a specific file (deletes untracked files). Pass a directory path to discard every modified or untracked file beneath it; the operation walks the status output and reverts each match individually.')
         .option('--dry-run', 'Show what would be discarded without doing it')
         .option('-y, --yes', 'Skip confirmation prompt')
         .action(withErrorHandling(async (file, options) => {

package/dist/src/commands/doctor.js

@@ -9,7 +9,7 @@ import { ExitCode } from '../errors/codes.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, success, warn } from '../utils/logger.js';
-import { executableExists } from '../utils/process.js';
+import { findExecutable } from '../utils/process.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 /**
@@ -255,9 +255,22 @@ const DOCTOR_CHECKS = [
         // failure site.
         name: 'Watchman available',
         run: async () => {
-            const present = await executableExists('watchman');
-            if (present)
-                return ok('Watchman available');
+            // Resolve the absolute path so the OK row names what doctor actually
+            // found. The 2026-04-25 eval flagged a confusing case where the
+            // operator's interactive shell returned no result for `which
+            // watchman` but doctor still printed "OK" — the cause was a
+            // PATH-export discrepancy between the shell and the spawned
+            // subprocess, and surfacing the resolved path makes the discrepancy
+            // visible without users having to re-run with a verbose flag.
+            const path = await findExecutable('watchman');
+            if (path) {
+                return {
+                    name: 'Watchman available',
+                    passed: true,
+                    severity: 'ok',
+                    message: `OK (${path})`,
+                };
+            }
             return warning('Watchman available', 'watchman is not installed or not on PATH. "fireforge watch" requires it.', 'Install watchman (brew install watchman / dnf install watchman / https://facebook.github.io/watchman/), then re-run doctor.');
         },
     },

package/dist/src/commands/download.js

@@ -69,6 +69,25 @@ async function cleanPatchTouchedFiles(engineDir, patchesDir, preExistingDirty) {
     }
     return { hadQueue: true, restored: toClean.length, preserved: preserved.length };
 }
+/**
+ * Prints a one-line nudge pointing at `fireforge import` when the project
+ * carries a non-empty patch queue but the just-downloaded engine has not
+ * yet had any patches applied. The post-download spinner closes with
+ * "Patch-touched files already match baseline" because a fresh tree IS at
+ * baseline, but the 2026-04-25 eval saw operators read that as "patches
+ * are restored" and skip the import step. The note is suppressed when
+ * patches/ is missing or the manifest is empty so unconfigured projects
+ * stay quiet.
+ */
+async function noteUnappliedPatches(patchesDir) {
+    if (!(await pathExists(patchesDir)))
+        return;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest || manifest.patches.length === 0)
+        return;
+    const n = manifest.patches.length;
+    info(`Note: ${n} patch${n === 1 ? '' : 'es'} in patches/ have not been applied to this fresh engine. Run "fireforge import" to apply them.`);
+}
 /**
  * Stops `restoreSpinner` with a message that reflects what actually
  * happened. Three branches: empty queue → explicit no-op; queue present but
@@ -151,6 +170,7 @@ export async function downloadCommand(projectRoot, options) {
                                 downloadedVersion: version,
                                 baseCommit,
                             });
+                            await noteUnappliedPatches(paths.patches);
                             outro(`Firefox ${version} is ready! (resumed from partial init)`);
                             return;
                         }
@@ -299,6 +319,7 @@ export async function downloadCommand(projectRoot, options) {
         downloadedVersion: version,
         baseCommit,
     });
+    await noteUnappliedPatches(paths.patches);
     outro(`Firefox ${version} is ready!`);
 }
 /** Registers the download command on the CLI program. */

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

@@ -15,6 +15,7 @@ import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
+import { renderDryRunPreview } from './export-flow.js';
 import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function checkBrandingManagedFiles(paths, config) {
     const changedFiles = await getWorkingTreeStatus(paths.engine);
@@ -158,7 +159,8 @@ async function checkDuplicateNewFileCreations(paths, diff) {
         .join('\n');
     throw new GeneralError('Export-all refuses to capture new-file creations that are already claimed by existing patches.\n\n' +
         `Conflicting creations:\n${conflictList}\n\n` +
-        'Only one patch may create a given path. Run "fireforge export <path> [...]" with an explicit file list that omits the already-claimed path(s), or resolve the conflict via "fireforge patch delete" / "fireforge re-export --files" before retrying export-all.');
+        'Only one patch may create a given path — two creation hunks on /dev/null cannot coexist in any apply order, so this case is structurally unrecoverable rather than verify-failing. The --allow-overlap escape hatch covers cross-patch MODIFICATION overlap (which yields a queue that fails verify but still applies); it deliberately does NOT cover this case. ' +
+        'Run "fireforge export <path> [...]" with an explicit file list that omits the already-claimed path(s), or resolve the conflict via "fireforge patch delete" / "fireforge re-export --files" before retrying export-all.');
 }
 /**
  * Runs the export-all command to export all changes as a patch.
@@ -166,7 +168,8 @@ async function checkDuplicateNewFileCreations(paths, diff) {
  * @param options - Export options
  */
 export async function exportAllCommand(projectRoot, options = {}) {
-    intro('FireForge Export All');
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge Export All (dry run)' : 'FireForge Export All');
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
@@ -236,13 +239,38 @@ export async function exportAllCommand(projectRoot, options = {}) {
     if (!metadata)
         return;
     const { patchName, selectedCategory, description } = metadata;
-    // Ensure patches directory exists
-    await ensureDir(paths.patches);
-    const s = spinner('Exporting all changes...');
+    // Ensure patches directory exists. Skip during a dry-run so the command
+    // is purely read-only — `--dry-run` callers should be safe to invoke
+    // against a project that has never exported a patch without leaving the
+    // empty `patches/` directory behind.
+    if (!isDryRun) {
+        await ensureDir(paths.patches);
+    }
+    const s = spinner(isDryRun ? 'Planning export-all...' : 'Exporting all changes...');
     try {
         // Extract affected files from diff
         const filesAffected = extractAffectedFiles(diff);
         await runPatchLint(paths.engine, filesAffected, diff, config, options.skipLint);
+        // Dry-run: enumerate filename, metadata, and supersede coverage without
+        // writing. Mirrors `fireforge export --dry-run` so the same preview
+        // surface is available for both targeted and aggregate exports. Runs
+        // AFTER lint so the operator sees the same lint output they would on
+        // a real run; runs BEFORE the supersede confirmation prompt because
+        // confirming a dry-run is meaningless.
+        if (isDryRun) {
+            s.stop('Plan ready');
+            await renderDryRunPreview({
+                patchesDir: paths.patches,
+                category: selectedCategory,
+                name: patchName,
+                description,
+                filesAffected,
+                sourceEsrVersion: config.firefox.version,
+                explicitSupersede: options.supersede === true,
+            });
+            outro('Dry run complete — no changes made');
+            return;
+        }
         // Check how many existing patches would be superseded
         const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
         if (!shouldProceed)
@@ -299,7 +327,8 @@ export function registerExportAll(program, { getProjectRoot, withErrorHandling }
         .option('--supersede', 'Allow superseding multiple existing patches')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--exclude-furnace', 'Export the non-Furnace subset of the aggregate diff instead of refusing when Furnace-managed files are modified. Furnace-managed files are still deployed by "fireforge furnace apply"; this flag only changes whether export-all aborts or filters in their presence.')
-        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap with non-superseded patches (the resulting queue fails verify)')
+        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap with non-superseded patches (the resulting queue fails verify). Does not bypass the new-file creation guard — two patches creating the same path is structurally unrecoverable, so that case still refuses regardless of this flag.')
+        .option('--dry-run', 'Print the export-all plan (filename, metadata, files affected, supersede preview) without writing anything to patches/. Lint still runs so the operator sees the same lint output a real run would produce.')
         .action(withErrorHandling(async (options) => {
         const { category, ...rest } = options;
         await exportAllCommand(getProjectRoot(), {

package/dist/src/commands/furnace/remove.js

@@ -212,6 +212,64 @@ async function cleanupCustomTestFiles(name, projectRoot, journal) {
     }
     return { partialFailures };
 }
+/**
+ * Removes the MochiKit test scaffold a `furnace create --with-tests
+ * --test-style mochikit` produced for the component (matches the rename
+ * counterpart in `rename.ts`). The test file is `test_<name>.html` under
+ * `engine/toolkit/content/tests/widgets/` and the registration is the
+ * `["test_<name>.html"]` entry in the same directory's `chrome.toml`.
+ *
+ * 2026-04-25 eval Finding 13: the prior cleanup only handled the
+ * browser-chrome mochitest layout under `browser/base/content/test/
+ * <binary>/`, which left mochikit-style scaffolds and their toml entries
+ * orphaned after `furnace remove`. The post-rename name passed in here
+ * is the canonical one written to disk by deploy/rename, so the file
+ * basenames match without needing to re-derive from the old name.
+ *
+ * Best-effort: each step warns on failure rather than throwing so the
+ * rest of the remove transaction proceeds. The journal still snapshots
+ * touched files so the outer rollback can restore them on a later
+ * failure in the same operation.
+ */
+async function cleanupCustomMochikitTestFiles(name, projectRoot, journal) {
+    const partialFailures = [];
+    const paths = getProjectPaths(projectRoot);
+    const widgetsTestDir = join(paths.engine, 'toolkit/content/tests/widgets');
+    if (!(await pathExists(widgetsTestDir))) {
+        return { partialFailures };
+    }
+    const testFileName = `test_${name}.html`;
+    const testFilePath = join(widgetsTestDir, testFileName);
+    try {
+        if (await pathExists(testFilePath)) {
+            await snapshotFile(journal, testFilePath);
+            await unlink(testFilePath);
+            info(`Deleted mochikit test file: toolkit/content/tests/widgets/${testFileName}`);
+        }
+    }
+    catch (error) {
+        const msg = `Could not delete mochikit test file ${testFileName} — ${toError(error).message}. Remove it manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    const chromeTomlPath = join(widgetsTestDir, 'chrome.toml');
+    try {
+        if (await pathExists(chromeTomlPath)) {
+            const toml = await readText(chromeTomlPath);
+            const headerLine = `["${testFileName}"]`;
+            if (toml.includes(headerLine)) {
+                await snapshotFile(journal, chromeTomlPath);
+                await writeText(chromeTomlPath, removeTomlSection(toml, testFileName));
+            }
+        }
+    }
+    catch (error) {
+        const msg = `Could not update widgets chrome.toml — ${toError(error).message}. Remove the test entry manually if needed.`;
+        warn(msg);
+        partialFailures.push(msg);
+    }
+    return { partialFailures };
+}
 /**
  * Removes generated xpcshell test scaffolds associated with a custom
  * component. 2026-04-24 eval Finding 5: `furnace remove` handled
@@ -433,6 +491,16 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
                 // versions.
                 const xpcshellResult = await cleanupCustomXpcshellTestFiles(name, projectRoot, journal);
                 testCleanupFailures.push(...xpcshellResult.partialFailures);
+                // 2026-04-25 eval Finding 13: mochikit-style scaffolds
+                // (`--test-style mochikit`) live under
+                // `engine/toolkit/content/tests/widgets/` with `chrome.toml`
+                // entries — neither the browser-chrome path nor the xpcshell
+                // path touches them. Without this pass, a `furnace create
+                // --with-tests --test-style mochikit` followed by `furnace
+                // remove` left the test file and its toml entry referencing a
+                // component that no longer exists.
+                const mochikitResult = await cleanupCustomMochikitTestFiles(name, projectRoot, journal);
+                testCleanupFailures.push(...mochikitResult.partialFailures);
             }
             // Remove entry from furnace.json
             if (type === 'stock') {

package/dist/src/commands/import.js

@@ -74,7 +74,15 @@ async function checkUncommittedPatchFiles(engineDir, patchesDir, forceImport) {
         if (dirtyFiles.length > 0) {
             const unmanagedDirtyFiles = await getUnmanagedDirtyFiles(engineDir, patchesDir, dirtyFiles);
             if (unmanagedDirtyFiles.length === 0) {
-                info('Patch-backed materialized files already match the stored patch stack.');
+                // Common path here: operator just ran `fireforge resolve` to
+                // regenerate a patch from manual conflict edits, so the engine
+                // already carries the patch's effects. The import below will
+                // still re-apply each patch (a no-op for files whose contents
+                // already match), so phrase the line as "no resync needed"
+                // rather than "patches already applied" — the latter contradicts
+                // the "Applied N patch(es)" summary `applyPatchesWithContinue`
+                // prints next, which the 2026-04-25 eval flagged as ambiguous.
+                info('Patch-touched files already match the stored patch stack — no engine resync needed before re-applying.');
             }
             else if (!forceImport) {
                 warn('Uncommitted changes detected in files that patches will modify:');

package/dist/src/commands/lint.js

@@ -3,6 +3,7 @@ import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getStatusWithCodes, hasChanges, isGitRepository } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
@@ -35,7 +36,7 @@ import { stripEnginePrefix } from '../utils/paths.js';
  * previous behaviour: passing a branding file explicitly still lints
  * it, so operators who need to audit branding content can do so.
  */
-async function resolveLintDiff(engineDir, files, binaryName) {
+async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
     if (files.length > 0) {
         const collectedFiles = new Set();
         let fileStatuses;
@@ -115,16 +116,31 @@ async function resolveLintDiff(engineDir, files, binaryName) {
         const expanded = await expandUntrackedDirectoryEntries(engineDir, rawStatus);
         const allPaths = [...new Set(expanded.map((entry) => entry.file))];
         const nonBrandingPaths = allPaths.filter((path) => !isBrandingManagedPath(path, binaryName));
-        const excludedCount = allPaths.length - nonBrandingPaths.length;
-        if (excludedCount > 0) {
-            info(`Excluded ${excludedCount} tool-managed branding file${excludedCount === 1 ? '' : 's'} from lint. Pass the path explicitly or use \`fireforge lint <path>\` to include them.`);
+        const brandingExcluded = allPaths.length - nonBrandingPaths.length;
+        // Drop Furnace-managed paths the same way branding is dropped: their
+        // contents are tool output (overrides, custom widgets, preview-
+        // generated stories) that the operator did not author and never
+        // intended to land on the patch queue. Without this carve-out, a
+        // post-`furnace preview` aggregate `lint` failed with one
+        // `missing-license-header` error per generated story file (eval
+        // Finding 19) — each story is intentionally header-less because it's
+        // re-generated from component metadata on every preview run.
+        const filteredPaths = furnacePrefixes
+            ? nonBrandingPaths.filter((path) => ![...furnacePrefixes].some((p) => path.startsWith(p)))
+            : nonBrandingPaths;
+        const furnaceExcluded = nonBrandingPaths.length - filteredPaths.length;
+        if (brandingExcluded > 0) {
+            info(`Excluded ${brandingExcluded} tool-managed branding file${brandingExcluded === 1 ? '' : 's'} from lint. Pass the path explicitly or use \`fireforge lint <path>\` to include them.`);
         }
-        if (nonBrandingPaths.length === 0) {
-            info('No non-branding changes to lint.');
+        if (furnaceExcluded > 0) {
+            info(`Excluded ${furnaceExcluded} Furnace-managed file${furnaceExcluded === 1 ? '' : 's'} from lint (deployed components and preview-generated stories). Pass the path explicitly to include them.`);
+        }
+        if (filteredPaths.length === 0) {
+            info('No non-branding, non-Furnace changes to lint.');
             outro('Nothing to lint');
             return null;
         }
-        const diff = await getDiffForFilesAgainstHead(engineDir, nonBrandingPaths.sort());
+        const diff = await getDiffForFilesAgainstHead(engineDir, filteredPaths.sort());
         if (!diff.trim()) {
             info('No diff content to lint.');
             outro('Nothing to lint');
@@ -185,7 +201,13 @@ export async function lintCommand(projectRoot, files, options = {}) {
     // the diff was resolved; hoisting it is cheap and keeps the two
     // call sites close together.
     const config = await loadConfig(projectRoot);
-    const diff = await resolveLintDiff(paths.engine, files, config.binaryName);
+    // Pull the Furnace-managed prefix set up-front so aggregate lint can
+    // mirror the branding exclusion for Furnace material — without it,
+    // preview-generated stories under `browser/components/storybook/
+    // stories/furnace/` show up as license-header errors on every
+    // post-preview lint run.
+    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+    const diff = await resolveLintDiff(paths.engine, files, config.binaryName, furnacePrefixes);
     if (diff === null)
         return;
     const filesAffected = extractAffectedFiles(diff);
@@ -284,7 +306,23 @@ export async function lintCommand(projectRoot, files, options = {}) {
             : '';
         throw new GeneralError(`Patch lint found ${failingErrors.length} ${options.onlyIntroduced ? 'introduced ' : ''}error(s). Fix these before exporting.${cumulativeSuppressed}`);
     }
-    outro('Lint passed with warnings');
+    // Notices are advisory and don't count as warnings — emitting "passed
+    // with warnings" when only notices fired contradicts the preceding
+    // `0 warning(s)` summary line and reads as a regression. Distinguish
+    // the three pass states explicitly. Errors suppressed by
+    // --only-introduced still warrant the "with warnings" outro — they
+    // print as ERROR rows but no longer fail the run, which is the same
+    // contract the operator gets from a real warning.
+    const suppressedErrors = options.onlyIntroduced && errors.length > 0;
+    if (warnings.length > 0 || suppressedErrors) {
+        outro('Lint passed with warnings');
+    }
+    else if (notices.length > 0) {
+        outro('Lint passed with notices');
+    }
+    else {
+        outro('Lint passed');
+    }
 }
 /**
  * Lints each patch in the queue as its own isolated diff, honouring
@@ -357,7 +395,15 @@ async function lintPerPatch(projectRoot, paths) {
         outro('Lint failed');
         throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
     }
-    outro('Lint passed with warnings');
+    if (warnings.length > 0) {
+        outro('Lint passed with warnings');
+    }
+    else if (notices.length > 0) {
+        outro('Lint passed with notices');
+    }
+    else {
+        outro('Lint passed');
+    }
 }
 /** Registers the lint command on the CLI program. */
 export function registerLint(program, { getProjectRoot, withErrorHandling }) {

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/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-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.js

@@ -98,8 +98,14 @@ export async function registerSharedCSS(engineDir, fileName, after, dryRun = fal
     const name = basename(fileName, '.css');
     const entry = `  skin/classic/browser/${name}.css    (../shared/${name}.css)`.replace(/\\/g, '/');
     const content = await readText(manifestPath);
-    // Idempotency check
-    if (content.includes(`skin/classic/browser/${name}.css`)) {
+    // Idempotency check. `furnace chrome-doc create` writes its CSS as a
+    // `content/browser/<name>.css` entry rather than the canonical
+    // `skin/classic/browser/<name>.css` form `register` produces; recognise
+    // both shapes so a follow-up `register` invocation against an
+    // already-chrome-doc-registered file reports `skipped` instead of
+    // appending a duplicate `skin/classic/browser/...` row.
+    if (content.includes(`skin/classic/browser/${name}.css`) ||
+        content.includes(`content/browser/${name}.css`)) {
         return { manifest, entry, skipped: true };
     }
     const { value } = withParserFallback(() => registerSharedCSSTokenized(content, name, entry, after), () => legacyRegisterSharedCSS(content, name, entry, after), manifest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",