@hominis/fireforge 0.21.0 → 0.21.2

package/dist/src/commands/patch/rename.js

@@ -18,12 +18,13 @@
  */
 import { rename as fsRename } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectPaths } from '../../core/config.js';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { sanitizeName } from '../../core/patch-export.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, resolvePatchIdentifier, savePatchesManifest, } from '../../core/patch-manifest.js';
+import { buildProjectedManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -66,23 +67,40 @@ async function commitRenameUnderLock(input) {
         if (!before) {
             throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during rename.`);
         }
+        let oldPath;
+        let newPath;
         if (filenameChanging) {
             const collisionInLock = fresh.patches.find((p) => p.filename === newFilename && p.filename !== target.filename);
             if (collisionInLock) {
                 throw new InvalidArgumentError(`Cannot rename to "${newFilename}" — a different patch claimed that filename concurrently.`, 'patch rename');
             }
-            const oldPath = join(patchesDir, target.filename);
-            const newPath = join(patchesDir, newFilename);
+            oldPath = join(patchesDir, target.filename);
+            newPath = join(patchesDir, newFilename);
             if (await pathExists(newPath)) {
                 throw new InvalidArgumentError(`Cannot rename: ${newFilename} already exists on disk. Resolve manually before retrying.`, 'patch rename');
             }
-            await fsRename(oldPath, newPath);
             fresh.patches[idx] = {
                 ...before,
                 filename: newFilename,
                 name: newName,
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
+        }
+        else {
+            fresh.patches[idx] = {
+                ...before,
+                ...(nameChanging ? { name: newName } : {}),
+                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
+            };
+        }
+        enforcePatchPolicy({
+            config: input.config,
+            manifest: buildProjectedManifest(fresh, fresh.patches),
+            command: 'patch rename',
+            forceUnsafe: input.forceUnsafe === true,
+        });
+        if (filenameChanging && oldPath !== undefined && newPath !== undefined) {
+            await fsRename(oldPath, newPath);
             try {
                 await savePatchesManifest(patchesDir, fresh);
             }
@@ -97,11 +115,6 @@ async function commitRenameUnderLock(input) {
             }
         }
         else {
-            fresh.patches[idx] = {
-                ...before,
-                ...(nameChanging ? { name: newName } : {}),
-                ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
-            };
             await savePatchesManifest(patchesDir, fresh);
         }
         try {
@@ -115,6 +128,7 @@ async function commitRenameUnderLock(input) {
                     ...(descriptionChanging ? { oldDescription: target.description, newDescription } : {}),
                 },
                 ...(input.yes === true ? { yes: true } : {}),
+                ...(input.forceUnsafe === true ? { unsafeOverride: true } : {}),
                 result: 'ok',
             });
         }
@@ -138,6 +152,7 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
         throw new InvalidArgumentError('Specify --to <new-name>. The new name is sanitised into the filename slug the same way `export --name` is.', 'patch rename');
     }
     const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
         throw new GeneralError('Patches directory not found.');
     }
@@ -187,6 +202,19 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
     if (descriptionChanging) {
         summary.push(`description: "${target.description || '(none)'}" → "${options.description ?? '(none)'}"`);
     }
+    enforcePatchPolicy({
+        config,
+        manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === target.filename
+            ? {
+                ...entry,
+                filename: newFilename,
+                name: nameChanging ? (options.to ?? entry.name) : entry.name,
+                ...(descriptionChanging ? { description: options.description ?? '' } : {}),
+            }
+            : entry)),
+        command: 'patch rename',
+        forceUnsafe: options.forceUnsafe === true,
+    });
     const decision = await confirmDestructive({
         operation: 'patch-rename',
         title: `Rename ${target.filename}`,
@@ -213,6 +241,8 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
         nameChanging,
         descriptionChanging,
         ...(options.yes === true ? { yes: true } : {}),
+        ...(options.forceUnsafe === true ? { forceUnsafe: true } : {}),
+        config,
     });
     if (filenameChanging) {
         info(`${target.filename} → ${newFilename}`);
@@ -237,6 +267,7 @@ export function registerPatchRename(parent, context) {
         .option('--description <text>', 'Replacement description (omit to leave description unchanged)')
         .option('--dry-run', 'Show what would change without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--force-unsafe', 'Bypass force-mode patchPolicy refusals')
         .action(withErrorHandling(async (name, options) => {
         await patchRenameCommand(getProjectRoot(), name, pickDefined(options));
     }));

package/dist/src/commands/patch/reorder.js

@@ -9,12 +9,13 @@
  * before any bytes move.
  */
 import { Option } from 'commander';
-import { getProjectPaths } from '../../core/config.js';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive, } from '../../core/destructive.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
+import { applyRenameMapToManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -184,7 +185,7 @@ function resolveDestination(target, manifestPatches, options) {
     }
     return { destinationOrder: anchor.order + 1, anchorFilename: anchor.filename };
 }
-async function commitReorderPlan(patchesDir, target, renameMap, anchorFilename, options, buildHistoryEntry) {
+async function commitReorderPlan(patchesDir, target, renameMap, anchorFilename, options, config, buildHistoryEntry) {
     await withPatchDirectoryLock(patchesDir, async () => {
         const currentManifest = await loadPatchesManifest(patchesDir);
         if (!currentManifest || currentManifest.patches.length === 0) {
@@ -216,6 +217,12 @@ async function commitReorderPlan(patchesDir, target, renameMap, anchorFilename,
         if (!renameMapsEqual(renameMap, currentRenameMap)) {
             throw new GeneralError('Patch queue changed while waiting for confirmation. Re-run reorder to recompute the rename plan.');
         }
+        enforcePatchPolicy({
+            config,
+            manifest: applyRenameMapToManifest(currentManifest, currentRenameMap),
+            command: 'patch reorder',
+            forceUnsafe: options.forceUnsafe === true,
+        });
         const currentProjected = projectReorder(await buildPatchQueueContext(patchesDir), currentRenameMap);
         const currentConflicts = lintPatchQueue(currentProjected).filter((i) => i.severity === 'error');
         if (currentConflicts.length > 0 && options.forceUnsafe !== true) {
@@ -262,6 +269,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
         throw new InvalidArgumentError('--to, --before, and --after are mutually exclusive.', 'patch reorder');
     }
     const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
         throw new GeneralError('Patches directory not found.');
     }
@@ -286,6 +294,12 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
     const projected = projectReorder(baseCtx, renameMap);
     const projectedIssues = lintPatchQueue(projected);
     const errorIssues = projectedIssues.filter((i) => i.severity === 'error');
+    enforcePatchPolicy({
+        config,
+        manifest: applyRenameMapToManifest(manifest, renameMap),
+        command: 'patch reorder',
+        forceUnsafe: options.forceUnsafe === true,
+    });
     const conflicts = errorIssues.length > 0
         ? {
             reason: `reorder would introduce ${errorIssues.length} cross-patch lint error(s)`,
@@ -344,7 +358,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
             result: 'ok',
         };
     };
-    await commitReorderPlan(paths.patches, target, renameMap, anchorFilename, options, buildHistoryEntry);
+    await commitReorderPlan(paths.patches, target, renameMap, anchorFilename, options, config, buildHistoryEntry);
     info(`Reordered ${renameMap.size} patch(es).`);
     outro('Reorder complete');
 }

package/dist/src/commands/re-export-files.js

@@ -6,6 +6,8 @@ import { computeProjectedLintRegressions } from '../core/lint-projection.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
@@ -163,6 +165,16 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
     await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
     const conflicts = await runProjectedCrossPatchLint(paths.patches, target.filename, projectedDiff);
+    const filesUpdates = buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet);
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (manifest) {
+        enforcePatchPolicy({
+            config,
+            manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === target.filename ? { ...entry, ...filesUpdates } : entry)),
+            command: 're-export --files',
+            forceUnsafe: options.forceUnsafe === true,
+        });
+    }
     // Shrinks are destructive (previously-owned files become unmanaged).
     // Additive-only changes still deserve a prompt because --files asserts
     // an authoritative file set.
@@ -205,7 +217,6 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // directory lock as the mutation (via the onCommitted hook) so two
     // concurrent re-exports cannot interleave records and a crash between
     // mutation and append cannot orphan the audit trail.
-    const filesUpdates = buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet);
     await updatePatchAndMetadata(paths.patches, target.filename, projectedDiff, filesUpdates, async () => {
         await appendHistory(paths.patches, {
             operation: 're-export-files',
@@ -219,6 +230,10 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
             ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
             result: 'ok',
         });
+    }, {
+        config,
+        command: 're-export --files',
+        forceUnsafe: options.forceUnsafe === true,
     });
     success(`Re-exported ${target.filename}`);
     outro('Re-export complete');

package/dist/src/commands/re-export.js

@@ -8,6 +8,7 @@ import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
+import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -218,6 +219,21 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
     const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
     const effectiveTier = options.tier ?? patch.tier;
+    const updates = {
+        filesAffected: currentFilesAffected,
+    };
+    if (options.tier !== undefined) {
+        updates.tier = options.tier;
+    }
+    if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
+        updates.lintIgnore = effectiveLintIgnore;
+    }
+    enforcePatchPolicy({
+        config,
+        manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === patch.filename ? { ...entry, ...updates } : entry)),
+        command: 're-export',
+        forceUnsafe: options.forceUnsafe === true,
+    });
     await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
     if (isDryRun) {
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
@@ -235,16 +251,11 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         // sequence allows a concurrent `resolve` / `rebase --continue` / `patch
         // compact` / `patch reorder` to rewrite the manifest between the two
         // writes and leave patch body and `filesAffected` disagreeing.
-        const updates = {
-            filesAffected: currentFilesAffected,
-        };
-        if (options.tier !== undefined) {
-            updates.tier = options.tier;
-        }
-        if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
-            updates.lintIgnore = effectiveLintIgnore;
-        }
-        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, updates);
+        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, updates, undefined, {
+            config,
+            command: 're-export',
+            forceUnsafe: options.forceUnsafe === true,
+        });
         // Keep the in-memory manifest in sync so subsequent iterations (notably
         // `--all --scan`, where `getClaimedFiles` reads from this manifest) see
         // the just-written `filesAffected`. The on-disk write above is the

package/dist/src/commands/verify.js

@@ -15,9 +15,10 @@
  * treat the output as pass/fail.
  */
 import { join } from 'node:path';
-import { getProjectPaths } from '../core/config.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
 import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
+import { evaluatePatchPolicy } from '../core/patch-policy.js';
 import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
@@ -108,6 +109,7 @@ function detectCrossPatchFileClaims(manifestPatches) {
 export async function verifyCommand(projectRoot) {
     intro('FireForge Verify');
     const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
     if (!(await pathExists(paths.patches))) {
         info('No patches directory. Nothing to verify.');
         outro('Verify clean');
@@ -129,6 +131,18 @@ export async function verifyCommand(projectRoot) {
     // same path in filesAffected. Not caught by per-patch consistency.
     const manifest = await loadPatchesManifest(paths.patches);
     if (manifest) {
+        const policyIssues = evaluatePatchPolicy(config, manifest);
+        if (policyIssues.length > 0) {
+            warn(`Patch policy issues (${policyIssues.length}):`);
+            for (const issue of policyIssues) {
+                const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
+                warn(`  ${label} [${issue.code}] ${issue.filename}: ${issue.message}`);
+                if (issue.severity === 'error')
+                    errorCount += 1;
+                else
+                    warningCount += 1;
+            }
+        }
         const crossClaims = detectCrossPatchFileClaims(manifest.patches);
         if (crossClaims.length > 0) {
             warn(`Cross-patch filesAffected conflicts (${crossClaims.length}):`);

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

@@ -17,9 +17,9 @@ 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", "typecheck", "markerComment"];
+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. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

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

@@ -28,6 +28,7 @@ export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'license',
     'wire',
     'patchLint',
+    'patchPolicy',
     'typecheck',
     'markerComment',
 ];
@@ -55,6 +56,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'patchLint.jsdocClassMethods',
     'patchLint.testAssertionFloor',
     'patchLint.chromeScriptJsDoc',
+    'patchPolicy',
     'typecheck',
     'typecheck.projects',
     'typecheck.extraShim',

package/dist/src/core/config-validate-patch-policy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validation helpers for `fireforge.json#patchPolicy`.
+ */
+import type { PatchPolicyConfig } from '../types/config.js';
+import { parseObject } from '../utils/parse.js';
+/** Parses and validates the optional patch policy config block. */
+export declare function parsePatchPolicyBlock(rec: ReturnType<typeof parseObject>): PatchPolicyConfig;

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

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validation helpers for `fireforge.json#patchPolicy`.
+ */
+import { ConfigError } from '../errors/config.js';
+import { toError } from '../utils/errors.js';
+import { parseObject } from '../utils/parse.js';
+import { isContainedRelativePath } from '../utils/paths.js';
+const PATCH_POLICY_MUTATION_MODES = ['error', 'warn', 'force'];
+function optionalConfigString(rec, key, label) {
+    const value = rec.raw(key);
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new ConfigError(`Config field "${label}" must be a string`);
+    }
+    return value;
+}
+function parsePositiveRangeEndpoint(raw, label) {
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw <= 0) {
+        throw new ConfigError(`Config field "${label}" must be a positive integer`);
+    }
+    return raw;
+}
+function parsePatchPolicyCategory(raw, label) {
+    if (typeof raw !== 'string' || !/^[a-z][a-z0-9-]*$/.test(raw)) {
+        throw new ConfigError(`Config field "${label}" must be a lowercase category identifier (letters, numbers, hyphens)`);
+    }
+    return raw;
+}
+function parsePatchPolicyRange(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`);
+    }
+    return {
+        from,
+        to,
+        category: parsePatchPolicyCategory(rec.raw('category'), `${label}.category`),
+    };
+}
+function parsePatchPolicyDocumentPath(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new ConfigError(`Config field "${label}" must be a non-empty string`);
+    }
+    if (!isContainedRelativePath(raw)) {
+        throw new ConfigError(`Config field "${label}" must be a project-relative path`);
+    }
+    return raw;
+}
+function parseReservedAllowedPatch(raw, label) {
+    let rec;
+    try {
+        rec = parseObject(raw, label);
+    }
+    catch {
+        throw new ConfigError(`Config field "${label}" must be an object`);
+    }
+    const filename = optionalConfigString(rec, 'filename', `${label}.filename`);
+    if (filename === undefined || filename.trim() === '') {
+        throw new ConfigError(`Config field "${label}.filename" must be a non-empty string`);
+    }
+    const files = rec.raw('files');
+    let parsedFiles;
+    if (files !== undefined) {
+        if (!Array.isArray(files) || files.some((value) => typeof value !== 'string')) {
+            throw new ConfigError(`Config field "${label}.files" must be an array of strings`);
+        }
+        parsedFiles = files;
+    }
+    const adr = parsePatchPolicyDocumentPath(rec.raw('adr'), `${label}.adr`);
+    const documentation = parsePatchPolicyDocumentPath(rec.raw('documentation'), `${label}.documentation`);
+    const out = { filename };
+    if (parsedFiles !== undefined)
+        out.files = parsedFiles;
+    if (adr !== undefined)
+        out.adr = adr;
+    if (documentation !== undefined)
+        out.documentation = documentation;
+    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 allowedRaw = rec.raw('allowed');
+    if (!Array.isArray(allowedRaw)) {
+        throw new ConfigError(`Config field "${label}.allowed" must be an array`);
+    }
+    return {
+        from,
+        to,
+        allowed: allowedRaw.map((entry, index) => parseReservedAllowedPatch(entry, `${label}.allowed[${String(index)}]`)),
+    };
+}
+function assertPolicyRangesDoNotOverlap(ranges, label) {
+    const sorted = [...ranges].sort((a, b) => a.from - b.from || a.to - b.to);
+    for (let i = 1; i < sorted.length; i++) {
+        const previous = sorted[i - 1];
+        const current = sorted[i];
+        if (previous && current && current.from <= previous.to) {
+            throw new ConfigError(`Config field "${label}" must not contain overlapping ranges (${previous.from}-${previous.to} overlaps ${current.from}-${current.to})`);
+        }
+    }
+}
+/** Parses and validates the optional patch policy config block. */
+export function parsePatchPolicyBlock(rec) {
+    const out = { ranges: [] };
+    const filenamePattern = optionalConfigString(rec, 'filenamePattern', 'patchPolicy.filenamePattern');
+    if (filenamePattern !== undefined) {
+        try {
+            new RegExp(filenamePattern);
+        }
+        catch (error) {
+            throw new ConfigError(`Config field "patchPolicy.filenamePattern" must be a valid regular expression: ${toError(error).message}`);
+        }
+        out.filenamePattern = filenamePattern;
+    }
+    const requireDescription = rec.raw('requireDescription');
+    if (requireDescription !== undefined) {
+        if (typeof requireDescription !== 'boolean') {
+            throw new ConfigError('Config field "patchPolicy.requireDescription" must be a boolean');
+        }
+        out.requireDescription = requireDescription;
+    }
+    const allowGaps = rec.raw('allowGaps');
+    if (allowGaps !== undefined) {
+        if (typeof allowGaps !== 'boolean') {
+            throw new ConfigError('Config field "patchPolicy.allowGaps" must be a boolean');
+        }
+        out.allowGaps = allowGaps;
+    }
+    const mutationMode = rec.raw('mutationMode');
+    if (mutationMode !== undefined) {
+        if (typeof mutationMode !== 'string' ||
+            !PATCH_POLICY_MUTATION_MODES.includes(mutationMode)) {
+            throw new ConfigError(`Config field "patchPolicy.mutationMode" must be one of: ${PATCH_POLICY_MUTATION_MODES.join(', ')}`);
+        }
+        out.mutationMode = mutationMode;
+    }
+    const rangesRaw = rec.raw('ranges');
+    if (!Array.isArray(rangesRaw) || rangesRaw.length === 0) {
+        throw new ConfigError('Config field "patchPolicy.ranges" must be a non-empty array');
+    }
+    out.ranges = rangesRaw.map((entry, index) => parsePatchPolicyRange(entry, `patchPolicy.ranges[${String(index)}]`));
+    assertPolicyRangesDoNotOverlap(out.ranges, 'patchPolicy.ranges');
+    const reservedRangesRaw = rec.raw('reservedRanges');
+    if (reservedRangesRaw !== undefined) {
+        if (!Array.isArray(reservedRangesRaw)) {
+            throw new ConfigError('Config field "patchPolicy.reservedRanges" must be an array');
+        }
+        out.reservedRanges = reservedRangesRaw.map((entry, index) => parsePatchPolicyReservedRange(entry, `patchPolicy.reservedRanges[${String(index)}]`));
+        assertPolicyRangesDoNotOverlap(out.reservedRanges, 'patchPolicy.reservedRanges');
+    }
+    return out;
+}
+//# sourceMappingURL=config-validate-patch-policy.js.map

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

@@ -8,6 +8,7 @@ import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
 import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
+import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 /**
  * Validates a raw config object and returns a typed FireForgeConfig.
  * @param data - Raw data to validate
@@ -136,6 +137,11 @@ export function validateConfig(data) {
     if (patchLintRec) {
         config.patchLint = parsePatchLintBlock(patchLintRec);
     }
+    // PatchPolicy
+    const patchPolicyRec = optionalConfigObject(rec, 'patchPolicy');
+    if (patchPolicyRec) {
+        config.patchPolicy = parsePatchPolicyBlock(patchPolicyRec);
+    }
     // Typecheck (top-level, distinct from patchLint — see TypecheckConfig docs).
     const typecheckRec = optionalConfigObject(rec, 'typecheck');
     if (typecheckRec) {

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

@@ -0,0 +1,7 @@
+import type { FurnaceConfig } from '../types/furnace.js';
+/**
+ * Orders furnace.json output using the existing file as the primary key
+ * sequence, preserving unknown extension keys and appending newly supported
+ * fields only when needed.
+ */
+export declare function orderFurnaceConfigForWrite(existing: Record<string, unknown> | undefined, config: FurnaceConfig): Record<string, unknown>;

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

@@ -0,0 +1,86 @@
+import { isObject } from '../utils/validation.js';
+const FURNACE_CONFIG_TOP_LEVEL_KEYS = new Set([
+    'version',
+    'componentPrefix',
+    'tokenPrefix',
+    'tokenAllowlist',
+    'platformPrefixes',
+    'runtimeVariables',
+    'tokenHostDocuments',
+    'ftlBasePath',
+    'scanPaths',
+    'stock',
+    'overrides',
+    'custom',
+]);
+function orderObjectLikeExisting(existing, next) {
+    if (!existing)
+        return next;
+    const ordered = {};
+    for (const key of Object.keys(existing)) {
+        if (Object.hasOwn(next, key)) {
+            ordered[key] = next[key];
+        }
+    }
+    for (const key of Object.keys(next)) {
+        if (!Object.hasOwn(ordered, key)) {
+            ordered[key] = next[key];
+        }
+    }
+    return ordered;
+}
+function orderComponentMapLikeExisting(existing, next) {
+    if (!isObject(next))
+        return next;
+    if (!isObject(existing))
+        return next;
+    const ordered = {};
+    for (const key of Object.keys(existing)) {
+        if (Object.hasOwn(next, key)) {
+            const existingValue = existing[key];
+            const nextValue = next[key];
+            ordered[key] =
+                isObject(existingValue) && isObject(nextValue)
+                    ? orderObjectLikeExisting(existingValue, nextValue)
+                    : nextValue;
+        }
+    }
+    for (const key of Object.keys(next)) {
+        if (!Object.hasOwn(ordered, key)) {
+            ordered[key] = next[key];
+        }
+    }
+    return ordered;
+}
+/**
+ * Orders furnace.json output using the existing file as the primary key
+ * sequence, preserving unknown extension keys and appending newly supported
+ * fields only when needed.
+ */
+export function orderFurnaceConfigForWrite(existing, config) {
+    const next = config;
+    if (!existing)
+        return next;
+    const ordered = {};
+    for (const key of Object.keys(existing)) {
+        if (key === 'overrides' || key === 'custom') {
+            ordered[key] = orderComponentMapLikeExisting(existing[key], next[key]);
+        }
+        else if (Object.hasOwn(next, key)) {
+            ordered[key] = next[key];
+        }
+        else if (!FURNACE_CONFIG_TOP_LEVEL_KEYS.has(key)) {
+            ordered[key] = existing[key];
+        }
+    }
+    for (const key of Object.keys(next)) {
+        if (Object.hasOwn(ordered, key))
+            continue;
+        ordered[key] =
+            key === 'overrides' || key === 'custom'
+                ? orderComponentMapLikeExisting(existing[key], next[key])
+                : next[key];
+    }
+    return ordered;
+}
+//# sourceMappingURL=furnace-config-order.js.map