@hominis/fireforge 0.49.2 → 0.50.0

package/dist/src/commands/export-placement-gate.d.ts

@@ -4,7 +4,7 @@
  * budgets. `gatePlacementPlan` owns every policy/confirmation decision a
  * placement export makes before the locked commit in `export.ts` runs.
  */
-import type { ExportOptions, PatchMetadata } from '../types/commands/index.js';
+import type { ExportOptions } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import type { SpinnerHandle } from '../utils/logger.js';
 import { type PlacementPlan } from './export-flow.js';
@@ -14,7 +14,11 @@ import { type PlacementPlan } from './export-flow.js';
  * shares this shape. With exactOptionalPropertyTypes the keys must be
  * omitted entirely (not set to undefined) when the flags are absent.
  */
-export declare function patchMetadataExtras(options: ExportOptions): Partial<Pick<PatchMetadata, 'tier' | 'lintIgnore'>>;
+export declare function patchMetadataExtras(options: ExportOptions): {
+    tier?: 'branding';
+    /** CLI flags only ever carry bare check IDs. */
+    lintIgnore?: string[];
+};
 /**
  * Resolves and gates the placement plan when any placement flag
  * (`--order`/`--before`/`--after`) was given: rejects the `--supersede`

package/dist/src/commands/export-shared.d.ts

@@ -1,3 +1,4 @@
+import type { LintIgnoreChecks } from '../core/patch-lint-ignore.js';
 import type { PatchesManifest, PatchLintIssue } from '../types/commands/index.js';
 import type { ExportOptions, PatchCategory } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
@@ -22,7 +23,7 @@ export interface RunPatchLintOptions {
      * `large-patch-lines` on a cohesive branding bundle that genuinely cannot
      * be split.
      */
-    ignoreChecks?: ReadonlySet<string> | undefined;
+    ignoreChecks?: LintIgnoreChecks | undefined;
     /**
      * Optional explicit tier override (threaded from `PatchMetadata.tier`).
      * Forces the branding-tier thresholds when set, independent of the

package/dist/src/commands/export-staged-registration.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Lets `export --order` land a new system module whose moz.build line is
+ * still unexported working-tree drift in the patch that registers it.
+ *
+ * The two refusals used to deadlock: the module's export failed
+ * `unregistered-system-module` because no patch body carried its moz.build
+ * line yet, and the registering patch could not be re-exported first
+ * because its line named a file no patch created. The way through is
+ * declared intent plus evidence: when the registering patch carries a
+ * staged registration for the module and the working tree's moz.build has
+ * exactly that line, the export is accepted and the operator is told to
+ * re-export the registering patch next. Without the declaration the
+ * refusal names the steps, with the exact `patch staged-dependency`
+ * command, instead of stopping at "register it".
+ *
+ * Consumed by export-flow.ts.
+ */
+import type { PatchQueueContext } from '../core/patch-lint.js';
+import type { PatchLintIssue } from '../types/commands/index.js';
+/** Result of {@link acceptTreeRegisteredModules}. */
+export interface TreeRegistrationOutcome {
+    /** The projected errors left after accepted modules are removed. */
+    remaining: PatchLintIssue[];
+    /** One note per accepted module, naming the re-export to run next. */
+    accepted: string[];
+    /** Detail lines for modules whose registration is in the tree but undeclared. */
+    advice: string[];
+}
+/**
+ * Removes `unregistered-system-module` findings for modules the pending
+ * export creates when a queue patch declares their registration as a
+ * staged dependency and the working tree's moz.build carries that line.
+ * For a module whose line is in the tree but undeclared, returns the steps
+ * that make it acceptable.
+ *
+ * @param args - The engine directory (the working tree), the current queue,
+ *   the filename the pending export would take, the files it creates, and
+ *   the placement projection's error findings
+ */
+export declare function acceptTreeRegisteredModules(args: {
+    engineDir: string;
+    baseCtx: PatchQueueContext;
+    newFilename: string;
+    pendingNewFiles: ReadonlySet<string>;
+    projectedIssues: readonly PatchLintIssue[];
+}): Promise<TreeRegistrationOutcome>;

package/dist/src/commands/export-staged-registration.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Lets `export --order` land a new system module whose moz.build line is
+ * still unexported working-tree drift in the patch that registers it.
+ *
+ * The two refusals used to deadlock: the module's export failed
+ * `unregistered-system-module` because no patch body carried its moz.build
+ * line yet, and the registering patch could not be re-exported first
+ * because its line named a file no patch created. The way through is
+ * declared intent plus evidence: when the registering patch carries a
+ * staged registration for the module and the working tree's moz.build has
+ * exactly that line, the export is accepted and the operator is told to
+ * re-export the registering patch next. Without the declaration the
+ * refusal names the steps, with the exact `patch staged-dependency`
+ * command, instead of stopping at "register it".
+ *
+ * Consumed by export-flow.ts.
+ */
+import { basename, dirname, join } from 'node:path';
+import { STAGED_DEPENDENCY_REASON_PLACEHOLDER } from '../core/patch-lint-staged-registration.js';
+import { pathExists, readText } from '../utils/fs.js';
+async function readLines(path) {
+    if (!(await pathExists(path)))
+        return undefined;
+    return (await readText(path)).split('\n').map((line) => line.trim());
+}
+/** The nearest moz.build at or above `modulePath` whose lines name `leaf` quoted. */
+async function findTreeRegistration(engineDir, modulePath) {
+    const leaf = basename(modulePath);
+    let dir = dirname(modulePath);
+    for (;;) {
+        const file = dir === '.' ? 'moz.build' : `${dir}/moz.build`;
+        const line = (await readLines(join(engineDir, file)))?.find((candidate) => candidate.includes(`"${leaf}"`) || candidate.includes(`'${leaf}'`));
+        if (line !== undefined)
+            return { file, line };
+        if (dir === '.' || dir === '')
+            return undefined;
+        const parent = dirname(dir);
+        dir = parent === dir ? '.' : parent;
+    }
+}
+/**
+ * Removes `unregistered-system-module` findings for modules the pending
+ * export creates when a queue patch declares their registration as a
+ * staged dependency and the working tree's moz.build carries that line.
+ * For a module whose line is in the tree but undeclared, returns the steps
+ * that make it acceptable.
+ *
+ * @param args - The engine directory (the working tree), the current queue,
+ *   the filename the pending export would take, the files it creates, and
+ *   the placement projection's error findings
+ */
+export async function acceptTreeRegisteredModules(args) {
+    const outcome = { remaining: [], accepted: [], advice: [] };
+    for (const issue of args.projectedIssues) {
+        if (issue.check !== 'unregistered-system-module' || !args.pendingNewFiles.has(issue.file)) {
+            outcome.remaining.push(issue);
+            continue;
+        }
+        const declared = args.baseCtx.entries.flatMap((entry) => (entry.metadata?.stagedDependencies?.registrations ?? [])
+            .filter((registration) => registration.creates === issue.file &&
+            (registration.owner === undefined || registration.owner === args.newFilename))
+            .map((registration) => ({ holder: entry.filename, registration })));
+        let accepted = false;
+        for (const { holder, registration } of declared) {
+            const lines = await readLines(join(args.engineDir, registration.file));
+            if (lines?.includes(registration.line.trim()) !== true)
+                continue;
+            outcome.accepted.push(`${issue.file} is registered by the working tree's ${registration.file} ` +
+                `("${registration.line.trim()}"), which ${holder} declares as a staged registration ` +
+                `but has not exported yet. Re-export ${holder} right after this export to land the ` +
+                `line: fireforge re-export ${holder}`);
+            accepted = true;
+            break;
+        }
+        if (accepted)
+            continue;
+        outcome.remaining.push(issue);
+        const tree = await findTreeRegistration(args.engineDir, issue.file);
+        if (tree === undefined)
+            continue;
+        const owner = args.baseCtx.entries.find((entry) => entry.metadata?.filesAffected.includes(tree.file))?.filename;
+        if (owner === undefined)
+            continue;
+        outcome.advice.push('', `${issue.file} is registered in the working tree's ${tree.file}, but ${owner} has not ` +
+            'exported that line. Land both without untangling the tree:', `  1. fireforge patch staged-dependency ${owner} --add --kind registration --file ${tree.file} ` +
+            `--line "${tree.line.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}" --creates ${issue.file} ` +
+            `--owner ${args.newFilename} ${STAGED_DEPENDENCY_REASON_PLACEHOLDER}`, '  2. re-run this export (a declared registration present in the working tree is accepted)', `  3. fireforge re-export ${owner}`);
+    }
+    return outcome;
+}

package/dist/src/commands/forward-import-remedy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The remedy printed under a forward-import refusal from `re-export`
+ * (plain refresh and `--scan` adoption alike): the earliest order the files
+ * can take as their own later patch, and the exact `patch staged-dependency
+ * --add` commands that declare the edges instead.
+ *
+ * The refusal used to end with "export them with --order <n> or run
+ * patch staged-dependency --add", which left the operator to work out both
+ * the number and every flag of the declaration from the finding text.
+ */
+import type { PatchesManifest, PatchLintIssue } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/** Inputs to {@link formatForwardImportRemedy}. */
+export interface ForwardImportRemedyInput {
+    /** What to do after the fix, e.g. "re-running the scan". */
+    reRunHint: string;
+    /** The refusal's findings; only `forward-import` and `forward-registration` ones are read. */
+    issues: readonly PatchLintIssue[];
+    /** Current manifest (null when unavailable: the order is then not named). */
+    manifest: PatchesManifest | null;
+    /** Project config; only `patchPolicy` is read. */
+    config?: Pick<FireForgeConfig, 'patchPolicy'>;
+    /** Category the files would be exported under (the refused patch's). */
+    category?: string;
+}
+/**
+ * Renders the remedy lines. Falls back to the generic sentence when the
+ * findings carry no structured declarations.
+ *
+ * @param input - See {@link ForwardImportRemedyInput}
+ */
+export declare function formatForwardImportRemedy(input: ForwardImportRemedyInput): string;

package/dist/src/commands/forward-import-remedy.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The remedy printed under a forward-import refusal from `re-export`
+ * (plain refresh and `--scan` adoption alike): the earliest order the files
+ * can take as their own later patch, and the exact `patch staged-dependency
+ * --add` commands that declare the edges instead.
+ *
+ * The refusal used to end with "export them with --order <n> or run
+ * patch staged-dependency --add", which left the operator to work out both
+ * the number and every flag of the declaration from the finding text.
+ */
+import { STAGED_DEPENDENCY_REASON_PLACEHOLDER } from '../core/patch-lint-staged-registration.js';
+import { earliestLegalOrderAfter } from '../core/patch-order-legal.js';
+import { formatPatchOrder } from '../core/patch-parse.js';
+function quoteArg(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function declarationCommand(declaration) {
+    const anchor = declaration.kind === 'import'
+        ? `--specifier ${quoteArg(declaration.specifier ?? '')}`
+        : `--kind registration --line ${quoteArg(declaration.line ?? '')}`;
+    return (`fireforge patch staged-dependency ${declaration.patch} --add --file ${declaration.file} ` +
+        `${anchor} --creates ${declaration.creates} --owner ${declaration.owner} ` +
+        STAGED_DEPENDENCY_REASON_PLACEHOLDER);
+}
+/**
+ * Renders the remedy lines. Falls back to the generic sentence when the
+ * findings carry no structured declarations.
+ *
+ * @param input - See {@link ForwardImportRemedyInput}
+ */
+export function formatForwardImportRemedy(input) {
+    const declarations = input.issues
+        .filter((issue) => issue.check === 'forward-import' || issue.check === 'forward-registration')
+        .flatMap((issue) => issue.stagedDeclarations ?? []);
+    const ownerOrders = declarations
+        .map((declaration) => input.manifest?.patches.find((patch) => patch.filename === declaration.owner)?.order)
+        .filter((order) => order !== undefined);
+    const latestOwner = ownerOrders.length > 0 ? Math.max(...ownerOrders) : undefined;
+    const legalOrder = latestOwner !== undefined && input.manifest !== null && input.category !== undefined
+        ? earliestLegalOrderAfter(input.config ?? {}, input.manifest, input.category, latestOwner)
+        : null;
+    const orderText = legalOrder !== null
+        ? `"fireforge export <files> --order ${formatPatchOrder(legalOrder)}"; ` +
+            `${formatPatchOrder(legalOrder)} is the earliest legal order after the latest creator ` +
+            `(${formatPatchOrder(latestOwner ?? legalOrder)})`
+        : '"fireforge export --order <n>"';
+    const lines = [
+        `Export those files as their own later patch (${orderText}; or ` +
+            '"fireforge patch split --order <n>"), or declare the intentional dependency with ' +
+            `"fireforge patch staged-dependency --add" before ${input.reRunHint}` +
+            (declarations.length > 0 ? ':' : '.'),
+    ];
+    const seen = new Set();
+    for (const declaration of declarations) {
+        const command = declarationCommand(declaration);
+        if (seen.has(command))
+            continue;
+        seen.add(command);
+        lines.push(`  ${command}`);
+    }
+    return lines.join('\n');
+}

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

@@ -2,7 +2,7 @@
 import { watch as fsWatch } from 'node:fs';
 import { loadConfig } from '../../core/config.js';
 import { applyAllComponents, computeComponentChecksums } 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 { isComponentSourceFile } from '../../core/furnace-constants.js';
 import { runFurnaceMutation, waitLockMutationOptions } from '../../core/furnace-operation.js';
@@ -108,7 +108,7 @@ async function runWatchLoop(projectRoot) {
             }
             const applied = result.applied.length;
             const skipped = result.skipped.length;
-            info(`Re-applied: ${applied} applied, ${skipped} skipped`);
+            info(`Re-applied: ${applied} applied, ${skipped} skipped${formatSkipBreakdown(result.skipped)}`);
             retryNeeded = false;
             lastChecksums = await snapshotWatchedChecksums(watchDirs);
         }
@@ -318,7 +318,7 @@ export async function furnaceApplyCommand(projectRoot, name, options = {}) {
         outro(`Dry run complete — would apply ${appliedCount}, skip ${skippedCount}`);
     }
     else {
-        outro(`Applied ${appliedCount}, skipped ${skippedCount}`);
+        outro(`Applied ${appliedCount}, skipped ${skippedCount}${formatSkipBreakdown(result.skipped)}`);
     }
     // Watch mode: re-apply on file changes in component directories
     if (options.watch && !dryRun) {

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

@@ -2,8 +2,9 @@
  * `fireforge furnace chrome-doc remove <name>` removes the files and
  * registrations created by `furnace chrome-doc create`.
  */
+import type { FurnaceLockWaitable } from '../../types/commands/index.js';
 /** Options for `furnace chrome-doc remove`. */
-export interface FurnaceChromeDocRemoveOptions {
+export interface FurnaceChromeDocRemoveOptions extends FurnaceLockWaitable {
     /** Skip confirmation. Required for real non-interactive removal. */
     yes?: boolean;
     /** Print the removal plan without writing files. */

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

@@ -8,7 +8,7 @@ import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { loadConfig } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.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 { createRollbackJournal, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { FurnaceError } from '../../errors/furnace.js';
@@ -138,7 +138,7 @@ export async function furnaceChromeDocRemoveCommand(projectRoot, name, options =
         plan,
         binaryName: forgeConfig.binaryName,
         operationContext: ctx,
-    }));
+    }), waitLockMutationOptions(options.waitLockSeconds));
     info(`Removed ${result.removedFiles} source file${result.removedFiles === 1 ? '' : 's'} and ` +
         `${result.removedJarEntries} jar registration${result.removedJarEntries === 1 ? '' : 's'} for "${name}".`);
     if (result.removedTestDir) {

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

@@ -15,8 +15,9 @@
  * mid-scaffold restores every touched file. A successful run leaves the tree
  * ready for `fireforge build`.
  */
+import type { FurnaceLockWaitable } from '../../types/commands/index.js';
 /** Options for `furnace chrome-doc create`. */
-export interface FurnaceChromeDocCreateOptions {
+export interface FurnaceChromeDocCreateOptions extends FurnaceLockWaitable {
     /**
      * Emit the titlebar-buttonbox markup and leave platform window controls
      * visible. Defaults to `true` because the common case is a full chrome

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

@@ -19,7 +19,7 @@
 import { join } from 'node:path';
 import { loadConfig } from '../../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.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 { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
@@ -343,7 +343,7 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
         browserWindow,
         binaryName: forgeConfig.binaryName,
         operationContext: ctx,
-    }));
+    }), waitLockMutationOptions(options.waitLockSeconds));
     const nextSteps = [
         `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
         `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,

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

@@ -5,7 +5,7 @@ import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { getFurnacePaths, writeFurnaceConfig } from '../../core/furnace-config.js';
 import { resolveFtlChromeSubPath, tagNameToClassName, WIDGETS_DIR, } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, describeTagNameProblem, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { isComponentInEngine, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
@@ -394,7 +394,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         testStyle,
         testDir,
         operationContext: ctx,
-    }));
+    }), waitLockMutationOptions(options.waitLockSeconds));
     note(formatSuccessNote({
         componentName,
         files,

package/dist/src/commands/furnace/deploy-named.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Targeted `furnace deploy <name>...`: one or more named components applied
+ * under ONE furnace lock hold.
+ *
+ * Deploying a set of widgets one invocation at a time put every call at the
+ * back of the engine-lock queue, so a forty-widget deploy waited forty
+ * times. Naming them together waits once. Each named component is still its
+ * own atomic unit (applied, then its state persisted, before the next one
+ * starts), exactly as a single-name deploy, so a failure or signal midway
+ * leaves every earlier component committed and consistent.
+ */
+import { type ApplyAllComponentsResult } from '../../core/furnace-apply.js';
+import type { FurnacePaths } from '../../core/furnace-config.js';
+import type { FurnaceOperationContext } from '../../core/furnace-operation.js';
+import type { FurnaceConfig } from '../../types/furnace.js';
+import { type FragmentIncluderRefresh } from './deploy-fragment-includers.js';
+/** Outcome of {@link deployNamedComponents}. */
+export type NamedDeployOutcome = {
+    kind: 'stock';
+    stock: string[];
+} | {
+    kind: 'result';
+    result: ApplyAllComponentsResult;
+    includers: FragmentIncluderRefresh;
+    /** Named entries that are stock (warned about, never applied). */
+    stock: string[];
+    /** Named entries that are overrides or custom components, in order. */
+    deployed: string[];
+};
+/**
+ * Applies each named override or custom component through the same
+ * pipeline as deploy-all (`applyAllComponents` with a `componentName`
+ * filter), persisting each one's state right after it applies cleanly.
+ * Only then are the other stale includers of the fragments the cleanly
+ * applied components include refreshed, so an includer that is itself
+ * named is applied once, as a named component.
+ *
+ * Must run inside one `runFurnaceMutation` so the whole set shares a single
+ * lock hold.
+ */
+export declare function deployNamedComponents(args: {
+    projectRoot: string;
+    names: readonly string[];
+    config: FurnaceConfig;
+    furnacePaths: FurnacePaths;
+    isDryRun: boolean;
+    operationContext: FurnaceOperationContext;
+}): Promise<NamedDeployOutcome>;

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

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Targeted `furnace deploy <name>...`: one or more named components applied
+ * under ONE furnace lock hold.
+ *
+ * Deploying a set of widgets one invocation at a time put every call at the
+ * back of the engine-lock queue, so a forty-widget deploy waited forty
+ * times. Naming them together waits once. Each named component is still its
+ * own atomic unit (applied, then its state persisted, before the next one
+ * starts), exactly as a single-name deploy, so a failure or signal midway
+ * leaves every earlier component committed and consistent.
+ */
+import { applyAllComponents } from '../../core/furnace-apply.js';
+import { getPersistableAppliedEntry, persistSingleComponentState, shouldPersistSingleComponentState, } from '../../core/furnace-state-persist.js';
+import { FurnaceError } from '../../errors/furnace.js';
+import { mergeApplyResults, refreshStaleFragmentIncluders, } from './deploy-fragment-includers.js';
+/**
+ * Splits the requested names into deployable and stock entries, refusing
+ * the whole invocation before any write when one is unknown. Duplicates
+ * are dropped, keeping the first occurrence.
+ */
+function partitionDeployNames(names, config) {
+    const deployable = [];
+    const stock = [];
+    for (const name of new Set(names)) {
+        if (name in config.overrides || name in config.custom)
+            deployable.push(name);
+        else if (config.stock.includes(name))
+            stock.push(name);
+        else
+            throw new FurnaceError(`Component "${name}" not found in furnace.json.`, name);
+    }
+    return { deployable, stock };
+}
+/** Folds several includer refreshes into one, without repeating a tag. */
+function mergeIncluderRefreshes(refreshes, named) {
+    // A named component is reported as deployed in its own right, never as
+    // an includer some other named component refreshed on its behalf.
+    const refreshed = [...new Set(refreshes.flatMap((r) => r.refreshed))].filter((tag) => !named.has(tag));
+    return {
+        fragments: [...new Set(refreshes.flatMap((r) => r.fragments))].sort(),
+        refreshed,
+        failed: refreshes.flatMap((r) => r.failed).filter((f) => !named.has(f.tag)),
+        results: refreshes.flatMap((r) => r.results),
+    };
+}
+/**
+ * Applies each named override or custom component through the same
+ * pipeline as deploy-all (`applyAllComponents` with a `componentName`
+ * filter), persisting each one's state right after it applies cleanly.
+ * Only then are the other stale includers of the fragments the cleanly
+ * applied components include refreshed, so an includer that is itself
+ * named is applied once, as a named component.
+ *
+ * Must run inside one `runFurnaceMutation` so the whole set shares a single
+ * lock hold.
+ */
+export async function deployNamedComponents(args) {
+    const { projectRoot, names, config, furnacePaths, isDryRun, operationContext } = args;
+    const { deployable, stock } = partitionDeployNames(names, config);
+    if (deployable.length === 0)
+        return { kind: 'stock', stock };
+    const results = [];
+    const clean = [];
+    for (const name of deployable) {
+        const result = await applyAllComponents(projectRoot, isDryRun, {
+            componentName: name,
+            persistState: false,
+            operationContext,
+        });
+        results.push(result);
+        // Each named deploy is atomic: state is persisted only when every apply
+        // step succeeded, and any rollback has already restored the engine.
+        if (shouldPersistSingleComponentState(result, isDryRun)) {
+            await persistSingleComponentState(projectRoot, getPersistableAppliedEntry('Deploy', name, result.applied[0]), furnacePaths);
+            clean.push(name);
+        }
+        else if (isDryRun) {
+            clean.push(name);
+        }
+    }
+    // Other deployed includers of a fragment these components include would
+    // otherwise keep a stale expansion. Only after a clean, persisted apply
+    // (dry-run always previews).
+    const refreshes = [];
+    for (const name of clean) {
+        refreshes.push(await refreshStaleFragmentIncluders({
+            projectRoot,
+            name,
+            config,
+            furnacePaths,
+            isDryRun,
+            operationContext,
+        }));
+    }
+    const includers = mergeIncluderRefreshes(refreshes, new Set(deployable));
+    const [first, ...rest] = results;
+    // `deployable` is non-empty, so `first` is always set.
+    const primary = first;
+    return {
+        kind: 'result',
+        result: mergeApplyResults(primary, [...rest, ...includers.results]),
+        includers,
+        stock,
+        deployed: deployable,
+    };
+}

package/dist/src/commands/furnace/deploy.d.ts

@@ -2,7 +2,8 @@ import type { FurnaceDeployOptions } from '../../types/commands/index.js';
 /**
  * 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 declare function furnaceDeployCommand(projectRoot: string, name?: string, options?: FurnaceDeployOptions): Promise<void>;
+export declare function furnaceDeployCommand(projectRoot: string, names?: string | readonly string[], options?: FurnaceDeployOptions): Promise<void>;