@hominis/fireforge 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.21.0
+
+### Features
+
+- **Chrome-doc previews and cleanup.** `furnace chrome-doc create` now supports `--dry-run`, validating the same target files and jar registrations without writing. New `furnace chrome-doc remove <name>` removes scaffolded chrome-doc files, jar entries, and optional xpcshell packaging-test directories, with `--dry-run` and `--yes` support.
+- **Versioned `status --json` schema.** The JSON output is now an object with `schemaVersion`, `summary`, and `files` instead of a bare array. Error paths also emit versioned JSON objects with `code` and `error`.
+
+### Hardening
+
+- **Override removal demotes back to stock.** Removing a Furnace override restores engine files, deletes the override workspace, clears override checksums, and re-adds the component to `stock` tracking instead of dropping it from `furnace.json`. Optional Furnace config fields, including `platformPrefixes`, are preserved across the write.
+- **Rename updates browser-chrome test bodies.** `furnace rename` now rewrites generated browser-chrome mochitest contents as well as filenames and `browser.toml`, preventing stale `waitForElement("<old>")` references after a component rename.
+- **UI build preflight is stricter.** `fireforge build --ui` now refuses before `mach build faster` when the current objdir lacks a completed launchable bundle, guiding fresh imports and partial builds through a full `fireforge build` first.
+- **Interrupt and diagnostics polish.** Signal-driven Furnace preview teardown has regression coverage for stale lock cleanup, `chrome-doc-rollback` markers round-trip through Furnace state validation, watch-mode permission failures name the macOS privacy remediation, and `test --doctor` prints the probed objdir, binary/app path, port, and elapsed time.
+
+### Documentation
+
+- **README — Storybook first-run and audit posture.** The Furnace preview docs now call out the upstream Storybook npm install and audit output as Firefox Storybook workspace dependency state, not FireForge package dependency state.
+- **README — chrome-doc lifecycle and JSON schema.** The Furnace and status sections document chrome-doc dry-runs/removal, UI-build preconditions, watch privacy guidance, and the new versioned `status --json` object.
+
 ## 0.20.0
 
 ### Features

package/README.md

@@ -36,7 +36,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 - **Python 3** (required by Firefox's `mach` build system).
 - **Git**
 - Platform build tools: Xcode on macOS, `build-essential` on Linux, Visual Studio Build Tools on Windows.
-- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH` so the dependency is visible during the usual onboarding sweep rather than at the watch-mode failure site. `fireforge watch` resolves watchman's absolute path via `which` / `where` and prepends its directory to the subprocess `PATH` it hands mach, so a homebrew-installed watchman at `/opt/homebrew/bin/watchman` (absent from the Node subprocess's default `PATH` on macOS) is still visible to `mach watch` without the operator having to re-export `PATH` manually.
+- **Watchman** (optional, only required by `fireforge watch`). Install via `brew install watchman` (macOS), `dnf install watchman` (Fedora), or follow the upstream [Meta docs](https://facebook.github.io/watchman/). `fireforge doctor` surfaces a warning row when it is not on `PATH` so the dependency is visible during the usual onboarding sweep rather than at the watch-mode failure site. `fireforge watch` resolves watchman's absolute path via `which` / `where` and prepends its directory to the subprocess `PATH` it hands mach, so a homebrew-installed watchman at `/opt/homebrew/bin/watchman` (absent from the Node subprocess's default `PATH` on macOS) is still visible to `mach watch` without the operator having to re-export `PATH` manually. If `mach watch` reports `Operation not permitted` / `EPERM` on macOS, FireForge points at the usual privacy fix: grant Full Disk Access or Files and Folders access to the terminal/Codex app and watchman, then restart watchman with `watchman shutdown-server`.
 
 ### Setup
 
@@ -290,9 +290,11 @@ When a patch queue drifts, e.g. due to overlapping new-file creations, forward i
 fireforge verify                    # fsck: manifest + cross-patch lint
 fireforge lint                      # includes the same cross-patch rules
 fireforge status --ownership        # flat path → owning patch table
-fireforge status --json             # machine-readable classified output
+fireforge status --json             # machine-readable classified object
 ```
 
+`status --json` emits a versioned object: `{ "schemaVersion": 1, "summary": { "total": <n>, "byClassification": { ... } }, "files": [...] }`. Error paths also emit a JSON object with `schemaVersion`, `code`, and `error` before exiting non-zero, so scripts can parse both clean and failing runs.
+
 Then fix with the appropriate primitive:
 
 | Problem                                        | Fix                                                                                                              |
@@ -379,6 +381,9 @@ Custom elements live under `toolkit/content/widgets`, but a fork's top-level chr
 fireforge furnace chrome-doc create mybrowser              # full chrome (titlebar + windowtype)
 fireforge furnace chrome-doc create overlay --no-titlebar  # frameless overlay
 fireforge furnace chrome-doc create mybrowser --with-tests # + xpcshell packaging-verification test
+fireforge furnace chrome-doc create mybrowser --dry-run    # preview without writing
+fireforge furnace chrome-doc remove mybrowser --dry-run    # preview cleanup
+fireforge furnace chrome-doc remove mybrowser --yes        # remove files + registrations
 ```
 
 The command writes:
@@ -390,7 +395,7 @@ The command writes:
 - 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.
+Writes are transactional: a SIGINT mid-scaffold rolls back every touched file. `--dry-run` validates the same paths and registrations without acquiring the mutation lock or writing. `furnace chrome-doc remove <name>` removes the scaffolded source files, jar registrations, and optional xpcshell packaging-test directory; use its `--dry-run` first when cleaning an experimental document. Requires an existing engine — run `fireforge download` first.
 
 #### Platform module compatibility
 
@@ -439,6 +444,8 @@ Three styles are available via `--test-style`:
 
 `furnace create`, `furnace remove`, and `furnace rename` re-read `furnace.json` inside the mutation lock before writing, so concurrent component edits preserve sibling entries instead of writing back a stale outer snapshot. `furnace refresh --all` continues past per-component refresh failures, reports the failed count, and exits non-zero with the failed override names after finishing the rest of the selection.
 
+`furnace preview` starts Firefox's upstream Storybook workspace. On the first run, `mach storybook` may install roughly a thousand npm packages under `engine/browser/components/storybook/` and may print npm audit counts from Storybook's transitive dependencies. FireForge frames that output as upstream Storybook dependency state; it does not mean FireForge's own package dependencies were installed into the project.
+
 ## Additional Commands
 
 The commands below cover project configuration, patch queue management, build packaging and development utilities. Run `fireforge <command> --help` for full option details.
@@ -540,6 +547,8 @@ Aggregate patch-size findings (`large-patch-files`, `large-patch-lines`) describ
 
 `fireforge build` is a transactional step: after a successful mach build it audits the dist bundle against engine-relative paths touched since the last successful build, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact or whose dist mtime is older than the source. Ends every build with a `Packaged: N updated, M stale, K missing, S skipped` summary. The audit is warn-only — it never fails a build that mach reported green.
 
+`fireforge build --ui` is intentionally a fast rebuild path, not a bootstrap path. It now refuses before invoking `mach build faster` unless the current objdir has a completed launchable bundle; fresh imports and partial builds should run a full `fireforge build` first.
+
 The audit applies seven routing rules to suppress false positives that previously trained operators to ignore its warnings:
 
 - **jar.mn registrations are authoritative.** When the source under audit is claimed by a `(source)` reference in an ancestor `jar.mn`, the audit walks the registration to compute the expected target path (e.g. `content/browser/mybrowser.js`) and probes the dist tree for a candidate whose absolute path ends with that suffix. Picking the correct artifact from a same-basename collision no longer depends on path-similarity scoring. If the registration target is missing from dist, the warning names the `jar.mn` entry so "registration is intact, packaging dropped the file" is distinguishable from "source is unregistered". This is the fix for the class of false positive where `engine/browser/base/content/<name>.js` (registered in `browser/base/jar.mn`) collided with an unrelated `browser/defaults/preferences/<name>.js` added by a separate patch; the heuristic could not distinguish them, so the audit falsely reported the correctly-packaged chrome resource as missing.
@@ -614,7 +623,7 @@ fireforge test --doctor
 fireforge test --doctor browser/base/content/test/foo/browser_bar.js
 ```
 
-Spawns the built browser headless, waits for a marionette handshake on `127.0.0.1:2828`, and reports PASS/FAIL with the tail of the browser's stderr on FAIL. Distinguishes "marionette wedged" (socket silent) from "mach test discovery failed" — both otherwise surface as a silent 360-second hang followed by `Passed: 0, Failed: 0`. Useful as a prefix on routine `fireforge test` invocations when marionette has been flaky.
+Spawns the built browser headless, waits for a marionette handshake on `127.0.0.1:2828`, and reports PASS/FAIL with the tail of the browser's stderr on FAIL. The success output also names the objdir, binary, app path, port, and elapsed probe time so CI logs show exactly what was probed. Distinguishes "marionette wedged" (socket silent) from "mach test discovery failed" — both otherwise surface as a silent 360-second hang followed by `Passed: 0, Failed: 0`. Useful as a prefix on routine `fireforge test` invocations when marionette has been flaky.
 
 The probe is a cascade of six layered checks — engine-present → mach-available → python-available → profile-creatable → browser-spawns → marionette-handshake. Each failure is tagged `[layer N/6: <name>]` so the first broken layer is surfaced immediately instead of the whole cascade blocking on the final socket poll. When the browser binary crashes at startup (missing dylib, wrong CPU arch, corrupt profile) the cascade fails at layer 5 within the settle window, not after the full socket timeout.
 

package/dist/src/commands/build.js

@@ -5,7 +5,7 @@ import { auditBuildArtifacts } from '../core/build-audit.js';
 import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, runMach, withBuildLock, } from '../core/mach.js';
+import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, runMach, withBuildLock, } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -106,6 +106,24 @@ export async function buildCommand(projectRoot, options) {
             throw new GeneralError(mismatchMessage);
         }
     }
+    if (options.ui) {
+        if (!buildCheck.exists || !buildCheck.objDir) {
+            const detail = buildCheck.objDir
+                ? `Build artifacts incomplete in ${buildCheck.objDir}/`
+                : 'No completed obj-* build artifacts found.';
+            throw new GeneralError(`UI-only builds require a completed full build first. ${detail}\n\n` +
+                'Run "fireforge build" and let it finish, then retry "fireforge build --ui".');
+        }
+        const bundleCheck = await hasRunnableBundle(paths.engine, config.binaryName, buildCheck.objDir);
+        if (!bundleCheck.runnable) {
+            const expectedSuffix = bundleCheck.expectedPath
+                ? ` Expected launchable binary at engine/${bundleCheck.expectedPath}.`
+                : '';
+            throw new GeneralError(`UI-only builds require a completed full build first.${expectedSuffix}\n\n` +
+                'Freshly imported or partially built trees cannot use `mach build faster` yet. ' +
+                'Run "fireforge build" and let it finish, then retry "fireforge build --ui".');
+        }
+    }
     // Log brand info if specified
     if (options.brand) {
         verbose(`Building with brand: ${options.brand}`);

package/dist/src/commands/furnace/chrome-doc-remove.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `fireforge furnace chrome-doc remove <name>` — removes the files and
+ * registrations created by `furnace chrome-doc create`.
+ */
+/** Options for `furnace chrome-doc remove`. */
+export interface FurnaceChromeDocRemoveOptions {
+    /** Skip confirmation. Required for real non-interactive removal. */
+    yes?: boolean;
+    /** Print the removal plan without writing files. */
+    dryRun?: boolean;
+}
+/** Runs `furnace chrome-doc remove <name>`. */
+export declare function furnaceChromeDocRemoveCommand(projectRoot: string, name: string, options?: FurnaceChromeDocRemoveOptions): Promise<void>;

package/dist/src/commands/furnace/chrome-doc-remove.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge furnace chrome-doc remove <name>` — removes the files and
+ * registrations created by `furnace chrome-doc create`.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { confirm } from '@clack/prompts';
+import { loadConfig } from '../../core/config.js';
+import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { FurnaceError } from '../../errors/furnace.js';
+import { pathExists, readText, removeDir, removeFile, writeText } from '../../utils/fs.js';
+import { cancel, info, intro, isCancel, note, outro } from '../../utils/logger.js';
+import { buildChromeDocPlan, validateChromeDocName } from './chrome-doc.js';
+function removeExactLine(content, line) {
+    const lines = content.split('\n');
+    const filtered = lines.filter((candidate) => candidate !== line);
+    return filtered.join('\n').replace(/\n*$/, '\n');
+}
+async function removeChromeDocJarEntryIfPresent(engineDir, file, entry, journal) {
+    const jarPath = join(engineDir, file);
+    if (!(await pathExists(jarPath))) {
+        throw new FurnaceError(`Required jar file ${jarPath} does not exist; cannot remove chrome-doc entry. Check that the fork's engine layout matches the expected browser/ and locales/ tree.`);
+    }
+    const existing = await readText(jarPath);
+    if (!existing.includes(entry)) {
+        return false;
+    }
+    await snapshotFile(journal, jarPath);
+    await writeText(jarPath, removeExactLine(existing, entry));
+    return true;
+}
+async function removeEmptyDirIfPresent(dirPath, journal) {
+    if (!(await pathExists(dirPath)))
+        return false;
+    const entries = await readdir(dirPath);
+    if (entries.length > 0)
+        return false;
+    await snapshotDir(journal, dirPath);
+    await removeDir(dirPath);
+    return true;
+}
+function renderChromeDocRemoveDryRun(name, plan) {
+    const jarLines = plan.jarEntries.map(({ file, entry, present }) => `  engine/${file}: ${present ? 'would remove' : 'not present'} ${entry.trim()}`);
+    const testLines = plan.testDir !== undefined
+        ? ['', 'Would remove test directory if present:', `  engine/${plan.testDir}/`]
+        : [];
+    return [
+        `[dry-run] Chrome document "${name}" removal plan`,
+        '',
+        'Would remove source files if present:',
+        ...plan.files.map((f) => `  engine/${f}`),
+        ...testLines,
+        '',
+        'Jar registrations:',
+        ...jarLines,
+    ].join('\n');
+}
+async function performChromeDocRemoveMutations(args) {
+    const journal = createRollbackJournal();
+    args.operationContext.registerJournal(journal);
+    let removedFiles = 0;
+    let removedJarEntries = 0;
+    let removedTestDir = false;
+    try {
+        for (const file of args.plan.files) {
+            const filePath = join(args.engineDir, file);
+            if (await pathExists(filePath)) {
+                await snapshotFile(journal, filePath);
+                await removeFile(filePath);
+                removedFiles++;
+            }
+        }
+        for (const { file, entry } of args.plan.jarEntries) {
+            if (await removeChromeDocJarEntryIfPresent(args.engineDir, file, entry, journal)) {
+                removedJarEntries++;
+            }
+        }
+        const testDir = join(args.engineDir, 'browser/base/content/test', `${args.binaryName}-xpcshell`, args.name);
+        if (await pathExists(testDir)) {
+            await snapshotDir(journal, testDir);
+            await removeDir(testDir);
+            removedTestDir = true;
+        }
+        await removeEmptyDirIfPresent(join(args.engineDir, 'browser/base/content/test', `${args.binaryName}-xpcshell`), journal);
+    }
+    catch (error) {
+        await restoreRollbackJournalOrThrow(journal, `Failed to remove chrome-doc "${args.name}"`);
+        throw error;
+    }
+    return { removedFiles, removedJarEntries, removedTestDir };
+}
+/** Runs `furnace chrome-doc remove <name>`. */
+export async function furnaceChromeDocRemoveCommand(projectRoot, name, options = {}) {
+    intro('Furnace chrome-doc remove');
+    validateChromeDocName(name);
+    const forgeConfig = await loadConfig(projectRoot);
+    const engineDir = join(projectRoot, 'engine');
+    if (!(await pathExists(engineDir))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first before removing a chrome-doc.');
+    }
+    const plan = await buildChromeDocPlan({
+        engineDir,
+        name,
+        withTests: true,
+        binaryName: forgeConfig.binaryName,
+        includeLocaleEntryWhenWildcard: true,
+    });
+    if (options.dryRun) {
+        note(renderChromeDocRemoveDryRun(name, plan), name);
+        outro('Dry run complete');
+        return;
+    }
+    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    if (!options.yes && !isInteractive) {
+        throw new FurnaceError(`Cannot remove chrome-doc "${name}" in non-interactive mode without --yes flag.`, name);
+    }
+    if (!options.yes && isInteractive) {
+        const confirmed = await confirm({
+            message: `Remove chrome document "${name}" and its scaffolded registrations?`,
+        });
+        if (isCancel(confirmed) || !confirmed) {
+            cancel('Remove cancelled');
+            return;
+        }
+    }
+    const result = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocRemoveMutations({
+        name,
+        engineDir,
+        plan,
+        binaryName: forgeConfig.binaryName,
+        operationContext: ctx,
+    }));
+    info(`Removed ${result.removedFiles} source file${result.removedFiles === 1 ? '' : 's'} and ` +
+        `${result.removedJarEntries} jar registration${result.removedJarEntries === 1 ? '' : 's'} for "${name}".`);
+    if (result.removedTestDir) {
+        info('Removed xpcshell packaging test directory.');
+    }
+    outro('Chrome document removed');
+}
+//# sourceMappingURL=chrome-doc-remove.js.map

package/dist/src/commands/furnace/chrome-doc.d.ts

@@ -35,7 +35,39 @@ export interface FurnaceChromeDocCreateOptions {
      * because the owning moz.build depends on the fork's layout.
      */
     withTests?: boolean;
+    /** Print the scaffold plan without writing files. */
+    dryRun?: boolean;
 }
+/**
+ * Validates a chrome-doc name. Lowercase ASCII, optional hyphens, no
+ * leading digit — the name is used verbatim in CSS selectors, jar.mn
+ * entries, FTL keys, and file basenames, so anything outside that
+ * character set would break at least one downstream consumer.
+ * @param name Chrome-doc name (file basename without extension).
+ * @throws InvalidArgumentError when the name is unusable.
+ */
+export declare function validateChromeDocName(name: string): void;
+export interface ChromeDocPlan {
+    files: string[];
+    dirs: string[];
+    jarEntries: Array<{
+        file: string;
+        entry: string;
+        present: boolean;
+    }>;
+    localeWildcardCapturesFtl: boolean;
+    testDir?: string;
+    testFiles: string[];
+}
+/** Builds the shared create/remove plan for a top-level chrome document. */
+export declare function buildChromeDocPlan(args: {
+    engineDir: string;
+    name: string;
+    withTests: boolean;
+    binaryName: string;
+    validateCreateConflicts?: boolean;
+    includeLocaleEntryWhenWildcard?: boolean;
+}): Promise<ChromeDocPlan>;
 /**
  * Runs `furnace chrome-doc create <name>`.
  * @param projectRoot Root directory of the project.

package/dist/src/commands/furnace/chrome-doc.js

@@ -37,7 +37,7 @@ const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
  * @param name Chrome-doc name (file basename without extension).
  * @throws InvalidArgumentError when the name is unusable.
  */
-function validateChromeDocName(name) {
+export function validateChromeDocName(name) {
     if (!name.trim()) {
         throw new InvalidArgumentError('Chrome-doc name is required', 'name');
     }
@@ -45,6 +45,106 @@ function validateChromeDocName(name) {
         throw new InvalidArgumentError('Chrome-doc name must be lowercase ASCII, may contain hyphens, and must not start with a digit (e.g. mybrowser, about-onboarding).', 'name');
     }
 }
+/** Builds the shared create/remove plan for a top-level chrome document. */
+export async function buildChromeDocPlan(args) {
+    const contentDir = join(args.engineDir, 'browser/base/content');
+    const sharedThemeDir = join(args.engineDir, 'browser/themes/shared');
+    const localeDir = join(args.engineDir, 'browser/locales/en-US/browser');
+    const dirs = [contentDir, sharedThemeDir, localeDir];
+    const xhtmlPath = join(contentDir, `${args.name}.xhtml`);
+    if (args.validateCreateConflicts && (await pathExists(xhtmlPath))) {
+        throw new FurnaceError(`${args.name}.xhtml already exists at ${xhtmlPath}. Remove it or choose a different name.`);
+    }
+    const jarMnPath = join(args.engineDir, 'browser/base/jar.mn');
+    const jarIncMnPath = join(args.engineDir, 'browser/themes/shared/jar.inc.mn');
+    const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
+    for (const requiredJarPath of [jarMnPath, jarIncMnPath, localeJarMnPath]) {
+        if (!(await pathExists(requiredJarPath))) {
+            throw new FurnaceError(`Required jar file ${requiredJarPath} does not exist; cannot register chrome-doc entry. Check that the fork's engine layout matches the expected browser/ and locales/ tree.`);
+        }
+    }
+    const [jarMn, jarIncMn, localeJarMn] = await Promise.all([
+        readText(jarMnPath),
+        readText(jarIncMnPath),
+        readText(localeJarMnPath),
+    ]);
+    const localeWildcardCapturesFtl = localesFtlWildcardCapturesScaffoldedName(localeJarMn);
+    const jarEntries = [];
+    for (const entry of jarMnEntriesForChromeDoc(args.name)) {
+        jarEntries.push({
+            file: 'browser/base/jar.mn',
+            entry,
+            present: jarMn.includes(entry),
+        });
+    }
+    const cssEntry = jarIncMnEntryForChromeDoc(args.name);
+    jarEntries.push({
+        file: 'browser/themes/shared/jar.inc.mn',
+        entry: cssEntry,
+        present: jarIncMn.includes(cssEntry),
+    });
+    if (!localeWildcardCapturesFtl || args.includeLocaleEntryWhenWildcard) {
+        const ftlEntry = localeJarMnEntryForChromeDoc(args.name);
+        jarEntries.push({
+            file: 'browser/locales/jar.mn',
+            entry: ftlEntry,
+            present: localeJarMn.includes(ftlEntry),
+        });
+    }
+    const files = [
+        `browser/base/content/${args.name}.xhtml`,
+        `browser/base/content/${args.name}.js`,
+        `browser/themes/shared/${args.name}-chrome.css`,
+        `browser/locales/en-US/browser/${args.name}.ftl`,
+    ];
+    const testFiles = [];
+    let testDir;
+    if (args.withTests) {
+        const testParentDir = `${args.binaryName}-xpcshell`;
+        testDir = `browser/base/content/test/${testParentDir}/${args.name}`;
+        testFiles.push(`${testDir}/${chromeDocPackagingTestFileName(args.name)}`, `${testDir}/xpcshell.toml`);
+    }
+    return {
+        files,
+        dirs,
+        jarEntries,
+        localeWildcardCapturesFtl,
+        ...(testDir ? { testDir } : {}),
+        testFiles,
+    };
+}
+function renderChromeDocCreateDryRun(name, plan) {
+    const dirLines = plan.dirs.map((dir) => `  ${dir}`);
+    const jarLines = plan.jarEntries.map(({ file, entry, present }) => `  engine/${file}: ${present ? 'already present' : 'would add'} ${entry.trim()}`);
+    const localeLine = plan.localeWildcardCapturesFtl
+        ? [
+            '',
+            'Locale jar.mn already has a [localization] wildcard that captures the FTL;',
+            'no per-file locale entry would be added.',
+        ]
+        : [];
+    const testLines = plan.testFiles.length > 0
+        ? [
+            '',
+            'Would create xpcshell packaging test files:',
+            ...plan.testFiles.map((f) => `  engine/${f}`),
+        ]
+        : [];
+    return [
+        `[dry-run] Chrome document "${name}" scaffold plan`,
+        '',
+        'Directories checked/created as needed:',
+        ...dirLines,
+        '',
+        'Would create source files:',
+        ...plan.files.map((f) => `  engine/${f}`),
+        ...testLines,
+        '',
+        'Jar registrations:',
+        ...jarLines,
+        ...localeLine,
+    ].join('\n');
+}
 /**
  * Appends a line to a jar.mn-style file when that exact line is not
  * already present. Captures the pre-write contents in the journal so a
@@ -192,6 +292,18 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
     }
     const withTitlebar = options.titlebar ?? true;
     const withTests = options.withTests ?? false;
+    const plan = await buildChromeDocPlan({
+        engineDir,
+        name,
+        withTests,
+        binaryName: forgeConfig.binaryName,
+        validateCreateConflicts: true,
+    });
+    if (options.dryRun) {
+        note(renderChromeDocCreateDryRun(name, plan), name);
+        outro('Dry run complete');
+        return;
+    }
     const written = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocMutations({
         name,
         license,

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

@@ -3,6 +3,7 @@ import { Option } from 'commander';
 import { pickDefined } from '../../utils/options.js';
 import { furnaceApplyCommand } from './apply.js';
 import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
+import { furnaceChromeDocRemoveCommand } from './chrome-doc-remove.js';
 import { furnaceCreateCommand } from './create.js';
 import { furnaceDeployCommand } from './deploy.js';
 import { furnaceDiffCommand } from './diff.js';
@@ -86,6 +87,10 @@ function registerFurnaceInfoCommands(furnace, context) {
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);
     }));
+    registerChromeDocCommands(furnace, context);
+}
+function registerChromeDocCommands(furnace, context) {
+    const { getProjectRoot, withErrorHandling } = context;
     const chromeDoc = furnace
         .command('chrome-doc')
         .description('Scaffold top-level chrome documents (xhtml + js + css + ftl + jar.mn)');
@@ -94,9 +99,18 @@ function registerFurnaceInfoCommands(furnace, context) {
         .description('Scaffold a new top-level chrome document')
         .option('--no-titlebar', 'Frameless overlay-style document (omits titlebar-buttonbox)')
         .option('--with-tests', 'Scaffold an xpcshell packaging-verification test that probes XCurProcD/chrome/browser/... directly (bypasses the xpcshell chrome:// URI limitation).')
+        .option('--dry-run', 'Show the chrome-doc scaffold plan without writing')
         .action(withErrorHandling(async (name, options) => {
         await furnaceChromeDocCreateCommand(getProjectRoot(), name, pickDefined(options));
     }));
+    chromeDoc
+        .command('remove <name>')
+        .description('Remove a scaffolded top-level chrome document')
+        .option('-y, --yes', 'Skip confirmation')
+        .option('--dry-run', 'Show the chrome-doc removal plan without writing')
+        .action(withErrorHandling(async (name, options) => {
+        await furnaceChromeDocRemoveCommand(getProjectRoot(), name, pickDefined(options));
+    }));
 }
 /**
  * Registers Furnace commands for authoring, inspection, and maintenance:

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

@@ -493,6 +493,9 @@ export async function furnaceRemoveCommand(projectRoot, name, options = {}) {
             }
             else if (freshType === 'override') {
                 freshConfig.overrides = Object.fromEntries(Object.entries(freshConfig.overrides).filter(([key]) => key !== name));
+                if (!freshConfig.stock.includes(name)) {
+                    freshConfig.stock.push(name);
+                }
             }
             else {
                 freshConfig.custom = Object.fromEntries(Object.entries(freshConfig.custom).filter(([key]) => key !== name));

package/dist/src/commands/furnace/rename-browser-test.d.ts

@@ -0,0 +1,2 @@
+/** Rewrites scaffolded browser-chrome test literals after a component rename. */
+export declare function updateBrowserChromeTestContent(content: string, oldName: string, newName: string, binaryName: string): string;

package/dist/src/commands/furnace/rename-browser-test.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { tagNameToClassName } from '../../core/furnace-constants.js';
+/** Escapes regex metacharacters so a user-supplied name is literal inside a RegExp. */
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function deriveTestStem(componentName, binaryName) {
+    const strippedName = componentName.startsWith('moz-') ? componentName.slice(4) : componentName;
+    const withoutBinaryPrefix = strippedName.startsWith(binaryName + '-')
+        ? strippedName.slice(binaryName.length + 1)
+        : strippedName;
+    return withoutBinaryPrefix.replace(/-/g, '_');
+}
+/** Rewrites scaffolded browser-chrome test literals after a component rename. */
+export function updateBrowserChromeTestContent(content, oldName, newName, binaryName) {
+    const oldClassName = tagNameToClassName(oldName);
+    const newClassName = tagNameToClassName(newName);
+    const oldUnderscored = oldName.replace(/-/g, '_');
+    const newUnderscored = newName.replace(/-/g, '_');
+    const oldTestStem = deriveTestStem(oldName, binaryName);
+    const newTestStem = deriveTestStem(newName, binaryName);
+    return content
+        .replace(new RegExp(escapeRegex(oldName), 'g'), newName)
+        .replace(new RegExp(escapeRegex(oldClassName), 'g'), newClassName)
+        .replace(new RegExp(escapeRegex(oldUnderscored), 'g'), newUnderscored)
+        .replace(new RegExp(escapeRegex(oldTestStem), 'g'), newTestStem);
+}
+//# sourceMappingURL=rename-browser-test.js.map

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

@@ -14,6 +14,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeDir, removeFile, writeText, } from '../../utils/fs.js';
 import { info, intro, note, outro, warn } from '../../utils/logger.js';
+import { updateBrowserChromeTestContent } from './rename-browser-test.js';
 import { renameComponentFileName, updateConfigForCustomRename, updateConfigForOverrideRename, } from './rename-helpers.js';
 import { renameXpcshellTestFiles } from './rename-xpcshell.js';
 /** Escapes regex metacharacters so a user-supplied name is literal inside a RegExp. */
@@ -58,7 +59,7 @@ async function renameTestFiles(engineDir, projectRoot, oldName, newName, journal
         try {
             await snapshotFile(journal, oldTestPath);
             const content = await readText(oldTestPath);
-            await writeText(newTestPath, content);
+            await writeText(newTestPath, updateBrowserChromeTestContent(content, oldName, newName, binaryName));
             await removeFile(oldTestPath);
             info(`Renamed test file: ${oldTestFileName} → ${newTestFileName}`);
         }

package/dist/src/commands/status.js

@@ -221,7 +221,7 @@ function filterFireForgeTempFiles(files) {
 async function renderJsonStatus(files, paths, projectRoot, binaryName) {
     const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
     const classified = await classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
-    const output = classified.map((f) => {
+    const outputFiles = classified.map((f) => {
         const entry = {
             file: f.file,
             status: f.status.trim(),
@@ -236,6 +236,24 @@ async function renderJsonStatus(files, paths, projectRoot, binaryName) {
         }
         return entry;
     });
+    const byClassification = {
+        unmanaged: 0,
+        'patch-backed': 0,
+        branding: 0,
+        furnace: 0,
+        conflict: 0,
+    };
+    for (const file of outputFiles) {
+        byClassification[file.classification]++;
+    }
+    const output = {
+        schemaVersion: 1,
+        summary: {
+            total: outputFiles.length,
+            byClassification,
+        },
+        files: outputFiles,
+    };
     process.stdout.write(JSON.stringify(output, null, 2) + '\n');
 }
 /**
@@ -267,7 +285,8 @@ async function assertEngineHasBaselineCommit(engineDir, options) {
             // 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');
+            process.stdout.write(JSON.stringify({ schemaVersion: 1, error: guidance, code: 'engine-baseline-missing' }) +
+                '\n');
         }
         throw new GeneralError(guidance);
     }
@@ -307,7 +326,7 @@ export async function statusCommand(projectRoot, options = {}) {
     // `withErrorHandling` does not log: bin/fireforge.ts catches it,
     // exits with the carried code, and stdout stays a single JSON line.
     const emitJsonError = (code, message) => {
-        process.stdout.write(JSON.stringify({ error: message, code }) + '\n');
+        process.stdout.write(JSON.stringify({ schemaVersion: 1, error: message, code }) + '\n');
         throw new CommandError(ExitCode.GENERAL_ERROR);
     };
     // Ownership mode is a flat file→patch table; sources are the manifest's

package/dist/src/commands/test.js

@@ -201,8 +201,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // 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)`.
+    let launchablePath;
     if (buildCheck.objDir) {
         const bundleCheck = await hasRunnableBundle(paths.engine, projectConfig.binaryName, buildCheck.objDir);
+        launchablePath = bundleCheck.expectedPath;
         if (!bundleCheck.runnable) {
             const expectedSuffix = bundleCheck.expectedPath
                 ? ` (expected at engine/${bundleCheck.expectedPath})`
@@ -287,6 +289,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         // (`info`/`warn`) is retained so TTY users keep the visual framing.
         const directLine = formatMarionettePreflightLine(preflight);
         process.stdout.write(`${directLine}\n`);
+        process.stdout.write(`Marionette preflight environment: objdir=${buildCheck.objDir ?? '(none)'}; binary=${projectConfig.binaryName}; app=${launchablePath ? `engine/${launchablePath}` : '(unknown)'}; port=${effectivePort ?? 2828}; elapsed=${preflight.durationMs}ms\n`);
         reportMarionettePreflight(preflight);
         if (testPaths.length === 0) {
             if (!preflight.ok) {

package/dist/src/commands/watch.js

@@ -60,14 +60,21 @@ function buildWatchmanConfigureTimeMessage() {
  * @param watchmanPath - Optional absolute path to the resolved watchman binary; surfaced in the guidance so the operator can see whether FireForge actually found one.
  * @returns User-facing failure guidance
  */
-function buildUnsupportedWatchMessage(exitCode, watchmanPath) {
+function hasWatchPermissionFailure(output) {
+    return /Operation not permitted|EPERM|EACCES/i.test(output);
+}
+function buildUnsupportedWatchMessage(exitCode, watchmanPath, output = '') {
     const watchmanLine = watchmanPath
         ? `  - FireForge resolved watchman at ${watchmanPath} and prepended its directory to the mach subprocess PATH. If mach still did not see it, ensure that path is stable between runs.\n`
         : '';
+    const permissionLine = hasWatchPermissionFailure(output)
+        ? '  - macOS may be blocking watchman or Terminal/Codex from reading the engine directory. Grant Full Disk Access or Files and Folders access to your terminal app and watchman, then restart watchman with "watchman shutdown-server".\n'
+        : '';
     return (`Watch failed with exit code ${exitCode}. Check the output above for details.\n\n` +
         'Common causes:\n' +
         '  - watchman is not installed or not in PATH right now\n' +
         '  - watchman was installed only after the current obj-* directory was configured; delete obj-* and rebuild\n' +
+        permissionLine +
         '  - mach watch is unsupported in the current objdir or build environment\n' +
         watchmanLine +
         '\n' +
@@ -194,7 +201,7 @@ export async function watchCommand(projectRoot) {
             throw new GeneralError(buildWatchmanConfigureTimeMessage());
         }
         // 130 is SIGINT (Ctrl+C), which is expected
-        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode, watchmanPath), 'mach watch');
+        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode, watchmanPath, combinedOutput), 'mach watch');
     }
     outro('Watch mode stopped');
 }

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

@@ -195,6 +195,9 @@ export function validateFurnaceConfig(data) {
     if (migrated['tokenAllowlist'] !== undefined) {
         config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
     }
+    if (migrated['platformPrefixes'] !== undefined) {
+        config.platformPrefixes = parseStringArray(migrated['platformPrefixes'], 'platformPrefixes');
+    }
     if (migrated['runtimeVariables'] !== undefined) {
         config.runtimeVariables = parseStringArray(migrated['runtimeVariables'], 'runtimeVariables');
     }
@@ -242,6 +245,7 @@ const PENDING_REPAIR_OPERATIONS = [
     'deploy-rollback',
     'remove-rollback',
     'create-rollback',
+    'chrome-doc-rollback',
     'override-rollback',
     'scan-rollback',
     'rename-rollback',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -70,7 +70,7 @@
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
+    "lint-staged": "^17.0.4",
     "prettier": "^3.7.4",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",