@hominis/fireforge 0.43.0 → 0.44.0

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
+import { FURNACE_PENDING_REPAIR_OPERATIONS } from '../types/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
@@ -128,9 +129,8 @@ export function validateFurnaceConfig(data) {
     // Warn when two custom components share a targetPath. Nothing technically
     // prevents co-location, but per-component removal and orphan detection
     // both reason about "files this component deployed into its directory" —
-    // shared directories make those judgements ambiguous, and historically a
-    // shared targetPath meant `furnace remove` of one component deleted the
-    // other's deployed files.
+    // shared directories make those judgements ambiguous, and can lead to
+    // `furnace remove` of one component deleting the other's deployed files.
     const targetPathOwners = new Map();
     for (const [name, custom_] of Object.entries(custom)) {
         const owners = targetPathOwners.get(custom_.targetPath) ?? [];
@@ -166,18 +166,11 @@ function validateFurnaceState(data) {
     }
     return result.state;
 }
-const PENDING_REPAIR_OPERATIONS = [
-    'preview-teardown',
-    'apply-rollback',
-    'deploy-rollback',
-    'remove-rollback',
-    'create-rollback',
-    'chrome-doc-rollback',
-    'override-rollback',
-    'scan-rollback',
-    'rename-rollback',
-    'refresh-rollback',
-];
+// Single source of truth: the list the union is derived from. The copy
+// this replaced was annotated, not linked — it caught a member REMOVED
+// from the union but never one ADDED to it, and listed them in a
+// different order.
+const PENDING_REPAIR_OPERATIONS = FURNACE_PENDING_REPAIR_OPERATIONS;
 function parsePendingRepair(data) {
     if (!isObject(data)) {
         return { error: 'field "pendingRepair" must be an object' };
@@ -337,8 +330,7 @@ export async function loadFurnaceConfig(root) {
  * reset, rebase, rebase --abort): every applied checksum describes content
  * that no longer exists, but pendingRepair tracks authoring-side rollback
  * issues in the component WORKSPACE and must survive an engine refresh.
- * No-ops when the state file does not exist. Centralized because the same
- * reset logic had drifted into four separate command files.
+ * No-ops when the state file does not exist.
  */
 export async function clearAppliedFurnaceState(root) {
     const paths = getFurnacePaths(root);
@@ -374,20 +366,15 @@ export async function writeFurnaceConfig(root, config) {
 }
 /**
  * Stamps every override's `baseVersion` to the supplied version. Used by
- * `fireforge rebase` after a successful patch re-export so a successful
- * ESR bump does not leave Furnace overrides in a doctor-failing drift
- * state. Returns the number of overrides stamped (zero if furnace.json
- * has no overrides, or if the file is missing).
+ * `fireforge rebase` after a successful patch re-export, so an ESR bump does
+ * not leave Furnace overrides in a doctor-failing drift state: `rebase`
+ * stamps patch `sourceEsrVersion` via `stampPatchVersions`, and without the
+ * matching override stamp `doctor` fails Furnace component validation on
+ * every override.
  *
- * Motivating case: a 140.9.0esr → 140.9.1esr rebase stamps patch
- * `sourceEsrVersion` via `stampPatchVersions`, but before 0.16.0 no
- * equivalent stamping ran for Furnace override `baseVersion`. `doctor`
- * then immediately failed Furnace component validation on every
- * override. The stamp is deliberately unconditional — `fireforge
- * furnace validate` is the right tool for "does this override still
- * apply", and rebase already attested that the patch layer re-validated
- * against the new ESR; the per-override health check belongs in a
- * separate pass, not inline with the stamp.
+ * The stamp is deliberately unconditional — `fireforge furnace validate` is
+ * the right tool for "does this override still apply", and rebase has
+ * already attested that the patch layer re-validated against the new ESR.
  *
  * @param root - Root directory of the project
  * @param version - Firefox version string to stamp onto every override
@@ -414,23 +401,20 @@ export async function stampFurnaceOverrideBaseVersions(root, version) {
  * Creates a default furnace configuration.
  *
  * When a `binaryName` is provided, the default config carries a
- * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
- * `fireforge token coverage` on a fresh project reports `0 tokens` and
- * labels every custom-property reference as `unknown` — the scan has
- * no prefix to key off. The 2026-04-21 eval walked directly into this
- * state (`furnace init` → `token add` → `token coverage` → zero
- * tokens), and only recovered after hand-editing furnace.json. Deriving
- * the prefix from the binary name matches the convention the scaffolded
- * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ * `tokenPrefix` derived as `--<binaryName>-`. Without it, `fireforge token
+ * coverage` on a fresh project reports `0 tokens` and labels every
+ * custom-property reference as `unknown`, because the scan has no prefix to
+ * key off. Deriving the prefix from the binary name matches the convention
+ * the scaffolded tokens CSS already uses for its `--<binaryName>-*`
+ * declarations.
  *
- * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
- * on the legacy no-arg call shape (existing tests, programmatic callers
- * bootstrapping from a not-yet-loaded config) still get a valid config
- * without a prefix; the CLI init path always has a `binaryName` from
- * `fireforge.json` and always sets one.
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers on
+ * the no-arg call shape still get a valid config without a prefix; the CLI
+ * init path always has a `binaryName` from `fireforge.json` and always sets
+ * one.
  *
- * @param options - Optional init context; pass `{ binaryName }` to
- *   derive the token prefix.
+ * @param options - Optional init context; pass `{ binaryName }` to derive
+ *   the token prefix.
  * @returns A valid FurnaceConfig
  */
 export function createDefaultFurnaceConfig(options = {}) {
@@ -496,15 +480,9 @@ export async function updateFurnaceState(root, updates) {
 /**
  * Engine-relative path of the directory `furnace preview` writes its
  * generated Storybook story files into. Treated as Furnace-managed so
- * `status` does not flag them as unmanaged and `lint` does not fail on
- * their (intentionally bare) license headers.
- *
- * 2026-04-25 eval Finding 19: a successful `furnace preview` run synced
- * 23 stories under this prefix; afterwards `status` showed all 23 as
- * untracked unmanaged changes and aggregate `lint` failed with 23
- * `missing-license-header` errors. The files are tool output — operators
- * are not expected to commit or hand-edit them — so the right shape is
- * to bucket them with the rest of Furnace's managed material.
+ * `status` does not flag them as unmanaged and `lint` does not fail on their
+ * (intentionally bare) license headers — they are tool output, not files an
+ * operator commits or hand-edits.
  */
 const FURNACE_STORYBOOK_STORIES_PREFIX = 'browser/components/storybook/stories/furnace/';
 /**

package/dist/src/core/furnace-constants.d.ts

@@ -2,6 +2,14 @@
 export declare const CUSTOM_ELEMENTS_JS = "toolkit/content/customElements.js";
 /** Path to jar.mn within the engine source tree (toolkit global) */
 export declare const JAR_MN = "toolkit/content/jar.mn";
+/**
+ * Upstream home of the MozLitElement widget sources.
+ *
+ * The trailing slash is NOT included: `build-audit-transforms.ts` needs
+ * `${WIDGETS_DIR}/` and its ordered prefix table depends on that slash, so
+ * appending it at the one site that wants it keeps the others correct.
+ */
+export declare const WIDGETS_DIR = "toolkit/content/widgets";
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export declare const FTL_DIR = "toolkit/locales/en-US/toolkit/global";
 /**

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

@@ -3,14 +3,22 @@
 export const CUSTOM_ELEMENTS_JS = 'toolkit/content/customElements.js';
 /** Path to jar.mn within the engine source tree (toolkit global) */
 export const JAR_MN = 'toolkit/content/jar.mn';
+/**
+ * Upstream home of the MozLitElement widget sources.
+ *
+ * The trailing slash is NOT included: `build-audit-transforms.ts` needs
+ * `${WIDGETS_DIR}/` and its ordered prefix table depends on that slash, so
+ * appending it at the one site that wants it keeps the others correct.
+ */
+export const WIDGETS_DIR = 'toolkit/content/widgets';
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
 /**
  * Suffix for the per-binary xpcshell scaffold parent directory. Components
  * created with `furnace create --with-tests --xpcshell` land at
  * `browser/base/content/test/<binaryName>${XPCSHELL_TEST_DIR_SUFFIX}/<component>/`.
- * Centralised so `create` / `remove` / `rename` / `validate` all agree on
- * the path template (2026-04-24 eval Finding 5).
+ * Centralised so `create` / `remove` / `rename` / `validate` all agree on the
+ * path template.
  */
 const XPCSHELL_TEST_DIR_SUFFIX = '-xpcshell';
 /**

package/dist/src/core/furnace-css-fragments.d.ts

@@ -1,8 +1,8 @@
 /**
- * Shared CSS fragments for Furnace widgets (field report D2).
+ * Shared CSS fragments for Furnace widgets.
  *
  * Shadow-DOM isolation forces each widget stylesheet to carry its own copy
- * of genuinely shared CSS (keyframes, resets). Hand-syncing those copies
+ * of genuinely shared CSS (keyframes, resets), and hand-syncing those copies
  * drifts. Instead, a workspace stylesheet declares an include directive
  * (a CSS block comment on its own line):
  *
@@ -14,9 +14,9 @@
  * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
  *
  * Drift contract: the apply fast-path and `furnace validate` compare the
- * *expanded* workspace source against the engine copy, so editing a
- * fragment surfaces as ordinary component drift and the next deploy
- * refreshes every consuming widget.
+ * *expanded* workspace source against the engine copy, so editing a fragment
+ * surfaces as ordinary component drift and the next deploy refreshes every
+ * consuming widget.
  */
 import type { ValidationIssue } from '../types/furnace.js';
 export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';

package/dist/src/core/furnace-css-fragments.js

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Shared CSS fragments for Furnace widgets (field report D2).
+ * Shared CSS fragments for Furnace widgets.
  *
  * Shadow-DOM isolation forces each widget stylesheet to carry its own copy
- * of genuinely shared CSS (keyframes, resets). Hand-syncing those copies
+ * of genuinely shared CSS (keyframes, resets), and hand-syncing those copies
  * drifts. Instead, a workspace stylesheet declares an include directive
  * (a CSS block comment on its own line):
  *
@@ -15,9 +15,9 @@
  * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
  *
  * Drift contract: the apply fast-path and `furnace validate` compare the
- * *expanded* workspace source against the engine copy, so editing a
- * fragment surfaces as ordinary component drift and the next deploy
- * refreshes every consuming widget.
+ * *expanded* workspace source against the engine copy, so editing a fragment
+ * surfaces as ordinary component drift and the next deploy refreshes every
+ * consuming widget.
  */
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';

package/dist/src/core/furnace-jsconfig.d.ts

@@ -1,23 +1,22 @@
 /**
- * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig
- * so typed cross-module imports of multi-file Furnace components work
- * (field report D3).
+ * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig so
+ * typed cross-module imports of multi-file Furnace components work.
  *
  * When a main widget imports a sibling helper via its deployed chrome URL
- * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module
- * shim swallows the import: value imports degrade to `any` and
+ * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module shim
+ * swallows the import: value imports degrade to `any` and
  * `import(...).SomeType` typedefs fail with TS2694. The fix is a `paths`
- * mapping from the chrome URL to the real workspace source. Furnace
- * already owns the jar.mn side of that mapping, so it can maintain the
- * jsconfig side automatically on every deploy.
+ * mapping from the chrome URL to the real workspace source. Furnace already
+ * owns the jar.mn side of that mapping, so it maintains the jsconfig side
+ * automatically on every deploy.
  *
  * Ownership contract: only entries whose key starts with
  * `chrome://global/content/elements/` AND whose mapped path resolves into
  * the Furnace custom-components workspace are managed (added, updated,
- * pruned). Everything else in the jsconfig — including hand-written
- * `paths` entries pointing elsewhere — is preserved verbatim. No
- * `baseUrl` is required or written: relative `paths` resolve against the
- * config file's directory.
+ * pruned). Everything else in the jsconfig — including hand-written `paths`
+ * entries pointing elsewhere — is preserved verbatim. No `baseUrl` is
+ * required or written: relative `paths` resolve against the config file's
+ * directory.
  */
 import type { FurnaceConfig } from '../types/furnace.js';
 /** Result summary of a jsconfig paths sync. */

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

@@ -1,24 +1,23 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig
- * so typed cross-module imports of multi-file Furnace components work
- * (field report D3).
+ * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig so
+ * typed cross-module imports of multi-file Furnace components work.
  *
  * When a main widget imports a sibling helper via its deployed chrome URL
- * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module
- * shim swallows the import: value imports degrade to `any` and
+ * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module shim
+ * swallows the import: value imports degrade to `any` and
  * `import(...).SomeType` typedefs fail with TS2694. The fix is a `paths`
- * mapping from the chrome URL to the real workspace source. Furnace
- * already owns the jar.mn side of that mapping, so it can maintain the
- * jsconfig side automatically on every deploy.
+ * mapping from the chrome URL to the real workspace source. Furnace already
+ * owns the jar.mn side of that mapping, so it maintains the jsconfig side
+ * automatically on every deploy.
  *
  * Ownership contract: only entries whose key starts with
  * `chrome://global/content/elements/` AND whose mapped path resolves into
  * the Furnace custom-components workspace are managed (added, updated,
- * pruned). Everything else in the jsconfig — including hand-written
- * `paths` entries pointing elsewhere — is preserved verbatim. No
- * `baseUrl` is required or written: relative `paths` resolve against the
- * config file's directory.
+ * pruned). Everything else in the jsconfig — including hand-written `paths`
+ * entries pointing elsewhere — is preserved verbatim. No `baseUrl` is
+ * required or written: relative `paths` resolve against the config file's
+ * directory.
  */
 import { readdir } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';

package/dist/src/core/furnace-marker.d.ts

@@ -1,14 +1,13 @@
 /**
  * Marker-comment resolution shared between furnace apply and deploy.
  *
- * 2026-04-26 eval Finding 6: when `markerComment` is unset in
- * fireforge.json, fall back to `binaryName.toUpperCase()` so the
- * patch-lint rule `lintModificationComments` (which keys on
- * `${binaryName.toUpperCase()}:`) accepts furnace-emitted edits on the
- * next `lint`/`export` round-trip. The helper tolerates the
- * undefined-config case (a project that hasn't run `fireforge setup`
- * yet) and the missing-binaryName case (test fixtures that mock
- * `loadConfig` with a partial shape).
+ * When `markerComment` is unset in fireforge.json, fall back to
+ * `binaryName.toUpperCase()` so the patch-lint rule
+ * `lintModificationComments` (which keys on `${binaryName.toUpperCase()}:`)
+ * accepts furnace-emitted edits on the next `lint`/`export` round-trip. The
+ * helper tolerates the undefined-config case (a project that has not run
+ * `fireforge setup` yet) and the missing-binaryName case (test fixtures that
+ * mock `loadConfig` with a partial shape).
  */
 export declare function resolveFurnaceMarkerComment(forgeConfig: {
     markerComment?: string;

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

@@ -2,14 +2,13 @@
 /**
  * Marker-comment resolution shared between furnace apply and deploy.
  *
- * 2026-04-26 eval Finding 6: when `markerComment` is unset in
- * fireforge.json, fall back to `binaryName.toUpperCase()` so the
- * patch-lint rule `lintModificationComments` (which keys on
- * `${binaryName.toUpperCase()}:`) accepts furnace-emitted edits on the
- * next `lint`/`export` round-trip. The helper tolerates the
- * undefined-config case (a project that hasn't run `fireforge setup`
- * yet) and the missing-binaryName case (test fixtures that mock
- * `loadConfig` with a partial shape).
+ * When `markerComment` is unset in fireforge.json, fall back to
+ * `binaryName.toUpperCase()` so the patch-lint rule
+ * `lintModificationComments` (which keys on `${binaryName.toUpperCase()}:`)
+ * accepts furnace-emitted edits on the next `lint`/`export` round-trip. The
+ * helper tolerates the undefined-config case (a project that has not run
+ * `fireforge setup` yet) and the missing-binaryName case (test fixtures that
+ * mock `loadConfig` with a partial shape).
  */
 export function resolveFurnaceMarkerComment(forgeConfig) {
     if (!forgeConfig)

package/dist/src/core/furnace-operation.d.ts

@@ -86,6 +86,37 @@ export declare function rollbackActiveOperationsForSignal(signal: FurnaceShutdow
  * touch this directly.
  */
 export declare function getFurnaceLockPath(root: string): string;
+/**
+ * Completes the rollback for a mutation body that owns its journal end to
+ * end, then rethrows. Never returns normally.
+ *
+ * Shaped as a catch-body handler rather than a `withJournalRollback(body)`
+ * wrapper on purpose: the eight calling bodies differ in early returns and
+ * in what they close over, and converting them to callbacks would
+ * restructure control flow through the engine's rollback path for a
+ * cosmetic gain.
+ *
+ * The ordering is the part worth centralising: `markRolledBack()` MUST run
+ * before the restore, so a restore that itself fails does not leave the
+ * lifecycle wrapper replaying the same journal on the way out. And the
+ * ORIGINAL error is rethrown unless the rollback is what failed — the
+ * operator needs to know what went wrong, and separately whether the engine
+ * could be put back.
+ *
+ * @param ctx - The furnace operation context from `runFurnaceMutation`
+ * @param journal - Rollback journal this body populated
+ * @param error - The error the body threw
+ * @param options - Project root, pending-repair tag, and message fragments
+ * @returns Never — always throws
+ */
+export declare function completeJournalRollback(ctx: FurnaceOperationContext, journal: RollbackJournal, error: unknown, options: {
+    projectRoot: string;
+    operation: FurnacePendingRepairOperation;
+    /** Prefix for the restore failure, e.g. `Failed to override component "x"`. */
+    failureMessage: string;
+    /** Subject recorded on the pending-repair marker, e.g. `component "x"`. */
+    subject: string;
+}): Promise<never>;
 /**
  * Forcibly removes the furnace lock directory for every active operation.
  *

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

@@ -1,14 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
-import { readLockStatus, withFileLock } from './file-lock.js';
+import { readLockStatus, releaseLockIfOwned, withFileLock } from './file-lock.js';
 import { loadFurnaceState, updateFurnaceState } from './furnace-config.js';
-import { restoreRollbackJournal } from './furnace-rollback.js';
+import { restoreRollbackJournal, restoreRollbackJournalOrThrow, } from './furnace-rollback.js';
 /** Sidecar lock filename used to serialize concurrent furnace mutations. */
 const FURNACE_LOCK_FILENAME = 'furnace.lock';
 /**
@@ -232,6 +231,42 @@ async function persistPendingRepair(root, operation, reason) {
 export function getFurnaceLockPath(root) {
     return join(root, FIREFORGE_DIR, FURNACE_LOCK_FILENAME);
 }
+/**
+ * Completes the rollback for a mutation body that owns its journal end to
+ * end, then rethrows. Never returns normally.
+ *
+ * Shaped as a catch-body handler rather than a `withJournalRollback(body)`
+ * wrapper on purpose: the eight calling bodies differ in early returns and
+ * in what they close over, and converting them to callbacks would
+ * restructure control flow through the engine's rollback path for a
+ * cosmetic gain.
+ *
+ * The ordering is the part worth centralising: `markRolledBack()` MUST run
+ * before the restore, so a restore that itself fails does not leave the
+ * lifecycle wrapper replaying the same journal on the way out. And the
+ * ORIGINAL error is rethrown unless the rollback is what failed — the
+ * operator needs to know what went wrong, and separately whether the engine
+ * could be put back.
+ *
+ * @param ctx - The furnace operation context from `runFurnaceMutation`
+ * @param journal - Rollback journal this body populated
+ * @param error - The error the body threw
+ * @param options - Project root, pending-repair tag, and message fragments
+ * @returns Never — always throws
+ */
+export async function completeJournalRollback(ctx, journal, error, options) {
+    // This body owns its rollback end to end, so tell the lifecycle wrapper
+    // not to restore the same journal again on the way out.
+    ctx.markRolledBack();
+    try {
+        await restoreRollbackJournalOrThrow(journal, options.failureMessage);
+    }
+    catch (rollbackError) {
+        await recordFurnaceRollbackFailure(options.projectRoot, options.operation, `${options.subject}: ${toError(rollbackError).message}`);
+        throw rollbackError;
+    }
+    throw error;
+}
 /**
  * Forcibly removes the furnace lock directory for every active operation.
  *
@@ -251,13 +286,15 @@ export function getFurnaceLockPath(root) {
 export async function forceReleaseFurnaceLocksForActiveOperations() {
     const paths = new Set([...activeOperations.values()].map((op) => getFurnaceLockPath(op.root)));
     for (const lockPath of paths) {
-        try {
-            await rm(lockPath, { recursive: true, force: true });
-            verbose(`Removed furnace lock at ${lockPath} during signal teardown`);
-        }
-        catch (error) {
-            verbose(`Could not remove furnace lock at ${lockPath} during signal teardown: ${toError(error).message}`);
-        }
+        // Ownership-checked, like every other release path. The bare `rm` this
+        // replaced would delete a lock a DIFFERENT process had acquired in the
+        // window between our operation dying and this sweep running — the exact
+        // race `releaseLock`'s PID verification was added to close, reopened
+        // here because the sweeper has no acquisition token to check.
+        const removed = await releaseLockIfOwned(lockPath);
+        verbose(removed
+            ? `Removed furnace lock at ${lockPath} during signal teardown`
+            : `Left furnace lock at ${lockPath} in place during signal teardown: it is not owned by this process`);
     }
 }
 /**
@@ -336,15 +373,15 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
         }
         catch (error) {
             // A thrown error leaves the engine mutated exactly as a signal does,
-            // so it gets the same treatment. Before 0.43.0 this was a bare
-            // finally: the throw path deregistered the operation and marked it
-            // completed, which removed it from the signal handler's view too, so
-            // a body that threw outside its own catch (notably anywhere in
-            // `applyAllComponents` outside its two per-component try blocks) left
-            // the checkout torn with no marker.
+            // so it gets the same treatment. A bare finally here would
+            // deregister the operation and mark it completed, removing it from
+            // the signal handler's view too, so a body that threw outside its
+            // own catch — notably anywhere in `applyAllComponents` outside its
+            // two per-component try blocks — would leave the checkout torn with
+            // no marker.
             //
             // This runs inside the withFileLock callback, so the furnace lock is
-            // still held for the duration of the restore — a competing process
+            // still held for the duration of the restore: a competing process
             // cannot start mutating half-way through it.
             await rollbackOperationForThrow(operation);
             throw error;

package/dist/src/core/furnace-precondition.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared precondition ladder for the Furnace command family: engine exists,
+ * `furnace.json` exists.
+ *
+ * Kept separate from the `GeneralError` ladder in `engine-precondition.ts`
+ * because the error CLASS is load-bearing here, not cosmetic: `FurnaceError`
+ * carries its own `userMessage` and exit code 9, so a helper raising
+ * `GeneralError` would silently change both.
+ *
+ * Deliberately NOT routed through this helper — each informs rather than
+ * refuses, and each says so at its own site: `furnace list`,
+ * `furnace status`, `furnace init`, and `verify`. `furnace validate`
+ * refusing is the intended line between inspecting and validating.
+ */
+import type { FurnaceConfig } from '../types/furnace.js';
+import type { ProjectPaths } from '../types/index.js';
+/** Options shared by the Furnace precondition assertions. */
+export interface FurnacePreconditionOptions {
+    /**
+     * Appended to the engine-missing refusal, e.g.
+     * `' to scaffold a chrome-doc.'`. The base message ends WITHOUT
+     * punctuation so the suffix reads as one sentence; callers passing nothing
+     * get a plain full stop.
+     */
+    engineMissingSuffix?: string;
+}
+/**
+ * Asserts that a specific engine directory exists, raising a `FurnaceError`.
+ *
+ * The path-taking form, for core helpers that already hold `engineDir` and
+ * have no project root to derive it from.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Optional message tailoring
+ */
+export declare function assertFurnaceEngineDirReady(engineDir: string, options?: FurnacePreconditionOptions): Promise<void>;
+/**
+ * Asserts that the engine checkout exists, raising a `FurnaceError`.
+ *
+ * The engine rung on its own, for the Furnace commands that scaffold or
+ * mutate component sources without needing `furnace.json` to exist yet.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Optional message tailoring
+ * @returns Resolved project paths, so callers do not re-derive them
+ */
+export declare function assertFurnaceEngineReady(projectRoot: string, options?: FurnacePreconditionOptions): Promise<{
+    paths: ProjectPaths;
+}>;
+/**
+ * Asserts the full Furnace ladder — engine checkout, then `furnace.json` —
+ * and returns the loaded config so callers do not read it a second time.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Optional message tailoring
+ * @returns Resolved project paths and the loaded furnace config
+ */
+export declare function assertFurnaceReady(projectRoot: string, options?: FurnacePreconditionOptions): Promise<{
+    paths: ProjectPaths;
+    config: FurnaceConfig;
+}>;

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

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared precondition ladder for the Furnace command family: engine exists,
+ * `furnace.json` exists.
+ *
+ * Kept separate from the `GeneralError` ladder in `engine-precondition.ts`
+ * because the error CLASS is load-bearing here, not cosmetic: `FurnaceError`
+ * carries its own `userMessage` and exit code 9, so a helper raising
+ * `GeneralError` would silently change both.
+ *
+ * Deliberately NOT routed through this helper — each informs rather than
+ * refuses, and each says so at its own site: `furnace list`,
+ * `furnace status`, `furnace init`, and `verify`. `furnace validate`
+ * refusing is the intended line between inspecting and validating.
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { pathExists } from '../utils/fs.js';
+import { getProjectPaths } from './config-paths.js';
+import { furnaceConfigExists, loadFurnaceConfig } from './furnace-config.js';
+/**
+ * Asserts that a specific engine directory exists, raising a `FurnaceError`.
+ *
+ * The path-taking form, for core helpers that already hold `engineDir` and
+ * have no project root to derive it from.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Optional message tailoring
+ */
+export async function assertFurnaceEngineDirReady(engineDir, options = {}) {
+    if (!(await pathExists(engineDir))) {
+        throw new FurnaceError(`Engine directory not found. Run "fireforge download" first${options.engineMissingSuffix ?? '.'}`);
+    }
+}
+/**
+ * Asserts that the engine checkout exists, raising a `FurnaceError`.
+ *
+ * The engine rung on its own, for the Furnace commands that scaffold or
+ * mutate component sources without needing `furnace.json` to exist yet.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Optional message tailoring
+ * @returns Resolved project paths, so callers do not re-derive them
+ */
+export async function assertFurnaceEngineReady(projectRoot, options = {}) {
+    const paths = getProjectPaths(projectRoot);
+    await assertFurnaceEngineDirReady(paths.engine, options);
+    return { paths };
+}
+/**
+ * Asserts the full Furnace ladder — engine checkout, then `furnace.json` —
+ * and returns the loaded config so callers do not read it a second time.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Optional message tailoring
+ * @returns Resolved project paths and the loaded furnace config
+ */
+export async function assertFurnaceReady(projectRoot, options = {}) {
+    const { paths } = await assertFurnaceEngineReady(projectRoot, options);
+    // `loadFurnaceConfig` refuses on its own with a fuller message, but the
+    // probe stays: it produces the shorter, action-first refusal the command
+    // layer has always shown for "you have not set Furnace up yet", which is a
+    // different situation from "your furnace.json is unreadable".
+    if (!(await furnaceConfigExists(projectRoot))) {
+        throw new FurnaceError('No furnace.json found. Run "fireforge furnace create" or "fireforge furnace override" to get started.');
+    }
+    return { paths, config: await loadFurnaceConfig(projectRoot) };
+}