@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/furnace-checksum-utils.d.ts

@@ -3,10 +3,10 @@ export declare function extractComponentChecksums(allChecksums: Record<string, s
 /** Prefixes component checksums so they can be stored in the flattened state format. */
 export declare function prefixChecksums(checksums: Record<string, string>, type: string, name: string): Record<string, string>;
 /**
- * Returns the filenames present in `previous` that are absent from `current`
- * — i.e. files we know we deployed last time but the workspace has since
- * deleted. The order of returned names is intentionally stable
- * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ * Returns the filenames present in `previous` that are absent from
+ * `current`, i.e. files we know we deployed last time but the workspace has
+ * since deleted. The order of returned names is stable (sorted
+ * alphabetically) so test snapshots and CLI output are deterministic.
  */
 export declare function diffDeletedFiles(previous: Record<string, string>, current: Record<string, string>): string[];
 /**
@@ -15,7 +15,7 @@ export declare function diffDeletedFiles(previous: Record<string, string>, curre
  * Strips a leading BOM and folds CRLF to LF, so a file that differs from its
  * deployed copy only by line endings or a byte-order mark is not reported as
  * drift. Every comparison that decides "has this component changed?" must
- * use it — otherwise `furnace status` and `furnace validate` can disagree
+ * use it. Otherwise `furnace status` and `furnace validate` can disagree
  * with `apply`'s skip fast-path about the same pair of files on a CRLF
  * checkout.
  *

package/dist/src/core/furnace-checksum-utils.js

@@ -22,10 +22,10 @@ export function prefixChecksums(checksums, type, name) {
     return result;
 }
 /**
- * Returns the filenames present in `previous` that are absent from `current`
- * — i.e. files we know we deployed last time but the workspace has since
- * deleted. The order of returned names is intentionally stable
- * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ * Returns the filenames present in `previous` that are absent from
+ * `current`, i.e. files we know we deployed last time but the workspace has
+ * since deleted. The order of returned names is stable (sorted
+ * alphabetically) so test snapshots and CLI output are deterministic.
  */
 export function diffDeletedFiles(previous, current) {
     const deleted = [];
@@ -42,7 +42,7 @@ export function diffDeletedFiles(previous, current) {
  * Strips a leading BOM and folds CRLF to LF, so a file that differs from its
  * deployed copy only by line endings or a byte-order mark is not reported as
  * drift. Every comparison that decides "has this component changed?" must
- * use it — otherwise `furnace status` and `furnace validate` can disagree
+ * use it. Otherwise `furnace status` and `furnace validate` can disagree
  * with `apply`'s skip fast-path about the same pair of files on a CRLF
  * checkout.
  *

package/dist/src/core/furnace-config-custom.d.ts

@@ -1,7 +1,7 @@
 /**
  * Parser for the `custom` entries in furnace.json. Extracted from
  * `furnace-config.ts` so the main config module stays under the
- * per-file LOC budget — the custom-component schema has grown to
+ * per-file LOC budget. The custom-component schema has grown to
  * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
  * each add their own validation branch.
  */

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

@@ -2,7 +2,7 @@
 /**
  * Parser for the `custom` entries in furnace.json. Extracted from
  * `furnace-config.ts` so the main config module stays under the
- * per-file LOC budget — the custom-component schema has grown to
+ * per-file LOC budget. The custom-component schema has grown to
  * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
  * each add their own validation branch.
  */
@@ -65,7 +65,7 @@ export function parseCustomConfig(data, name) {
             ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
             : {}),
         ...(data['keyboardCovered'] === true ? { keyboardCovered: true } : {}),
-        // Explicit `kind: "element"` is the default; normalize it away so the
+        // Explicit `kind: "element"` is the default. Normalize it away so the
         // stored config carries the field only when it changes behavior.
         ...(data['kind'] === 'library' ? { kind: 'library' } : {}),
         ...(sharedFtl !== undefined ? { sharedFtl } : {}),

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

@@ -60,7 +60,7 @@ function orderComponentMapLikeExisting(existing, next) {
 export function orderFurnaceConfigForWrite(existing, config) {
     // FurnaceConfig is plain parsed-JSON data, but as an interface it carries
     // no index signature, so the compiler cannot verify the JsonObject
-    // contract structurally — hence the double assertion. This is the one
+    // contract structurally, hence the double assertion. This is the one
     // place a typed furnace config re-enters the raw-document world.
     // eslint-disable-next-line no-restricted-syntax -- see above
     const next = config;

package/dist/src/core/furnace-config-tokens.d.ts

@@ -6,12 +6,12 @@
 /**
  * Validates a `tokenHostDocuments` raw value. Each entry must be a non-empty
  * relative path contained in the engine tree. Throws `FurnaceError` on
- * violation; does nothing for `undefined` (field is optional).
+ * violation. Does nothing for `undefined` (field is optional).
  */
 export declare function validateTokenHostDocuments(raw: unknown): void;
 /**
  * Validates a `runtimeVariables` raw value. Each entry must start with `--`
- * (it is a CSS custom property name). Throws `FurnaceError` on violation;
- * does nothing for `undefined` (field is optional).
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation.
+ * Does nothing for `undefined` (field is optional).
  */
 export declare function validateRuntimeVariables(raw: unknown): void;

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

@@ -10,7 +10,7 @@ import { parseStringArray } from './furnace-config-array-utils.js';
 /**
  * Validates a `tokenHostDocuments` raw value. Each entry must be a non-empty
  * relative path contained in the engine tree. Throws `FurnaceError` on
- * violation; does nothing for `undefined` (field is optional).
+ * violation. Does nothing for `undefined` (field is optional).
  */
 export function validateTokenHostDocuments(raw) {
     if (raw === undefined)
@@ -27,8 +27,8 @@ export function validateTokenHostDocuments(raw) {
 }
 /**
  * Validates a `runtimeVariables` raw value. Each entry must start with `--`
- * (it is a CSS custom property name). Throws `FurnaceError` on violation;
- * does nothing for `undefined` (field is optional).
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation.
+ * Does nothing for `undefined` (field is optional).
  */
 export function validateRuntimeVariables(raw) {
     if (raw === undefined)

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

@@ -110,8 +110,8 @@ export function applyOptionalFurnaceFields(migrated, config) {
         }
         config.ftlBasePath = migrated['ftlBasePath'];
     }
-    // Validate optional typecheckJsconfig — consumer-owned jsconfig whose
-    // chrome-elements `paths` entries Furnace maintains on deploy.
+    // Validate optional typecheckJsconfig. This is a consumer-owned jsconfig
+    // whose chrome-elements `paths` entries Furnace maintains on deploy.
     if (migrated['typecheckJsconfig'] !== undefined) {
         const jsconfigPath = migrated['typecheckJsconfig'];
         if (!isString(jsconfigPath) || jsconfigPath.includes('..')) {

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

@@ -6,7 +6,7 @@ export declare const SHARED_FRAGMENTS_DIR = "shared";
 /**
  * Paths for furnace-related files and directories.
  */
-interface FurnacePaths {
+export interface FurnacePaths {
     /** Path to furnace.json */
     furnaceConfig: string;
     /** Path to components directory */
@@ -70,8 +70,8 @@ export declare function writeFurnaceConfig(root: string, config: FurnaceConfig):
  * matching override stamp `doctor` fails 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 has
+ * The stamp is 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
@@ -92,11 +92,11 @@ export declare function stampFurnaceOverrideBaseVersions(root: string, version:
  * declarations.
  *
  * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers on
- * the no-arg call shape still get a valid config without a prefix; the CLI
+ * 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
+ * @param options - Optional init context. Pass `{ binaryName }` to derive
  *   the token prefix.
  * @returns A valid FurnaceConfig
  */

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

@@ -53,25 +53,18 @@ export async function furnaceConfigExists(root) {
     const paths = getFurnacePaths(root);
     return pathExists(paths.furnaceConfig);
 }
+/** True when a recovered record carries at least one entry. */
+function hasEntries(record) {
+    return Object.keys(record).length > 0;
+}
 /** The current (and only) config schema version. */
 const CURRENT_CONFIG_VERSION = 1;
 /**
- * Migrates a furnace config from an older schema version to the current one.
- * Returns the data unchanged if it is already at the current version.
- *
- * When a future version 2 is introduced, add a `case 1:` that transforms
- * v1 data into v2 shape and falls through to validation. The pattern is:
- *
- * ```
- * case 1:
- *   data = migrateV1ToV2(data);
- *   // fallthrough
- * case 2:
- *   break;
- * ```
+ * Rejects a config whose `version` field is not the single schema version that
+ * exists. A non-integer or sub-1 value is a malformed document. A value above
+ * the current version was written by a newer FireForge and cannot be read here.
  */
-function migrateFurnaceConfig(data) {
-    const version = data['version'];
+function validateConfigVersion(version) {
     if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
         throw new FurnaceError(`Furnace config: "version" must be a positive integer (got ${JSON.stringify(version)}). ` +
             `Current schema version is ${CURRENT_CONFIG_VERSION}.`);
@@ -80,9 +73,6 @@ function migrateFurnaceConfig(data) {
         throw new FurnaceError(`Furnace config: version ${version} is newer than what this version of FireForge supports (${CURRENT_CONFIG_VERSION}). ` +
             'Upgrade FireForge to read this config.');
     }
-    // Today only version 1 exists, so no migration is needed. When future
-    // versions are added, migration steps will be chained here.
-    return data;
 }
 /**
  * Validates a raw config object and returns a typed FurnaceConfig.
@@ -97,39 +87,36 @@ export function validateFurnaceConfig(data) {
     // Furnace config documents arrive from JSON.parse (loadFurnaceConfig /
     // writeFurnaceConfig round-trips), which can only produce JSON values,
     // so the object check above is the only invariant left to establish.
-    // Run migration before validation so older configs are transparently upgraded.
-    const migrated = migrateFurnaceConfig(data);
-    if (migrated['version'] !== CURRENT_CONFIG_VERSION) {
-        throw new FurnaceError(`Furnace config: "version" must be ${CURRENT_CONFIG_VERSION} after migration`);
-    }
-    if (!isString(migrated['componentPrefix'])) {
+    const raw = data;
+    validateConfigVersion(raw['version']);
+    if (!isString(raw['componentPrefix'])) {
         throw new FurnaceError('Furnace config: "componentPrefix" must be a string');
     }
     // Validate optional tokenPrefix
-    if (migrated['tokenPrefix'] !== undefined && !isString(migrated['tokenPrefix'])) {
+    if (raw['tokenPrefix'] !== undefined && !isString(raw['tokenPrefix'])) {
         throw new FurnaceError('Furnace config: "tokenPrefix" must be a string if provided');
     }
     // Validate optional tokenAllowlist
-    if (migrated['tokenAllowlist'] !== undefined) {
-        parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
+    if (raw['tokenAllowlist'] !== undefined) {
+        parseStringArray(raw['tokenAllowlist'], 'tokenAllowlist');
     }
-    // Validate optional runtimeVariables — CSS runtime state channels
+    // Validate optional runtimeVariables: CSS runtime state channels
     // (e.g. `--cam-x`) that are exempt from `token-prefix-violation`.
-    validateRuntimeVariables(migrated['runtimeVariables']);
-    // Validate optional tokenHostDocuments — list of chrome XHTMLs that the
+    validateRuntimeVariables(raw['runtimeVariables']);
+    // Validate optional tokenHostDocuments: list of chrome XHTMLs that the
     // `missing-token-link` validator scans for the tokens CSS link.
-    validateTokenHostDocuments(migrated['tokenHostDocuments']);
-    const stock = parseStockList(migrated['stock']);
-    const overrides = parseNamedComponentMap(migrated['overrides'], 'override', 'overrides', parseOverrideConfig);
-    const custom = parseNamedComponentMap(migrated['custom'], 'custom', 'custom', parseCustomConfig);
+    validateTokenHostDocuments(raw['tokenHostDocuments']);
+    const stock = parseStockList(raw['stock']);
+    const overrides = parseNamedComponentMap(raw['overrides'], 'override', 'overrides', parseOverrideConfig);
+    const custom = parseNamedComponentMap(raw['custom'], 'custom', 'custom', parseCustomConfig);
     // Detect circular composes references among custom components.
     detectComposesCycles(custom);
     // Validate that every composes reference points to a known component.
     validateComposesReferences(stock, overrides, custom);
     // 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 can lead to
+    // both reason about "files this component deployed into its directory".
+    // 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)) {
@@ -146,12 +133,12 @@ export function validateFurnaceConfig(data) {
     }
     const config = {
         version: CURRENT_CONFIG_VERSION,
-        componentPrefix: migrated['componentPrefix'],
+        componentPrefix: raw['componentPrefix'],
         stock,
         overrides,
         custom,
     };
-    applyOptionalFurnaceFields(migrated, config);
+    applyOptionalFurnaceFields(raw, config);
     return config;
 }
 /**
@@ -167,8 +154,8 @@ function validateFurnaceState(data) {
     return result.state;
 }
 // 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
+// this replaced was annotated rather than linked, so 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) {
@@ -228,7 +215,7 @@ function sanitizeFurnaceState(data) {
                 }
                 appliedChecksums[filePath] = checksum;
             }
-            if (Object.keys(appliedChecksums).length > 0 || !hasInvalidChecksum) {
+            if (hasEntries(appliedChecksums) || !hasInvalidChecksum) {
                 state.appliedChecksums = appliedChecksums;
                 recoveredFields.push('appliedChecksums');
             }
@@ -245,7 +232,7 @@ function sanitizeFurnaceState(data) {
                     engineChecksums[filePath] = checksum;
                 }
             }
-            if (Object.keys(engineChecksums).length > 0) {
+            if (hasEntries(engineChecksums)) {
                 state.engineChecksums = engineChecksums;
                 recoveredFields.push('engineChecksums');
             }
@@ -351,14 +338,14 @@ export async function writeFurnaceConfig(root, config) {
     if (await pathExists(paths.furnaceConfig)) {
         try {
             const raw = await readJson(paths.furnaceConfig);
-            // JSON.parse output is JSON data by construction, so the object
-            // check is the only invariant left for the JsonObject contract.
+            // JSON.parse only produces JSON data, so the object check is the
+            // only invariant left for the JsonObject contract.
             if (isObject(raw))
                 existing = raw;
         }
         catch {
             // A missing or corrupt furnace.json means there is no prior document to
-            // preserve key order from; the writer falls back to canonical ordering.
+            // preserve key order from. The writer falls back to canonical ordering.
             existing = undefined;
         }
     }
@@ -372,8 +359,8 @@ export async function writeFurnaceConfig(root, config) {
  * matching override stamp `doctor` fails 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 has
+ * The stamp is 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
@@ -409,11 +396,11 @@ export async function stampFurnaceOverrideBaseVersions(root, version) {
  * declarations.
  *
  * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers on
- * the no-arg call shape still get a valid config without a prefix; the CLI
+ * 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
+ * @param options - Optional init context. Pass `{ binaryName }` to derive
  *   the token prefix.
  * @returns A valid FurnaceConfig
  */
@@ -481,8 +468,8 @@ 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 — they are tool output, not files an
- * operator commits or hand-edits.
+ * (intentionally bare) license headers. They are tool output rather than
+ * files an operator commits or hand-edits.
  */
 const FURNACE_STORYBOOK_STORIES_PREFIX = 'browser/components/storybook/stories/furnace/';
 /**
@@ -517,8 +504,8 @@ export async function collectFurnaceManagedPrefixes(root) {
     }
     // Always include the preview-generated stories prefix when furnace is
     // initialised. The directory may not exist yet (no preview ever ran),
-    // but classifying it as furnace-managed is safe even when empty —
-    // status simply has nothing to bucket.
+    // but classifying it as furnace-managed is safe even when empty. Status
+    // simply has nothing to bucket.
     prefixes.add(FURNACE_STORYBOOK_STORIES_PREFIX);
     return prefixes;
 }

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

@@ -5,7 +5,7 @@ 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
+ * 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.
  */
@@ -27,15 +27,15 @@ export declare function xpcshellTestParentDir(binaryName: string): string;
 /**
  * Resolves the engine-relative directory a browser-chrome scaffold is
  * written to: the `--test-dir` override when given, else
- * `browser/base/content/test/<binaryName>`. The scaffolder AND the
+ * `browser/base/content/test/<binaryName>`. The scaffolder and the
  * dry-run / success formatters resolve through this one function, so the
  * printed plan cannot disagree with the files that land on disk.
  */
 export declare function resolveBrowserChromeTestDir(binaryName: string, override?: string): string;
 /**
  * Resolves the engine-relative directory an xpcshell scaffold is written
- * to. A `--test-dir` override names the FINAL directory (no per-component
- * segment is appended); the default is
+ * to. A `--test-dir` override names the final directory (no per-component
+ * segment is appended). The default is
  * `browser/base/content/test/<binaryName>-xpcshell/<componentName>`.
  */
 export declare function resolveXpcshellTestDir(binaryName: string, componentName: string, override?: string): string;
@@ -62,8 +62,8 @@ export declare function resolveFtlChromeSubPath(ftlBasePath?: string): string |
  * given `ftlBasePath`. For the default toolkit tree this yields
  * `toolkit/locales/jar.mn`.
  *
- * Returns `undefined` when the path does not contain a `locales/` segment —
- * callers must treat that as "cannot locate" and degrade gracefully.
+ * Returns `undefined` when the path does not contain a `locales/` segment.
+ * Callers must treat that as "cannot locate" and degrade gracefully.
  */
 export declare function resolveFtlLocaleJarMnPath(ftlBasePath?: string): string | undefined;
 /**

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

@@ -1,12 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 /** Path to customElements.js within the engine source tree */
 export const CUSTOM_ELEMENTS_JS = 'toolkit/content/customElements.js';
+import { normalizePathSlashes } from '../utils/paths.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
+ * 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.
  */
@@ -38,7 +39,7 @@ export function xpcshellTestParentDir(binaryName) {
 /**
  * Resolves the engine-relative directory a browser-chrome scaffold is
  * written to: the `--test-dir` override when given, else
- * `browser/base/content/test/<binaryName>`. The scaffolder AND the
+ * `browser/base/content/test/<binaryName>`. The scaffolder and the
  * dry-run / success formatters resolve through this one function, so the
  * printed plan cannot disagree with the files that land on disk.
  */
@@ -47,8 +48,8 @@ export function resolveBrowserChromeTestDir(binaryName, override) {
 }
 /**
  * Resolves the engine-relative directory an xpcshell scaffold is written
- * to. A `--test-dir` override names the FINAL directory (no per-component
- * segment is appended); the default is
+ * to. A `--test-dir` override names the final directory (no per-component
+ * segment is appended). The default is
  * `browser/base/content/test/<binaryName>-xpcshell/<componentName>`.
  */
 export function resolveXpcshellTestDir(binaryName, componentName, override) {
@@ -78,7 +79,7 @@ export function resolveFtlDir(configuredPath) {
  * degrade gracefully rather than inventing a path.
  */
 export function resolveFtlChromeSubPath(ftlBasePath) {
-    const path = (ftlBasePath ?? FTL_DIR).replace(/\\/g, '/');
+    const path = normalizePathSlashes(ftlBasePath ?? FTL_DIR);
     const match = /^(.*?)\/locales\/[^/]+\/(.+?)\/?$/.exec(path);
     if (!match?.[2])
         return undefined;
@@ -89,11 +90,11 @@ export function resolveFtlChromeSubPath(ftlBasePath) {
  * given `ftlBasePath`. For the default toolkit tree this yields
  * `toolkit/locales/jar.mn`.
  *
- * Returns `undefined` when the path does not contain a `locales/` segment —
- * callers must treat that as "cannot locate" and degrade gracefully.
+ * Returns `undefined` when the path does not contain a `locales/` segment.
+ * Callers must treat that as "cannot locate" and degrade gracefully.
  */
 export function resolveFtlLocaleJarMnPath(ftlBasePath) {
-    const path = (ftlBasePath ?? FTL_DIR).replace(/\\/g, '/');
+    const path = normalizePathSlashes(ftlBasePath ?? FTL_DIR);
     const match = /^(.*?)\/locales\/[^/]+\//.exec(path);
     if (!match?.[1])
         return undefined;

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

@@ -9,8 +9,8 @@
  *     @fireforge-include shared-anims.css
  *
  * naming a fragment file in `components/shared/`. `furnace deploy` expands
- * the fragment into the *deployed* copy only — the workspace source stays
- * DRY — fencing the expansion between the directive line and a matching
+ * the fragment into the *deployed* copy only (the workspace source stays
+ * DRY), fencing the expansion between the directive line and a matching
  * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
  *
  * Drift contract: the apply fast-path and `furnace validate` compare the
@@ -24,7 +24,7 @@ export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 export declare function listFragmentIncludes(css: string): string[];
 /**
  * Collapses fenced fragment expansions back to their bare directives.
- * Inverse of {@link expandCssFragments}; used to compare a deployed file
+ * Inverse of {@link expandCssFragments}. Used to compare a deployed file
  * against its workspace source and to re-expand idempotently.
  */
 export declare function stripExpandedFragments(css: string): string;
@@ -52,7 +52,7 @@ export declare function expandCssFragments(css: string, sharedDir: string): Prom
 export declare function extractExpandedFragmentBodies(css: string): Map<string, string>;
 /**
  * Deploys one component file: CSS sources carrying include directives are
- * written as their fragment-expanded form; everything else is a plain
+ * written as their fragment-expanded form. Everything else is a plain
  * copy. Extracted here so `applyCustomComponent` stays inside the
  * per-file line budget.
  *
@@ -73,7 +73,7 @@ export declare function describeFragmentExpansion(src: string): Promise<string>;
  * @param componentDir - Workspace directory of the component
  * @param tagName - Component tag name for issue attribution
  * @param sharedDir - Shared fragments directory
- * @param engineTargetDir - Deployed directory in the engine (optional —
- *   pre-deploy validation skips the staleness check)
+ * @param engineTargetDir - Deployed directory in the engine. Optional, and
+ *   pre-deploy validation skips the staleness check.
  */
 export declare function validateCssFragments(componentDir: string, tagName: string, sharedDir: string, engineTargetDir?: string): Promise<ValidationIssue[]>;

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

@@ -10,8 +10,8 @@
  *     @fireforge-include shared-anims.css
  *
  * naming a fragment file in `components/shared/`. `furnace deploy` expands
- * the fragment into the *deployed* copy only — the workspace source stays
- * DRY — fencing the expansion between the directive line and a matching
+ * the fragment into the *deployed* copy only (the workspace source stays
+ * DRY), fencing the expansion between the directive line and a matching
  * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
  *
  * Drift contract: the apply fast-path and `furnace validate` compare the
@@ -24,7 +24,7 @@ import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { copyFile, pathExists, readText, writeText } from '../utils/fs.js';
 export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
-// Local copy of the directory name for message text — importing the
+// Local copy of the directory name for message text. Importing the
 // binding for value use keeps a single source of truth.
 import { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 const INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-include\s+([\w./-]+)\s*\*\/\s*$/;
@@ -41,7 +41,7 @@ export function listFragmentIncludes(css) {
 }
 /**
  * Collapses fenced fragment expansions back to their bare directives.
- * Inverse of {@link expandCssFragments}; used to compare a deployed file
+ * Inverse of {@link expandCssFragments}. Used to compare a deployed file
  * against its workspace source and to re-expand idempotently.
  */
 export function stripExpandedFragments(css) {
@@ -54,8 +54,8 @@ export function stripExpandedFragments(css) {
         if (!inc?.[1])
             continue;
         // A bare directive (workspace file) has no fence to strip. Only skip
-        // the expansion body when a matching end marker actually follows —
-        // otherwise an unterminated fence would silently eat the rest of the
+        // the expansion body when a matching end marker actually follows.
+        // Otherwise an unterminated fence would silently eat the rest of the
         // file.
         let endIndex = -1;
         for (let j = i + 1; j < lines.length; j++) {
@@ -141,7 +141,7 @@ export function extractExpandedFragmentBodies(css) {
 }
 /**
  * Deploys one component file: CSS sources carrying include directives are
- * written as their fragment-expanded form; everything else is a plain
+ * written as their fragment-expanded form. Everything else is a plain
  * copy. Extracted here so `applyCustomComponent` stays inside the
  * per-file line budget.
  *
@@ -180,8 +180,8 @@ export async function describeFragmentExpansion(src) {
  * @param componentDir - Workspace directory of the component
  * @param tagName - Component tag name for issue attribution
  * @param sharedDir - Shared fragments directory
- * @param engineTargetDir - Deployed directory in the engine (optional —
- *   pre-deploy validation skips the staleness check)
+ * @param engineTargetDir - Deployed directory in the engine. Optional, and
+ *   pre-deploy validation skips the staleness check.
  */
 export async function validateCssFragments(componentDir, tagName, sharedDir, engineTargetDir) {
     const issues = [];
@@ -194,8 +194,8 @@ export async function validateCssFragments(componentDir, tagName, sharedDir, eng
         entries = await readdir(componentDir);
     }
     catch {
-        // An unreadable component directory contributes no fragment issues; return
-        // what has been collected so far rather than failing validation.
+        // An unreadable component directory contributes no fragment issues.
+        // Return what has been collected so far rather than failing validation.
         return issues;
     }
     for (const fileName of entries) {

package/dist/src/core/furnace-dir-entry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The minimal `readdir(..., { withFileTypes: true })` entry shape the furnace
+ * apply path needs, plus the single predicate that decides whether an entry is
+ * a copy candidate. Kept in its own leaf module so both `furnace-apply-helpers`
+ * and its dry-run mirror can share one definition without importing each other.
+ */
+/** Structural subset of `Dirent` used by the furnace apply/dry-run walkers. */
+export interface DirectoryEntry {
+    isFile(): boolean;
+    isSymbolicLink?(): boolean;
+    name: string;
+}
+/**
+ * True for a plain-file directory entry. Symlinks and directories are
+ * never copy candidates.
+ *
+ * @param entry - Directory entry to classify
+ * @returns True when the entry is a regular file
+ */
+export declare function isRegularFile(entry: DirectoryEntry): boolean;

package/dist/src/core/furnace-dir-entry.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The minimal `readdir(..., { withFileTypes: true })` entry shape the furnace
+ * apply path needs, plus the single predicate that decides whether an entry is
+ * a copy candidate. Kept in its own leaf module so both `furnace-apply-helpers`
+ * and its dry-run mirror can share one definition without importing each other.
+ */
+/**
+ * True for a plain-file directory entry. Symlinks and directories are
+ * never copy candidates.
+ *
+ * @param entry - Directory entry to classify
+ * @returns True when the entry is a regular file
+ */
+export function isRegularFile(entry) {
+    if (!entry.isFile())
+        return false;
+    if (typeof entry.isSymbolicLink === 'function' && entry.isSymbolicLink())
+        return false;
+    return true;
+}