@hominis/fireforge 0.21.1 → 0.21.3

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/patch-export-coverage.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Patch coverage and supersession helpers used by export planning.
+ */
+import type { PatchInfo, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Finds patches that are completely superseded by newer patches.
+ * A patch is superseded if all its affected files are covered by newer patches.
+ * @param patchesDir - Path to the patches directory
+ * @param newPatchFiles - Files affected by the new patch
+ * @param excludeFilename - Filename to exclude from results (the new patch itself)
+ * @returns Superseded patches
+ */
+export declare function findSupersededPatches(patchesDir: string, newPatchFiles: string[], excludeFilename?: string): Promise<PatchInfo[]>;
+/**
+ * Report whether a patch is fully covered by a new export, and which of its
+ * files caused the coverage.
+ */
+export interface PatchCoverage {
+    covered: boolean;
+    byFiles: string[];
+}
+/**
+ * Checks whether a patch is fully covered by a new export.
+ * A patch is fully covered when every file it affects is present in the new export.
+ * @param patchFiles - Files affected by the existing patch
+ * @param targetFiles - Files affected by the new export
+ * @returns Coverage report with the triggering file list when `covered` is true
+ */
+export declare function isPatchFullyCovered(patchFiles: string[], targetFiles: string[]): PatchCoverage;
+/**
+ * Finds patches whose filesAffected entries are fully covered by the specified files.
+ * Used for complete supersession when exporting full-file patches.
+ * @param patchesDir - Path to the patches directory
+ * @param targetFiles - Files affected by the new export
+ * @param excludeFilename - Filename to exclude from results (the new patch itself)
+ * @returns Patches that are fully covered by the new export
+ */
+export declare function findAllPatchesForFiles(patchesDir: string, targetFiles: string[], excludeFilename?: string): Promise<PatchInfo[]>;
+/**
+ * Describes which files in a covered patch triggered its supersession.
+ * Returned from `planExport` so dry-run previews can render a complete
+ * "moved / removed" picture rather than a bare patch count.
+ */
+export interface SupersedeCoverageDetail {
+    /** Existing patch filename. */
+    filename: string;
+    /** Files the existing patch claimed that the new export also claims. */
+    coveredByFiles: string[];
+}
+/**
+ * Resolves coverage details for every existing patch that the new export
+ * would fully cover.
+ */
+export declare function findAllPatchesForFilesWithDetails(patchesDir: string, targetFiles: string[], excludeFilename?: string): Promise<{
+    patch: PatchInfo;
+    coverage: PatchCoverage;
+    metadata: PatchMetadata;
+}[]>;

package/dist/src/core/patch-export-coverage.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Patch coverage and supersession helpers used by export planning.
+ */
+import { discoverPatches, isNewFilePatch } from './patch-apply.js';
+import { loadPatchesManifest } from './patch-manifest.js';
+/**
+ * Finds patches that are completely superseded by newer patches.
+ * A patch is superseded if all its affected files are covered by newer patches.
+ * @param patchesDir - Path to the patches directory
+ * @param newPatchFiles - Files affected by the new patch
+ * @param excludeFilename - Filename to exclude from results (the new patch itself)
+ * @returns Superseded patches
+ */
+export async function findSupersededPatches(patchesDir, newPatchFiles, excludeFilename) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return [];
+    const patches = await discoverPatches(patchesDir);
+    const superseded = [];
+    for (const metadata of manifest.patches) {
+        if (excludeFilename && metadata.filename === excludeFilename)
+            continue;
+        if (metadata.filesAffected.length === 1) {
+            const affectedFile = metadata.filesAffected[0];
+            if (affectedFile && newPatchFiles.includes(affectedFile)) {
+                const patch = patches.find((p) => p.filename === metadata.filename);
+                if (patch && (await isNewFilePatch(patch.path))) {
+                    superseded.push(patch);
+                }
+            }
+        }
+    }
+    return superseded;
+}
+/**
+ * Checks whether a patch is fully covered by a new export.
+ * A patch is fully covered when every file it affects is present in the new export.
+ * @param patchFiles - Files affected by the existing patch
+ * @param targetFiles - Files affected by the new export
+ * @returns Coverage report with the triggering file list when `covered` is true
+ */
+export function isPatchFullyCovered(patchFiles, targetFiles) {
+    if (patchFiles.length === 0) {
+        return { covered: false, byFiles: [] };
+    }
+    const targetFileSet = new Set(targetFiles);
+    const covered = patchFiles.every((file) => targetFileSet.has(file));
+    return {
+        covered,
+        byFiles: covered ? [...patchFiles] : [],
+    };
+}
+/**
+ * Finds patches whose filesAffected entries are fully covered by the specified files.
+ * Used for complete supersession when exporting full-file patches.
+ * @param patchesDir - Path to the patches directory
+ * @param targetFiles - Files affected by the new export
+ * @param excludeFilename - Filename to exclude from results (the new patch itself)
+ * @returns Patches that are fully covered by the new export
+ */
+export async function findAllPatchesForFiles(patchesDir, targetFiles, excludeFilename) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return [];
+    const patches = await discoverPatches(patchesDir);
+    const superseded = [];
+    for (const metadata of manifest.patches) {
+        if (excludeFilename && metadata.filename === excludeFilename)
+            continue;
+        if (isPatchFullyCovered(metadata.filesAffected, targetFiles).covered) {
+            const patch = patches.find((p) => p.filename === metadata.filename);
+            if (patch) {
+                superseded.push(patch);
+            }
+        }
+    }
+    return superseded;
+}
+/**
+ * Resolves coverage details for every existing patch that the new export
+ * would fully cover.
+ */
+export async function findAllPatchesForFilesWithDetails(patchesDir, targetFiles, excludeFilename) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return [];
+    const patches = await discoverPatches(patchesDir);
+    const results = [];
+    for (const metadata of manifest.patches) {
+        if (excludeFilename && metadata.filename === excludeFilename)
+            continue;
+        const coverage = isPatchFullyCovered(metadata.filesAffected, targetFiles);
+        if (!coverage.covered)
+            continue;
+        const patch = patches.find((p) => p.filename === metadata.filename);
+        if (!patch)
+            continue;
+        results.push({ patch, coverage, metadata });
+    }
+    return results;
+}
+//# sourceMappingURL=patch-export-coverage.js.map

package/dist/src/core/patch-export-metadata.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Manifest metadata mutation helpers for patch export commands.
+ */
+import type { PatchMetadata } from '../types/commands/index.js';
+/**
+ * Optional `PatchMetadata` keys safe to clear via the helpers below.
+ */
+export type ClearablePatchMetadataField = 'tier' | 'lintIgnore';
+/**
+ * Updates metadata for a patch in the manifest.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Patch filename
+ * @param updates - Field values to set
+ * @param unsetFields - Optional fields to remove from the entry
+ */
+export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>, unsetFields?: ReadonlyArray<ClearablePatchMetadataField>): Promise<void>;
+/** Return shape from a `mutatePatchMetadata` mutator. */
+export interface PatchMetadataMutation {
+    /** Field values to set on the entry. */
+    set?: Partial<PatchMetadata>;
+    /** Optional fields to remove from the entry entirely. */
+    unset?: ReadonlyArray<ClearablePatchMetadataField>;
+}
+/** Result of a successful `mutatePatchMetadata` call. */
+export interface PatchMetadataMutationResult {
+    /** Pre-mutation snapshot of the patch's metadata. */
+    before: PatchMetadata;
+    /** Post-mutation state of the patch's metadata. */
+    after: PatchMetadata;
+}
+/**
+ * Reads a patch's metadata under the directory lock, applies a mutator
+ * function to compute the update, and writes the result back.
+ */
+export declare function mutatePatchMetadata(patchesDir: string, filename: string, mutator: (existing: PatchMetadata) => PatchMetadataMutation): Promise<PatchMetadataMutationResult | null>;

package/dist/src/core/patch-export-metadata.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Manifest metadata mutation helpers for patch export commands.
+ */
+import { withPatchDirectoryLock } from './patch-apply.js';
+import { loadPatchesManifest, savePatchesManifest } from './patch-manifest.js';
+/**
+ * Merges `updates` onto `existing` and removes the listed optional fields.
+ */
+function applyMetadataUpdate(existing, updates, unset) {
+    const next = { ...existing, ...updates };
+    for (const field of unset) {
+        switch (field) {
+            case 'tier':
+                delete next.tier;
+                break;
+            case 'lintIgnore':
+                delete next.lintIgnore;
+                break;
+        }
+    }
+    return next;
+}
+/**
+ * Updates metadata for a patch in the manifest.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Patch filename
+ * @param updates - Field values to set
+ * @param unsetFields - Optional fields to remove from the entry
+ */
+export async function updatePatchMetadata(patchesDir, filename, updates, unsetFields = []) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            return;
+        const patchIndex = manifest.patches.findIndex((p) => p.filename === filename);
+        if (patchIndex === -1)
+            return;
+        const existingPatch = manifest.patches[patchIndex];
+        if (existingPatch) {
+            manifest.patches[patchIndex] = applyMetadataUpdate(existingPatch, updates, unsetFields);
+            await savePatchesManifest(patchesDir, manifest);
+        }
+    });
+}
+/**
+ * Reads a patch's metadata under the directory lock, applies a mutator
+ * function to compute the update, and writes the result back.
+ */
+export async function mutatePatchMetadata(patchesDir, filename, mutator) {
+    return await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            return null;
+        const patchIndex = manifest.patches.findIndex((p) => p.filename === filename);
+        if (patchIndex === -1)
+            return null;
+        const existingPatch = manifest.patches[patchIndex];
+        if (!existingPatch)
+            return null;
+        const { set = {}, unset = [] } = mutator(existingPatch);
+        const updatedPatch = applyMetadataUpdate(existingPatch, set, unset);
+        manifest.patches[patchIndex] = updatedPatch;
+        await savePatchesManifest(patchesDir, manifest);
+        return { before: existingPatch, after: updatedPatch };
+    });
+}
+//# sourceMappingURL=patch-export-metadata.js.map

package/dist/src/core/patch-export-update.d.ts

@@ -0,0 +1,20 @@
+import type { PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Optional post-commit hook for {@link updatePatchAndMetadata}. Runs inside
+ * the patch directory lock after the mutation has succeeded but before the
+ * lock is released.
+ */
+export type UpdatePatchCommittedHook = () => Promise<void>;
+/** Optional policy gate run against the under-lock projected manifest. */
+export interface UpdatePatchPolicyGate {
+    config: FireForgeConfig;
+    command: string;
+    forceUnsafe?: boolean;
+}
+/**
+ * Updates a patch file body and its manifest row under the same patch
+ * directory lock. Intended for commands like `re-export --files` where the
+ * file body and `filesAffected` metadata must move together.
+ */
+export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook, policyGate?: UpdatePatchPolicyGate): Promise<void>;