@hominis/fireforge 0.49.2 → 0.51.0

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>;

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);
         }