@hominis/fireforge 0.49.1 → 0.50.0

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

@@ -1,17 +1,18 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { loadConfig } from '../../core/config.js';
 import { applyAllComponents } from '../../core/furnace-apply.js';
-import { logApplyResult } from '../../core/furnace-apply-output.js';
+import { formatSkipBreakdown, logApplyResult } from '../../core/furnace-apply-output.js';
 import { getFurnacePaths } from '../../core/furnace-config.js';
 import { reportJsconfigPathsSync } from '../../core/furnace-jsconfig.js';
-import { runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
+import { runFurnaceMutation, waitLockMutationOptions } from '../../core/furnace-operation.js';
 import { assertFurnaceReady } from '../../core/furnace-precondition.js';
-import { getPersistableAppliedEntry, getStepFailureCount, persistSingleComponentState, shouldPersistSingleComponentState, } from '../../core/furnace-state-persist.js';
+import { getStepFailureCount } from '../../core/furnace-state-persist.js';
 import { hasBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftError, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { info, intro, note, notice, outro, spinner, warn } from '../../utils/logger.js';
-import { formatFragmentIncluderNotice, mergeApplyResults, refreshStaleFragmentIncluders, } from './deploy-fragment-includers.js';
+import { formatFragmentIncluderNotice } from './deploy-fragment-includers.js';
+import { deployNamedComponents } from './deploy-named.js';
 import { runDeployValidation } from './validation-output.js';
 /**
  * Builds the final deploy failure summary from apply and validation error counts.
@@ -39,51 +40,6 @@ function getFailedComponentNames(result) {
     }
     return failed;
 }
-/**
- * Applies a single named override or custom component in targeted deploy
- * mode.
- *
- * Delegates to {@link applyAllComponents} with a `componentName` filter so
- * targeted deploys run the exact same pipeline as deploy-all, including
- * workspace-deletion detection, engine orphan undeploy, and jar.mn /
- * customElements.js re-sync. Calling the per-component apply helpers
- * directly never prunes: renaming a helper file in the workspace then leaves
- * the old deployed file and its stale jar.mn line in the engine.
- *
- * `persistState: false` matters here: the batch persist path replaces
- * `appliedChecksums` wholesale with only this run's entries, which for a
- * named deploy would wipe every other component's state. Named deploy keeps
- * its per-component state merge ({@link persistSingleComponentState}) and
- * its atomicity gate ({@link shouldPersistSingleComponentState}) at the call
- * site. Rollback on failure happens inside `applyAllComponents`. The journal
- * returned on success is ignored (the deploy keeps its files).
- *
- * The caller then runs the fragment-includer follow-up
- * ({@link refreshStaleFragmentIncluders}) ONLY after this component's state
- * is persisted: each includer is applied and persisted as its own unit, so
- * a signal mid-loop restores at most the includer in flight and leaves every
- * earlier unit committed. Moving the persist after the includer loop would
- * silently break that atomicity.
- *
- * @param name - Component name to apply
- * @param config - Loaded Furnace configuration
- * @param isDryRun - Whether file writes should be skipped
- * @returns Apply result for the named component, or `stock` for stock-only
- *   entries
- */
-async function applyNamedComponent(name, config, isDryRun, projectRoot, operationContext) {
-    if (!(name in config.overrides) && !(name in config.custom)) {
-        if (config.stock.includes(name)) {
-            return 'stock';
-        }
-        throw new FurnaceError(`Component "${name}" not found in furnace.json.`, name);
-    }
-    return applyAllComponents(projectRoot, isDryRun, {
-        componentName: name,
-        persistState: false,
-        ...(operationContext ? { operationContext } : {}),
-    });
-}
 /**
  * Prints the deploy summary after apply and validation complete.
  * @param result - Aggregate apply result
@@ -109,7 +65,7 @@ function printDeploymentSummary(result, totalErrors, totalWarnings, componentCou
                 : ''), 'Dry Run Summary');
     }
     else {
-        note(`Applied ${appliedCount}, skipped ${skippedCount}\n` +
+        note(`Applied ${appliedCount}, skipped ${skippedCount}${formatSkipBreakdown(result.skipped)}\n` +
             `${applyErrors} apply error(s)` +
             (stepErrorCount > 0 ? `, ${stepErrorCount} registration step error(s)` : '') +
             `\n` +
@@ -132,14 +88,25 @@ function enforceScopedOverrideVersionDriftPreflight(scopedDrift, force) {
         throw new FurnaceError(formatOverrideBaseVersionDriftError(scopedDrift));
     }
 }
+/**
+ * Normalises the positional argument: a single name (programmatic callers)
+ * or the variadic list commander passes. An empty list means "deploy all".
+ */
+function normalizeDeployNames(names) {
+    if (names === undefined)
+        return [];
+    return typeof names === 'string' ? [names] : [...names];
+}
 /**
  * Runs the furnace deploy command: apply components then validate in one step.
  * @param projectRoot - Root directory of the project
- * @param name - Optional component name to deploy (deploys all if omitted)
+ * @param names - Component name(s) to deploy, all under one lock hold
+ *   (deploys all when omitted or empty)
  * @param options - Command options
  */
-export async function furnaceDeployCommand(projectRoot, name, options = {}) {
+export async function furnaceDeployCommand(projectRoot, names, options = {}) {
     const isDryRun = options.dryRun ?? false;
+    const requested = normalizeDeployNames(names);
     intro(isDryRun ? 'Furnace Deploy (dry run)' : 'Furnace Deploy');
     const { config } = await assertFurnaceReady(projectRoot);
     const furnacePaths = getFurnacePaths(projectRoot);
@@ -157,7 +124,9 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     const forgeConfig = await loadConfig(projectRoot);
     const driftEntries = findOverrideBaseVersionDrift(config, forgeConfig.firefox.version);
     const force = options.force ?? false;
-    const scopedDrift = name ? driftEntries.filter((entry) => entry.name === name) : driftEntries;
+    const scopedDrift = requested.length > 0
+        ? driftEntries.filter((entry) => requested.includes(entry.name))
+        : driftEntries;
     enforceScopedOverrideVersionDriftPreflight(scopedDrift, force);
     // --- Step 1: Apply ---
     const applySpinner = spinner(isDryRun ? 'Calculating planned actions...' : 'Applying components to engine...');
@@ -166,55 +135,37 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     // phase below is read-only and runs outside the lock so two concurrent
     // `furnace deploy` runs only contend on the actual mutation.
     const applyOutcome = await runFurnaceMutation(projectRoot, 'deploy-rollback', async (ctx) => {
-        if (name) {
-            const namedApplyResult = await applyNamedComponent(name, config, isDryRun, projectRoot, ctx);
-            if (namedApplyResult === 'stock') {
-                return { kind: 'stock' };
-            }
-            // Named deploy is atomic: state is persisted only when every apply
-            // step succeeded. Any rollback triggered by applyNamedComponent has
-            // already restored the engine to its pre-deploy state, so persisting
-            // partial checksums here would mis-report the next status/apply run
-            // against a workspace that was never actually deployed.
-            const primaryClean = shouldPersistSingleComponentState(namedApplyResult, isDryRun);
-            if (primaryClean) {
-                await persistSingleComponentState(projectRoot, getPersistableAppliedEntry('Deploy', name, namedApplyResult.applied[0]), furnacePaths);
-            }
-            // Other deployed includers of a fragment this component includes
-            // would otherwise keep a stale expansion. Only after a clean,
-            // persisted primary apply (dry-run always previews).
-            if (!primaryClean && !isDryRun) {
-                return { kind: 'result', result: namedApplyResult };
-            }
-            const includers = await refreshStaleFragmentIncluders({
+        if (requested.length > 0) {
+            return deployNamedComponents({
                 projectRoot,
-                name,
+                names: requested,
                 config,
                 furnacePaths,
                 isDryRun,
                 operationContext: ctx,
             });
-            return {
-                kind: 'result',
-                result: mergeApplyResults(namedApplyResult, includers.results),
-                includers,
-            };
         }
         const allResult = await applyAllComponents(projectRoot, isDryRun, {
             operationContext: ctx,
         });
-        return { kind: 'result', result: allResult };
+        return { kind: 'all', result: allResult };
     }, { dryRun: isDryRun, ...waitLockMutationOptions(options.waitLockSeconds) });
+    const warnStock = () => {
+        for (const stockName of applyOutcome.kind === 'all' ? [] : applyOutcome.stock) {
+            warn(`"${stockName}" is a stock component. Stock components are not applied locally.`);
+        }
+    };
     if (applyOutcome.kind === 'stock') {
         applySpinner.stop('Apply skipped');
-        warn(`"${name}" is a stock component. Stock components are not applied locally.`);
+        warnStock();
         outro(isDryRun ? 'Dry run complete (no files modified)' : 'Deploy complete');
         return;
     }
     const result = applyOutcome.result;
     applySpinner.stop(isDryRun ? 'Planned actions calculated' : 'Components applied');
+    warnStock();
     logApplyResult(result, isDryRun);
-    if (applyOutcome.includers) {
+    if (applyOutcome.kind === 'result') {
         for (const line of formatFragmentIncluderNotice(applyOutcome.includers, isDryRun)) {
             notice(line);
         }
@@ -235,20 +186,33 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     }
     const validateSpinner = spinner(isDryRun ? 'Validating (read-only)...' : 'Validating...');
     const failedComponents = getFailedComponentNames(result);
+    // A named deploy validates every named component that applied, then the
+    // includers it refreshed. The first clean name leads (the validation
+    // runner skips the whole named branch when its lead failed), and every
+    // failed name is counted as skipped.
+    const deployed = applyOutcome.kind === 'result' ? applyOutcome.deployed : [];
+    const failedNamed = deployed.filter((tag) => failedComponents.has(tag));
+    const lead = deployed.find((tag) => !failedComponents.has(tag)) ?? deployed[0];
     const validation = await runDeployValidation({
         validateSpinner,
-        name,
+        name: lead,
         config,
         furnacePaths,
         failedComponents,
         isDryRun,
         projectRoot,
         dryRunActions: result.actions,
-        alsoValidate: applyOutcome.includers?.refreshed ?? [],
+        alsoValidate: applyOutcome.kind === 'result'
+            ? [...deployed.filter((tag) => tag !== lead), ...applyOutcome.includers.refreshed]
+            : [],
     });
     if (validation.done)
         return;
-    const { totalErrors, totalWarnings, componentCount, skippedValidationCount } = validation;
+    const { totalErrors, totalWarnings, componentCount } = validation;
+    // The runner counts a failed lead itself; failed extras it drops silently.
+    const skippedValidationCount = lead !== undefined && failedComponents.has(lead)
+        ? failedNamed.length
+        : validation.skippedValidationCount + failedNamed.length;
     // --- Step 3: Summary ---
     printDeploymentSummary(result, totalErrors, totalWarnings, componentCount, skippedValidationCount, isDryRun);
 }

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

@@ -4,6 +4,8 @@ import { join } from 'node:path';
 import { getProjectPaths, loadState } from '../../core/config.js';
 import { diffLines, renderHunks } from '../../core/diff-hunks.js';
 import { getOverrideEngineTargetPath } from '../../core/furnace-apply-helpers.js';
+import { normalizeForChecksum } from '../../core/furnace-checksum-utils.js';
+import { composeComponentSource } from '../../core/furnace-composed-source.js';
 import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
 import { isComponentSourceFile, resolveFtlDir } from '../../core/furnace-constants.js';
 import { getFileContentAtRef } from '../../core/git-file-ops.js';
@@ -108,6 +110,14 @@ async function diffOverride(name, projectRoot, config) {
  * copy. Shows what would change (or has changed) on the next
  * `furnace apply`.
  *
+ * The workspace side is the Furnace-composed source: a stylesheet with
+ * `@fireforge-include` directives is compared in its fragment-expanded
+ * form, exactly as apply deploys it. Comparing the raw source instead
+ * reported every freshly deployed fragment includer as a large difference
+ * (the inlined fragment bodies and end markers), so the diff could not show
+ * whether a deploy would change anything. Line endings and a BOM are
+ * ignored, as apply's own drift check ignores them.
+ *
  * `.ftl` files deploy to `engine/<ftlDir>/<name>.ftl` via
  * `applyCustomFtlFile`, not to `customConfig.targetPath`, so the
  * deployment-target lookup has to branch on extension. Without the branch, a
@@ -136,7 +146,19 @@ async function diffCustom(name, projectRoot, config) {
         if (!isComponentSourceFile(entry.name))
             continue;
         const workspacePath = join(customDir, entry.name);
-        const workspaceContent = await readText(workspacePath);
+        const rawWorkspace = await readText(workspacePath);
+        let workspaceContent = rawWorkspace;
+        let composedNote = '';
+        try {
+            workspaceContent = await composeComponentSource(rawWorkspace, entry.name, furnacePaths.sharedDir);
+            if (workspaceContent !== rawWorkspace)
+                composedNote = ' (composed: fragments expanded)';
+        }
+        catch (error) {
+            // A missing fragment: no composed form exists, so show the raw
+            // source and say why; `furnace validate` reports the fragment itself.
+            composedNote = ` (raw: ${toError(error).message})`;
+        }
         // `.ftl` files deploy to the locale tree, not the component's
         // targetPath. Mirror `applyCustomFtlFile`'s target computation so the
         // diff header and the existence probe name the same path apply
@@ -154,13 +176,14 @@ async function diffCustom(name, projectRoot, config) {
             hasDifferences = true;
             continue;
         }
-        const deployedContent = await readText(deployedPath);
+        const deployedContent = normalizeForChecksum(await readText(deployedPath));
+        workspaceContent = normalizeForChecksum(workspaceContent);
         if (workspaceContent === deployedContent) {
             continue;
         }
         hasDifferences = true;
         info(`--- ${deployedDisplayPath}`);
-        info(`+++ components/custom/${name}/${entry.name}`);
+        info(`+++ components/custom/${name}/${entry.name}${composedNote}`);
         for (const line of formatUnifiedDiff(deployedContent, workspaceContent)) {
             info(line);
         }

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Command, Option } from 'commander';
 import { withEngineSessionLock } from '../../core/engine-session-lock.js';
-import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
 import { furnaceApplyCommand } from './apply.js';
 import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceChromeDocRemoveCommand } from './chrome-doc-remove.js';
@@ -19,6 +19,18 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
+import { parseMaxWarnings } from './validate-report.js';
+/**
+ * Splits the raw `--wait-lock` value off a furnace leaf's parsed options and
+ * resolves it into `waitLockSeconds` (flag, else `FIREFORGE_WAIT_LOCK`, else
+ * undefined) for the furnace lock `runFurnaceMutation` takes. Used by the
+ * leaves that take only Furnace's lock, where the flag used to be accepted
+ * and ignored.
+ */
+function withFurnaceLockBudget(options) {
+    const { waitLock, ...rest } = options;
+    return pickDefined({ ...rest, waitLockSeconds: resolveWaitLockSeconds(waitLock) });
+}
 async function runEngineLockedFurnaceCommand(context, command, operation, waitLockSeconds) {
     const projectRoot = context.getProjectRoot();
     await withEngineSessionLock(projectRoot, command, () => operation(projectRoot), {
@@ -51,16 +63,24 @@ function registerFurnaceApplyCommand(furnace, context) {
 function registerFurnaceDeployCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
     const deploy = furnace
-        .command('deploy [name]')
-        .description('Apply components and validate in one step')
+        .command('deploy [names...]')
+        .description('Apply components and validate in one step (name several to deploy them under one lock hold)')
         .option('--dry-run', 'Show what would be changed without writing (reads may overlap concurrent mutations)')
         .option('--force', 'Proceed despite baseVersion drift (stale overrides)')
-        .option('--skip-validate', 'Skip the validation step (apply only)');
-    addWaitLockOption(deploy).action(withErrorHandling(async (name, options) => {
+        .option('--skip-validate', 'Skip the validation step (apply only)')
+        .addHelpText('after', [
+        '',
+        'Deploy registers every .mjs and .css file in a custom component directory in',
+        'toolkit/content/jar.mn, including extra modules beside the main one (e.g.',
+        'components/custom/<tag>/<tag>-rows.mjs). Add the file to the directory and run',
+        '`fireforge furnace deploy <tag>` instead of writing the jar.mn line by hand; a line',
+        'that already exists anywhere in jar.mn is kept and never duplicated.',
+    ].join('\n'));
+    addWaitLockOption(deploy).action(withErrorHandling(async (names, options) => {
         const { waitLock, ...rest } = options ?? {};
         const waitLockSeconds = resolveWaitLockSeconds(waitLock);
         const parsed = pickDefined({ ...rest, waitLockSeconds });
-        const run = (projectRoot) => furnaceDeployCommand(projectRoot, name, parsed);
+        const run = (projectRoot) => furnaceDeployCommand(projectRoot, names, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
@@ -103,15 +123,15 @@ function registerFurnaceInfoCommands(furnace, context) {
     }));
     registerFurnaceApplyCommand(furnace, context);
     registerFurnaceDeployCommand(furnace, context);
-    furnace
+    const scan = furnace
         .command('scan')
         .description('Scan engine for available components. Report-only by default: persist the discovered ' +
         'inventory into the stock section of furnace.json with --track (or the interactive ' +
         'prompt); deploy/validate consume the inventory from there.')
         .option('--deep', 'Search additional Firefox directories beyond the default widgets path')
-        .option('--track', 'Persist every discovered untracked component into the stock section of furnace.json (non-interactive)')
-        .action(withErrorHandling(async (options) => {
-        await furnaceScanCommand(getProjectRoot(), pickDefined(options));
+        .option('--track', 'Persist every discovered untracked component into the stock section of furnace.json (non-interactive)');
+    addWaitLockOption(scan).action(withErrorHandling(async (options) => {
+        await furnaceScanCommand(getProjectRoot(), withFurnaceLockBudget(options));
     }));
     furnace
         .command('init')
@@ -122,7 +142,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         .action(withErrorHandling(async (options) => {
         await furnaceInitCommand(getProjectRoot(), options);
     }));
-    furnace
+    const create = furnace
         .command('create [name]')
         .description('Create a new custom component')
         .option('-d, --description <desc>', 'Component description')
@@ -140,9 +160,9 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
         .option('--shared-ftl <path>', 'Participate in an existing feature-scoped .ftl at this path (e.g. "browser/mybrowser-dock.ftl"); skips the per-component .ftl scaffold (implies --localized)')
         .option('--dry-run', 'Show the planned file set and furnace.json changes without writing')
-        .option('--allow-prefix-mismatch', 'Create the component even when its name does not start with the configured `componentPrefix` in furnace.json. Without this flag the command refuses to write anything on a prefix mismatch.')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceCreateCommand(getProjectRoot(), name, options);
+        .option('--allow-prefix-mismatch', 'Create the component even when its name does not start with the configured `componentPrefix` in furnace.json. Without this flag the command refuses to write anything on a prefix mismatch.');
+    addWaitLockOption(create).action(withErrorHandling(async (name, options) => {
+        await furnaceCreateCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
     registerChromeDocCommands(furnace, context);
 }
@@ -151,23 +171,23 @@ function registerChromeDocCommands(furnace, context) {
     const chromeDoc = furnace
         .command('chrome-doc')
         .description('Scaffold top-level chrome documents (xhtml + js + css + ftl + jar.mn)');
-    chromeDoc
+    const chromeDocCreate = chromeDoc
         .command('create <name>')
         .description('Scaffold a new top-level chrome document')
         .option('--no-titlebar', 'Frameless overlay-style document (omits titlebar-buttonbox)')
         .option('--browser-window', 'Emit the browser.xhtml-like main-window skeleton (<html id="main-window"> with windowtype/chromehidden/persist root attributes platform C++ reads before scripts run) for the document configured as the fork\'s main browser window; implies the titlebar markup')
         .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));
+        .option('--dry-run', 'Show the chrome-doc scaffold plan without writing');
+    addWaitLockOption(chromeDocCreate).action(withErrorHandling(async (name, options) => {
+        await furnaceChromeDocCreateCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
-    chromeDoc
+    const chromeDocRemove = 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));
+        .option('--dry-run', 'Show the chrome-doc removal plan without writing');
+    addWaitLockOption(chromeDocRemove).action(withErrorHandling(async (name, options) => {
+        await furnaceChromeDocRemoveCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
 }
 /**
@@ -178,12 +198,13 @@ function registerChromeDocCommands(furnace, context) {
  */
 function registerFurnaceModifyCommands(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const override = furnace
         .command('override [names...]')
         .description('Fork one or more existing components for modification')
         .addOption(new Option('-t, --type <type>', 'Override type').choices(['css-only', 'full']))
-        .option('-d, --description <desc>', 'Description')
-        .action(withErrorHandling(async (names, options) => {
+        .option('-d, --description <desc>', 'Description');
+    addWaitLockOption(override).action(withErrorHandling(async (names, rawOptions) => {
+        const options = withFurnaceLockBudget(rawOptions);
         if (names.length <= 1) {
             await furnaceOverrideCommand(getProjectRoot(), names[0], options);
         }
@@ -198,26 +219,29 @@ function registerFurnaceModifyCommands(furnace, context) {
         .action(withErrorHandling(async (options) => {
         await furnaceListCommand(getProjectRoot(), options);
     }));
-    furnace
+    const remove = furnace
         .command('remove <name>')
         .description('Remove a component from the workspace')
-        .option('-y, --yes', 'Skip confirmation')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceRemoveCommand(getProjectRoot(), name, options);
+        .option('-y, --yes', 'Skip confirmation');
+    addWaitLockOption(remove).action(withErrorHandling(async (name, options) => {
+        await furnaceRemoveCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
-    furnace
+    const preview = furnace
         .command('preview')
         .description('Start component preview (Storybook)')
-        .option('--install', 'Force reinstall Storybook dependencies')
-        .action(withErrorHandling(async (options) => {
-        await furnacePreviewCommand(getProjectRoot(), options);
+        .option('--install', 'Force reinstall Storybook dependencies');
+    addWaitLockOption(preview).action(withErrorHandling(async (options) => {
+        await furnacePreviewCommand(getProjectRoot(), withFurnaceLockBudget(options));
     }));
     furnace
         .command('validate [name]')
         .description('Run accessibility and compatibility checks')
         .option('--fix', 'Auto-fix registration issues (missing jar.mn entries, customElements.js)')
+        .option('--json', 'Write the result as one JSON document (findings, excepted findings, stale exceptions, verdict) to stdout')
+        .option('--max-warnings <n>', 'Fail when more than <n> warnings remain after furnace.json validationExceptions (0 for a warning-clean gate)')
         .action(withErrorHandling(async (name, options) => {
-        await furnaceValidateCommand(getProjectRoot(), name, pickDefined(options ?? {}));
+        const { maxWarnings, ...rest } = options ?? {};
+        await furnaceValidateCommand(getProjectRoot(), name, pickDefined({ ...rest, maxWarnings: parseMaxWarnings(maxWarnings) }));
     }));
     furnace
         .command('diff [name]')
@@ -225,21 +249,22 @@ function registerFurnaceModifyCommands(furnace, context) {
         .action(withErrorHandling(async (name) => {
         await furnaceDiffCommand(getProjectRoot(), name);
     }));
-    furnace
+    const refresh = furnace
         .command('refresh [name]')
         .description('Merge upstream Firefox changes into overrides (three-way merge)')
         .option('--dry-run', 'Show what would change without modifying files')
         .option('-a, --all', 'Refresh all overrides in a single batch')
         .addOption(new Option('-s, --strategy <strategy>', 'Auto-resolve conflicts (ours = keep local, theirs = accept upstream)').choices(['ours', 'theirs']))
-        .option('--reset-base', 'Reset baseline to current engine HEAD (skips three-way merge, recovers from missing baseCommit)')
-        .action(withErrorHandling(async (name, options) => {
-        await furnaceRefreshCommand(getProjectRoot(), name, pickDefined(options));
+        .option('--reset-base', 'Reset baseline to current engine HEAD (skips three-way merge, recovers from missing baseCommit)');
+    addWaitLockOption(refresh).action(withErrorHandling(async (name, options) => {
+        await furnaceRefreshCommand(getProjectRoot(), name, withFurnaceLockBudget(options));
     }));
-    furnace
+    const rename = furnace
         .command('rename <old-name> <new-name>')
         .description('Rename a component (updates files, config, and registrations)')
-        .action(withErrorHandling(async (oldName, newName) => {
-        await furnaceRenameCommand(getProjectRoot(), oldName, newName);
+        .option('--dry-run', 'Show the planned file moves, furnace.json change and engine registration edits without writing');
+    addWaitLockOption(rename).action(withErrorHandling(async (oldName, newName, options) => {
+        await furnaceRenameCommand(getProjectRoot(), oldName, newName, withFurnaceLockBudget(options));
     }));
     registerFurnaceSyncCommand(furnace, context);
 }

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

@@ -2,7 +2,7 @@
 import { stat } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, posix } from 'node:path';
 import { text } from '@clack/prompts';
-import { getProjectPaths, loadConfig, mutateConfig, writeConfig } from '../../core/config.js';
+import { getProjectPaths, loadConfig, loadRawConfigDocument, mutateConfig, validateConfig, withConfigFileLock, writeConfigDocument, } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { DEFAULT_LICENSE } from '../../core/license-headers.js';
@@ -239,14 +239,21 @@ async function scaffoldTokensCss(projectRoot) {
     // `fireforge lint` after a `token add` fails on raw-color-value issues for
     // tokens the operator just created. The add is idempotent, so re-running
     // `furnace init --force` does not duplicate the entry.
+    // The edit seeds from the raw document under the config lock, like
+    // `fireforge config`: a validated round-trip would drop keys written with
+    // `config --force`, and an unlocked one could lose a concurrent write.
     try {
         const existingAllowlist = forgeConfig.patchLint?.rawColorAllowlist ?? [];
         if (!existingAllowlist.includes(tokensCssPath)) {
-            const updatedConfig = mutateConfig(forgeConfig, 'patchLint.rawColorAllowlist', [
-                ...existingAllowlist,
-                tokensCssPath,
-            ]);
-            await writeConfig(projectRoot, updatedConfig);
+            await withConfigFileLock(projectRoot, async () => {
+                const raw = await loadRawConfigDocument(projectRoot);
+                const current = validateConfig(raw).patchLint?.rawColorAllowlist ?? [];
+                if (current.includes(tokensCssPath))
+                    return;
+                const updated = mutateConfig(raw, 'patchLint.rawColorAllowlist', [...current, tokensCssPath], true);
+                validateConfig(updated);
+                await writeConfigDocument(projectRoot, updated);
+            });
             info(`Added ${tokensCssPath} to patchLint.rawColorAllowlist`);
         }
     }

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

@@ -6,7 +6,7 @@ import { getProjectPaths, loadConfig, loadState } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { getFurnacePaths, writeFurnaceConfig } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -160,7 +160,7 @@ async function performOverrideMutations(args) {
                 subject: `component "${args.componentName}"`,
             });
         }
-    });
+    }, waitLockMutationOptions(args.waitLockSeconds));
 }
 /**
  * Throws if `componentName` is already classified as something `override`
@@ -322,6 +322,7 @@ export async function furnaceOverrideCommand(projectRoot, name, options = {}) {
         ftlDir,
         firefoxVersion: forgeConfig.firefox.version,
         ...(state.baseCommit ? { baseCommit: state.baseCommit } : {}),
+        waitLockSeconds: options.waitLockSeconds,
     });
     // --- Success ---
     note(`Files copied to components/overrides/${componentName}/:\n` +
@@ -421,6 +422,7 @@ export async function furnaceBatchOverrideCommand(projectRoot, names, options =
                 ftlDir,
                 firefoxVersion: forgeConfig.firefox.version,
                 ...(state.baseCommit ? { baseCommit: state.baseCommit } : {}),
+                waitLockSeconds: options.waitLockSeconds,
             });
             succeeded.push(componentName);
         }

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

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { applyAllComponents } from '../../core/furnace-apply.js';
 import { updateFurnaceState } from '../../core/furnace-config.js';
-import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { restoreRollbackJournal } from '../../core/furnace-rollback.js';
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
@@ -224,7 +224,7 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
     // entrypoint's global signal handlers consulting the lifecycle registry.
     // The body's own try/catch + teardown path handles the normal exit case
     // (mach storybook returns or throws).
-    await runFurnaceMutation(projectRoot, 'preview-teardown', async (ctx) => {
+    const mutate = async (ctx) => {
         // Register the stories cleanup as an extra teardown hook so the signal
         // handler can wipe the staged stories directory in addition to the
         // journal restore.
@@ -336,7 +336,8 @@ export async function furnacePreviewCommand(projectRoot, options = {}) {
             // holds and downstream formatters always see a message/stack pair.
             throw toError(primaryError);
         }
-    });
+    };
+    await runFurnaceMutation(projectRoot, 'preview-teardown', mutate, waitLockMutationOptions(options.waitLockSeconds));
     if (previewResult &&
         previewResult.exitCode !== 0 &&
         previewResult.exitCode !== 130 &&

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

@@ -6,7 +6,7 @@ import { getOverrideEngineTargetPath } from '../../core/furnace-apply-helpers.js
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
 import { isComponentSourceFile } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { refreshOverrideFile } from '../../core/furnace-refresh.js';
 import { createRollbackJournal, restoreRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -165,7 +165,7 @@ async function refreshSingleOverride(projectRoot, name, options = {}) {
             }
             throw error;
         }
-    }, { dryRun });
+    }, { dryRun, ...waitLockMutationOptions(options.waitLockSeconds) });
     return { results, currentVersion };
 }
 /**