@hominis/fireforge 0.18.1 → 0.18.2

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

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch tier <name>` — sets or clears `PatchMetadata.tier` on
+ * a single patch without rewriting the `.patch` file body.
+ *
+ * Companion to `fireforge re-export <name> --tier <tier>`. Re-export is
+ * the right tool when the patch body itself needs to be regenerated; this
+ * subcommand exists for the metadata-only adjustment, where the operator
+ * has discovered (e.g. from a `lint --per-patch` warning) that the
+ * threshold-tier override should be set but the patch body is already
+ * correct. Avoiding the re-export saves the engine read + diff
+ * regeneration roundtrip and leaves the `.patch` file's mtime alone.
+ *
+ * Modes are mutually exclusive: exactly one of `--tier <branding>` or
+ * `--clear` must be supplied per invocation.
+ */
+import { Option } from 'commander';
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory } from '../../core/destructive.js';
+import { updatePatchMetadata } from '../../core/patch-export.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+import { pickDefined } from '../../utils/options.js';
+/**
+ * Runs the `patch tier` command: updates `PatchMetadata.tier` on the
+ * named patch (or clears the field) and writes the manifest.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options
+ */
+export async function patchTierCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch tier (dry run)' : 'FireForge patch tier');
+    // Mode mutex: a single invocation either sets or clears the tier.
+    // Combining both is ambiguous — the operator's intent is not obvious
+    // and silently picking one would mask the typo.
+    const setting = options.tier !== undefined;
+    const clearing = options.clear === true;
+    if (setting && clearing) {
+        throw new InvalidArgumentError('--tier and --clear are mutually exclusive. Pick one mode per invocation.', 'patch tier');
+    }
+    if (!setting && !clearing) {
+        throw new InvalidArgumentError('Specify --tier <tier> to set the override, or --clear to remove it.', 'patch tier');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const target = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!target) {
+        const available = manifest.patches
+            .map((p) => p.name && p.name !== p.filename ? `${p.filename} (name: ${p.name})` : p.filename)
+            .join(', ');
+        throw new InvalidArgumentError(`Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo). Available: ${available}`, identifier);
+    }
+    const before = target.tier;
+    const after = setting ? options.tier : undefined;
+    if (before === after) {
+        info(after === undefined
+            ? `${target.filename}: tier is already absent — no change.`
+            : `${target.filename}: tier is already "${after}" — no change.`);
+        outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch tier (no-op)');
+        return;
+    }
+    const action = after === undefined
+        ? `clear tier (was "${before}")`
+        : before === undefined
+            ? `set tier to "${after}"`
+            : `change tier from "${before}" to "${after}"`;
+    if (isDryRun) {
+        info(`[dry-run] ${target.filename}: would ${action}.`);
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    // Single write under the patch directory lock (delegated inside
+    // updatePatchMetadata). Setting routes through `updates`; clearing
+    // routes through `unsetFields` so TypeScript's exact optional types
+    // do not have to carry an explicit `undefined` on the `tier` field.
+    if (after !== undefined) {
+        await updatePatchMetadata(paths.patches, target.filename, { tier: after });
+    }
+    else {
+        await updatePatchMetadata(paths.patches, target.filename, {}, ['tier']);
+    }
+    try {
+        await appendHistory(paths.patches, {
+            operation: 'patch-tier',
+            args: {
+                filename: target.filename,
+                ...(before !== undefined ? { before } : {}),
+                ...(after !== undefined ? { after } : {}),
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            result: 'ok',
+        });
+    }
+    catch (historyError) {
+        warn(`History log append failed after patch tier committed (${target.filename}): ${toError(historyError).message}`);
+    }
+    info(`${target.filename}: ${action}.`);
+    outro('Patch tier complete');
+}
+/**
+ * Registers the `patch tier` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchTier(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('tier <name>')
+        .description('Set or clear PatchMetadata.tier on a single patch (no .patch body rewrite). Use --tier <branding> to set, --clear to remove.')
+        .addOption(new Option('--tier <tier>', 'Force the tier override on the patch (only "branding" recognised)').choices(['branding']))
+        .option('--clear', 'Remove the tier override (restores tier auto-detection)')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        const { tier, ...rest } = options;
+        await patchTierCommand(getProjectRoot(), name, {
+            ...pickDefined(rest),
+            ...(tier !== undefined ? { tier: tier } : {}),
+        });
+    }));
+}
+//# sourceMappingURL=tier.js.map

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

@@ -11,6 +11,85 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, outro, success, warn } from '../utils/logger.js';
 import { runPatchLint } from './export-shared.js';
+/**
+ * Computes the effective `tier` and `lintIgnore` carrying both the
+ * patch's existing values and the CLI flag overrides. Pure helper —
+ * extracted from {@link reExportFilesInPlace} both to share with the
+ * standard re-export path conceptually and to keep the orchestrator
+ * function under the per-file LOC budget.
+ *
+ * Tier resolution: the CLI flag takes precedence; the patch's existing
+ * tier is the fallback. Lint-ignore resolution: union of the patch's
+ * existing list and the CLI flag values, de-duplicated; an empty
+ * result returns `undefined` so the caller can drop the field rather
+ * than write an empty array.
+ */
+function resolveEffectiveTierAndLintIgnore(target, options) {
+    const existingIgnoreSet = new Set(target.lintIgnore ?? []);
+    const flagIgnoreSet = new Set(options.lintIgnore ?? []);
+    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
+    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const effectiveTier = options.tier ?? target.tier;
+    return { effectiveTier, effectiveLintIgnore, flagIgnoreSet };
+}
+/**
+ * Projects the cross-patch context (replace the target entry with its
+ * shrunken self), runs the patch-queue lint against the projection,
+ * and returns a conflict report only for regressions introduced *by*
+ * this shrink. Pre-existing cross-patch errors are surfaced as a
+ * non-blocking warning so the user does not walk away thinking the
+ * queue is clean. Extracted from {@link reExportFilesInPlace} to keep
+ * the orchestrator function under the per-file LOC budget.
+ */
+async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedDiff) {
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const projectedNewFiles = new Map();
+    for (const path of detectNewFilesInDiff(projectedDiff)) {
+        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
+    }
+    const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
+    const projectedEntries = baseCtx.entries.map((entry) => {
+        if (entry.filename !== targetFilename)
+            return entry;
+        return {
+            ...entry,
+            diff: projectedDiff,
+            newFiles: projectedNewFiles,
+            modifiedFileAdditions: projectedModifiedFileAdditions,
+        };
+    });
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
+    if (baselineIssues.length > 0 && regressions.length === 0) {
+        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing ` +
+            `cross-patch error(s) unrelated to this shrink. Run "fireforge verify" to list them.`);
+    }
+    if (regressions.length === 0)
+        return null;
+    return {
+        reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
+        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+    };
+}
+/**
+ * Builds the `Partial<PatchMetadata>` payload for the `--files` write,
+ * folding in the CLI flag overrides for `tier` and `lintIgnore` only
+ * when the operator actually asked for them. Extracted to keep
+ * {@link reExportFilesInPlace} under the per-file LOC budget.
+ */
+function buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet) {
+    const updates = {
+        filesAffected: actualProjectedFiles,
+    };
+    if (options.tier !== undefined) {
+        updates.tier = options.tier;
+    }
+    if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
+        updates.lintIgnore = effectiveLintIgnore;
+    }
+    return updates;
+}
 /**
  * Handles `re-export --files` end-to-end: computes the projected diff,
  * runs the per-patch and cross-patch lint against a context in which the
@@ -77,50 +156,13 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // have to choose between `--skip-lint` (blunt) and the full rebase path.
     // `target.tier` threads the explicit branding-threshold opt-in for
     // the branding patch that also touches a non-allowlisted sibling.
-    const ignoreChecks = target.lintIgnore?.length ? new Set(target.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks, target.tier);
-    // Project the cross-patch context: replace the target entry with its
-    // would-be shrunken self (new diff + new newFiles + new
-    // modifiedFileAdditions). The projected entry must repopulate both
-    // source-site maps so the forward-import rule sees imports the
-    // shrunken diff would add — or stop adding — consistently with how a
-    // real rebuild would see them.
-    const baseCtx = await buildPatchQueueContext(paths.patches);
-    const projectedNewFiles = new Map();
-    for (const path of detectNewFilesInDiff(projectedDiff)) {
-        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
-    }
-    const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
-    const projectedEntries = baseCtx.entries.map((entry) => {
-        if (entry.filename !== target.filename)
-            return entry;
-        return {
-            ...entry,
-            diff: projectedDiff,
-            newFiles: projectedNewFiles,
-            modifiedFileAdditions: projectedModifiedFileAdditions,
-        };
-    });
-    // Baseline-vs-projected diffing: only regressions introduced *by* this
-    // shrink should block. A pre-existing cross-patch error elsewhere in
-    // the queue must not prevent the user from shrinking an unrelated
-    // patch (which is often exactly the tool they reach for to repair
-    // such a queue).
-    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
-    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
-    const conflicts = regressions.length > 0
-        ? {
-            reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
-            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
-        }
-        : null;
-    // Surface pre-existing errors as a non-blocking warning so the user
-    // doesn't walk away thinking the queue is clean.
-    if (baselineIssues.length > 0 && regressions.length === 0) {
-        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing ` +
-            `cross-patch error(s) unrelated to this shrink. Run "fireforge verify" to list them.`);
-    }
+    // CLI flags `--tier` and `--lint-ignore` participate too, with
+    // append/union semantics on the lint-ignore list (matching the
+    // standard re-export path).
+    const { effectiveTier, effectiveLintIgnore, flagIgnoreSet } = resolveEffectiveTierAndLintIgnore(target, options);
+    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);
     // Shrinks are destructive (previously-owned files become unmanaged).
     // Additive-only changes still deserve a prompt because --files asserts
     // an authoritative file set.
@@ -163,7 +205,8 @@ 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.
-    await updatePatchAndMetadata(paths.patches, target.filename, projectedDiff, { filesAffected: actualProjectedFiles }, async () => {
+    const filesUpdates = buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet);
+    await updatePatchAndMetadata(paths.patches, target.filename, projectedDiff, filesUpdates, async () => {
         await appendHistory(paths.patches, {
             operation: 're-export-files',
             args: {

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
 import { confirm, multiselect } from '@clack/prompts';
+import { Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
@@ -204,10 +205,29 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     // The paired `patch.tier` threads the explicit branding-threshold
     // opt-in the same way, for the branding patch that also touches a
     // non-allowlisted registration sibling.
-    const ignoreChecks = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, patch.tier);
+    //
+    // The CLI flags `--tier` and `--lint-ignore` participate too, with
+    // append/union semantics on the lint-ignore list (the operator's
+    // intuition for "I want this patch to also suppress X" — explicit
+    // removal lives on the `fireforge patch lint-ignore` subcommand).
+    // Computed before the lint pass so the new intent takes effect on
+    // this invocation, not the next one.
+    const existingIgnoreSet = new Set(patch.lintIgnore ?? []);
+    const flagIgnoreSet = new Set(options.lintIgnore ?? []);
+    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
+    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
+    const effectiveTier = options.tier ?? patch.tier;
+    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
     if (isDryRun) {
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
+        if (effectiveTier !== undefined && effectiveTier !== patch.tier) {
+            info(`[dry-run] ${patch.filename}: tier would become ${effectiveTier}`);
+        }
+        const addedIgnores = [...flagIgnoreSet].filter((id) => !existingIgnoreSet.has(id));
+        if (addedIgnores.length > 0) {
+            info(`[dry-run] ${patch.filename}: lintIgnore would gain ${addedIgnores.join(', ')}`);
+        }
     }
     else {
         // Atomic body + manifest update under a single patch-directory lock.
@@ -215,9 +235,16 @@ 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.
-        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, {
+        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);
         // 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
@@ -228,7 +255,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             if (existingEntry) {
                 manifest.patches[patchIndex] = {
                     ...existingEntry,
-                    filesAffected: currentFilesAffected,
+                    ...updates,
                 };
             }
         }
@@ -291,6 +318,15 @@ export async function reExportCommand(projectRoot, patches, options) {
             throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier.', '--files');
         }
     }
+    // --tier and --lint-ignore are per-patch metadata edits; combining them
+    // with --all silently rewrites every patch's tier/ignore list, which is
+    // virtually always wrong (different patches have different shapes).
+    // Refuse the combination so the operator must enumerate the targets.
+    const usingTierFlag = options.tier !== undefined;
+    const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
+    if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {
+        throw new InvalidArgumentError('--tier and --lint-ignore require explicit patch identifiers and cannot be combined with --all (different patches typically need different metadata).', '--all');
+    }
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
@@ -396,8 +432,15 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('-y, --yes', 'Skip confirmation when --files shrinks a patch (required for non-TTY)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
         .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceEsrVersion in patches.json to firefox.version from fireforge.json. No effect on a partial run.")
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], [])
         .action(withErrorHandling(async (patches, options) => {
-        await reExportCommand(getProjectRoot(), patches, pickDefined(options));
+        const { tier, lintIgnore, ...rest } = options;
+        await reExportCommand(getProjectRoot(), patches, {
+            ...pickDefined(rest),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
+        });
     }));
 }
 //# sourceMappingURL=re-export.js.map

package/dist/src/core/git-diff.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { GitError } from '../errors/git.js';
@@ -35,6 +35,16 @@ export async function getFileDiff(repoDir, filePath) {
  */
 export async function generateNewFileDiff(repoDir, filePath) {
     const fullPath = join(repoDir, filePath);
+    // Defensive check: a directory here means a caller bypassed the
+    // expansion layers and handed the leaf reader a path it cannot
+    // read. Surface it with an actionable message naming the offending
+    // path rather than the raw `EISDIR` that `readText` would throw —
+    // recurring bug class (see the belt-and-suspenders note in
+    // `getDiffForFilesAgainstHead`).
+    const fileStat = await stat(fullPath);
+    if (fileStat.isDirectory()) {
+        throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
+    }
     const content = await readText(fullPath);
     // Compute the abbreviated git blob hash for the index line
     let blobHash = '0000000000';
@@ -212,7 +222,29 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
             }
             continue;
         }
-        if (!(await pathExists(join(repoDir, file)))) {
+        const fullPath = join(repoDir, file);
+        if (!(await pathExists(fullPath))) {
+            continue;
+        }
+        // Second defence against the EISDIR regression: a non-HEAD path
+        // that exists on disk is usually a new file, but can also be a
+        // directory that arrived without the trailing slash
+        // `expandUntrackedDirectoryEntries` would have produced (caller
+        // stripped it, submodule entry, tracked-file-replaced-by-dir).
+        // Expand it via the same helper used by the slash branch and
+        // recurse so each contained file is diffed individually; fail
+        // loud when the directory has no readable content rather than
+        // silently skipping it.
+        const fileStat = await stat(fullPath);
+        if (fileStat.isDirectory()) {
+            const innerFiles = await getUntrackedFilesInDir(repoDir, file);
+            if (innerFiles.length === 0) {
+                throw new GitError(`'${file}' is a directory with no untracked content (submodule or gitignored?) — cannot diff as a file`, `ls-files --others -- ${file}`);
+            }
+            const innerDiff = await getDiffForFilesAgainstHead(repoDir, innerFiles);
+            if (innerDiff.trim()) {
+                diffs.push(innerDiff);
+            }
             continue;
         }
         const diff = await generateNewFileDiff(repoDir, file);

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

@@ -21,6 +21,10 @@ export interface CommitExportedPatchInput {
     diff: string;
     filesAffected: string[];
     sourceEsrVersion: string;
+    /** Optional `PatchMetadata.tier` opt-in (only `"branding"` recognised). */
+    tier?: 'branding';
+    /** Optional `PatchMetadata.lintIgnore` (empty array treated as absent). */
+    lintIgnore?: string[];
 }
 export interface CommitExportedPatchResult {
     patchFilename: string;
@@ -88,13 +92,71 @@ export type UpdatePatchCommittedHook = () => Promise<void>;
  *   the mutation succeeds. See {@link UpdatePatchCommittedHook}.
  */
 export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook): Promise<void>;
+/**
+ * Optional `PatchMetadata` keys safe to clear via the helpers below.
+ * Required keys (filename, order, etc.) are excluded by construction so
+ * an over-eager `unsetFields: ['filename']` cannot delete a field the
+ * manifest validator requires. Add new keys here only when they become
+ * optional on the type.
+ */
+export type ClearablePatchMetadataField = 'tier' | 'lintIgnore';
 /**
  * Updates metadata for a patch in the manifest.
+ *
+ * Required-field updates go through the `updates` partial. Clearing an
+ * optional field (e.g. removing the `tier` override) goes through
+ * `unsetFields` because TypeScript's `exactOptionalPropertyTypes` does
+ * not let `Partial<PatchMetadata>` carry an explicit `undefined` value
+ * for fields whose declared type does not include `undefined`. The
+ * implementation deletes the listed keys from the merged record before
+ * writing, so the on-disk JSON omits them and the validator's
+ * "preserve only when present" contract is preserved.
+ *
  * @param patchesDir - Path to the patches directory
  * @param filename - Patch filename
- * @param updates - Partial metadata updates
+ * @param updates - Field values to set. Pass an empty object when only
+ *   clearing fields.
+ * @param unsetFields - Optional fields to remove from the entry (so
+ *   serialization drops them).
+ */
+export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>, unsetFields?: ReadonlyArray<ClearablePatchMetadataField>): Promise<void>;
+/**
+ * Return shape from a {@link 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 {@link mutatePatchMetadata} call.
  */
-export declare function updatePatchMetadata(patchesDir: string, filename: string, updates: Partial<PatchMetadata>): Promise<void>;
+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 — all
+ * under a single lock so a concurrent writer cannot interleave a
+ * read-modify-write cycle. Useful for operations that need to compute
+ * the new value from the old (e.g. unioning a `lintIgnore` list,
+ * removing a specific entry), which {@link updatePatchMetadata}'s flat
+ * merge cannot express on its own.
+ *
+ * The mutator returns `{ set, unset }` so it can both write fields
+ * and drop optional ones. `set` and `unset` are merged before write:
+ * `set` runs first via spread, then `unset` deletes the listed keys.
+ *
+ * @returns The pre/post metadata pair when the patch is found and the
+ *   write succeeds; `null` when the manifest is missing or the named
+ *   patch is not in it. Callers should treat `null` as "no-op, nothing
+ *   to log".
+ */
+export declare function mutatePatchMetadata(patchesDir: string, filename: string, mutator: (existing: PatchMetadata) => PatchMetadataMutation): Promise<PatchMetadataMutationResult | null>;
 /**
  * Finds patches that are completely superseded by newer patches.
  * A patch is superseded if all its affected files are covered by newer patches.
@@ -196,6 +258,19 @@ export interface PlanExportInput {
     description: string;
     filesAffected: string[];
     sourceEsrVersion: string;
+    /**
+     * Optional `PatchMetadata.tier` opt-in carried from the CLI flag.
+     * Only `"branding"` is currently recognised. When provided the field
+     * is written into the new patch's metadata; when absent the field
+     * stays unset and tier resolution falls back to auto-detection.
+     */
+    tier?: 'branding';
+    /**
+     * Optional `PatchMetadata.lintIgnore` carried from the CLI flag.
+     * Empty arrays are treated as "field absent" — the validator only
+     * preserves the field when it has at least one entry.
+     */
+    lintIgnore?: string[];
 }
 /**
  * Read-only planning function — computes everything a real export would