@hominis/fireforge 0.30.1 → 0.31.0

package/dist/src/commands/wire.js

@@ -144,39 +144,12 @@ async function ensureSubscriptSourceExists(projectRoot, subscriptDir, name, dryR
     }
 }
 /**
- * Wires a chrome subscript into the browser.
- *
- * @param projectRoot - Root directory of the project
- * @param name - Subscript name (without .js extension)
- * @param options - Command options
+ * Validates the `--dom` fragment argument and computes its engine-root-
+ * relative path. Accepts absolute, repo-root-relative (`engine/...`), and
+ * engine-relative inputs; rejects missing files and paths escaping
+ * engine/. Returns undefined when `--dom` was not supplied.
  */
-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);
-    }
-    // Validate init/destroy expressions BEFORE the dry-run/real fork so
-    // both paths enforce the same contract. Pre-0.16.0, validation only
-    // ran inside `addInitToBrowserInit`/`addDestroyToBrowserInit` (the
-    // real-execution path), so `--dry-run --init 'void 0'` succeeded and
-    // rendered a plausible-looking preview even though the real run would
-    // reject the same arguments. Dropping `void 0` into the template
-    // silently (or breaking out of the string literal) was already
-    // prevented downstream — this hoist just makes the failure surface
-    // identical in preview mode.
-    if (options.init !== undefined) {
-        validateWireExpression(options.init, 'init expression');
-    }
-    if (options.destroy !== undefined) {
-        validateWireExpression(options.destroy, 'destroy expression');
-    }
-    consumeParserFallbackEvents();
-    const subscriptDir = await resolveWireSubscriptDir(projectRoot, options);
+async function resolveDomFragmentPath(projectRoot, dom) {
     // Validate DOM fragment file exists and compute path relative to engine root.
     //
     // Accepts three shapes:
@@ -193,12 +166,11 @@ export async function wireCommand(projectRoot, name, options = {}) {
     // packaging-breaking nonsense. For absolute inputs this pre-existing
     // contract was fine — `toRootRelativePath` handles absolute candidates
     // correctly — so we only strip the prefix when the input is relative.
-    let domFilePath;
-    if (options.dom) {
+    if (!dom)
+        return undefined;
+    {
         const paths = getProjectPaths(projectRoot);
-        const domCandidate = isExplicitAbsolutePath(options.dom)
-            ? options.dom
-            : stripEnginePrefix(options.dom);
+        const domCandidate = isExplicitAbsolutePath(dom) ? dom : stripEnginePrefix(dom);
         // `pathExists` resolves relative paths against CWD, so an engine-
         // relative `domCandidate` (e.g. `browser/base/content/foo.inc.xhtml`)
         // would be probed inside the operator's shell directory rather than
@@ -213,50 +185,21 @@ export async function wireCommand(projectRoot, name, options = {}) {
             ? domCandidate
             : join(paths.engine, domCandidate);
         if (!(await pathExists(domProbePath))) {
-            throw new InvalidArgumentError(`DOM fragment file not found: ${options.dom}`, 'dom');
+            throw new InvalidArgumentError(`DOM fragment file not found: ${dom}`, 'dom');
         }
         if (!isPathInsideRoot(paths.engine, domCandidate)) {
-            throw new InvalidArgumentError(`DOM fragment file must stay within engine/: ${options.dom}`, 'dom');
+            throw new InvalidArgumentError(`DOM fragment file must stay within engine/: ${dom}`, 'dom');
         }
-        domFilePath = toRootRelativePath(paths.engine, domCandidate);
-    }
-    // Resolve the chrome document the `#include` directive will land in.
-    // Only consulted when `--dom` is supplied — we still resolve it here so
-    // the dry-run plan can print the target accurately.
-    //
-    // `stripEnginePrefix` is applied so `--target engine/browser/base/browser.xhtml`
-    // and `--target browser/base/browser.xhtml` are treated identically,
-    // matching the `--dom` normalization above. Absolute `--target` paths
-    // stay absolute (the containment check downstream rejects them).
-    const normalizedTarget = options.target !== undefined && !isExplicitAbsolutePath(options.target)
-        ? stripEnginePrefix(options.target)
-        : options.target;
-    if (normalizedTarget !== undefined && !isContainedRelativePath(normalizedTarget)) {
-        throw new InvalidArgumentError(`Target chrome document must stay within engine/: ${options.target ?? ''}`, 'target');
+        return toRootRelativePath(paths.engine, domCandidate);
     }
-    const domTargetPath = await resolveDomTargetPath(projectRoot, normalizedTarget);
-    if (domFilePath) {
-        await assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath);
-    }
-    // Verify the subscript file exists in engine/ (skip for dry-run:
-    // dry-run is meant to preview the mutation plan without requiring
-    // the subscript to already exist, matching the "plan before write"
-    // pattern operators rely on for setup scripts).
-    //
-    // Dry-run keeps the existence check advisory rather than fatal: the
-    // "wire first, create file after" workflow is a legitimate use of
-    // preview, but operators who run dry-run over a typo were surprised
-    // when the real command then refused with `Subscript file not
-    // found`. 2026-04-23 eval (Finding in eval 2): dry-run produced a
-    // plausible plan and the non-dry-run invocation then errored. The
-    // info line surfaces the mismatch in preview mode so the operator
-    // can act on the warning before re-running without --dry-run.
-    await ensureSubscriptSourceExists(projectRoot, subscriptDir, name, options.dryRun ?? false);
-    if (options.dryRun) {
-        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);
-        return;
-    }
-    const result = await wireSubscript(projectRoot, name, {
+}
+/**
+ * Builds the wireSubscript option bag from the command flags, omitting
+ * every key whose flag is absent (exactOptionalPropertyTypes) and the
+ * defaults the lower layer already assumes.
+ */
+function buildWireSubscriptOptions(options, domFilePath, domTargetPath, subscriptDir) {
+    return {
         ...(options.init !== undefined ? { init: options.init } : {}),
         ...(options.destroy !== undefined ? { destroy: options.destroy } : {}),
         ...(domFilePath !== undefined ? { domFilePath } : {}),
@@ -264,12 +207,25 @@ export async function wireCommand(projectRoot, name, options = {}) {
         ...(options.after !== undefined ? { after: options.after } : {}),
         ...(subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR ? { subscriptDir } : {}),
         dryRun: false,
-    });
+    };
+}
+/**
+ * Surfaces any legacy parser fallbacks the wiring run consumed, so the
+ * operator knows which files were mutated by the regex path rather than
+ * the AST path.
+ */
+function reportParserFallbacks() {
     const parserFallbacks = consumeParserFallbackEvents();
     if (parserFallbacks.length > 0) {
         const contexts = [...new Set(parserFallbacks.map((event) => event.context))];
         info(`Legacy parser fallback was used for ${contexts.length} file${contexts.length === 1 ? '' : 's'}: ${contexts.join(', ')}`);
     }
+}
+/**
+ * Prints the per-mutation success/skip rows for a completed (non-dry-run)
+ * wire invocation.
+ */
+function reportWireResult(result, name, options, domFilePath, domTargetPath) {
     if (result.subscriptAdded) {
         success(`Added loadSubScript for ${name}.js to browser-main.js`);
     }
@@ -306,6 +262,81 @@ export async function wireCommand(projectRoot, name, options = {}) {
     else {
         success(`Registered ${name}.js in ${result.jarMnResult.manifest}`);
     }
+}
+/**
+ * Wires a chrome subscript into the browser.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param name - Subscript name (without .js extension)
+ * @param options - Command 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);
+    }
+    // Validate init/destroy expressions BEFORE the dry-run/real fork so
+    // both paths enforce the same contract. Pre-0.16.0, validation only
+    // ran inside `addInitToBrowserInit`/`addDestroyToBrowserInit` (the
+    // real-execution path), so `--dry-run --init 'void 0'` succeeded and
+    // rendered a plausible-looking preview even though the real run would
+    // reject the same arguments. Dropping `void 0` into the template
+    // silently (or breaking out of the string literal) was already
+    // prevented downstream — this hoist just makes the failure surface
+    // identical in preview mode.
+    if (options.init !== undefined) {
+        validateWireExpression(options.init, 'init expression');
+    }
+    if (options.destroy !== undefined) {
+        validateWireExpression(options.destroy, 'destroy expression');
+    }
+    consumeParserFallbackEvents();
+    const subscriptDir = await resolveWireSubscriptDir(projectRoot, options);
+    const domFilePath = await resolveDomFragmentPath(projectRoot, options.dom);
+    // Resolve the chrome document the `#include` directive will land in.
+    // Only consulted when `--dom` is supplied — we still resolve it here so
+    // the dry-run plan can print the target accurately.
+    //
+    // `stripEnginePrefix` is applied so `--target engine/browser/base/browser.xhtml`
+    // and `--target browser/base/browser.xhtml` are treated identically,
+    // matching the `--dom` normalization above. Absolute `--target` paths
+    // stay absolute (the containment check downstream rejects them).
+    const normalizedTarget = options.target !== undefined && !isExplicitAbsolutePath(options.target)
+        ? stripEnginePrefix(options.target)
+        : options.target;
+    if (normalizedTarget !== undefined && !isContainedRelativePath(normalizedTarget)) {
+        throw new InvalidArgumentError(`Target chrome document must stay within engine/: ${options.target ?? ''}`, 'target');
+    }
+    const domTargetPath = await resolveDomTargetPath(projectRoot, normalizedTarget);
+    if (domFilePath) {
+        await assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath);
+    }
+    // Verify the subscript file exists in engine/ (skip for dry-run:
+    // dry-run is meant to preview the mutation plan without requiring
+    // the subscript to already exist, matching the "plan before write"
+    // pattern operators rely on for setup scripts).
+    //
+    // Dry-run keeps the existence check advisory rather than fatal: the
+    // "wire first, create file after" workflow is a legitimate use of
+    // preview, but operators who run dry-run over a typo were surprised
+    // when the real command then refused with `Subscript file not
+    // found`. 2026-04-23 eval (Finding in eval 2): dry-run produced a
+    // plausible plan and the non-dry-run invocation then errored. The
+    // info line surfaces the mismatch in preview mode so the operator
+    // can act on the warning before re-running without --dry-run.
+    await ensureSubscriptSourceExists(projectRoot, subscriptDir, name, options.dryRun ?? false);
+    if (options.dryRun) {
+        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);
+        return;
+    }
+    const result = await wireSubscript(projectRoot, name, buildWireSubscriptOptions(options, domFilePath, domTargetPath, subscriptDir));
+    reportParserFallbacks();
+    reportWireResult(result, name, options, domFilePath, domTargetPath);
     outro('Wiring complete');
 }
 /** Registers the wire command on the CLI program. */

package/dist/src/core/build-audit.d.ts

@@ -1,4 +1,4 @@
-import type { BuildBaseline } from './build-baseline.js';
+import type { BuildBaseline } from './build-baseline-types.js';
 /** Result of a single artifact lookup. */
 export interface AuditEntry {
     /** Engine-relative source file path (POSIX separators). */

package/dist/src/core/build-audit.js

@@ -35,16 +35,13 @@
  */
 import { stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { detectPlatformGate } from './build-audit-platform.js';
 import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByRegistration, } from './build-audit-registration.js';
 import { countTrailingSegmentMatches, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
 import { resolveArtifactByKnownTransform } from './build-audit-transforms.js';
-import { hasChanges, isMissingHeadError } from './git.js';
-import { git } from './git-base.js';
-import { getUntrackedFiles } from './git-status.js';
+import { collectChangedEnginePaths } from './engine-changes.js';
 /** Path extensions that are conventionally packaged into the Firefox bundle. */
 const PACKAGEABLE_EXTENSIONS = [
     '.js',
@@ -114,47 +111,6 @@ export function isPackageablePath(sourcePath) {
     }
     return false;
 }
-/**
- * Collects engine-relative paths changed since the baseline's HEAD SHA.
- * Always includes modified + untracked workdir paths. When the baseline is
- * missing or the engine has no HEAD yet, falls back to workdir-only diffs.
- */
-async function collectChangedFiles(engineDir, baseline) {
-    const collected = new Set();
-    if (baseline?.engineHeadSha) {
-        try {
-            const output = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
-            for (const line of output.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-        }
-        catch (error) {
-            if (!isMissingHeadError(error)) {
-                verbose(`Audit: could not diff against baseline SHA — ${toError(error).message}`);
-            }
-        }
-    }
-    try {
-        if (await hasChanges(engineDir)) {
-            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
-            for (const line of worktreeDiff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-            const untracked = await getUntrackedFiles(engineDir);
-            for (const file of untracked) {
-                collected.add(file);
-            }
-        }
-    }
-    catch (error) {
-        verbose(`Audit: could not enumerate workdir changes — ${toError(error).message}`);
-    }
-    return [...collected].sort();
-}
 /*
  * Finds the unique obj-star directory with a dist subtree, or undefined
  * when zero or multiple match. The ambiguous case is already rejected
@@ -500,7 +456,7 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
     }
     const testsRoot = await resolveTestsRoot(engineDir);
     const testsPackaged = await hasPackagedTestsMarker(testsRoot);
-    const changed = await collectChangedFiles(engineDir, baseline);
+    const changed = await collectChangedEnginePaths(engineDir, baseline, 'Audit');
     if (changed.length === 0) {
         return summary;
     }

package/dist/src/core/build-baseline-types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Type of the last-build baseline marker, split out of `build-baseline.ts`
+ * so its consumers (`build-audit`, `build-prepare`, `test-stale-check`) can
+ * import the shape without importing the I/O module — `build-baseline.ts`
+ * itself depends on `build-audit.ts` at runtime, and a type import back
+ * into it would make the dependency graph cyclic.
+ */
+/** Shape of the on-disk baseline marker. */
+export interface BuildBaseline {
+    /** SHA of engine HEAD at the time the build succeeded. */
+    engineHeadSha: string;
+    /**
+     * ISO-8601 timestamp of when the baseline was recorded. Informational —
+     * downstream code keys off `engineHeadSha` for diffs, but the timestamp
+     * helps operators reason about stale markers.
+     */
+    builtAt: string;
+    /**
+     * The binaryName used at build time. Captured so the dist-tree audit
+     * can resolve the expected bundle root under obj-star/dist/ even when
+     * the project has since been renamed.
+     */
+    binaryName: string;
+    /**
+     * Content hash per packageable engine path that was dirty at build
+     * time (modified-against-HEAD or untracked). Used by
+     * `checkStaleBuildForTest` to distinguish "this file's content was
+     * already in `dist/` when the build completed" from "this file has
+     * been edited since". Missing on baselines written before 0.16.0; the
+     * stale-check falls back to the path-only comparison in that case,
+     * so older baselines retain their existing behavior.
+     *
+     * Keys are engine-relative POSIX paths. Values are hex-encoded
+     * SHA-256 digests of the file contents at the moment the baseline
+     * was recorded.
+     */
+    packageableFingerprints?: Record<string, string>;
+}

package/dist/src/core/build-baseline-types.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Type of the last-build baseline marker, split out of `build-baseline.ts`
+ * so its consumers (`build-audit`, `build-prepare`, `test-stale-check`) can
+ * import the shape without importing the I/O module — `build-baseline.ts`
+ * itself depends on `build-audit.ts` at runtime, and a type import back
+ * into it would make the dependency graph cyclic.
+ */
+export {};
+//# sourceMappingURL=build-baseline-types.js.map

package/dist/src/core/build-baseline.d.ts

@@ -15,37 +15,7 @@
  * on successful build completion; a failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-/** Shape of the on-disk baseline marker. */
-export interface BuildBaseline {
-    /** SHA of engine HEAD at the time the build succeeded. */
-    engineHeadSha: string;
-    /**
-     * ISO-8601 timestamp of when the baseline was recorded. Informational —
-     * downstream code keys off `engineHeadSha` for diffs, but the timestamp
-     * helps operators reason about stale markers.
-     */
-    builtAt: string;
-    /**
-     * The binaryName used at build time. Captured so the dist-tree audit
-     * can resolve the expected bundle root under obj-star/dist/ even when
-     * the project has since been renamed.
-     */
-    binaryName: string;
-    /**
-     * Content hash per packageable engine path that was dirty at build
-     * time (modified-against-HEAD or untracked). Used by
-     * `checkStaleBuildForTest` to distinguish "this file's content was
-     * already in `dist/` when the build completed" from "this file has
-     * been edited since". Missing on baselines written before 0.16.0; the
-     * stale-check falls back to the path-only comparison in that case,
-     * so older baselines retain their existing behavior.
-     *
-     * Keys are engine-relative POSIX paths. Values are hex-encoded
-     * SHA-256 digests of the file contents at the moment the baseline
-     * was recorded.
-     */
-    packageableFingerprints?: Record<string, string>;
-}
+import type { BuildBaseline } from './build-baseline-types.js';
 /** Name of the last-build marker file under `.fireforge/`. */
 export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 /**

package/dist/src/core/build-prepare.d.ts

@@ -3,7 +3,7 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
-import type { BuildBaseline } from './build-baseline.js';
+import type { BuildBaseline } from './build-baseline-types.js';
 /**
  * Result of the build preparation phase.
  */

package/dist/src/core/build-prepare.js

@@ -9,13 +9,11 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
+import { collectChangedEnginePaths } from './engine-changes.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
 import { runFurnaceMutation } from './furnace-operation.js';
 import { cleanStories } from './furnace-stories.js';
-import { hasChanges, isMissingHeadError } from './git.js';
-import { git } from './git-base.js';
-import { getUntrackedFiles } from './git-status.js';
 import { generateMozconfig, runMach } from './mach.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
@@ -30,47 +28,6 @@ export function isBackendInvalidatingFile(path) {
     }
     return false;
 }
-/**
- * Collects engine-relative paths of files changed since the baseline's HEAD
- * SHA plus any workdir modifications. Defensive — git failures surface as
- * verbose lines and return the files collected so far. An empty result
- * means "no drift we can prove" rather than "no drift occurred".
- */
-async function collectBackendRelevantChanges(engineDir, baseline) {
-    const collected = new Set();
-    if (baseline.engineHeadSha) {
-        try {
-            const diff = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
-            for (const line of diff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-        }
-        catch (error) {
-            if (!isMissingHeadError(error)) {
-                verbose(`Auto-configure: could not diff engine against baseline — ${toError(error).message}`);
-            }
-        }
-    }
-    try {
-        if (await hasChanges(engineDir)) {
-            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
-            for (const line of worktreeDiff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-            for (const file of await getUntrackedFiles(engineDir)) {
-                collected.add(file);
-            }
-        }
-    }
-    catch (error) {
-        verbose(`Auto-configure: could not enumerate workdir changes — ${toError(error).message}`);
-    }
-    return [...collected];
-}
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Cleans Furnace stories from engine (prevents leaking into production)
@@ -101,7 +58,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     // work against a stale recursive-make backend.
     let reconfigured = false;
     if (options.previousBaseline) {
-        const changed = await collectBackendRelevantChanges(paths.engine, options.previousBaseline);
+        const changed = await collectChangedEnginePaths(paths.engine, options.previousBaseline, 'Auto-configure');
         const invalidating = changed.filter(isBackendInvalidatingFile);
         if (invalidating.length > 0) {
             info(`Backend config changed; running backend regeneration first (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched).`);

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

@@ -8,14 +8,6 @@ export declare const CONFIG_FILENAME = "fireforge.json";
 export declare const FIREFORGE_DIR = ".fireforge";
 /** Name of the state file */
 export declare const STATE_FILENAME = "state.json";
-/** Name of the engine directory */
-export declare const ENGINE_DIR = "engine";
-/** Name of the patches directory */
-export declare const PATCHES_DIR = "patches";
-/** Name of the configs directory */
-export declare const CONFIGS_DIR = "configs";
-/** Name of the source directory */
-export declare const SRC_DIR = "src";
 /** Supported top-level fireforge.json keys backed by the current schema. */
 export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */

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

@@ -10,13 +10,13 @@ export const FIREFORGE_DIR = '.fireforge';
 /** Name of the state file */
 export const STATE_FILENAME = 'state.json';
 /** Name of the engine directory */
-export const ENGINE_DIR = 'engine';
+const ENGINE_DIR = 'engine';
 /** Name of the patches directory */
-export const PATCHES_DIR = 'patches';
+const PATCHES_DIR = 'patches';
 /** Name of the configs directory */
-export const CONFIGS_DIR = 'configs';
+const CONFIGS_DIR = 'configs';
 /** Name of the source directory */
-export const SRC_DIR = 'src';
+const SRC_DIR = 'src';
 /** Supported top-level fireforge.json keys backed by the current schema. */
 export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'name',

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

@@ -2,12 +2,6 @@
  * Project state file management (.fireforge/state.json).
  */
 import type { FireForgeState } from '../types/config.js';
-/**
- * Validates a parsed project state object and returns a typed FireForgeState.
- * @param data - Parsed JSON state data
- * @returns Validated FireForgeState
- */
-export declare function validateFireForgeState(data: unknown): FireForgeState;
 /**
  * Loads the fireforge state, or returns defaults if it doesn't exist.
  * @param root - Root directory of the project

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

@@ -70,7 +70,7 @@ function sanitizeProjectState(data) {
  * @param data - Parsed JSON state data
  * @returns Validated FireForgeState
  */
-export function validateFireForgeState(data) {
+function validateFireForgeState(data) {
     const result = sanitizeProjectState(data);
     if (result.issues.length > 0) {
         throw new ConfigError(`Invalid FireForge state: ${result.issues.join('; ')}`);

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

@@ -28,7 +28,13 @@ function parsePatchPolicyCategory(raw, label) {
     }
     return raw;
 }
-function parsePatchPolicyRange(raw, label) {
+/**
+ * Shared head of every patch-policy range shape: the value must be an
+ * object carrying positive integer `from`/`to` endpoints with
+ * `to >= from`. Returns the parsed record so callers can read their
+ * shape-specific fields from it.
+ */
+function parseRangeBounds(raw, label) {
     let rec;
     try {
         rec = parseObject(raw, label);
@@ -41,6 +47,10 @@ function parsePatchPolicyRange(raw, label) {
     if (to < from) {
         throw new ConfigError(`Config field "${label}.to" must be greater than or equal to from`);
     }
+    return { rec, from, to };
+}
+function parsePatchPolicyRange(raw, label) {
+    const { rec, from, to } = parseRangeBounds(raw, label);
     return {
         from,
         to,
@@ -90,18 +100,7 @@ function parseReservedAllowedPatch(raw, label) {
     return out;
 }
 function parsePatchPolicyReservedRange(raw, label) {
-    let rec;
-    try {
-        rec = parseObject(raw, label);
-    }
-    catch {
-        throw new ConfigError(`Config field "${label}" must be an object`);
-    }
-    const from = parsePositiveRangeEndpoint(rec.raw('from'), `${label}.from`);
-    const to = parsePositiveRangeEndpoint(rec.raw('to'), `${label}.to`);
-    if (to < from) {
-        throw new ConfigError(`Config field "${label}.to" must be greater than or equal to from`);
-    }
+    const { rec, from, to } = parseRangeBounds(raw, label);
     const allowedRaw = rec.raw('allowed');
     if (!Array.isArray(allowedRaw)) {
         throw new ConfigError(`Config field "${label}.allowed" must be an array`);