@hominis/fireforge 0.35.0 → 0.36.0

package/dist/src/core/firefox-download.js

@@ -134,4 +134,3 @@ export async function downloadFile(url, destPath, onProgress) {
     }
     return totalSize > 0 ? totalSize : undefined;
 }
-//# sourceMappingURL=firefox-download.js.map

package/dist/src/core/firefox-extract.js

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 import { ExtractionError } from '../errors/download.js';
 import { elapsedSince } from '../utils/elapsed.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
-import { exec, executableExists } from '../utils/process.js';
+import { exec, execStream, executableExists } from '../utils/process.js';
 /**
  * Returns true when an archive member path could land outside the
  * extraction root: absolute (POSIX or Windows drive/backslash rooted) or
@@ -88,26 +88,86 @@ export function findUnsafeArchiveLink(verboseLines) {
  * (~38%) to this one-time extraction step, versus ~44 s if run
  * sequentially.
  */
-async function preflightArchiveEntries(archivePath) {
+/**
+ * Incremental line splitter for streamed listings. Keeps only the current
+ * partial line in memory, so a 350k-entry Firefox listing costs O(longest
+ * line), not O(listing).
+ */
+function createLineScanner(onLine) {
+    let buffer = '';
+    return {
+        push(chunk) {
+            buffer += chunk;
+            let idx;
+            while ((idx = buffer.indexOf('\n')) !== -1) {
+                onLine(buffer.slice(0, idx));
+                buffer = buffer.slice(idx + 1);
+            }
+        },
+        flush() {
+            if (buffer.length > 0) {
+                onLine(buffer);
+                buffer = '';
+            }
+        },
+    };
+}
+/**
+ * Runs one tar listing pass, streaming lines through `checkLine` and
+ * returning the first unsafe finding (or null) plus the exit code.
+ *
+ * Streaming matters for safety, not just memory: the buffered `exec`
+ * collector silently truncates at 50 MB, and a full Firefox `-tvf` listing
+ * already sits in the 40–50 MB range — so the buffered implementation could
+ * scan only the head of the listing while reporting the archive safe. A
+ * crafted archive could exploit exactly that by padding benign entries
+ * first and hiding a traversal name or absolute link target past the cap.
+ * With per-line streaming EVERY entry is scanned, with bounded memory.
+ */
+async function runListingScan(archivePath, tarFlag, checkLine) {
     // LC_ALL=C keeps the -tvf column format stable for the link parse.
     const listEnv = { LC_ALL: 'C', LANG: 'C' };
-    const [nameListing, verboseListing] = await Promise.all([
-        exec('tar', ['-tf', archivePath], { env: listEnv }),
-        exec('tar', ['-tvf', archivePath], { env: listEnv }),
+    let unsafe = null;
+    let stderrTail = '';
+    const scanner = createLineScanner((line) => {
+        if (unsafe === null) {
+            unsafe = checkLine(line);
+        }
+    });
+    const exitCode = await execStream('tar', [tarFlag, archivePath], {
+        env: listEnv,
+        onStdout: (chunk) => {
+            scanner.push(chunk);
+        },
+        onStderr: (chunk) => {
+            // Keep a small diagnostic tail; the listing itself is the big stream.
+            stderrTail = (stderrTail + chunk).slice(-4096);
+        },
+    });
+    scanner.flush();
+    return { unsafe, exitCode, stderrTail };
+}
+async function preflightArchiveEntries(archivePath) {
+    const [nameScan, linkScan] = await Promise.all([
+        runListingScan(archivePath, '-tf', (line) => {
+            const name = line.trim();
+            if (name.length === 0)
+                return null;
+            return isUnsafeArchivePath(name) ? name : null;
+        }),
+        runListingScan(archivePath, '-tvf', (line) => findUnsafeArchiveLink([line])),
     ]);
-    if (nameListing.exitCode !== 0) {
-        throw new ExtractionError(archivePath, new Error(`tar -tf preflight exited with code ${nameListing.exitCode}:\n${nameListing.stderr}`));
+    if (nameScan.exitCode !== 0) {
+        throw new ExtractionError(archivePath, new Error(`tar -tf preflight exited with code ${nameScan.exitCode}:\n${nameScan.stderrTail}`));
     }
-    const unsafeName = findUnsafeArchiveEntryName(nameListing.stdout.split('\n'));
-    if (unsafeName !== null) {
-        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root: ${unsafeName}`));
+    if (nameScan.unsafe !== null) {
+        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root: ${nameScan.unsafe}`));
     }
-    if (verboseListing.exitCode !== 0) {
-        throw new ExtractionError(archivePath, new Error(`tar -tvf preflight exited with code ${verboseListing.exitCode}:\n${verboseListing.stderr}`));
+    if (linkScan.exitCode !== 0) {
+        throw new ExtractionError(archivePath, new Error(`tar -tvf preflight exited with code ${linkScan.exitCode}:\n${linkScan.stderrTail}`));
     }
-    const unsafeLink = findUnsafeArchiveLink(verboseListing.stdout.split('\n'));
-    if (unsafeLink !== null) {
-        throw new ExtractionError(archivePath, new Error(`Archive rejected: link could escape the extraction root (${unsafeLink})`));
+    if (linkScan.unsafe !== null) {
+        throw new ExtractionError(archivePath, new Error(`Archive rejected: link could escape the extraction root (${linkScan.unsafe})`));
     }
 }
 /**
@@ -172,4 +232,3 @@ export function formatBytes(bytes) {
     }
     return `${size.toFixed(1)} ${units[unitIndex]}`;
 }
-//# sourceMappingURL=firefox-extract.js.map

package/dist/src/core/firefox-ignorefile.js

@@ -28,4 +28,3 @@ export async function ensureFirefoxIgnorefileCompatibility(engineDir) {
     await writeText(hgignorePath, await readText(gitignorePath));
     return 'created';
 }
-//# sourceMappingURL=firefox-ignorefile.js.map

package/dist/src/core/firefox.d.ts

@@ -35,6 +35,18 @@ export type FirefoxSourcePhase = 'download' | 'extract';
 /** Callback fired at phase transitions during {@link downloadFirefoxSource}. */
 export type FirefoxSourcePhaseCallback = (phase: FirefoxSourcePhase) => void;
 export type FirefoxSourceProgressCallback = (message: string) => void;
+/**
+ * Sweeps orphaned working directories left behind by interrupted downloads
+ * (`<engine>.tmp-*` from extraction, `<engine>.replacement-*` from --force
+ * replacement). Both hold multi-GB partial trees, are worthless after the
+ * owning process died, and nothing else ever reclaimed them. Deliberately
+ * does NOT touch `<engine>.backup-*`: a backup may hold the operator's
+ * previous engine after a failed forced replacement and is their recovery
+ * copy — callers should surface its existence instead.
+ *
+ * @returns names of the directories that were removed
+ */
+export declare function sweepOrphanedEngineWorkDirs(destDir: string): Promise<string[]>;
 /**
  * Downloads and extracts Firefox source.
  * @param version - Firefox version to download

package/dist/src/core/firefox.js

@@ -33,6 +33,63 @@ export function getDownloadUrl(version, product = 'firefox') {
 export function getTarballFilename(version, product = 'firefox') {
     return resolveArchive(version, product).filename;
 }
+/**
+ * Classifies an extraction failure as archive corruption (invalidate the
+ * cache and re-download) versus an environmental problem (keep the cached
+ * archive; the retry can reuse it). Environmental signatures are the
+ * conservative list — anything unrecognized is treated as corruption so a
+ * genuinely bad archive can never survive in the cache.
+ */
+function isLikelyArchiveCorruptionError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof Error ? error.code : undefined;
+    if (code === 'ENOSPC' || code === 'EACCES' || code === 'EPERM' || code === 'EDQUOT') {
+        return false;
+    }
+    if (/No space left on device|Permission denied|Disk quota exceeded/i.test(message)) {
+        return false;
+    }
+    // Missing tar binary / preflight refusing an unsafe archive both carry
+    // ExtractionError text that names the condition; a missing tar is
+    // environmental, an unsafe-entry rejection indicts the archive.
+    if (/"tar" command was not found/i.test(message)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Sweeps orphaned working directories left behind by interrupted downloads
+ * (`<engine>.tmp-*` from extraction, `<engine>.replacement-*` from --force
+ * replacement). Both hold multi-GB partial trees, are worthless after the
+ * owning process died, and nothing else ever reclaimed them. Deliberately
+ * does NOT touch `<engine>.backup-*`: a backup may hold the operator's
+ * previous engine after a failed forced replacement and is their recovery
+ * copy — callers should surface its existence instead.
+ *
+ * @returns names of the directories that were removed
+ */
+export async function sweepOrphanedEngineWorkDirs(destDir) {
+    const { readdir } = await import('node:fs/promises');
+    const { basename, dirname } = await import('node:path');
+    const parent = dirname(destDir);
+    const enginePrefixTmp = `${basename(destDir)}.tmp-`;
+    const enginePrefixReplacement = `${basename(destDir)}.replacement-`;
+    let entries;
+    try {
+        entries = await readdir(parent);
+    }
+    catch {
+        return [];
+    }
+    const removed = [];
+    for (const name of entries) {
+        if (name.startsWith(enginePrefixTmp) || name.startsWith(enginePrefixReplacement)) {
+            await removeDir(join(parent, name));
+            removed.push(name);
+        }
+    }
+    return removed;
+}
 /**
  * Downloads and extracts Firefox source.
  * @param version - Firefox version to download
@@ -60,7 +117,13 @@ export async function downloadFirefoxSource(version, product, destDir, cacheDir,
     }
     catch (error) {
         await removeDir(tempDir);
-        await invalidateArchiveCache(archive, cacheDir);
+        // Only throw away the ~600 MB cached archive when the failure indicts
+        // the ARCHIVE, not the environment. ENOSPC, a permission problem in
+        // destDir, or tar disappearing mid-run used to invalidate a perfectly
+        // good download and force a full re-fetch on retry.
+        if (isLikelyArchiveCorruptionError(error)) {
+            await invalidateArchiveCache(archive, cacheDir);
+        }
         throw error;
     }
     // Firefox source extracts to a subdirectory (e.g., firefox-140.0/)
@@ -80,4 +143,3 @@ export async function downloadFirefoxSource(version, product, destDir, cacheDir,
         await rename(tempDir, destDir);
     }
 }
-//# sourceMappingURL=firefox.js.map

package/dist/src/core/furnace-apply-dry-run.js

@@ -102,4 +102,3 @@ export async function buildCustomDryRunActions(name, componentDir, engineDir, co
     }
     return { actions, stepErrors };
 }
-//# sourceMappingURL=furnace-apply-dry-run.js.map

package/dist/src/core/furnace-apply-ftl.d.ts

@@ -4,9 +4,13 @@
  * per-file LOC budget.
  *
  * Every helper here degrades gracefully: if the locale jar.mn is missing or
- * the FTL tree is non-standard, apply logs a `stepError` rather than
- * aborting the whole command. Missing jar.mn on a fork without a locale
- * package should not block a working `.mjs`/`.css` from shipping.
+ * the FTL tree is non-standard, apply logs an ADVISORY `stepError`
+ * (`advisory: true`) rather than aborting the whole command. Advisory step
+ * errors are reported as warnings and never trigger rollback — missing
+ * jar.mn on a fork without a locale package should not block a working
+ * `.mjs`/`.css` from shipping (the blocking/advisory split exists because
+ * this contract used to be contradicted: any FTL step error rolled back
+ * the whole apply).
  */
 import type { CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';

package/dist/src/core/furnace-apply-ftl.js

@@ -5,9 +5,13 @@
  * per-file LOC budget.
  *
  * Every helper here degrades gracefully: if the locale jar.mn is missing or
- * the FTL tree is non-standard, apply logs a `stepError` rather than
- * aborting the whole command. Missing jar.mn on a fork without a locale
- * package should not block a working `.mjs`/`.css` from shipping.
+ * the FTL tree is non-standard, apply logs an ADVISORY `stepError`
+ * (`advisory: true`) rather than aborting the whole command. Advisory step
+ * errors are reported as warnings and never trigger rollback — missing
+ * jar.mn on a fork without a locale package should not block a working
+ * `.mjs`/`.css` from shipping (the blocking/advisory split exists because
+ * this contract used to be contradicted: any FTL step error rolled back
+ * the whole apply).
  */
 import { join, relative } from 'node:path';
 import { toError } from '../utils/errors.js';
@@ -86,7 +90,7 @@ export async function applySharedFtlPrune(engineDir, name, ftlDir, config, affec
             affectedPaths.push(prunedPath);
     }
     catch (error) {
-        stepErrors.push({ step: 'locale jar.mn prune', error: toError(error).message });
+        stepErrors.push({ step: 'locale jar.mn prune', error: toError(error).message, advisory: true });
     }
 }
 /**
@@ -139,6 +143,7 @@ export async function applyCustomFtlFile(engineDir, name, componentDir, ftlDir,
         stepErrors.push({
             step: 'locale jar.mn registration',
             error: `Locale jar.mn not found at ${localeJarRel}; component "${name}" ships without a chrome URI for ${ftlFile}. Add the file manually or set furnace.json "ftlBasePath" to a tree that owns a jar.mn.`,
+            advisory: true,
         });
         return;
     }
@@ -155,6 +160,7 @@ export async function applyCustomFtlFile(engineDir, name, componentDir, ftlDir,
         stepErrors.push({
             step: 'locale jar.mn registration',
             error: toError(error).message,
+            advisory: true,
         });
     }
 }
@@ -199,4 +205,3 @@ export async function removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, con
     }
     await removeLocaleFtlJarMnEntry(engineDir, localeJarRel, tagName, chromeSubPath);
 }
-//# sourceMappingURL=furnace-apply-ftl.js.map

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

@@ -421,4 +421,3 @@ export async function applyOverrideComponent(engineDir, name, componentDir, conf
     return { affectedPaths };
 }
 export { diffDeletedFiles, extractComponentChecksums, prefixChecksums, } from './furnace-checksum-utils.js';
-//# sourceMappingURL=furnace-apply-helpers.js.map

package/dist/src/core/furnace-apply-output.js

@@ -45,7 +45,8 @@ export function logApplyResult(result, isDryRun) {
         for (const applied of result.applied) {
             if (applied.stepErrors && applied.stepErrors.length > 0) {
                 for (const stepErr of applied.stepErrors) {
-                    warn(`${applied.name}: [${stepErr.step}] ${stepErr.error}`);
+                    const advisoryPrefix = stepErr.advisory === true ? '(advisory) ' : '';
+                    warn(`${applied.name}: ${advisoryPrefix}[${stepErr.step}] ${stepErr.error}`);
                 }
             }
         }
@@ -54,4 +55,3 @@ export function logApplyResult(result, isDryRun) {
         error(`${err.name} — ${err.error}`);
     }
 }
-//# sourceMappingURL=furnace-apply-output.js.map

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

@@ -31,4 +31,10 @@ export declare function applyAllComponents(root: string, dryRun?: boolean, optio
 }): Promise<ApplyResult & {
     actions?: DryRunAction[];
     rollbackJournal?: RollbackJournal;
-}>;
+}>; /**
+ * Shared context threaded through the batch apply loops. Bundles the state
+ * both loops mutate (result/actions/checksums) with the immutable run
+ * parameters — the previous 12–13 positional parameters let call sites
+ * drift (the named-apply state-wipe bug) and made every new parameter a
+ * two-signature change.
+ */

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

@@ -13,6 +13,7 @@ import { resolveFurnaceMarkerComment } from './furnace-marker.js';
 import { recordFurnaceRollbackFailure } from './furnace-operation.js';
 import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
+import { blockingStepErrors, hasBlockingStepErrors } from './furnace-step-errors.js';
 import { runPostApplyConsistencyChecks } from './furnace-validate-registration.js';
 export { computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
 function addMissingComponentError(result, name, directoryPath) {
@@ -29,7 +30,9 @@ function buildOverrideUndeployActions(name, config, engineDir, deletedFiles, ftl
         description: `Restore engine/${fileName.endsWith('.ftl') ? `${ftlDir}/${fileName}` : `${config.basePath}/${fileName}`} to Firefox baseline`,
     }));
 }
-async function applyOverrideBatch(config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName) {
+async function applyOverrideBatch(ctx) {
+    const { config, furnacePaths, state, engineDir, ftlDir, dryRun } = ctx;
+    const { result, allActions, newChecksums, rollbackJournal, componentName } = ctx;
     const overrideEntries = Object.entries(config.overrides).filter(([name]) => !componentName || name === componentName);
     const totalOverrides = overrideEntries.length;
     let overrideIndex = 0;
@@ -162,7 +165,9 @@ async function reconcileCustomRegistrationAfterUndeploy(engineDir, name, config,
         filesAffected.push(CUSTOM_ELEMENTS_JS);
     }
 }
-async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName, markerComment) {
+async function applyCustomBatch(ctx, root, markerComment) {
+    const { config, furnacePaths, state, engineDir, ftlDir, dryRun } = ctx;
+    const { result, allActions, newChecksums, rollbackJournal, componentName } = ctx;
     const allKnown = new Set([
         ...config.stock,
         ...Object.keys(config.overrides),
@@ -251,7 +256,7 @@ async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ft
             if (dryRun && actions) {
                 allActions.push(...actions);
             }
-            if (!dryRun && deletedFiles.length > 0 && stepErrors.length === 0) {
+            if (!dryRun && deletedFiles.length > 0 && blockingStepErrors(stepErrors).length === 0) {
                 await reconcileCustomRegistrationAfterUndeploy(engineDir, name, customConfig, deletedFiles, currentChecksums, rollbackJournal, filesAffectedTotal);
             }
             filesAffectedTotal.push(...filesAffected);
@@ -261,9 +266,11 @@ async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ft
                 filesAffected: filesAffectedTotal,
                 ...(stepErrors.length > 0 ? { stepErrors } : {}),
             });
-            // Only store checksums when the component applied without step errors,
-            // so that partially failed components are re-applied on the next run.
-            if (!dryRun && stepErrors.length === 0) {
+            // Only store checksums when the component applied without BLOCKING
+            // step errors, so that partially failed components are re-applied on
+            // the next run. Advisory errors (FTL degradation) still persist —
+            // re-applying cannot fix a fork that has no locale jar.mn.
+            if (!dryRun && blockingStepErrors(stepErrors).length === 0) {
                 Object.assign(newChecksums, prefixChecksums(currentChecksums, 'custom', name));
             }
         }
@@ -338,16 +345,38 @@ export async function applyAllComponents(root, dryRun = false, options) {
             throw new FurnaceError(`Component "${componentName}" not found in furnace.json. Run "fireforge furnace list" to see registered components.`, componentName);
         }
     }
-    await applyOverrideBatch(config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName);
-    await applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName, markerComment);
-    // Check for any partial failures (step errors on applied components).
-    const hasStepErrors = result.applied.some((entry) => 'stepErrors' in entry && entry.stepErrors.length > 0);
+    const batchContext = {
+        config,
+        furnacePaths,
+        state,
+        engineDir,
+        ftlDir,
+        dryRun,
+        result,
+        allActions,
+        newChecksums,
+        rollbackJournal,
+        componentName,
+    };
+    await applyOverrideBatch(batchContext);
+    await applyCustomBatch(batchContext, root, markerComment);
+    // Check for any partial failures (blocking step errors on applied
+    // components). Advisory step errors (e.g. FTL degradation) are warnings
+    // and never gate rollback.
+    const hasApplyStepErrors = result.applied.some((entry) => hasBlockingStepErrors(entry));
     // Orphaned components are implicitly cleaned up: newChecksums only
     // contains entries for components that still exist in furnace.json,
     // and it fully replaces state.appliedChecksums below.
-    if (!dryRun && !hasStepErrors && result.errors.length === 0) {
+    if (!dryRun && !hasApplyStepErrors && result.errors.length === 0) {
         await runPostApplyConsistencyChecks(root, config, result, ftlDir);
     }
+    // Recompute AFTER the consistency checks: they MUTATE entry.stepErrors
+    // when the applied output is inconsistent (e.g. a jar.mn entry that
+    // silently mis-landed). Reading the pre-check snapshot meant those
+    // failures skipped rollback and persisted checksums for a component
+    // known to be inconsistent — while the CLI simultaneously reported
+    // "failed to apply cleanly".
+    const hasStepErrors = result.applied.some((entry) => hasBlockingStepErrors(entry));
     // --- Rollback on failure, persist on success (skip for dry-run) ---
     if (!dryRun) {
         if (result.errors.length > 0 || hasStepErrors) {
@@ -386,5 +415,10 @@ export async function applyAllComponents(root, dryRun = false, options) {
         result.actions = allActions;
     }
     return result;
-}
-//# sourceMappingURL=furnace-apply.js.map
+} /**
+ * Shared context threaded through the batch apply loops. Bundles the state
+ * both loops mutate (result/actions/checksums) with the immutable run
+ * parameters — the previous 12–13 positional parameters let call sites
+ * drift (the named-apply state-wipe bug) and made every new parameter a
+ * two-signature change.
+ */

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

@@ -36,4 +36,3 @@ export function diffDeletedFiles(previous, current) {
     }
     return deleted.sort();
 }
-//# sourceMappingURL=furnace-checksum-utils.js.map

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

@@ -24,4 +24,3 @@ export function parseStringArray(value, fieldName) {
     }
     return items;
 }
-//# sourceMappingURL=furnace-config-array-utils.js.map

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

@@ -61,4 +61,3 @@ export function parseCustomConfig(data, name) {
         ...(sharedFtl !== undefined ? { sharedFtl } : {}),
     };
 }
-//# sourceMappingURL=furnace-config-custom.js.map

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

@@ -83,4 +83,3 @@ export function orderFurnaceConfigForWrite(existing, config) {
     }
     return ordered;
 }
-//# sourceMappingURL=furnace-config-order.js.map

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

@@ -40,4 +40,3 @@ export function validateRuntimeVariables(raw) {
         }
     }
 }
-//# sourceMappingURL=furnace-config-tokens.js.map

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

@@ -130,4 +130,3 @@ export function applyOptionalFurnaceFields(migrated, config) {
         config.scanPaths = paths;
     }
 }
-//# sourceMappingURL=furnace-config-validate.js.map

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

@@ -46,6 +46,17 @@ export declare function validateFurnaceConfig(data: unknown): FurnaceConfig;
  * @throws Error if config doesn't exist or is invalid
  */
 export declare function loadFurnaceConfig(root: string): Promise<FurnaceConfig>;
+/**
+ * Clears applied furnace state while preserving `pendingRepair`.
+ *
+ * Used whenever the engine baseline is replaced or reset (download --force,
+ * reset, rebase, rebase --abort): every applied checksum describes content
+ * that no longer exists, but pendingRepair tracks authoring-side rollback
+ * issues in the component WORKSPACE and must survive an engine refresh.
+ * No-ops when the state file does not exist. Centralized because the same
+ * reset logic had drifted into four separate command files.
+ */
+export declare function clearAppliedFurnaceState(root: string): Promise<void>;
 /**
  * Writes a furnace configuration to furnace.json.
  * @param root - Root directory of the project

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

@@ -122,6 +122,25 @@ export function validateFurnaceConfig(data) {
     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 historically a
+    // shared targetPath meant `furnace remove` of one component deleted the
+    // other's deployed files.
+    const targetPathOwners = new Map();
+    for (const [name, custom_] of Object.entries(custom)) {
+        const owners = targetPathOwners.get(custom_.targetPath) ?? [];
+        owners.push(name);
+        targetPathOwners.set(custom_.targetPath, owners);
+    }
+    for (const [targetPath, owners] of targetPathOwners) {
+        if (owners.length > 1) {
+            warn(`furnace.json: custom components ${owners.join(', ')} share targetPath "${targetPath}". ` +
+                'Give each component its own directory — shared directories make per-component ' +
+                'removal and drift detection ambiguous.');
+        }
+    }
     const config = {
         version: CURRENT_CONFIG_VERSION,
         componentPrefix: migrated['componentPrefix'],
@@ -308,6 +327,24 @@ export async function loadFurnaceConfig(root) {
         throw new FurnaceError(`Invalid furnace.json at ${paths.furnaceConfig}: ${toError(error).message}`);
     }
 }
+/**
+ * Clears applied furnace state while preserving `pendingRepair`.
+ *
+ * Used whenever the engine baseline is replaced or reset (download --force,
+ * reset, rebase, rebase --abort): every applied checksum describes content
+ * that no longer exists, but pendingRepair tracks authoring-side rollback
+ * issues in the component WORKSPACE and must survive an engine refresh.
+ * No-ops when the state file does not exist. Centralized because the same
+ * reset logic had drifted into four separate command files.
+ */
+export async function clearAppliedFurnaceState(root) {
+    const paths = getFurnacePaths(root);
+    if (!(await pathExists(paths.furnaceState)))
+        return;
+    await updateFurnaceState(root, (current) => ({
+        ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
+    }));
+}
 /**
  * Writes a furnace configuration to furnace.json.
  * @param root - Root directory of the project
@@ -500,4 +537,3 @@ export async function collectFurnaceManagedPrefixes(root) {
     prefixes.add(FURNACE_STORYBOOK_STORIES_PREFIX);
     return prefixes;
 }
-//# sourceMappingURL=furnace-config.js.map

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

@@ -87,4 +87,3 @@ export function stripComponentPrefix(tagName, componentPrefix) {
     }
     return tagName;
 }
-//# sourceMappingURL=furnace-constants.js.map

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

@@ -240,4 +240,3 @@ export async function validateCssFragments(componentDir, tagName, sharedDir, eng
     }
     return issues;
 }
-//# sourceMappingURL=furnace-css-fragments.js.map

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

@@ -91,4 +91,3 @@ export function topologicalSortCustom(custom) {
     }
     return sorted;
 }
-//# sourceMappingURL=furnace-graph-utils.js.map

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

@@ -38,9 +38,8 @@ export interface JsconfigSyncResult {
  * writing.
  *
  * The consumer owns the jsconfig file: a missing file is an error with
- * guidance rather than a silent scaffold, and JSONC (comments/trailing
- * commas) is unsupported for the managed file — `readJson` is a strict
- * JSON parser, so the error message says so explicitly.
+ * guidance rather than a silent scaffold. JSONC comments and trailing commas
+ * are preserved; Furnace edits only `compilerOptions.paths`.
  *
  * @param root - Project root directory
  * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)