@hominis/fireforge 0.18.1 → 0.18.3

package/dist/src/commands/import.js

@@ -74,7 +74,15 @@ async function checkUncommittedPatchFiles(engineDir, patchesDir, forceImport) {
         if (dirtyFiles.length > 0) {
             const unmanagedDirtyFiles = await getUnmanagedDirtyFiles(engineDir, patchesDir, dirtyFiles);
             if (unmanagedDirtyFiles.length === 0) {
-                info('Patch-backed materialized files already match the stored patch stack.');
+                // Common path here: operator just ran `fireforge resolve` to
+                // regenerate a patch from manual conflict edits, so the engine
+                // already carries the patch's effects. The import below will
+                // still re-apply each patch (a no-op for files whose contents
+                // already match), so phrase the line as "no resync needed"
+                // rather than "patches already applied" — the latter contradicts
+                // the "Applied N patch(es)" summary `applyPatchesWithContinue`
+                // prints next, which the 2026-04-25 eval flagged as ambiguous.
+                info('Patch-touched files already match the stored patch stack — no engine resync needed before re-applying.');
             }
             else if (!forceImport) {
                 warn('Uncommitted changes detected in files that patches will modify:');

package/dist/src/commands/lint.js

@@ -3,6 +3,7 @@ import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getStatusWithCodes, hasChanges, isGitRepository } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
@@ -35,7 +36,7 @@ import { stripEnginePrefix } from '../utils/paths.js';
  * previous behaviour: passing a branding file explicitly still lints
  * it, so operators who need to audit branding content can do so.
  */
-async function resolveLintDiff(engineDir, files, binaryName) {
+async function resolveLintDiff(engineDir, files, binaryName, furnacePrefixes) {
     if (files.length > 0) {
         const collectedFiles = new Set();
         let fileStatuses;
@@ -115,16 +116,31 @@ async function resolveLintDiff(engineDir, files, binaryName) {
         const expanded = await expandUntrackedDirectoryEntries(engineDir, rawStatus);
         const allPaths = [...new Set(expanded.map((entry) => entry.file))];
         const nonBrandingPaths = allPaths.filter((path) => !isBrandingManagedPath(path, binaryName));
-        const excludedCount = allPaths.length - nonBrandingPaths.length;
-        if (excludedCount > 0) {
-            info(`Excluded ${excludedCount} tool-managed branding file${excludedCount === 1 ? '' : 's'} from lint. Pass the path explicitly or use \`fireforge lint <path>\` to include them.`);
+        const brandingExcluded = allPaths.length - nonBrandingPaths.length;
+        // Drop Furnace-managed paths the same way branding is dropped: their
+        // contents are tool output (overrides, custom widgets, preview-
+        // generated stories) that the operator did not author and never
+        // intended to land on the patch queue. Without this carve-out, a
+        // post-`furnace preview` aggregate `lint` failed with one
+        // `missing-license-header` error per generated story file (eval
+        // Finding 19) — each story is intentionally header-less because it's
+        // re-generated from component metadata on every preview run.
+        const filteredPaths = furnacePrefixes
+            ? nonBrandingPaths.filter((path) => ![...furnacePrefixes].some((p) => path.startsWith(p)))
+            : nonBrandingPaths;
+        const furnaceExcluded = nonBrandingPaths.length - filteredPaths.length;
+        if (brandingExcluded > 0) {
+            info(`Excluded ${brandingExcluded} tool-managed branding file${brandingExcluded === 1 ? '' : 's'} from lint. Pass the path explicitly or use \`fireforge lint <path>\` to include them.`);
         }
-        if (nonBrandingPaths.length === 0) {
-            info('No non-branding changes to lint.');
+        if (furnaceExcluded > 0) {
+            info(`Excluded ${furnaceExcluded} Furnace-managed file${furnaceExcluded === 1 ? '' : 's'} from lint (deployed components and preview-generated stories). Pass the path explicitly to include them.`);
+        }
+        if (filteredPaths.length === 0) {
+            info('No non-branding, non-Furnace changes to lint.');
             outro('Nothing to lint');
             return null;
         }
-        const diff = await getDiffForFilesAgainstHead(engineDir, nonBrandingPaths.sort());
+        const diff = await getDiffForFilesAgainstHead(engineDir, filteredPaths.sort());
         if (!diff.trim()) {
             info('No diff content to lint.');
             outro('Nothing to lint');
@@ -185,7 +201,13 @@ export async function lintCommand(projectRoot, files, options = {}) {
     // the diff was resolved; hoisting it is cheap and keeps the two
     // call sites close together.
     const config = await loadConfig(projectRoot);
-    const diff = await resolveLintDiff(paths.engine, files, config.binaryName);
+    // Pull the Furnace-managed prefix set up-front so aggregate lint can
+    // mirror the branding exclusion for Furnace material — without it,
+    // preview-generated stories under `browser/components/storybook/
+    // stories/furnace/` show up as license-header errors on every
+    // post-preview lint run.
+    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+    const diff = await resolveLintDiff(paths.engine, files, config.binaryName, furnacePrefixes);
     if (diff === null)
         return;
     const filesAffected = extractAffectedFiles(diff);
@@ -284,7 +306,23 @@ export async function lintCommand(projectRoot, files, options = {}) {
             : '';
         throw new GeneralError(`Patch lint found ${failingErrors.length} ${options.onlyIntroduced ? 'introduced ' : ''}error(s). Fix these before exporting.${cumulativeSuppressed}`);
     }
-    outro('Lint passed with warnings');
+    // Notices are advisory and don't count as warnings — emitting "passed
+    // with warnings" when only notices fired contradicts the preceding
+    // `0 warning(s)` summary line and reads as a regression. Distinguish
+    // the three pass states explicitly. Errors suppressed by
+    // --only-introduced still warrant the "with warnings" outro — they
+    // print as ERROR rows but no longer fail the run, which is the same
+    // contract the operator gets from a real warning.
+    const suppressedErrors = options.onlyIntroduced && errors.length > 0;
+    if (warnings.length > 0 || suppressedErrors) {
+        outro('Lint passed with warnings');
+    }
+    else if (notices.length > 0) {
+        outro('Lint passed with notices');
+    }
+    else {
+        outro('Lint passed');
+    }
 }
 /**
  * Lints each patch in the queue as its own isolated diff, honouring
@@ -357,7 +395,15 @@ async function lintPerPatch(projectRoot, paths) {
         outro('Lint failed');
         throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
     }
-    outro('Lint passed with warnings');
+    if (warnings.length > 0) {
+        outro('Lint passed with warnings');
+    }
+    else if (notices.length > 0) {
+        outro('Lint passed with notices');
+    }
+    else {
+        outro('Lint passed');
+    }
 }
 /** Registers the lint command on the CLI program. */
 export function registerLint(program, { getProjectRoot, withErrorHandling }) {

package/dist/src/commands/patch/index.d.ts

@@ -1,14 +1,16 @@
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`delete`, `reorder`) so they do not clutter the top-level
- * command list. Queue-level verbs like `lint`, `export`, `verify`, and
- * `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
+ * they do not clutter the top-level command list. Queue-level verbs
+ * like `lint`, `export`, `verify`, and `status` stay flat.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
+export { patchLintIgnoreCommand } from './lint-ignore.js';
 export { patchReorderCommand } from './reorder.js';
+export { patchTierCommand } from './tier.js';
 /**
  * Registers the `patch` subcommand parent and its verbs on the CLI.
  *

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

@@ -1,16 +1,20 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch <verb>` parent command. Groups single-patch
- * mutations (`delete`, `reorder`) so they do not clutter the top-level
- * command list. Queue-level verbs like `lint`, `export`, `verify`, and
- * `status` stay flat.
+ * mutations (`compact`, `delete`, `lint-ignore`, `reorder`, `tier`) so
+ * they do not clutter the top-level command list. Queue-level verbs
+ * like `lint`, `export`, `verify`, and `status` stay flat.
  */
 import { registerPatchCompact } from './compact.js';
 import { registerPatchDelete } from './delete.js';
+import { registerPatchLintIgnore } from './lint-ignore.js';
 import { registerPatchReorder } from './reorder.js';
+import { registerPatchTier } from './tier.js';
 export { patchCompactCommand } from './compact.js';
 export { patchDeleteCommand } from './delete.js';
+export { patchLintIgnoreCommand } from './lint-ignore.js';
 export { patchReorderCommand } from './reorder.js';
+export { patchTierCommand } from './tier.js';
 /**
  * Registers the `patch` subcommand parent and its verbs on the CLI.
  *
@@ -20,7 +24,7 @@ export { patchReorderCommand } from './reorder.js';
 export function registerPatch(program, context) {
     const patch = program
         .command('patch')
-        .description('Manage individual patches in the queue (compact, delete, reorder)')
+        .description('Manage individual patches in the queue (compact, delete, lint-ignore, reorder, tier)')
         // Match `fireforge furnace`'s no-args contract: print the group's help and
         // exit 0. Without this default action, commander routes `fireforge patch`
         // (no subcommand) through its own help-then-exit-1 path, so scripts that
@@ -32,6 +36,8 @@ export function registerPatch(program, context) {
     });
     registerPatchCompact(patch, context);
     registerPatchDelete(patch, context);
+    registerPatchLintIgnore(patch, context);
     registerPatchReorder(patch, context);
+    registerPatchTier(patch, context);
 }
 //# sourceMappingURL=index.js.map

package/dist/src/commands/patch/lint-ignore.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `fireforge patch lint-ignore <name>` — adds, removes, or clears entries
+ * in `PatchMetadata.lintIgnore` without rewriting the `.patch` file body.
+ *
+ * Companion to `fireforge re-export <name> --lint-ignore <id>` (which is
+ * append-only). Existence is justified by the cases re-export cannot
+ * express:
+ * - Removing a single entry without dropping the rest of the list.
+ * - Clearing the entire list when the operator wants the rule(s) to
+ *   start firing again.
+ * - Editing metadata when the patch body is already correct, so the
+ *   re-export's engine read + diff regeneration roundtrip is wasted.
+ *
+ * Modes are mutually exclusive: exactly one of `--add`, `--remove`, or
+ * `--clear` must be supplied per invocation. The read-modify-write
+ * happens inside the patch directory lock via {@link mutatePatchMetadata}
+ * so a concurrent writer cannot interleave between the read and the
+ * write — important when an operator scripts repeated invocations or
+ * runs `--add` and `--remove` back-to-back.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchLintIgnoreOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch lint-ignore` command: reads the patch's existing
+ * `lintIgnore`, applies the requested mode, and writes the manifest.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (exactly one of `add`/`remove`/`clear`)
+ */
+export declare function patchLintIgnoreCommand(projectRoot: string, identifier: string, options?: PatchLintIgnoreOptions): Promise<void>;
+/**
+ * Registers the `patch lint-ignore` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchLintIgnore(parent: Command, context: CommandContext): void;

package/dist/src/commands/patch/lint-ignore.js

@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch lint-ignore <name>` — adds, removes, or clears entries
+ * in `PatchMetadata.lintIgnore` without rewriting the `.patch` file body.
+ *
+ * Companion to `fireforge re-export <name> --lint-ignore <id>` (which is
+ * append-only). Existence is justified by the cases re-export cannot
+ * express:
+ * - Removing a single entry without dropping the rest of the list.
+ * - Clearing the entire list when the operator wants the rule(s) to
+ *   start firing again.
+ * - Editing metadata when the patch body is already correct, so the
+ *   re-export's engine read + diff regeneration roundtrip is wasted.
+ *
+ * Modes are mutually exclusive: exactly one of `--add`, `--remove`, or
+ * `--clear` must be supplied per invocation. The read-modify-write
+ * happens inside the patch directory lock via {@link mutatePatchMetadata}
+ * so a concurrent writer cannot interleave between the read and the
+ * write — important when an operator scripts repeated invocations or
+ * runs `--add` and `--remove` back-to-back.
+ */
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory } from '../../core/destructive.js';
+import { mutatePatchMetadata } 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';
+/**
+ * Computes the post-mutation `lintIgnore` list for a given mode.
+ * Returns `undefined` when the result should drop the field from the
+ * manifest entirely (matching the validator's "preserve only when
+ * present" contract).
+ */
+function applyMode(existing, mode, values) {
+    const existingSet = new Set(existing);
+    if (mode === 'add') {
+        for (const v of values)
+            existingSet.add(v);
+        const merged = [...existingSet];
+        return merged.length > 0 ? merged : undefined;
+    }
+    if (mode === 'remove') {
+        for (const v of values)
+            existingSet.delete(v);
+        const remaining = [...existingSet];
+        return remaining.length > 0 ? remaining : undefined;
+    }
+    // mode === 'clear'
+    return undefined;
+}
+/**
+ * Renders a one-line summary of the planned change for use in
+ * `info()` / dry-run / history args.
+ */
+function describeChange(before, after, mode, values) {
+    const beforeSet = new Set(before);
+    const afterSet = new Set(after);
+    if (mode === 'clear') {
+        return before.length === 0
+            ? 'lintIgnore was already empty — no change'
+            : `lintIgnore cleared (was ${before.join(', ')})`;
+    }
+    if (mode === 'add') {
+        const added = values.filter((v) => !beforeSet.has(v));
+        if (added.length === 0) {
+            return 'lintIgnore unchanged (all requested IDs were already present)';
+        }
+        return `lintIgnore += ${added.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
+    }
+    // mode === 'remove'
+    const removed = values.filter((v) => beforeSet.has(v));
+    if (removed.length === 0) {
+        return 'lintIgnore unchanged (none of the requested IDs were present)';
+    }
+    return `lintIgnore −= ${removed.join(', ')} → ${[...afterSet].join(', ') || '(empty)'}`;
+}
+/**
+ * Runs the `patch lint-ignore` command: reads the patch's existing
+ * `lintIgnore`, applies the requested mode, and writes the manifest.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options (exactly one of `add`/`remove`/`clear`)
+ */
+export async function patchLintIgnoreCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch lint-ignore (dry run)' : 'FireForge patch lint-ignore');
+    // Mode mutex: exactly one mode per invocation. Combinations like
+    // `--add foo --remove bar` are rejected — an operator who needs both
+    // runs the command twice (clearer audit trail) and `--clear` plus a
+    // mode is contradictory.
+    const adding = (options.add?.length ?? 0) > 0;
+    const removing = (options.remove?.length ?? 0) > 0;
+    const clearing = options.clear === true;
+    const modeCount = [adding, removing, clearing].filter(Boolean).length;
+    if (modeCount > 1) {
+        throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', 'patch lint-ignore');
+    }
+    if (modeCount === 0) {
+        throw new InvalidArgumentError('Specify --add <id>, --remove <id>, or --clear.', 'patch lint-ignore');
+    }
+    const mode = adding ? 'add' : removing ? 'remove' : 'clear';
+    const values = mode === 'add' ? (options.add ?? []) : mode === 'remove' ? (options.remove ?? []) : [];
+    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);
+    }
+    if (isDryRun) {
+        const existing = target.lintIgnore ?? [];
+        const projected = applyMode(existing, mode, values) ?? [];
+        info(`[dry-run] ${target.filename}: ${describeChange(existing, projected, mode, values)}.`);
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    const result = await mutatePatchMetadata(paths.patches, target.filename, (existing) => {
+        const next = applyMode(existing.lintIgnore ?? [], mode, values);
+        // Either set the new list when non-empty or unset the field
+        // entirely. The mutation API splits these to keep the
+        // exactOptionalPropertyTypes contract clean — only set values land
+        // in the typed `Partial<PatchMetadata>`, and the unset list is
+        // applied via `delete` after spread.
+        return next !== undefined ? { set: { lintIgnore: next } } : { unset: ['lintIgnore'] };
+    });
+    if (!result) {
+        // Race: target vanished between the manifest read above and the
+        // locked mutate. Surfacing as a hard error rather than a silent
+        // no-op — the operator's intent did not land.
+        throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during the update. Re-run after investigating.`);
+    }
+    const existing = result.before.lintIgnore ?? [];
+    const projected = result.after.lintIgnore ?? [];
+    info(`${target.filename}: ${describeChange(existing, projected, mode, values)}.`);
+    try {
+        await appendHistory(paths.patches, {
+            operation: 'patch-lint-ignore',
+            args: {
+                filename: target.filename,
+                mode,
+                values: [...values],
+                before: existing,
+                after: projected,
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            result: 'ok',
+        });
+    }
+    catch (historyError) {
+        warn(`History log append failed after patch lint-ignore committed (${target.filename}): ${toError(historyError).message}`);
+    }
+    outro('Patch lint-ignore complete');
+}
+/**
+ * Registers the `patch lint-ignore` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchLintIgnore(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('lint-ignore <name>')
+        .description('Edit PatchMetadata.lintIgnore on a single patch (no .patch body rewrite). One mode per invocation.')
+        .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable)', (value, prev) => [...prev, value], [])
+        .option('--remove <check-id>', 'Lint check ID to remove from the patch lintIgnore list (repeatable)', (value, prev) => [...prev, value], [])
+        .option('--clear', 'Drop the lintIgnore field entirely')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        // Commander defaults `--add`/`--remove` to `[]` so they appear in
+        // the options object even when unused. Strip empty arrays so
+        // `pickDefined` sees them as absent — otherwise the mode-count
+        // mutex would treat zero-length arrays as a present mode.
+        const normalized = {};
+        if (options.add !== undefined && options.add.length > 0)
+            normalized.add = options.add;
+        if (options.remove !== undefined && options.remove.length > 0)
+            normalized.remove = options.remove;
+        if (options.clear === true)
+            normalized.clear = true;
+        if (options.dryRun === true)
+            normalized.dryRun = true;
+        if (options.yes === true)
+            normalized.yes = true;
+        await patchLintIgnoreCommand(getProjectRoot(), name, normalized);
+    }));
+}
+//# sourceMappingURL=lint-ignore.js.map

package/dist/src/commands/patch/tier.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `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 { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchTierOptions } from '../../types/commands/index.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 declare function patchTierCommand(projectRoot: string, identifier: string, options?: PatchTierOptions): Promise<void>;
+/**
+ * Registers the `patch tier` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchTier(parent: Command, context: CommandContext): void;

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