@hominis/fireforge 0.13.2 → 0.14.0

package/dist/src/commands/run.js

@@ -2,14 +2,13 @@
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
-import { extractComponentChecksums, hasComponentChanged } from '../core/furnace-apply-helpers.js';
-import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from '../core/furnace-config.js';
+import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, hasBuildArtifacts, run } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, removeDir, removeFile } from '../utils/fs.js';
-import { info, intro, verbose, warn } from '../utils/logger.js';
+import { info, intro, verbose } from '../utils/logger.js';
 /**
  * Cleans the dev profile to prevent stale-state startup failures.
  *
@@ -47,47 +46,6 @@ async function cleanDevProfile(engineDir) {
         verbose(`Non-fatal dev profile cleanup failure: ${toError(error).message}`);
     }
 }
-/**
- * Checks whether any Furnace component has changed since the last apply
- * and warns the user. The build command auto-applies, but run does not,
- * so this advisory message prevents the common "forgot to apply" mistake.
- */
-async function warnIfFurnaceStale(projectRoot) {
-    try {
-        if (!(await furnaceConfigExists(projectRoot)))
-            return;
-        const config = await loadFurnaceConfig(projectRoot);
-        const state = await loadFurnaceState(projectRoot);
-        const furnacePaths = getFurnacePaths(projectRoot);
-        if (!state.appliedChecksums)
-            return;
-        const stale = [];
-        for (const name of Object.keys(config.overrides)) {
-            const dir = `${furnacePaths.overridesDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'override', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
-        for (const name of Object.keys(config.custom)) {
-            const dir = `${furnacePaths.customDir}/${name}`;
-            if (!(await pathExists(dir)))
-                continue;
-            const prev = extractComponentChecksums(state.appliedChecksums, 'custom', name);
-            if (await hasComponentChanged(dir, prev))
-                stale.push(name);
-        }
-        if (stale.length > 0) {
-            warn(`Furnace component${stale.length === 1 ? '' : 's'} modified since last apply: ${stale.join(', ')}. ` +
-                'Run "fireforge furnace apply" (or "fireforge build" which auto-applies) to update the engine.');
-        }
-    }
-    catch {
-        // Non-fatal: a broken furnace config should not block run.
-        verbose('Furnace staleness check skipped due to an error.');
-    }
-}
 /**
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project
@@ -120,6 +78,13 @@ export async function runCommand(projectRoot) {
     await cleanDevProfile(paths.engine);
     info('Launching browser...\n');
     const exitCode = await run(paths.engine);
+    // Exit-code whitelist:
+    //   0   — clean shutdown
+    //   130 — SIGINT (Ctrl+C), user-initiated termination
+    //   143 — SIGTERM, graceful-shutdown termination
+    // SIGKILL (137) and other signal-induced codes are intentionally NOT
+    // whitelisted: those indicate abnormal termination the operator should
+    // see surface as a build-time error.
     if (exitCode !== 0 && exitCode !== 130 && exitCode !== 143) {
         throw new BuildError(`Browser exited with code ${exitCode}`, 'mach run');
     }

package/dist/src/commands/setup-support.js

@@ -178,23 +178,41 @@ async function promptSetupInputs(options) {
             throw new CancellationError();
         },
     });
+    return finalizePromptedSetupInputs(project);
+}
+/**
+ * Validates the raw prompt result and resolves the canonical
+ * {@link ResolvedSetupInputs}. Extracted from {@link promptSetupInputs} so
+ * the prompt body stays under the per-function line limit.
+ */
+function finalizePromptedSetupInputs(project) {
     const sanitizedName = project.name.toLowerCase().replace(/[^a-z0-9]/g, '');
-    const finalName = project.name;
-    const finalVendor = project.vendor;
-    const finalAppId = (typeof project.appId === 'string' ? project.appId.trim() : '') ||
-        `org.${sanitizedName}.browser`;
-    const finalBinaryName = (typeof project.binaryName === 'string' ? project.binaryName.trim() : '') || sanitizedName;
+    // Project names that contain no ASCII alphanumerics (e.g. "----", "漢字",
+    // emoji-only) collapse to an empty sanitised slug, which would silently
+    // produce an invalid `appId` ("org..browser") and an empty `binaryName`.
+    // Refuse to derive defaults from such names — the user must supply
+    // explicit appId / binaryName values instead.
+    const explicitAppId = typeof project.appId === 'string' ? project.appId.trim() : '';
+    const explicitBinaryName = typeof project.binaryName === 'string' ? project.binaryName.trim() : '';
+    if (sanitizedName === '' && (explicitAppId === '' || explicitBinaryName === '')) {
+        throw new InvalidArgumentError(`Project name "${project.name}" contains no characters that can be used to derive default appId / binaryName values. Re-run setup and supply --app-id and --binary-name explicitly.`, 'name');
+    }
+    const finalAppId = explicitAppId || `org.${sanitizedName}.browser`;
+    const finalBinaryName = explicitBinaryName || sanitizedName;
     const finalFirefoxVersion = (typeof project.firefoxVersion === 'string' ? project.firefoxVersion.trim() : '') ||
         '140.9.0esr';
     if (!isValidAppId(finalAppId)) {
         throw new InvalidArgumentError(`Derived appId "${finalAppId}" is invalid.`, 'appId');
     }
+    if (finalBinaryName === '') {
+        throw new InvalidArgumentError('Derived binaryName is empty. Supply --binary-name explicitly.', 'binaryName');
+    }
     if (!isValidFirefoxVersion(finalFirefoxVersion)) {
         throw new InvalidArgumentError(`Default Firefox version "${finalFirefoxVersion}" is invalid.`, 'firefoxVersion');
     }
     return {
-        finalName,
-        finalVendor,
+        finalName: project.name,
+        finalVendor: project.vendor,
         finalAppId,
         finalBinaryName,
         finalFirefoxVersion,

package/dist/src/commands/status.js

@@ -97,16 +97,64 @@ function renderRawStatus(files) {
     }
 }
 /**
- * Expands collapsed untracked directory entries into individual file entries.
- * Git status may report an entire untracked directory as a single entry (e.g. "?? dir/").
- * This function expands those into individual file entries so each file can be classified.
+ * Default maximum number of files we will materialise from a single
+ * untracked directory. Pathological inputs (an accidental dump of build
+ * output, a symlink that resolves into a huge unrelated tree, etc.)
+ * should not be able to balloon `status` into multi-gigabyte memory or
+ * hang the CLI. Going over this cap surfaces a warning so the user knows
+ * the listing has been truncated, and it bounds the JSON / default
+ * rendering paths.
+ *
+ * Override via the `FIREFORGE_MAX_UNTRACKED_FILES` environment variable
+ * for monorepos or fixture-heavy projects with legitimately large
+ * untracked directories.
  */
+const DEFAULT_MAX_UNTRACKED_FILES_PER_DIR = 5000;
+function resolveMaxUntrackedFilesPerDir() {
+    const raw = process.env['FIREFORGE_MAX_UNTRACKED_FILES'];
+    if (raw === undefined || raw.length === 0)
+        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        warn(`Ignoring FIREFORGE_MAX_UNTRACKED_FILES="${raw}" — expected a positive integer. Falling back to ${DEFAULT_MAX_UNTRACKED_FILES_PER_DIR}.`);
+        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
+    }
+    return parsed;
+}
+const MAX_UNTRACKED_FILES_PER_DIR = resolveMaxUntrackedFilesPerDir();
+/**
+ * Emits a prominent top-of-output warning when one or more untracked
+ * directories were truncated during expansion. Individual per-dir warnings
+ * already fired inside expandDirectoryEntries but are easily lost in
+ * scrollback for large status outputs; this banner summarises the total
+ * hidden count so the user doesn't miss that an export based on this
+ * status would be incomplete.
+ */
+function renderTruncationBanner(truncations) {
+    if (truncations.length === 0)
+        return;
+    const hidden = truncations.reduce((sum, rec) => sum + (rec.total - rec.shown), 0);
+    const dirList = truncations.map((r) => `${r.dir} (${r.total - r.shown} hidden)`).join(', ');
+    warn(`⚠ Status output is truncated: ${hidden.toLocaleString()} untracked file(s) across ${truncations.length} director(y/ies) are not shown. ` +
+        `Truncated: ${dirList}. ` +
+        `Add a .gitignore entry or clean the directory before exporting, otherwise the export will omit these files.`);
+}
 async function expandDirectoryEntries(files, engineDir) {
     const expanded = [];
+    const truncations = [];
     for (const entry of files) {
         if (entry.file.endsWith('/') && entry.status.includes('?')) {
             const individualFiles = await getUntrackedFilesInDir(engineDir, entry.file);
-            for (const f of individualFiles) {
+            if (individualFiles.length > MAX_UNTRACKED_FILES_PER_DIR) {
+                warn(`Untracked directory ${entry.file} contains ${individualFiles.length} files — only the first ${MAX_UNTRACKED_FILES_PER_DIR} will be classified. Consider adding a .gitignore entry.`);
+                truncations.push({
+                    dir: entry.file,
+                    total: individualFiles.length,
+                    shown: MAX_UNTRACKED_FILES_PER_DIR,
+                });
+            }
+            const limited = individualFiles.slice(0, MAX_UNTRACKED_FILES_PER_DIR);
+            for (const f of limited) {
                 expanded.push({ status: '??', file: f });
             }
         }
@@ -114,7 +162,7 @@ async function expandDirectoryEntries(files, engineDir) {
             expanded.push(entry);
         }
     }
-    return expanded;
+    return { entries: expanded, truncations };
 }
 /**
  * Classifies files into patch-backed, unmanaged, or branding buckets.
@@ -226,9 +274,11 @@ export async function statusCommand(projectRoot, options = {}) {
             throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
         }
         const manifest = await loadPatchesManifest(paths.patches);
-        const rawFilesOwnership = (await isGitRepository(paths.engine))
+        const ownershipExpansion = (await isGitRepository(paths.engine))
             ? await expandDirectoryEntries(await getStatusWithCodes(paths.engine), paths.engine)
-            : [];
+            : { entries: [], truncations: [] };
+        const rawFilesOwnership = ownershipExpansion.entries;
+        renderTruncationBanner(ownershipExpansion.truncations);
         // Only walk the patch bodies when the directory actually exists.
         // Fresh projects with no patch queue yet pass through with an empty
         // creators map, which degrades to the old filesAffected-only
@@ -263,7 +313,8 @@ export async function statusCommand(projectRoot, options = {}) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     const rawFiles = await getStatusWithCodes(paths.engine);
-    const files = await expandDirectoryEntries(rawFiles, paths.engine);
+    const { entries: files, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
+    renderTruncationBanner(truncations);
     if (files.length === 0) {
         info('No modified files');
         outro('Working tree clean');

package/dist/src/commands/test.js

@@ -9,20 +9,26 @@ import { pathExists } from '../utils/fs.js';
 import { info, intro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
- * Strips the "engine/" prefix from a path if present.
+ * Strips a leading "engine/" or "engine\\" prefix from a path if present.
  * Users may specify paths like "engine/browser/modules/..." from the project
  * root, but mach test expects paths relative to the engine directory.
+ *
+ * The match is case-insensitive because case-insensitive filesystems
+ * (default macOS, Windows) treat "Engine/" and "engine/" as the same
+ * directory, and a literal lowercase-only check left mach with a
+ * non-stripped prefix that resolved to a different path under the engine
+ * tree. Tab and other whitespace before the prefix is also ignored.
+ *
  * @param testPath - Path as provided by the user
  * @returns Path relative to the engine directory
  */
 function normalizeTestPath(testPath) {
-    if (testPath.startsWith('engine/')) {
-        return testPath.slice('engine/'.length);
+    const trimmed = testPath.trim();
+    const match = /^engine[/\\]/i.exec(trimmed);
+    if (match) {
+        return trimmed.slice(match[0].length);
     }
-    if (testPath.startsWith('engine\\')) {
-        return testPath.slice('engine\\'.length);
-    }
-    return testPath;
+    return trimmed;
 }
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];

package/dist/src/commands/token.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { Option } from 'commander';
 import { loadConfig } from '../core/config.js';
 import { loadFurnaceConfig } from '../core/furnace-config.js';
 import { addToken, getTokensCssPath, validateTokenAdd, } from '../core/token-manager.js';
@@ -96,7 +98,15 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .command('add <token-name> <value>')
         .description('Add a design token to CSS and documentation')
         .requiredOption('--category <cat>', 'Token category (e.g., "Colors — Canvas", "Spacing")')
-        .requiredOption('--mode <mode>', 'Dark mode behavior: auto, static, or override')
+        .addOption(
+    // Use Commander's .choices() so invalid --mode values are rejected with
+    // the built-in "argument must be one of …" message and --help lists the
+    // valid choices up-front. The runtime check in tokenAddCommand remains
+    // as a defence-in-depth guard for programmatic callers that bypass
+    // Commander's argument parsing.
+    new Option('--mode <mode>', 'Dark mode behavior')
+        .choices(['auto', 'static', 'override'])
+        .makeOptionMandatory(true))
         .option('--description <desc>', 'Comment description for the CSS file')
         .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
         .option('--dry-run', 'Show what would be changed without writing')

package/dist/src/commands/watch.js

@@ -1,10 +1,49 @@
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, watchWithOutput, } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner } from '../utils/logger.js';
-import { executableExists } from '../utils/process.js';
+import { exec, executableExists } from '../utils/process.js';
+const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
+/**
+ * Probes watchman by running `watchman --version`. A binary that exists
+ * in PATH but cannot respond (corrupt install, server crashed mid-session,
+ * permission denied on the state directory) would otherwise surface as a
+ * confusing mid-watch failure. Returns the trimmed version string when
+ * the probe succeeds; throws a {@link GeneralError} with actionable
+ * remediation when it does not.
+ */
+async function probeWatchman() {
+    try {
+        const result = await exec('watchman', ['--version'], {
+            timeout: WATCHMAN_PROBE_TIMEOUT_MS,
+        });
+        if (result.exitCode !== 0) {
+            throw new GeneralError(`Watchman is installed but "watchman --version" exited ${result.exitCode}.\n\n` +
+                (result.stderr.trim() ? `Output:\n${result.stderr.trim()}\n\n` : '') +
+                'Re-install or repair watchman, then rerun "fireforge watch".');
+        }
+        const version = result.stdout.trim();
+        if (!version) {
+            throw new GeneralError('Watchman is installed but "watchman --version" produced no output. ' +
+                'Re-install or repair watchman, then rerun "fireforge watch".');
+        }
+        return version;
+    }
+    catch (error) {
+        if (error instanceof GeneralError)
+            throw error;
+        throw new GeneralError(`Watchman is installed but did not respond within ${WATCHMAN_PROBE_TIMEOUT_MS}ms.\n\n` +
+            `Underlying cause: ${toError(error).message}\n\n` +
+            'Common fixes:\n' +
+            '  - Restart watchman: "watchman shutdown-server" then retry\n' +
+            "  - Check filesystem permissions on watchman's state directory\n" +
+            '  - Re-install watchman if the binary is corrupt');
+    }
+}
 /**
  * Builds remediation guidance for objdirs configured before watchman was available.
  * @returns User-facing configure-time watchman guidance
@@ -51,6 +90,11 @@ export async function watchCommand(projectRoot) {
         throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
             'Install watchman first, then rerun "fireforge watch".');
     }
+    // Verify watchman actually responds — a binary that is in PATH but
+    // unable to respond (broken install, crashed server, bad state dir
+    // permissions) would otherwise surface as a confusing mid-build failure
+    // instead of an actionable preflight error.
+    await probeWatchman();
     // Check for build artifacts before starting watch
     const buildCheck = await hasBuildArtifacts(paths.engine);
     if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
@@ -71,6 +115,12 @@ export async function watchCommand(projectRoot) {
             "Run 'fireforge build' first to create the initial build, then run 'fireforge watch'.");
     }
     info(`Using build artifacts from ${buildCheck.objDir}/`);
+    // Advisory: warn when Furnace components have drifted since the last
+    // apply so the user doesn't launch watch-mode builds with stale
+    // components baked in. Mirrors the check in `fireforge run` — without
+    // it, users editing a component then running `watch` would see their
+    // change never surface in the rebuilt browser.
+    await warnIfFurnaceStale(projectRoot);
     // Generate mozconfig (in case it's not up to date)
     const mozconfigSpinner = spinner('Generating mozconfig...');
     try {

package/dist/src/commands/wire.js

@@ -28,6 +28,21 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
     info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
     outro('Dry run complete');
 }
+/**
+ * Validates a subscript name supplied on the command line. Subscripts are
+ * resolved into filenames under the subscript directory and registered in
+ * jar.mn by this name, so any path separator or `..` segment would let
+ * the caller write outside the intended directory or corrupt the manifest.
+ * Mirrors the validation already applied to setup's binaryName and furnace
+ * custom component targetPath.
+ */
+function validateWireName(name) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(name)) {
+        throw new InvalidArgumentError(`Subscript name "${name}" is invalid. ` +
+            'Names must start with a letter or underscore and contain only letters, digits, underscores, or hyphens. ' +
+            'Path separators and parent-directory segments are not permitted.', 'name');
+    }
+}
 /**
  * Wires a chrome subscript into the browser.
  *
@@ -37,6 +52,14 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
  */
 export async function wireCommand(projectRoot, name, options = {}) {
     intro('Wire');
+    validateWireName(name);
+    if (options.after !== undefined) {
+        // --after references an existing init block by its subscript name, so
+        // it must follow the same naming rules as `name` itself. Without this
+        // check, a caller could sneak a path-traversal segment in through
+        // --after and have it forwarded unchanged to the lookup layer.
+        validateWireName(options.after);
+    }
     consumeParserFallbackEvents();
     // Resolve subscript directory: CLI flag > fireforge.json > default
     let subscriptDir = DEFAULT_BROWSER_SUBSCRIPT_DIR;

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

@@ -22,11 +22,25 @@ export function validateConfig(data) {
     catch {
         throw new ConfigError('Config must be an object');
     }
-    // Required string fields
+    // Required string fields. Empty strings would technically pass the
+    // typeof-check below but are never valid for any of these identifier
+    // fields — rejecting them here prevents downstream code (Firefox build,
+    // launcher binary lookup, AppID assertions) from failing with confusing
+    // errors much later.
     const name = requireConfigString(rec, 'name');
     const vendor = requireConfigString(rec, 'vendor');
     const appId = requireConfigString(rec, 'appId');
     const binaryName = requireConfigString(rec, 'binaryName');
+    for (const [field, value] of [
+        ['name', name],
+        ['vendor', vendor],
+        ['appId', appId],
+        ['binaryName', binaryName],
+    ]) {
+        if (value.trim() === '') {
+            throw new ConfigError(`Config field "${field}" must not be empty`);
+        }
+    }
     if (binaryName.includes('..') ||
         binaryName.includes('/') ||
         binaryName.includes('\\') ||

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

@@ -34,7 +34,7 @@ export { addCustomElementRegistration, removeCustomElementRegistration, validate
  * @param tagName - Custom element tag name
  * @param files - Filenames to register (e.g. ["moz-widget.mjs", "moz-widget.css"])
  */
-export declare function addJarMnEntries(engineDir: string, tagName: string, files: string[]): Promise<void>;
+export declare function addJarMnEntries(engineDir: string, tagName: string, files: string[]): Promise<number>;
 /**
  * Removes all jar.mn entries for a given tag name.
  *

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

@@ -69,7 +69,7 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     // check so that "moz-card.css" does not match "moz-card-group.css".
     const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
     if (newFiles.length === 0)
-        return;
+        return 0;
     // Build new entry lines using the indent detected from existing entries.
     const indent = detectJarMnIndent(lines);
     const newEntries = newFiles.map((f) => `${indent}content/global/elements/${f}  (widgets/${tagName}/${f})`);
@@ -111,6 +111,7 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     lines.splice(insertIndex, 0, ...newEntries);
     content = lines.join('\n');
     await writeText(filePath, content);
+    return newFiles.length;
 }
 /**
  * Removes all jar.mn entries for a given tag name.

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

@@ -0,0 +1,17 @@
+/**
+ * Furnace staleness advisory — shared between `fireforge run` and
+ * `fireforge watch`. Both commands launch the built browser without
+ * first running `furnace apply`, so this helper surfaces a warning when
+ * component files have drifted from the last-applied checksums and the
+ * user is about to run with stale engine state.
+ *
+ * The check is advisory only: errors (broken furnace config, partial
+ * state, transient filesystem failure) must never block the caller.
+ */
+/**
+ * Emits a warning when any tracked override or custom component has
+ * changed on disk since the last apply. Safe to call from any build-time
+ * command that does not auto-apply — a failure inside the probe is
+ * downgraded to a verbose log and the caller continues.
+ */
+export declare function warnIfFurnaceStale(projectRoot: string): Promise<void>;

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

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Furnace staleness advisory — shared between `fireforge run` and
+ * `fireforge watch`. Both commands launch the built browser without
+ * first running `furnace apply`, so this helper surfaces a warning when
+ * component files have drifted from the last-applied checksums and the
+ * user is about to run with stale engine state.
+ *
+ * The check is advisory only: errors (broken furnace config, partial
+ * state, transient filesystem failure) must never block the caller.
+ */
+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';
+/**
+ * Emits a warning when any tracked override or custom component has
+ * changed on disk since the last apply. Safe to call from any build-time
+ * command that does not auto-apply — a failure inside the probe is
+ * downgraded to a verbose log and the caller continues.
+ */
+export async function warnIfFurnaceStale(projectRoot) {
+    try {
+        if (!(await furnaceConfigExists(projectRoot)))
+            return;
+        const config = await loadFurnaceConfig(projectRoot);
+        const state = await loadFurnaceState(projectRoot);
+        const furnacePaths = getFurnacePaths(projectRoot);
+        if (!state.appliedChecksums)
+            return;
+        const stale = [];
+        for (const name of Object.keys(config.overrides)) {
+            const dir = `${furnacePaths.overridesDir}/${name}`;
+            if (!(await pathExists(dir)))
+                continue;
+            const prev = extractComponentChecksums(state.appliedChecksums, 'override', name);
+            if (await hasComponentChanged(dir, prev))
+                stale.push(name);
+        }
+        for (const name of Object.keys(config.custom)) {
+            const dir = `${furnacePaths.customDir}/${name}`;
+            if (!(await pathExists(dir)))
+                continue;
+            const prev = extractComponentChecksums(state.appliedChecksums, 'custom', name);
+            if (await hasComponentChanged(dir, prev))
+                stale.push(name);
+        }
+        if (stale.length > 0) {
+            warn(`Furnace component${stale.length === 1 ? '' : 's'} modified since last apply: ${stale.join(', ')}. ` +
+                'Run "fireforge furnace apply" (or "fireforge build" which auto-applies) to update the engine.');
+        }
+    }
+    catch {
+        // Non-fatal: a broken furnace config should not block the caller.
+        verbose('Furnace staleness check skipped due to an error.');
+    }
+}
+//# sourceMappingURL=furnace-staleness.js.map

package/dist/src/core/signal-critical.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Signal-deferred critical sections.
+ *
+ * Commands that perform a compound mutation (e.g. "apply a patch to the
+ * engine, then persist progress to a session file on disk") need to finish
+ * the pair atomically with respect to SIGINT / SIGTERM. The furnace rollback
+ * mechanism is not the right tool here: rebase-style operations intentionally
+ * leave the engine mutated and only need the on-disk bookkeeping write to
+ * complete before the process exits.
+ *
+ * `runInSignalCriticalSection(fn)` wraps a short body in a registry slot.
+ * While the body runs, the CLI entry point's SIGINT / SIGTERM handlers wait
+ * for the slot to clear before calling `process.exit`, so a signal that
+ * lands mid-body is held until the body's state write finishes.
+ *
+ * This module is a pure runtime registry — it installs no signal handlers
+ * itself. The bin entry point is responsible for awaiting
+ * `waitForActiveCriticalSections` before terminating.
+ */
+/**
+ * Runs `fn` inside a signal-deferred critical section. The CLI entry point's
+ * signal handlers `await` every active section before exiting, so a SIGINT or
+ * SIGTERM that arrives during `fn` will hold exit until `fn` returns (or
+ * rejects).
+ *
+ * `fn` should be short — anything that takes longer than the bounded wait in
+ * the bin handler (`SIGNAL_CRITICAL_SECTION_TIMEOUT_MS`) will time out and
+ * the handler will exit anyway. The intent is "guard the apply + state
+ * persist pair," not "postpone exit indefinitely."
+ */
+export declare function runInSignalCriticalSection<T>(label: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Returns true while any critical section is currently running. Used by the
+ * bin entry point's signal handler to decide whether to await before exit.
+ */
+export declare function hasActiveCriticalSection(): boolean;
+/**
+ * Waits for every active critical section to complete or for `timeoutMs` to
+ * elapse, whichever comes first. Never rejects: a section that throws still
+ * resolves from the registry's perspective because `runInSignalCriticalSection`
+ * cleans up in `finally`.
+ */
+export declare function waitForActiveCriticalSections(timeoutMs: number): Promise<void>;
+/**
+ * Test-only helper: clears the critical-section registry. Production code
+ * must never call this — it voids the exit-ordering guarantee for any
+ * section still in flight.
+ */
+export declare function resetCriticalSectionsForTests(): void;