@hominis/fireforge 0.18.2 → 0.18.5

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.
 
@@ -355,11 +358,11 @@ fireforge furnace chrome-doc create mybrowser --with-tests # + xpcshell packagin
 
 The command writes:
 
-- `engine/browser/base/content/<name>.xhtml` — XHTML shell, optional titlebar-buttonbox, Fluent `<link>`.
+- `engine/browser/base/content/<name>.xhtml` — XHTML shell. `data-l10n-id` is bound on the leaf `<title>` only (binding it on the root `<window>` would let Fluent's first-paint translation pass overwrite the entire body subtree, the standard `data-l10n-id`-on-non-leaf failure mode). The `<head>` loads `chrome://global/content/customElements.js` ahead of the per-doc subscript so any `<moz-*>` widget the author drops into the body resolves through the toolkit registry instead of silently degrading to `HTMLUnknownElement` — matches the `webrtcIndicator.xhtml` shape upstream uses for non-`browser.xhtml` chrome documents. Under `--with-titlebar` (the default) the root carries the `navigator:browser` minimum attribute set: `windowtype="navigator:browser"`, `customtitlebar="true"`, default `width="1024"` / `height="640"`, and `persist="screenX screenY width height sizemode"` so XULStore remembers geometry across restarts; without these a fork shipping the scaffold verbatim opens at the OS intrinsic minimum size on first launch and forgets the user's window position.
 - `engine/browser/base/content/<name>.js` — startup-topic observer fired on first idle.
-- `engine/browser/themes/shared/<name>-chrome.css` — scoped CSS; emits the macOS `.titlebar-button { display: none }` carve-out under `--no-titlebar`.
+- `engine/browser/themes/shared/<name>-chrome.css` — scoped CSS. Under `--with-titlebar` the buttonbox container is a `-moz-window-dragging: drag` region and `.titlebar-buttonbox` opts into the platform-native `-moz-window-button-box` appearance so the OS renders traffic-light / minimize-maximize-close controls in their canonical positions; under `--no-titlebar` the macOS `.titlebar-button { display: none }` carve-out is emitted instead so frameless overlays don't inherit the platform window controls `global.css` applies by default.
 - `engine/browser/locales/en-US/browser/<name>.ftl` — Fluent stub keyed on `<name>-window-title`.
-- Appends the corresponding `jar.mn` / `jar.inc.mn` / `locales/jar.mn` entries.
+- Appends the corresponding `jar.mn` / `jar.inc.mn` entries. The locales/jar.mn append is suppressed when the fork's existing `engine/browser/locales/jar.mn` already carries a `[localization] (%browser/**/*.ftl)` (or `(%browser/*.ftl)`) wildcard that would already pick up the scaffolded FTL — on those forks a per-file `locale/<name>.ftl` entry would be dead weight at best and an outright build break when the fork has dropped the `% locale browser …` registration the per-file entry depends on. Forks still on the legacy registration get the per-file entry as before.
 - When `--with-tests` is set, also scaffolds an xpcshell test + `xpcshell.toml` under `engine/browser/base/content/test/<binary>-xpcshell/<name>/` that probes the packaged app directory (`Services.dirsvc.get("XCurProcD")/chrome/browser/...`) directly rather than going through `chrome://` URI resolution — see "Platform module compatibility" and the xpcshell chrome-URI note further down for why direct filesystem probing is the reliable way to verify chrome-doc packaging. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator because the owning moz.build depends on the fork layout.
 
 Writes are transactional: a SIGINT mid-scaffold rolls back every touched file. Requires an existing engine — run `fireforge download` first.
@@ -426,6 +429,8 @@ fireforge config customKey "value" --force
 
 Writes are serialised behind a sidecar lock — two concurrent `fireforge config` invocations against the same `fireforge.json` (for example, parallel automation steps) queue instead of racing the read-modify-write. The lock is released automatically on process exit; stale locks from a crashed earlier command are reclaimed on the next invocation via the PID-alive probe.
 
+Re-setting a key to its current value is a no-op: `fireforge.json` is not rewritten, key ordering is preserved, and the success log surfaces `<key> = <value> (unchanged)` instead of a fresh `Set …` line. This means automation that idempotently runs `fireforge config <key> <value>` no longer produces spurious diffs in `fireforge.json`.
+
 ### Patch queue management
 
 ```bash
@@ -466,10 +471,14 @@ 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.
+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` does three more things in the same step so the file is owned end-to-end by tooling: it registers the tokens CSS path in `patchLint.rawColorAllowlist` (so raw color literals inside it are not flagged by `fireforge lint`); it adds the matching `skin/classic/browser/<binaryName>-tokens.css (../shared/<binaryName>-tokens.css)` entry to `browser/themes/shared/jar.inc.mn` (so `fireforge status` does not flag the file as unmanaged or unregistered); and it 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.
 
 ### Diff-scoped lint (`lint --since`)
 
@@ -511,6 +520,10 @@ The build also auto-runs `mach configure` before the mach build step when any `m
 
 Mach build failures with known-cryptic mozbuild errors now print actionable hints. Example: a `JS_PREFERENCE_PP_FILES` entry with no `#filter` / `#expand` directives now prints `Hint: ...use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.` alongside the raw mach traceback.
 
+When mach prints a post-build `config.status is out of date …` or `Config object not found by mach. / Configure complete!` banner on a successful build, FireForge surfaces a one-line annotation immediately before its own `Build completed in Xm Ys!` outro explaining that the banner is a known side effect of tool-managed branding edits applied before the build and that the build does not need to be re-run. The FireForge exit code remains authoritative regardless of the mach guard text.
+
+The reported `Build completed in Xm Ys!` duration is wall-clock measured with `Date.now()`, so it includes any time the host spent suspended (laptop sleep, system idle) during the build. Treat it as wall-clock-with-sleep, not active CPU time, when comparing builds across machines or sessions.
+
 ### Relocated workspaces: `fireforge build --rewrite-mozinfo`
 
 When a workspace is moved to a new path (e.g. the project directory was renamed or relocated on disk), `obj-*/mozinfo.json` still records the old `topsrcdir` / `topobjdir`. The pre-flight detects the mismatch and aborts with a "delete and rebuild" instruction — correct but expensive; a fresh clean build typically runs ~20 minutes and discards ~14 GB of intact obj artefacts on a moved checkout.

package/dist/src/commands/build.js

@@ -157,18 +157,33 @@ export async function buildCommand(projectRoot, options) {
         throw new BuildError(`Build failed with exit code ${result.exitCode}`, options.ui ? 'mach build faster' : 'mach build');
     }
     // Tool-managed branding edits that land on `browser/moz.configure`
-    // before the build cause mach's post-build guard to print
-    // "config.status is out of date … Be sure to run |mach build|" even
-    // though the build itself completed cleanly. 2026-04-21 eval finding:
-    // operators read that as "your build is stale" and either rebuilt
-    // (wasting ~10 minutes) or doubted the Fireforge "Build completed"
-    // footer. Annotate the captured output so the operator knows the
-    // warning is expected and not actionable.
-    const staleConfigurePattern = /config\.status is out of date/i;
-    if (staleConfigurePattern.test(result.stdout) || staleConfigurePattern.test(result.stderr)) {
-        info('Note: mach reported "config.status is out of date" after this build. ' +
-            'That notice is a known side effect of tool-managed branding edits applied before the build ' +
-            'and does not require a rebuild — the Fireforge exit code is authoritative.');
+    // before the build cause mach's post-build guard to print one of two
+    // banners that read like build failures even though the build
+    // completed cleanly:
+    //
+    //   1) "config.status is out of date with respect to ..."
+    //   2) "Config object not found by mach. / Configure complete! /
+    //      Be sure to run |mach build| to pick up any changes."
+    //
+    // 2026-04-21 eval covered (1); 2026-04-26 eval Finding 8 reproduced
+    // (2) on a successful build. The pre-fix pattern only matched (1),
+    // so operators on the (2) path saw mach's own "Configure complete!"
+    // and "run |mach build|" lines unexplained between mach's
+    // "Your build was successful!" and FireForge's own "Build completed
+    // in Xm Ys" outro — a contradictory tail. Both shapes now route
+    // through the same annotation, emitted BEFORE FireForge's outro so
+    // the operator's last terminal line is the explanation, not the
+    // confusing mach guard text.
+    const staleConfigurePatterns = [
+        /config\.status is out of date/i,
+        /Config object not found by mach\.[\s\S]*Configure complete!/i,
+    ];
+    const captured = `${result.stdout}\n${result.stderr}`;
+    if (staleConfigurePatterns.some((p) => p.test(captured))) {
+        info('Note: mach printed a post-build "Configure complete!" / "config.status is out of date" ' +
+            'banner. That is a known side effect of tool-managed branding edits applied before the ' +
+            'build and does not mean the build is stale or that you need to rerun mach — the FireForge ' +
+            'exit code is authoritative.');
     }
     // Warn-only post-build audit: surfaces silent packaging drops (files
     // edited in engine/ but never registered for packaging) against the

package/dist/src/commands/config.js

@@ -111,6 +111,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         }
         const parsedValue = parseValue(value, key);
         const keyIsKnown = SUPPORTED_CONFIG_PATHS.includes(key);
+        let unchanged;
         try {
             // Serialise the read → mutate → write round-trip behind the sidecar
             // config lock so two concurrent `fireforge config` invocations can't
@@ -122,7 +123,21 @@ export async function configCommand(projectRoot, key, value, options = {}) {
             // were never enough on their own — the lost update happens before
             // the rename, inside the read-modify step. Readers stay lock-free
             // (see `withConfigFileLock` docstring).
-            await withConfigFileLock(projectRoot, async () => {
+            unchanged = await withConfigFileLock(projectRoot, async () => {
+                // 2026-04-26 eval Finding 11: short-circuit when the new value
+                // matches the current on-disk value. Pre-fix, every set ran
+                // through `mutateConfig` + `writeConfig`, which round-trips
+                // through `JSON.stringify` and rewrites the file even when no
+                // semantic change happened — the rewrite reorders top-level
+                // keys (`license`, `markerComment`, etc.) on every harmless
+                // re-set, producing diff churn for no reason. The check uses
+                // the raw on-disk document so forced-keys round-trip the same
+                // as known keys.
+                const rawConfig = await loadRawConfigDocument(projectRoot);
+                const currentValue = getNestedValue(rawConfig, key);
+                if (deepEqual(currentValue, parsedValue)) {
+                    return true;
+                }
                 // `--force` is intended as an escape hatch for *unknown* keys; it
                 // should not also let the user write a structurally invalid value
                 // for a *known* key. Apply strict validation whenever the key is
@@ -133,7 +148,6 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                     // keys (which `validateConfig` would strip) survive the round-trip.
                     // Without this, writing a second --force key would silently drop
                     // every earlier forced key from fireforge.json.
-                    const rawConfig = await loadRawConfigDocument(projectRoot);
                     const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
                     await writeConfigDocument(projectRoot, updatedConfig);
                 }
@@ -142,15 +156,54 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                     const updatedConfig = mutateConfig(config, key, parsedValue);
                     await writeConfig(projectRoot, updatedConfig);
                 }
+                return false;
             });
         }
         catch (error) {
             throw new InvalidArgumentError(`Invalid value for "${key}": ${toError(error).message}`, key);
         }
-        success(`Set ${key} = ${formatValue(parsedValue)}`);
+        if (unchanged) {
+            info(`${key} = ${formatValue(parsedValue)} (unchanged)`);
+        }
+        else {
+            success(`Set ${key} = ${formatValue(parsedValue)}`);
+        }
     }
     outro('');
 }
+/**
+ * Structural equality check covering the shapes that
+ * `fireforge config` accepts: primitives (strings, numbers, booleans),
+ * `null`, arrays of primitives, and nested objects. Used to short-circuit
+ * no-op writes (Finding 11) — when the parsed value matches the current
+ * on-disk value, skip the mutate + write step entirely.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (Array.isArray(b))
+        return false;
+    const ar = a;
+    const br = b;
+    const keysA = Object.keys(ar);
+    const keysB = Object.keys(br);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((k) => deepEqual(ar[k], br[k]));
+}
 /** Registers the config command on the CLI program. */
 export function registerConfig(program, { getProjectRoot, withErrorHandling }) {
     program

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/chrome-doc-templates.d.ts

@@ -24,12 +24,29 @@ export declare const FURNACE_CHROME_DOC_SENTINEL = "data-furnace-chrome-doc";
  * XHTML shell for a top-level chrome document.
  *
  * The emitted document:
- * - Declares `windowtype="navigator:browser"` when `withTitlebar` is true
- *   so chrome-wide stylesheets that target the browser window still apply.
- * - Emits a titlebar-buttonbox placeholder when `withTitlebar` is true so
- *   platform-native window controls render.
+ * - When `withTitlebar` is true, declares the `navigator:browser` minimum
+ *   set: `windowtype`, `customtitlebar`, default `width`/`height`, and a
+ *   `persist` allowlist for screen position + size + sizemode. Without
+ *   these, a fork-owned chrome doc that ships as the main window opens
+ *   at the OS intrinsic minimum size on first launch and forgets the
+ *   user's last-known geometry across restarts. The titlebar-buttonbox
+ *   placeholder is emitted alongside so platform-native window controls
+ *   render with the matching CSS rules from `generateChromeDocCss`.
+ * - Loads `chrome://global/content/customElements.js` in `<head>` ahead
+ *   of the per-doc subscript. Without it, every `<moz-*>` widget the
+ *   author drops into the body silently degrades to `HTMLUnknownElement`
+ *   and the upstream a11y/keyboard semantics that motivated the use of
+ *   the toolkit widget in the first place are lost. Matches the
+ *   `webrtcIndicator.xhtml` shape upstream uses for non-`browser.xhtml`
+ *   chrome documents.
  * - Links the per-document CSS at `chrome://browser/content/<name>-chrome.css`
  *   and the Fluent bundle `browser/<name>.ftl`.
+ * - Keeps `data-l10n-id` on the leaf `<title>` only. Binding the same key
+ *   on the root `<window>` would cause Fluent's first-paint translation
+ *   pass to overwrite the entire body subtree with the message's text
+ *   value (the standard `data-l10n-id`-on-non-leaf failure mode), since
+ *   the FTL stub gives `<name>-window-title` a value rather than an
+ *   attribute-only message.
  * - Carries the `data-furnace-chrome-doc="<name>"` sentinel so fork-side
  *   patches to upstream platform modules (DevToolsStartup, PageActions, …)
  *   that assume `browser.xhtml`'s DOM can guard against it cheaply. See
@@ -46,10 +63,21 @@ export declare function generateChromeDocXhtml(name: string, withTitlebar: boole
  */
 export declare function generateChromeDocJs(name: string, licenseHeader: string): string;
 /**
- * Scoped CSS for a chrome document. When `withTitlebar` is false the
- * macOS `.titlebar-button { display: none }` carve-out is emitted so
- * frameless overlay-style documents don't inherit the platform window
- * controls that `global.css` applies by default.
+ * Scoped CSS for a chrome document.
+ *
+ * When `withTitlebar` is true, the matching navigator:browser minimum
+ * CSS is emitted alongside the layout rules: the buttonbox container is
+ * a draggable region (`-moz-window-dragging: drag`) so the user can drag
+ * the window from the title bar, and the buttonbox itself opts into the
+ * platform-native window-button-box appearance so the OS renders the
+ * traffic-light / minimize-maximize-close controls in their canonical
+ * positions. Without these rules the buttonbox markup still draws but
+ * is unstyled and non-draggable, which is the failure mode a fork that
+ * ships the scaffold verbatim hits on first launch.
+ *
+ * When `withTitlebar` is false the macOS `.titlebar-button { display: none }`
+ * carve-out is emitted so frameless overlay-style documents don't inherit
+ * the platform window controls that `global.css` applies by default.
  */
 export declare function generateChromeDocCss(name: string, withTitlebar: boolean, licenseHeader: string): string;
 /** Fluent stub — one placeholder message keyed to the window title. */
@@ -92,3 +120,26 @@ export declare function jarIncMnEntryForChromeDoc(name: string): string;
  * "jar.mn: Cannot find ${name}.ftl".
  */
 export declare function localeJarMnEntryForChromeDoc(name: string): string;
+/**
+ * Returns true when `jarMnContents` already carries a `[localization]`-style
+ * wildcard rooted at `%browser/` whose pattern would already pick up a
+ * scaffolded `browser/<name>.ftl` file. Recognises:
+ *
+ *   - `(%browser/**\/*.ftl)` — recursive (the upstream shape).
+ *   - `(%browser/*.ftl)` — flat.
+ *
+ * Forks that have migrated entirely to `[localization]` wildcards typically
+ * keep no per-file `locale/...` entries for FTL at all; appending one
+ * there is dead weight at best, and an outright build break when the fork
+ * has also dropped the `% locale browser …` registration. The chrome-doc
+ * scaffolder consults this predicate before its locales/jar.mn append and
+ * skips the per-file write when the wildcard already covers the scaffold's
+ * target path.
+ *
+ * Conservative by design: only wildcards rooted at `%browser/` count, and
+ * a `(%browser/foo.ftl)`-style explicit reference (no `*`) is not treated
+ * as a capture. A fork with a narrower wildcard (e.g. `(%browser/about/*.ftl)`)
+ * is correctly NOT captured by this predicate, because that wildcard would
+ * not pick up the top-level `browser/<name>.ftl` the scaffold writes.
+ */
+export declare function localesFtlWildcardCapturesScaffoldedName(jarMnContents: string): boolean;