@hominis/fireforge 0.35.0 → 0.37.0

package/dist/src/core/furnace-stale-export.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
+ *
+ * Exports capture the DEPLOYED engine copies of furnace-managed files, not
+ * the `components/` sources. Editing a component source and re-exporting
+ * its owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
+ * exports the stale deployed copy — per-patch lint then flags the old line
+ * count and the patch body lags the source. This gate detects that
+ * sequence by comparing component source directories against the checksums
+ * recorded at the last apply (`FurnaceState.appliedChecksums`) — the same
+ * signal `warnIfFurnaceStale` uses for run/watch — and refuses the export
+ * unless the operator passes `--allow-stale-furnace`.
+ *
+ * Checksum-based on purpose: git checkouts and `furnace refresh` churn
+ * mtimes without content changes, so an mtime comparison would misfire.
+ *
+ * Probe failures (broken furnace config, missing state) degrade to a
+ * verbose log and an empty result — a broken furnace setup must never
+ * block non-furnace patch work.
+ */
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { verbose, warn } from '../utils/logger.js';
+import { extractComponentChecksums, hasComponentChanged } from './furnace-apply-helpers.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+import { resolveFtlDir } from './furnace-constants.js';
+/**
+ * Returns the furnace components whose deployed engine copies the given
+ * files fall under AND whose `components/` sources have changed since the
+ * last apply. Empty when furnace is not configured, never applied, or the
+ * probe fails.
+ *
+ * Files are attributed per component: the custom `targetPath` / override
+ * `basePath` prefixes, plus — for a localized non-sharedFtl custom
+ * component — its exact deployed `<ftlDir>/<name>.ftl` file (the shared
+ * FTL dir as a whole stays unclaimed; sibling files there belong to other
+ * components). `sharedFtl` bundles are NOT furnace-deployed (apply only
+ * prunes a dangling per-widget jar.mn line), so they have no deployed copy
+ * to go stale and get no candidate by design. The storybook stories prefix
+ * is likewise skipped.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ */
+export async function findStaleFurnaceComponentsForFiles(projectRoot, files) {
+    try {
+        if (files.length === 0)
+            return [];
+        if (!(await furnaceConfigExists(projectRoot)))
+            return [];
+        const config = await loadFurnaceConfig(projectRoot);
+        const state = await loadFurnaceState(projectRoot);
+        if (!state.appliedChecksums)
+            return [];
+        const furnacePaths = getFurnacePaths(projectRoot);
+        const ftlDir = resolveFtlDir(config.ftlBasePath);
+        const ftlPrefix = ftlDir.endsWith('/') ? ftlDir : `${ftlDir}/`;
+        const candidates = [
+            ...Object.entries(config.overrides).map(([name, cfg]) => ({
+                name,
+                type: 'override',
+                prefix: cfg.basePath.endsWith('/') ? cfg.basePath : `${cfg.basePath}/`,
+                exactFiles: [],
+            })),
+            ...Object.entries(config.custom).map(([name, cfg]) => ({
+                name,
+                type: 'custom',
+                prefix: cfg.targetPath.endsWith('/') ? cfg.targetPath : `${cfg.targetPath}/`,
+                // A localized non-sharedFtl component also owns exactly one
+                // deployed file in the shared FTL dir (applyCustomFtlFile copies
+                // `<name>.ftl` there). sharedFtl bundles are not furnace-deployed.
+                exactFiles: cfg.localized && cfg.sharedFtl === undefined ? [`${ftlPrefix}${name}.ftl`] : [],
+            })),
+        ];
+        const stale = [];
+        for (const candidate of candidates) {
+            if (!files.some((file) => file.startsWith(candidate.prefix) || candidate.exactFiles.includes(file)))
+                continue;
+            const sourceRoot = candidate.type === 'override' ? furnacePaths.overridesDir : furnacePaths.customDir;
+            const sourceDir = `${sourceRoot}/${candidate.name}`;
+            if (!(await pathExists(sourceDir)))
+                continue;
+            const previous = extractComponentChecksums(state.appliedChecksums, candidate.type, candidate.name);
+            if (await hasComponentChanged(sourceDir, previous)) {
+                stale.push({ name: candidate.name, type: candidate.type, prefix: candidate.prefix });
+            }
+        }
+        return stale;
+    }
+    catch (error) {
+        verbose(`Stale-furnace export gate skipped due to an error: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+/**
+ * Gate helper for export/re-export: refuses (or, with `allow`, warns) when
+ * any exported file belongs to a furnace component whose source changed
+ * since the last apply — the export would capture the stale deployed copy.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ * @param allow - True when the operator passed `--allow-stale-furnace`
+ * @param command - Which command runs the gate (message wording only)
+ */
+export async function enforceFreshFurnaceSources(projectRoot, files, allow, command) {
+    const stale = await findStaleFurnaceComponentsForFiles(projectRoot, files);
+    if (stale.length === 0)
+        return;
+    const list = stale
+        .map((component) => `${component.name} (components/${component.type === 'custom' ? 'custom' : 'overrides'}/${component.name}/ → ${component.prefix})`)
+        .join(', ');
+    const message = `Component source${stale.length === 1 ? '' : 's'} changed since the last furnace apply: ${list}. ` +
+        `The deployed engine cop${stale.length === 1 ? 'y is' : 'ies are'} stale, so this ${command} would ` +
+        'capture the OLD component content into the patch. Run "fireforge furnace deploy" (or ' +
+        '"fireforge furnace apply") first so the export captures the current source, or pass ' +
+        '--allow-stale-furnace to export the deployed copy anyway.';
+    if (allow) {
+        warn(message);
+        return;
+    }
+    throw new GeneralError(message);
+}

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

@@ -55,4 +55,3 @@ export async function warnIfFurnaceStale(projectRoot) {
         verbose('Furnace staleness check skipped due to an error.');
     }
 }
-//# sourceMappingURL=furnace-staleness.js.map

package/dist/src/core/furnace-state-persist.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Single-component furnace state persistence.
+ *
+ * There are exactly two sanctioned ways checksums land in
+ * furnace-state.json:
+ *
+ *  1. The BATCH path inside `applyAllComponents` (persistState: true),
+ *     which replaces `appliedChecksums` wholesale — correct only when the
+ *     run covered every component.
+ *  2. The per-component MERGE in this module, which rewrites only the
+ *     `<type>/<name>/…` keys of the component that was applied.
+ *
+ * Every targeted (named) apply/deploy MUST use path 2 with
+ * `persistState: false`. Routing a named run through the batch path wipes
+ * every other component's checksum state: the batch loops filter to the
+ * named component, so the wholesale replace persists a state file
+ * containing only that component. Downstream, `diffDeletedFiles` and
+ * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
+ * components' stale engine files become undetectable by apply AND by
+ * `furnace validate` (2026-07-05 review, finding F1 — `furnace apply
+ * <name>` had exactly this bug while `furnace deploy <name>` documented
+ * and avoided it).
+ */
+import { type applyAllComponents } from './furnace-apply.js';
+import { type getFurnacePaths } from './furnace-config.js';
+type ApplyAllResult = Awaited<ReturnType<typeof applyAllComponents>>;
+/**
+ * Counts applied entries that carry at least one BLOCKING step error
+ * (advisory step errors are warnings and never fail a run).
+ */
+export declare function getStepFailureCount(result: ApplyAllResult): number;
+/**
+ * Decides whether a single-component apply/deploy completed cleanly enough
+ * to persist its checksums into furnace-state.json.
+ *
+ * Named runs are atomic: if any apply step fails, the rollback journal
+ * restores the engine to its pre-run state and this helper returns `false`
+ * so state is not touched. The conditions must stay in lock-step with the
+ * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * future refactor cannot drift them apart and accidentally persist partial
+ * state.
+ */
+export declare function shouldPersistSingleComponentState(result: ApplyAllResult, isDryRun: boolean): boolean;
+/**
+ * Validates and narrows the applied entry a named run should persist.
+ *
+ * Guards against future refactors that might reorder or misroute the
+ * applied[] array: a named run persists state under a single component
+ * name, so the first applied entry MUST be that component. Persisting a
+ * different component's checksums would cause the next status/apply run to
+ * mis-report health for both components involved.
+ *
+ * @param commandLabel - Human label for error messages ("Deploy", "Apply")
+ */
+export declare function getPersistableAppliedEntry(commandLabel: string, name: string, appliedEntry: ApplyAllResult['applied'][number] | undefined): {
+    name: string;
+    type: 'override' | 'custom';
+};
+/**
+ * Persists checksum state for a successfully applied named component by
+ * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * replacing the whole map.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param appliedEntry - Applied component descriptor
+ * @param furnacePaths - Resolved Furnace workspace paths
+ */
+export declare function persistSingleComponentState(projectRoot: string, appliedEntry: {
+    name: string;
+    type: 'override' | 'custom';
+}, furnacePaths: ReturnType<typeof getFurnacePaths>): Promise<void>;
+export {};

package/dist/src/core/furnace-state-persist.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Single-component furnace state persistence.
+ *
+ * There are exactly two sanctioned ways checksums land in
+ * furnace-state.json:
+ *
+ *  1. The BATCH path inside `applyAllComponents` (persistState: true),
+ *     which replaces `appliedChecksums` wholesale — correct only when the
+ *     run covered every component.
+ *  2. The per-component MERGE in this module, which rewrites only the
+ *     `<type>/<name>/…` keys of the component that was applied.
+ *
+ * Every targeted (named) apply/deploy MUST use path 2 with
+ * `persistState: false`. Routing a named run through the batch path wipes
+ * every other component's checksum state: the batch loops filter to the
+ * named component, so the wholesale replace persists a state file
+ * containing only that component. Downstream, `diffDeletedFiles` and
+ * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
+ * components' stale engine files become undetectable by apply AND by
+ * `furnace validate` (2026-07-05 review, finding F1 — `furnace apply
+ * <name>` had exactly this bug while `furnace deploy <name>` documented
+ * and avoided it).
+ */
+import { join } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { computeComponentChecksums, prefixChecksums, } from './furnace-apply.js';
+import { updateFurnaceState } from './furnace-config.js';
+import { countEntriesWithBlockingStepErrors } from './furnace-step-errors.js';
+/**
+ * Counts applied entries that carry at least one BLOCKING step error
+ * (advisory step errors are warnings and never fail a run).
+ */
+export function getStepFailureCount(result) {
+    return countEntriesWithBlockingStepErrors(result.applied);
+}
+/**
+ * Decides whether a single-component apply/deploy completed cleanly enough
+ * to persist its checksums into furnace-state.json.
+ *
+ * Named runs are atomic: if any apply step fails, the rollback journal
+ * restores the engine to its pre-run state and this helper returns `false`
+ * so state is not touched. The conditions must stay in lock-step with the
+ * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * future refactor cannot drift them apart and accidentally persist partial
+ * state.
+ */
+export function shouldPersistSingleComponentState(result, isDryRun) {
+    if (isDryRun)
+        return false;
+    if (result.errors.length > 0)
+        return false;
+    if (getStepFailureCount(result) > 0)
+        return false;
+    return result.applied.length > 0;
+}
+/**
+ * Validates and narrows the applied entry a named run should persist.
+ *
+ * Guards against future refactors that might reorder or misroute the
+ * applied[] array: a named run persists state under a single component
+ * name, so the first applied entry MUST be that component. Persisting a
+ * different component's checksums would cause the next status/apply run to
+ * mis-report health for both components involved.
+ *
+ * @param commandLabel - Human label for error messages ("Deploy", "Apply")
+ */
+export function getPersistableAppliedEntry(commandLabel, name, appliedEntry) {
+    if (!appliedEntry) {
+        throw new FurnaceError(`${commandLabel} for "${name}" finished without producing an applied component entry; ` +
+            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to ` +
+            `reconcile state, then retry. If this persists, file a bug with the ` +
+            `output of "fireforge doctor".`);
+    }
+    if (appliedEntry.type !== 'override' && appliedEntry.type !== 'custom') {
+        throw new FurnaceError(`${commandLabel} for "${name}" returned an unsupported component type "${appliedEntry.type}"; ` +
+            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to reconcile, ` +
+            `then verify the component with "fireforge furnace validate" before retrying.`);
+    }
+    if (appliedEntry.name !== name) {
+        throw new FurnaceError(`${commandLabel} for "${name}" returned an applied entry for a different component ` +
+            `("${appliedEntry.name}"); refusing to persist mismatched state. ` +
+            `Run "fireforge doctor --repair-furnace" to reconcile, then retry.`);
+    }
+    return {
+        name: appliedEntry.name,
+        type: appliedEntry.type,
+    };
+}
+/**
+ * Persists checksum state for a successfully applied named component by
+ * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * replacing the whole map.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param appliedEntry - Applied component descriptor
+ * @param furnacePaths - Resolved Furnace workspace paths
+ */
+export async function persistSingleComponentState(projectRoot, appliedEntry, furnacePaths) {
+    const componentDir = appliedEntry.type === 'override'
+        ? join(furnacePaths.overridesDir, appliedEntry.name)
+        : join(furnacePaths.customDir, appliedEntry.name);
+    const checksums = await computeComponentChecksums(componentDir);
+    const prefixed = prefixChecksums(checksums, appliedEntry.type, appliedEntry.name);
+    const componentPrefix = `${appliedEntry.type}/${appliedEntry.name}/`;
+    await updateFurnaceState(projectRoot, (current) => ({
+        ...current,
+        appliedChecksums: {
+            ...Object.fromEntries(Object.entries(current.appliedChecksums ?? {}).filter(([key]) => !key.startsWith(componentPrefix))),
+            ...prefixed,
+        },
+        engineChecksums: {
+            ...Object.fromEntries(Object.entries(current.engineChecksums ?? {}).filter(([key]) => !key.startsWith(componentPrefix))),
+            ...prefixed,
+        },
+        lastApply: new Date().toISOString(),
+    }));
+}

package/dist/src/core/furnace-step-errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared predicates over {@link StepError} lists.
+ *
+ * Step errors come in two severities: BLOCKING (the default — the apply is
+ * considered failed, triggers rollback and a non-zero exit) and ADVISORY
+ * (`advisory: true` — reported as a warning, never blocks; used by the
+ * `.ftl` helpers whose contract is graceful degradation). Every gate that
+ * decides rollback/failure must count only blocking errors; every reporter
+ * should still surface advisory ones. This module is a leaf (types-only
+ * imports) so both `furnace-apply.ts` and its callers can share the
+ * predicates without import cycles.
+ */
+import type { StepError } from '../types/furnace.js';
+/** Narrow shape shared by applied-component entries carrying step errors. */
+export interface HasStepErrors {
+    stepErrors?: StepError[];
+}
+/** Returns only the blocking (non-advisory) step errors. */
+export declare function blockingStepErrors(stepErrors: StepError[] | undefined): StepError[];
+/** True when the entry carries at least one blocking step error. */
+export declare function hasBlockingStepErrors(entry: HasStepErrors): boolean;
+/** Counts applied entries that carry at least one blocking step error. */
+export declare function countEntriesWithBlockingStepErrors(entries: readonly HasStepErrors[]): number;

package/dist/src/core/furnace-step-errors.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared predicates over {@link StepError} lists.
+ *
+ * Step errors come in two severities: BLOCKING (the default — the apply is
+ * considered failed, triggers rollback and a non-zero exit) and ADVISORY
+ * (`advisory: true` — reported as a warning, never blocks; used by the
+ * `.ftl` helpers whose contract is graceful degradation). Every gate that
+ * decides rollback/failure must count only blocking errors; every reporter
+ * should still surface advisory ones. This module is a leaf (types-only
+ * imports) so both `furnace-apply.ts` and its callers can share the
+ * predicates without import cycles.
+ */
+/** Returns only the blocking (non-advisory) step errors. */
+export function blockingStepErrors(stepErrors) {
+    return (stepErrors ?? []).filter((e) => e.advisory !== true);
+}
+/** True when the entry carries at least one blocking step error. */
+export function hasBlockingStepErrors(entry) {
+    return blockingStepErrors(entry.stepErrors).length > 0;
+}
+/** Counts applied entries that carry at least one blocking step error. */
+export function countEntriesWithBlockingStepErrors(entries) {
+    return entries.filter((entry) => hasBlockingStepErrors(entry)).length;
+}

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

@@ -184,4 +184,3 @@ export async function cleanStories(engineDir) {
     await removeDir(storiesDir);
     return count;
 }
-//# sourceMappingURL=furnace-stories.js.map

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

@@ -55,4 +55,3 @@ export async function validateAccessibility(componentDir, tagName, customConfig)
     }
     return issues;
 }
-//# sourceMappingURL=furnace-validate-accessibility.js.map

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

@@ -4,4 +4,3 @@ export { validateAccessibility } from './furnace-validate-accessibility.js';
 export { validateCompatibility } from './furnace-validate-compatibility.js';
 export { checkRegistrationConsistency, validateJarMnEntries, validateRegistrationPatterns, validateTokenLink, } from './furnace-validate-registration.js';
 export { validateStructure } from './furnace-validate-structure.js';
-//# sourceMappingURL=furnace-validate-checks.js.map

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

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { hasRawCssColors } from '../utils/regex.js';
 import { classExtendsMozLitElement, collectCssVariableDeclarations, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
-async function validateMjsCompatibility(mjsPath, tagName) {
+async function validateMjsCompatibility(mjsPath, tagName, isLibrary) {
     if (!(await pathExists(mjsPath)))
         return [];
     const mjsContent = await readText(mjsPath);
@@ -11,6 +11,12 @@ async function validateMjsCompatibility(mjsPath, tagName) {
     if (hasRelativeModuleImport(mjsContent)) {
         issues.push(createIssue(tagName, 'error', 'relative-import', 'Imports must use chrome:// URIs, not relative paths.'));
     }
+    // A library component (kind: "library") deliberately defines no element:
+    // it exports a base class + helpers for other components to extend, so
+    // the define/extends requirements do not apply.
+    if (isLibrary) {
+        return issues;
+    }
     if (!hasCustomElementDefineCall(mjsContent)) {
         issues.push(createIssue(tagName, 'error', 'no-custom-element-define', 'Missing customElements.define() call. Component will not be registered.'));
     }
@@ -124,7 +130,8 @@ export async function validateCompatibility(componentDir, tagName, type, config,
     const issues = [];
     const mjsPath = join(componentDir, `${tagName}.mjs`);
     const cssPath = join(componentDir, `${tagName}.css`);
-    const mjsIssues = await validateMjsCompatibility(mjsPath, tagName);
+    const isLibrary = type === 'custom' && config?.custom[tagName]?.kind === 'library';
+    const mjsIssues = await validateMjsCompatibility(mjsPath, tagName, isLibrary);
     issues.push(...mjsIssues);
     const cssIssues = await validateCssCompatibility(cssPath, tagName, type, config, root);
     issues.push(...cssIssues);
@@ -149,4 +156,3 @@ export async function validateCompatibility(componentDir, tagName, type, config,
     }
     return issues;
 }
-//# sourceMappingURL=furnace-validate-compatibility.js.map

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

@@ -434,4 +434,3 @@ export async function findOrphanedEngineFiles(root, config, tagName, state, ftlD
     }
     return issues;
 }
-//# sourceMappingURL=furnace-validate-helpers.js.map

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

@@ -5,12 +5,13 @@ import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
-import { stripJsComments } from '../utils/regex.js';
+import { escapeRegex, stripJsComments } from '../utils/regex.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, FTL_DIR, JAR_MN } from './furnace-constants.js';
 import { expandCssFragments, listFragmentIncludes } from './furnace-css-fragments.js';
 import { findStaleJarMnEntries } from './furnace-registration.js';
+import { isTagAlreadyRegistered } from './furnace-registration-ast.js';
 import { isTagInCorrectCustomElementsPlacement } from './furnace-registration-validate.js';
 import { getTokensCssPath } from './token-manager.js';
 /**
@@ -47,9 +48,6 @@ export async function validateRegistrationPatterns(root, config) {
     }
     return issues;
 }
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /**
  * Checks registration consistency for a single custom component.
  *
@@ -160,8 +158,11 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
     const cePath = join(engineDir, CUSTOM_ELEMENTS_JS);
     if (await pathExists(cePath)) {
         const ceContent = await readText(cePath);
-        status.customElementsPresent =
-            ceContent.includes(`"${name}"`) || ceContent.includes(`'${name}'`);
+        // Structure-aware check shared with the ADD path — a bare substring
+        // test counted any mention of the tag (a leftover comment, an
+        // unrelated string) as "registered", masking genuinely missing
+        // registrations from both validate and the re-apply drift oracle.
+        status.customElementsPresent = isTagAlreadyRegistered(ceContent, name);
         if (status.customElementsPresent) {
             status.customElementsCorrectBlock = isTagInCorrectCustomElementsPlacement(ceContent, name, true);
         }
@@ -396,4 +397,3 @@ export async function runPostApplyConsistencyChecks(root, config, result, ftlDir
         }
     }
 }
-//# sourceMappingURL=furnace-validate-registration.js.map

package/dist/src/core/furnace-validate-structure.d.ts

@@ -1,4 +1,12 @@
 import type { ComponentType, CustomComponentConfig, ValidationIssue } from '../types/furnace.js';
+/**
+ * Returns true when file content carries unresolved three-way-merge
+ * conflict markers (as left behind by `furnace refresh`). Shared between
+ * the structure validator and `furnace sync`'s pre-apply gate — both must
+ * agree on what "conflicted" means so a file that validate flags can never
+ * slip through sync into the engine.
+ */
+export declare function containsMergeConflictMarkers(content: string): boolean;
 /**
  * Validates the file structure of a component directory.
  * Checks for required files and naming conventions.

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

@@ -2,6 +2,16 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
+/**
+ * Returns true when file content carries unresolved three-way-merge
+ * conflict markers (as left behind by `furnace refresh`). Shared between
+ * the structure validator and `furnace sync`'s pre-apply gate — both must
+ * agree on what "conflicted" means so a file that validate flags can never
+ * slip through sync into the engine.
+ */
+export function containsMergeConflictMarkers(content) {
+    return /^<{7}\s/m.test(content) || /^>{7}\s/m.test(content) || /^={7}$/m.test(content);
+}
 /**
  * Validates the file structure of a component directory.
  * Checks for required files and naming conventions.
@@ -27,8 +37,9 @@ export async function validateStructure(componentDir, tagName, type, customConfi
             message: `Required file ${tagName}.mjs not found.`,
         });
     }
-    // .css should exist
-    if (!(await pathExists(cssPath))) {
+    // .css should exist — except for library components (base class + helpers,
+    // no element of their own), which render nothing and need no stylesheet.
+    if (!(await pathExists(cssPath)) && customConfig?.kind !== 'library') {
         issues.push({
             component: tagName,
             severity: 'warning',
@@ -65,7 +76,7 @@ export async function validateStructure(componentDir, tagName, type, customConfi
             !entry.name.endsWith('.ftl'))
             continue;
         const content = await readText(join(componentDir, entry.name));
-        if (/^<{7}\s/m.test(content) || /^>{7}\s/m.test(content) || /^={7}$/m.test(content)) {
+        if (containsMergeConflictMarkers(content)) {
             issues.push({
                 component: tagName,
                 severity: 'error',
@@ -109,4 +120,3 @@ export async function validateStructure(componentDir, tagName, type, customConfi
     }
     return issues;
 }
-//# sourceMappingURL=furnace-validate-structure.js.map

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

@@ -298,4 +298,3 @@ async function findOrphanXpcshellScaffolds(root, config) {
     }
     return issues;
 }
-//# sourceMappingURL=furnace-validate.js.map

package/dist/src/core/furnace-version-drift.d.ts

@@ -14,9 +14,12 @@
  * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
  * surfacing — even "140.0" vs "140.9.0esr" is a real drift signal.
  *
- * The result is advisory: apply/deploy emit warnings but do not fail, and
- * status reports drift alongside the component overview. Nothing here
- * should be wired into a blocking code path without an operator prompt.
+ * The result GATES apply/deploy: both warn and then FAIL without --force
+ * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
+ * re-checks it after refresh before applying. Status reports drift
+ * alongside the component overview. Keep this doc in sync with the gates —
+ * an earlier version claimed the result was advisory, which invited
+ * re-breaking the gate.
  */
 import type { FurnaceConfig } from '../types/furnace.js';
 /** Severity of the version drift between an override's base and the current Firefox version. */

package/dist/src/core/furnace-version-drift.js

@@ -15,9 +15,12 @@
  * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
  * surfacing — even "140.0" vs "140.9.0esr" is a real drift signal.
  *
- * The result is advisory: apply/deploy emit warnings but do not fail, and
- * status reports drift alongside the component overview. Nothing here
- * should be wired into a blocking code path without an operator prompt.
+ * The result GATES apply/deploy: both warn and then FAIL without --force
+ * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
+ * re-checks it after refresh before applying. Status reports drift
+ * alongside the component overview. Keep this doc in sync with the gates —
+ * an earlier version claimed the result was advisory, which invited
+ * re-breaking the gate.
  */
 /**
  * Parses a version string into its major, minor, and patch numeric
@@ -98,4 +101,3 @@ export function formatOverrideBaseVersionDriftError(entries) {
         'update baseVersion in furnace.json to acknowledge the new baseline, ' +
         'or pass --force to proceed despite the drift.');
 }
-//# sourceMappingURL=furnace-version-drift.js.map

package/dist/src/core/git-base.js

@@ -117,4 +117,3 @@ export async function configureGitPerformance(repoDir) {
     await git(['config', 'core.fsmonitor', 'false'], repoDir);
     await git(['config', 'feature.manyFiles', 'true'], repoDir);
 }
-//# sourceMappingURL=git-base.js.map

package/dist/src/core/git-diff.js

@@ -476,4 +476,3 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
         }
     });
 }
-//# sourceMappingURL=git-diff.js.map

package/dist/src/core/git-file-ops.js

@@ -228,4 +228,3 @@ export async function isBinaryFile(repoDir, filePath) {
         return false;
     }
 }
-//# sourceMappingURL=git-file-ops.js.map

package/dist/src/core/git-status.d.ts

@@ -12,9 +12,22 @@ export declare function parsePorcelainStatus(output: string): GitStatusEntry[];
  * @returns Parsed git status entries
  */
 export declare function getWorkingTreeStatus(repoDir: string): Promise<GitStatusEntry[]>;
+/**
+ * Resolves the per-directory expansion cap, honoring the same
+ * FIREFORGE_MAX_UNTRACKED_FILES override the status command documents.
+ */
+export declare function resolveMaxUntrackedFilesPerDir(): number;
 /**
  * Expands collapsed untracked directory entries into individual file entries.
  * Git status may report "?? dir/" instead of listing each file underneath.
+ *
+ * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
+ * 5000) with a warning on overflow. The cap used to exist only in the
+ * status command's private expander; this shared one — used by reset,
+ * discard, verify, lint, export-all — was unbounded, so e.g. `reset
+ * --dry-run` after an interrupted download (unborn HEAD, the entire ~300k
+ * file tree untracked) enumerated and printed every file.
+ *
  * @param repoDir - Repository directory
  * @param entries - Parsed status entries
  * @returns Status entries with untracked directories expanded to individual files