@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { watch as fsWatch } from 'node:fs';
-import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { loadConfig } from '../../core/config.js';
 import { applyAllComponents, computeComponentChecksums } from '../../core/furnace-apply.js';
 import { logApplyResult } from '../../core/furnace-apply-output.js';
-import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, } from '../../core/furnace-config.js';
+import { getFurnacePaths } from '../../core/furnace-config.js';
 import { isComponentSourceFile } from '../../core/furnace-constants.js';
 import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { getPersistableAppliedEntry, persistSingleComponentState, shouldPersistSingleComponentState, } from '../../core/furnace-state-persist.js';
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftError, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
@@ -74,11 +75,10 @@ function classifyWatchApplyError(err) {
 async function runWatchLoop(projectRoot) {
     const furnacePaths = getFurnacePaths(projectRoot);
     // Both categories are eligible targets. The set is fixed; only existence
-    // varies over time — a component dir created AFTER watch started (e.g.
-    // the user runs `furnace create` in another terminal) must be picked up
-    // without restarting watch. The prior one-shot `pathExists` check at
-    // startup captured only the dirs that existed then, leaving any later
-    // creation invisible.
+    // varies over time — a component dir created AFTER watch started (the user
+    // running `furnace create` in another terminal) must be picked up without
+    // restarting watch. A one-shot `pathExists` check at startup captures only
+    // the dirs that existed then, leaving any later creation invisible.
     const candidateDirs = [furnacePaths.overridesDir, furnacePaths.customDir];
     const watchDirs = [];
     const watchers = new Map();
@@ -253,16 +253,7 @@ async function runWatchLoop(projectRoot) {
  */
 export async function furnaceApplyCommand(projectRoot, name, options = {}) {
     intro(name ? `Furnace Apply (${name})` : 'Furnace Apply');
-    // Verify engine exists
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
-    }
-    // Load furnace config
-    if (!(await furnaceConfigExists(projectRoot))) {
-        throw new FurnaceError('No furnace.json found. Run "fireforge furnace create" or "fireforge furnace override" to get started.');
-    }
-    const config = await loadFurnaceConfig(projectRoot);
+    const { config } = await assertFurnaceReady(projectRoot);
     const overrideCount = Object.keys(config.overrides).length;
     const customCount = Object.keys(config.custom).length;
     if (overrideCount === 0 && customCount === 0) {
@@ -289,12 +280,12 @@ export async function furnaceApplyCommand(projectRoot, name, options = {}) {
         // `persistState: false` for a NAMED apply is load-bearing: the batch
         // persist path replaces `appliedChecksums` wholesale with only this
         // run's entries, and the batch loops filter to the named component —
-        // so routing a named apply through it persisted a state file
-        // containing ONLY that component, wiping every other component's
-        // checksums. Orphan detection and deleted-file undeploy both key on
-        // that state, so the wiped components' stale engine files became
-        // invisible to apply AND to `furnace validate`. Named apply merges
-        // per-component state below, exactly like `furnace deploy <name>`.
+        // so routing a named apply through it persists a state file containing
+        // ONLY that component, wiping every other component's checksums.
+        // Orphan detection and deleted-file undeploy both key on that state,
+        // so the wiped components' stale engine files become invisible to
+        // apply AND to `furnace validate`. Named apply merges per-component
+        // state below, exactly like `furnace deploy <name>`.
         const applyResult = await applyAllComponents(projectRoot, dryRun, {
             operationContext: ctx,
             ...(name !== undefined ? { componentName: name, persistState: false } : {}),

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

@@ -7,10 +7,11 @@ import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { loadConfig } from '../../core/config.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
-import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { stdioIsInteractive } from '../../core/destructive.js';
+import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
+import { createRollbackJournal, snapshotDir, snapshotFile } from '../../core/furnace-rollback.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.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';
@@ -87,20 +88,12 @@ async function performChromeDocRemoveMutations(args) {
         await removeEmptyDirIfPresent(join(args.engineDir, 'browser/base/content/test', `${args.binaryName}-xpcshell`), journal);
     }
     catch (error) {
-        // This body owns its rollback end to end, so tell the lifecycle wrapper
-        // not to restore the same journal again on the way out.
-        args.operationContext.markRolledBack();
-        try {
-            await restoreRollbackJournalOrThrow(journal, `Failed to remove chrome-doc "${args.name}"`);
-        }
-        catch (rollbackError) {
-            // Matches the seven sibling mutation sites: a failed rollback leaves the
-            // engine in an unknown state, so record the repair breadcrumb and let
-            // the rollback error win rather than discarding it.
-            await recordFurnaceRollbackFailure(args.projectRoot, 'chrome-doc-rollback', `chrome-doc "${args.name}": ${toError(rollbackError).message}`);
-            throw rollbackError;
-        }
-        throw error;
+        return await completeJournalRollback(args.operationContext, journal, error, {
+            projectRoot: args.projectRoot,
+            operation: 'chrome-doc-rollback',
+            failureMessage: `Failed to remove chrome-doc "${args.name}"`,
+            subject: `chrome-doc "${args.name}"`,
+        });
     }
     return { removedFiles, removedJarEntries, removedTestDir };
 }
@@ -110,9 +103,9 @@ export async function furnaceChromeDocRemoveCommand(projectRoot, name, options =
     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.');
-    }
+    await assertFurnaceEngineReady(projectRoot, {
+        engineMissingSuffix: ' before removing a chrome-doc.',
+    });
     const plan = await buildChromeDocPlan({
         engineDir,
         name,
@@ -125,7 +118,7 @@ export async function furnaceChromeDocRemoveCommand(projectRoot, name, options =
         outro('Dry run complete');
         return;
     }
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     if (!options.yes && !isInteractive) {
         throw new FurnaceError(`Cannot remove chrome-doc "${name}" in non-interactive mode without --yes flag.`, name);
     }

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

@@ -41,23 +41,25 @@
  */
 export declare function generateChromeDocXhtml(name: string, withTitlebar: boolean, license: string): string;
 /**
- * browser.xhtml-like scaffold for the document that ships as the fork's
- * MAIN BROWSER WINDOW (0.34.0 field report): the generic dialog-shaped
- * `<window>` scaffold was wrong for the `tokenHostDocuments[0]` /
- * BROWSER_CHROME_URL target — platform C++ reads the root element BEFORE
- * any script runs, and expects the `browser.xhtml` shape:
+ * browser.xhtml-like scaffold for the document that ships as the fork's MAIN
+ * BROWSER WINDOW.
+ *
+ * The generic dialog-shaped `<window>` scaffold is wrong for the
+ * `tokenHostDocuments[0]` / BROWSER_CHROME_URL target: platform C++ reads
+ * the root element BEFORE any script runs, and expects the `browser.xhtml`
+ * shape:
  *
  * - `<html id="main-window">` root (not `<window id="<name>-window">`) —
  *   upstream code from nsXULWindow sizing to session restore looks up
  *   `main-window` by id;
  * - `windowtype="navigator:browser"`, `chromehidden=""` and the geometry
  *   `persist` allowlist declared as ROOT ATTRIBUTES so the platform's
- *   pre-script pass (window tracking, XULStore geometry, chrome flags)
- *   sees them;
+ *   pre-script pass (window tracking, XULStore geometry, chrome flags) sees
+ *   them;
  * - the same head/bootstrap wiring (customElements.js, per-doc subscript,
  *   CSS + Fluent links) and `data-furnace-chrome-doc` sentinel as the
- *   generic scaffold, so jar.mn registration and the platform-module
- *   guard pattern are unchanged.
+ *   generic scaffold, so jar.mn registration and the platform-module guard
+ *   pattern are unchanged.
  */
 export declare function generateBrowserWindowXhtml(name: string, license: string): string;
 /**
@@ -105,25 +107,23 @@ export declare function jarMnEntriesForChromeDoc(name: string): string[];
 /**
  * jar.inc.mn entry that registers the scoped CSS under `content/browser/`.
  *
- * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn`
- * is included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
- * `browser/themes/linux/jar.mn`, `browser/themes/windows/jar.mn`), and every
- * existing entry in those manifests resolves paths relative to the including
- * manifest's directory. A bare `(shared/…)` path produced
- * `obj-.../browser/themes/osx/shared/<name>-chrome.css` which does not exist;
- * `(../shared/…)` matches the upstream pattern and resolves under
- * `browser/themes/shared/`.
+ * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn` is
+ * included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
+ * `.../linux/`, `.../windows/`), and every existing entry in those manifests
+ * resolves paths relative to the INCLUDING manifest's directory. A bare
+ * `(shared/…)` path resolves to
+ * `obj-.../browser/themes/osx/shared/<name>-chrome.css`, which does not
+ * exist.
  */
 export declare function jarIncMnEntryForChromeDoc(name: string): string;
 /**
  * locales/jar.mn entry that registers the `.ftl` under the browser locale
  * bundle. The source path is resolved by mach-locale-jar relative to the
- * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL
- * file is scaffolded at `browser/${name}.ftl` under that root — the `%`
- * prefix means "per-locale content" and the `browser/` subdirectory
- * matches the subdir the scaffolder writes into. Before this fix the
- * entry emitted `(%${name}.ftl)`, which pointed at `en-US/${name}.ftl`
- * and broke the first post-scaffold `fireforge build` with
+ * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL file
+ * is scaffolded at `browser/${name}.ftl` under that root — the `%` prefix
+ * means "per-locale content" and the `browser/` subdirectory matches where
+ * the scaffolder writes. A bare `(%${name}.ftl)` points at
+ * `en-US/${name}.ftl` and breaks the first post-scaffold build with
  * "jar.mn: Cannot find ${name}.ftl".
  */
 export declare function localeJarMnEntryForChromeDoc(name: string): string;

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

@@ -99,23 +99,25 @@ export function generateChromeDocXhtml(name, withTitlebar, license) {
 `;
 }
 /**
- * browser.xhtml-like scaffold for the document that ships as the fork's
- * MAIN BROWSER WINDOW (0.34.0 field report): the generic dialog-shaped
- * `<window>` scaffold was wrong for the `tokenHostDocuments[0]` /
- * BROWSER_CHROME_URL target — platform C++ reads the root element BEFORE
- * any script runs, and expects the `browser.xhtml` shape:
+ * browser.xhtml-like scaffold for the document that ships as the fork's MAIN
+ * BROWSER WINDOW.
+ *
+ * The generic dialog-shaped `<window>` scaffold is wrong for the
+ * `tokenHostDocuments[0]` / BROWSER_CHROME_URL target: platform C++ reads
+ * the root element BEFORE any script runs, and expects the `browser.xhtml`
+ * shape:
  *
  * - `<html id="main-window">` root (not `<window id="<name>-window">`) —
  *   upstream code from nsXULWindow sizing to session restore looks up
  *   `main-window` by id;
  * - `windowtype="navigator:browser"`, `chromehidden=""` and the geometry
  *   `persist` allowlist declared as ROOT ATTRIBUTES so the platform's
- *   pre-script pass (window tracking, XULStore geometry, chrome flags)
- *   sees them;
+ *   pre-script pass (window tracking, XULStore geometry, chrome flags) sees
+ *   them;
  * - the same head/bootstrap wiring (customElements.js, per-doc subscript,
  *   CSS + Fluent links) and `data-furnace-chrome-doc` sentinel as the
- *   generic scaffold, so jar.mn registration and the platform-module
- *   guard pattern are unchanged.
+ *   generic scaffold, so jar.mn registration and the platform-module guard
+ *   pattern are unchanged.
  */
 export function generateBrowserWindowXhtml(name, license) {
     return `<?xml version="1.0"?>
@@ -278,14 +280,13 @@ export function jarMnEntriesForChromeDoc(name) {
 /**
  * jar.inc.mn entry that registers the scoped CSS under `content/browser/`.
  *
- * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn`
- * is included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
- * `browser/themes/linux/jar.mn`, `browser/themes/windows/jar.mn`), and every
- * existing entry in those manifests resolves paths relative to the including
- * manifest's directory. A bare `(shared/…)` path produced
- * `obj-.../browser/themes/osx/shared/<name>-chrome.css` which does not exist;
- * `(../shared/…)` matches the upstream pattern and resolves under
- * `browser/themes/shared/`.
+ * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn` is
+ * included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
+ * `.../linux/`, `.../windows/`), and every existing entry in those manifests
+ * resolves paths relative to the INCLUDING manifest's directory. A bare
+ * `(shared/…)` path resolves to
+ * `obj-.../browser/themes/osx/shared/<name>-chrome.css`, which does not
+ * exist.
  */
 export function jarIncMnEntryForChromeDoc(name) {
     return `    content/browser/${name}-chrome.css           (../shared/${name}-chrome.css)`;
@@ -293,12 +294,11 @@ export function jarIncMnEntryForChromeDoc(name) {
 /**
  * locales/jar.mn entry that registers the `.ftl` under the browser locale
  * bundle. The source path is resolved by mach-locale-jar relative to the
- * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL
- * file is scaffolded at `browser/${name}.ftl` under that root — the `%`
- * prefix means "per-locale content" and the `browser/` subdirectory
- * matches the subdir the scaffolder writes into. Before this fix the
- * entry emitted `(%${name}.ftl)`, which pointed at `en-US/${name}.ftl`
- * and broke the first post-scaffold `fireforge build` with
+ * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL file
+ * is scaffolded at `browser/${name}.ftl` under that root — the `%` prefix
+ * means "per-locale content" and the `browser/` subdirectory matches where
+ * the scaffolder writes. A bare `(%${name}.ftl)` points at
+ * `en-US/${name}.ftl` and breaks the first post-scaffold build with
  * "jar.mn: Cannot find ${name}.ftl".
  */
 export function localeJarMnEntryForChromeDoc(name) {

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

@@ -3,30 +3,29 @@
  * Packaging-verification test templates for
  * `fireforge furnace chrome-doc create --with-tests`.
  *
- * Motivation: an operator who scaffolds a top-level chrome document wants
- * to know "did the file actually land in the packaged bundle?" before
- * relying on it at runtime. Both natural test harnesses have gaps for
- * this question:
+ * An operator who scaffolds a top-level chrome document wants to know "did
+ * the file actually land in the packaged bundle?" before relying on it at
+ * runtime. Both natural test harnesses have gaps for that question:
  *
  *   - xpcshell's `chrome://browser/*` URI registration lags what the real
  *     browser loads even with `firefox-appdir = "browser"` set, so
- *     `NetUtil.asyncFetch("chrome://browser/content/<name>.xhtml")` can
- *     fail with `NS_ERROR_FILE_NOT_FOUND` against a file that IS
- *     correctly packaged (the motivating case).
+ *     `NetUtil.asyncFetch("chrome://browser/content/<name>.xhtml")` can fail
+ *     with `NS_ERROR_FILE_NOT_FOUND` against a file that IS correctly
+ *     packaged.
  *   - Browser-chrome mochitests require a `tabbrowser`, which a
  *     fork-authored chrome doc that replaces `browser.xhtml` deliberately
- *     does not carry (the URILoadingHelper crash path).
+ *     does not carry.
  *
  * This scaffold threads the needle by probing the filesystem directly:
- * `Services.dirsvc.get("XCurProcD", Ci.nsIFile)` returns the current
- * process directory (the browser app dir when `firefox-appdir = "browser"`),
- * and the packaged chrome layout for a jar.mn entry
- * `content/browser/<name>.xhtml` is stable across platforms at
- * `<AppDir>/chrome/browser/content/browser/<name>.xhtml` on an unpacked
- * tree (the default for `mach build` without `MOZ_CHROME_MULTILOCALE`
- * / omnijar). A tree that packs omni.ja would need a different probe;
- * the scaffold notes that out-of-scope case explicitly rather than
- * silently producing a test that fails on packed builds.
+ * `Services.dirsvc.get("XCurProcD", Ci.nsIFile)` returns the current process
+ * directory (the browser app dir when `firefox-appdir = "browser"`), and the
+ * packaged chrome layout for a jar.mn entry `content/browser/<name>.xhtml`
+ * is stable across platforms at
+ * `<AppDir>/chrome/browser/content/browser/<name>.xhtml` on an unpacked tree
+ * (the default for `mach build` without `MOZ_CHROME_MULTILOCALE` / omnijar).
+ * A tree that packs omni.ja would need a different probe; the scaffold notes
+ * that out-of-scope case explicitly rather than silently producing a test
+ * that fails on packed builds.
  */
 /**
  * Returns the canonical xpcshell test basename for a chrome doc packaging
@@ -70,17 +69,16 @@ add_task(async function test_${taskSuffix}_files_packaged() {
   const appDir = Services.dirsvc.get("XCurProcD", Ci.nsIFile);
 
   // Probes a pair of candidate layouts for the same packaged file:
-  //   1) \`<AppDir>/chrome/browser/…\` — the unpacked layout when
-  //      XCurProcD honours \`firefox-appdir = "browser"\` and resolves
-  //      into \`dist/bin/browser/\`.
-  //   2) \`<AppDir>/browser/chrome/browser/…\` — the macOS .app bundle
-  //      layout and some ESR configurations, where XCurProcD sits one
-  //      level above \`browser/\` even when the appdir directive is set.
+  //   1) \`<AppDir>/chrome/browser/…\` — the unpacked layout when XCurProcD
+  //      honours \`firefox-appdir = "browser"\` and resolves into
+  //      \`dist/bin/browser/\`.
+  //   2) \`<AppDir>/browser/chrome/browser/…\` — the macOS .app bundle layout
+  //      and some ESR configurations, where XCurProcD sits one level above
+  //      \`browser/\` even when the appdir directive is set.
   // If either path exists the file is packaged; the assertion only fails
   // when BOTH layouts miss, which is the actual stale-build / missing
-  // jar.mn entry case. Before this dual probe, the eval on macOS
-  // consistently failed against layout (2) even though the file was
-  // packaged correctly.
+  // jar.mn entry case. A single-layout probe fails on macOS against layout
+  // (2) even though the file is packaged correctly.
   function probeEither(primary, fallback, description) {
     const primaryFile = appDir.clone();
     for (const segment of primary) {
@@ -121,9 +119,8 @@ add_task(async function test_${taskSuffix}_files_packaged() {
   // \`content/browser/<name>-chrome.css\` (see \`chromeDocJarIncMnCssEntry\`
   // in \`src/commands/furnace/chrome-doc-templates.ts\`), so the packaged
   // file lands under \`chrome/browser/content/browser/\`, not under
-  // \`skin/classic/browser/\`. The 2026-04-21 eval's first
-  // \`fireforge test --build\` against a scaffolded chrome-doc reported
-  // a false failure because the probe was looking at the skin layout.
+  // \`skin/classic/browser/\`. Probing the skin layout reports a false
+  // failure on the first \`fireforge test --build\` after a scaffold.
   probeEither(
     ["chrome", "browser", "content", "browser", "${name}-chrome.css"],
     ["browser", "chrome", "browser", "content", "browser", "${name}-chrome.css"],

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

@@ -2,18 +2,18 @@
  * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
  * chrome document (xhtml + js + css + ftl + jar.mn registrations).
  *
- * Motivation: `furnace create` covers custom elements under
- * `toolkit/content/widgets/`, but top-level chrome documents (the
- * `mybrowser.xhtml`-class entry points a fork adds alongside or instead
- * of `browser.xhtml`) are today hand-authored with error-prone jar.mn +
- * jar.inc.mn + locales/jar.mn glue. The `*` preprocessor flag, the
- * macOS titlebar-button carve-out, the startup-topic observer, and the
- * Fluent linkage each have silent-break failure modes.
+ * `furnace create` covers custom elements under `toolkit/content/widgets/`,
+ * but top-level chrome documents — the `mybrowser.xhtml`-class entry points
+ * a fork adds alongside or instead of `browser.xhtml` — are otherwise
+ * hand-authored with error-prone jar.mn + jar.inc.mn + locales/jar.mn glue.
+ * The `*` preprocessor flag, the macOS titlebar-button carve-out, the
+ * startup-topic observer, and the Fluent linkage each have silent-break
+ * failure modes.
  *
- * This command writes the four source files and appends three jar.mn
- * entries under a rollback journal identical in shape to `furnace create`.
- * A SIGINT mid-scaffold restores every touched file; a successful run
- * leaves the tree ready for `fireforge build`.
+ * This command writes the four source files and appends three jar.mn entries
+ * under a rollback journal identical in shape to `furnace create`. A SIGINT
+ * mid-scaffold restores every touched file; a successful run leaves the tree
+ * ready for `fireforge build`.
  */
 /** Options for `furnace chrome-doc create`. */
 export interface FurnaceChromeDocCreateOptions {
@@ -27,12 +27,11 @@ export interface FurnaceChromeDocCreateOptions {
     /**
      * Scaffold an xpcshell packaging-verification test alongside the chrome
      * document. The generated test probes `XCurProcD/chrome/browser/...` on
-     * disk rather than going through `chrome://` URI resolution — that
-     * bypasses xpcshell's limited browser-chrome manifest set (the
-     * motivating failure mode where `NetUtil.asyncFetch` returns
-     * `NS_ERROR_FILE_NOT_FOUND` against a file that IS packaged).
-     * Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator
-     * because the owning moz.build depends on the fork's layout.
+     * disk rather than going through `chrome://` URI resolution, which
+     * bypasses xpcshell's limited browser-chrome manifest set — where
+     * `NetUtil.asyncFetch` returns `NS_ERROR_FILE_NOT_FOUND` against a file
+     * that IS packaged. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to
+     * the operator because the owning moz.build depends on the fork's layout.
      */
     withTests?: boolean;
     /** Print the scaffold plan without writing files. */

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

@@ -3,29 +3,29 @@
  * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
  * chrome document (xhtml + js + css + ftl + jar.mn registrations).
  *
- * Motivation: `furnace create` covers custom elements under
- * `toolkit/content/widgets/`, but top-level chrome documents (the
- * `mybrowser.xhtml`-class entry points a fork adds alongside or instead
- * of `browser.xhtml`) are today hand-authored with error-prone jar.mn +
- * jar.inc.mn + locales/jar.mn glue. The `*` preprocessor flag, the
- * macOS titlebar-button carve-out, the startup-topic observer, and the
- * Fluent linkage each have silent-break failure modes.
+ * `furnace create` covers custom elements under `toolkit/content/widgets/`,
+ * but top-level chrome documents — the `mybrowser.xhtml`-class entry points
+ * a fork adds alongside or instead of `browser.xhtml` — are otherwise
+ * hand-authored with error-prone jar.mn + jar.inc.mn + locales/jar.mn glue.
+ * The `*` preprocessor flag, the macOS titlebar-button carve-out, the
+ * startup-topic observer, and the Fluent linkage each have silent-break
+ * failure modes.
  *
- * This command writes the four source files and appends three jar.mn
- * entries under a rollback journal identical in shape to `furnace create`.
- * A SIGINT mid-scaffold restores every touched file; a successful run
- * leaves the tree ready for `fireforge build`.
+ * This command writes the four source files and appends three jar.mn entries
+ * under a rollback journal identical in shape to `furnace create`. A SIGINT
+ * mid-scaffold restores every touched file; a successful run leaves the tree
+ * ready for `fireforge build`.
  */
 import { join } from 'node:path';
 import { loadConfig } from '../../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
-import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
+import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
+import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
-import { pathExists, readText, writeText } from '../../utils/fs.js';
+import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { intro, note, outro, warn } from '../../utils/logger.js';
 import { generateBrowserWindowXhtml, generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, localesFtlWildcardCapturesScaffoldedName, } from './chrome-doc-templates.js';
 import { chromeDocPackagingTestFileName, generateChromeDocPackagingManifest, generateChromeDocPackagingTest, } from './chrome-doc-tests.js';
@@ -189,7 +189,6 @@ async function performChromeDocMutations(args) {
         for (const dir of [contentDir, sharedThemeDir, localeDir]) {
             if (!(await pathExists(dir))) {
                 recordCreatedDir(journal, dir);
-                const { ensureDir } = await import('../../utils/fs.js');
                 await ensureDir(dir);
             }
         }
@@ -230,9 +229,9 @@ async function performChromeDocMutations(args) {
         // wildcard already pick up the scaffolded FTL automatically — appending
         // a per-file `locale/...` entry on top is at best dead weight and at
         // worst a build error when the fork has dropped the `% locale browser`
-        // registration the per-file entry depends on. The wildcard predicate
-        // is intentionally narrow: only `%browser/`-rooted globs that end in
-        // `*.ftl` count as a capture.
+        // registration the per-file entry depends on. The wildcard predicate is
+        // intentionally narrow: only `%browser/`-rooted globs ending in `*.ftl`
+        // count as a capture.
         if (await pathExists(localeJarMnPath)) {
             const existingLocaleJar = await readText(localeJarMnPath);
             if (localesFtlWildcardCapturesScaffoldedName(existingLocaleJar)) {
@@ -256,7 +255,6 @@ async function performChromeDocMutations(args) {
         if (args.withTests) {
             const testParentDir = `${args.binaryName}-xpcshell`;
             const testDir = join(args.engineDir, 'browser/base/content/test', testParentDir, args.name);
-            const { ensureDir } = await import('../../utils/fs.js');
             if (!(await pathExists(testDir))) {
                 recordCreatedDir(journal, testDir);
             }
@@ -274,20 +272,12 @@ async function performChromeDocMutations(args) {
         }
     }
     catch (error) {
-        // This body owns its rollback end to end, so tell the lifecycle wrapper
-        // not to restore the same journal again on the way out.
-        args.operationContext.markRolledBack();
-        try {
-            await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
-        }
-        catch (rollbackError) {
-            // Matches the seven sibling mutation sites: when the rollback itself
-            // fails the engine is in an unknown state, so leave a breadcrumb for
-            // `doctor --repair-furnace` and let the rollback error win.
-            await recordFurnaceRollbackFailure(args.projectRoot, 'chrome-doc-rollback', `chrome-doc "${args.name}": ${toError(rollbackError).message}`);
-            throw rollbackError;
-        }
-        throw error;
+        return await completeJournalRollback(args.operationContext, journal, error, {
+            projectRoot: args.projectRoot,
+            operation: 'chrome-doc-rollback',
+            failureMessage: `Failed to scaffold chrome-doc "${args.name}"`,
+            subject: `chrome-doc "${args.name}"`,
+        });
     }
     return written;
 }
@@ -303,18 +293,18 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
     const forgeConfig = await loadConfig(projectRoot);
     const license = forgeConfig.license ?? DEFAULT_LICENSE;
     const engineDir = join(projectRoot, 'engine');
-    if (!(await pathExists(engineDir))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to scaffold a chrome-doc.');
-    }
+    await assertFurnaceEngineReady(projectRoot, {
+        engineMissingSuffix: ' to scaffold a chrome-doc.',
+    });
     const browserWindow = options.browserWindow ?? false;
     // The browser-window skeleton always carries its own titlebar markup and
     // chrome attributes; --no-titlebar only applies to the generic scaffold.
     const withTitlebar = browserWindow ? true : (options.titlebar ?? true);
     const withTests = options.withTests ?? false;
-    // Hint: when the scaffolded document is the configured token-host
-    // document (the fork's main browser window), the generic dialog-shaped
-    // scaffold is almost certainly wrong (0.34.0 field report: correct
-    // jar.mn registrations, wrong document body).
+    // Hint: when the scaffolded document is the configured token-host document
+    // (the fork's main browser window), the generic dialog-shaped scaffold is
+    // almost certainly wrong — correct jar.mn registrations, wrong document
+    // body.
     if (!browserWindow && (await furnaceConfigExists(projectRoot))) {
         try {
             const furnaceConfig = await loadFurnaceConfig(projectRoot);

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

@@ -1,9 +1,9 @@
 /**
  * Browser-chrome test scaffolding for `furnace create --with-tests`,
- * including the 0.34.0 `--test-dir` redirect and collision safety
- * (existing manifests are appended to; head.js and test implementations
- * are never overwritten). Split out of `create.ts` to keep that command
- * file within the per-file line budget.
+ * including the `--test-dir` redirect and collision safety (existing
+ * manifests are appended to; head.js and test implementations are never
+ * overwritten). Split out of `create.ts` to keep that command file within
+ * the per-file line budget.
  */
 import { type RollbackJournal } from '../../core/furnace-rollback.js';
 import type { ProjectLicense } from '../../types/config.js';

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

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Browser-chrome test scaffolding for `furnace create --with-tests`,
- * including the 0.34.0 `--test-dir` redirect and collision safety
- * (existing manifests are appended to; head.js and test implementations
- * are never overwritten). Split out of `create.ts` to keep that command
- * file within the per-file line budget.
+ * including the `--test-dir` redirect and collision safety (existing
+ * manifests are appended to; head.js and test implementations are never
+ * overwritten). Split out of `create.ts` to keep that command file within
+ * the per-file line budget.
  */
 import { join } from 'node:path';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getLicenseHeader } from '../../core/license-headers.js';
-import { registerTestManifest } from '../../core/manifest-register.js';
+import { registerTestManifest } from '../../core/moz-manifest-register.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
@@ -74,9 +74,9 @@ export async function scaffoldTestFiles(componentName, license, forgeConfig, pat
         : strippedName;
     const underscored = withoutBinaryPrefix.replace(/-/g, '_');
     const testFileName = `browser_${binaryName}_${underscored}.js`;
-    // --test-dir redirects the scaffold (0.34.0 field report: the hardcoded
-    // .../test/<binaryName>/ target collided with a test suite owned by a
-    // different patch). The manifest-registration name is the path below
+    // --test-dir redirects the scaffold: the hardcoded
+    // `.../test/<binaryName>/` target can collide with a test suite owned by a
+    // different patch. The manifest-registration name is the path below
     // browser/base/content/test/ (nested manifests are supported).
     const testDirRel = testDirOverride ?? `${TEST_SCAFFOLD_ROOT}${binaryName}`;
     const testDirName = testDirRel.slice(TEST_SCAFFOLD_ROOT.length);

package/dist/src/commands/furnace/create-mochikit.d.ts

@@ -2,13 +2,12 @@
  * MochiKit (chrome://mochikit) test-harness scaffolder for
  * `fireforge furnace create --test-style=mochikit`.
  *
- * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
- * the top-level chrome document. Forks with a bespoke chrome document
- * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
- * browser-chrome tests today. MochiKit tests load the component module
- * directly via `chrome://global/` and assert against `customElements`, so
- * they work against any fork that registers the upstream toolkit test
- * manifest tree — including those without a tabbrowser.
+ * Browser-chrome mochitests require a `tabbrowser` in the top-level chrome
+ * document, so forks with a bespoke chrome document that deliberately omits
+ * one cannot run them. MochiKit tests load the component module directly via
+ * `chrome://global/` and assert against `customElements`, so they work
+ * against any fork that registers the upstream toolkit test manifest tree —
+ * including those without a tabbrowser.
  */
 import { type RollbackJournal } from '../../core/furnace-rollback.js';
 import type { ProjectLicense } from '../../types/config.js';