@hominis/fireforge 0.10.1 → 0.11.0

package/dist/src/commands/status.js

@@ -2,10 +2,13 @@
 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, isGitRepository } from '../core/git.js';
 import { getUntrackedFilesInDir } from '../core/git-status.js';
 import { isFileRegistered, matchesRegistrablePattern } from '../core/manifest-rules.js';
+import { buildOwnershipTable, renderOwnershipTable } from '../core/ownership-table.js';
 import { computePatchedContent } from '../core/patch-apply.js';
+import { buildPatchQueueContext, collectNewFileCreatorsByPath } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -116,7 +119,7 @@ async function expandDirectoryEntries(files, engineDir) {
 /**
  * Classifies files into patch-backed, unmanaged, or branding buckets.
  */
-async function classifyFiles(files, engineDir, patchesDir, binaryName) {
+async function classifyFiles(files, engineDir, patchesDir, binaryName, furnacePrefixes) {
     const manifest = await loadPatchesManifest(patchesDir);
     // Build set of all patch-claimed file paths
     const patchClaimedFiles = new Set();
@@ -134,6 +137,20 @@ async function classifyFiles(files, engineDir, patchesDir, binaryName) {
             results.push({ ...entry, classification: 'branding' });
             continue;
         }
+        // Furnace-managed component paths
+        if (furnacePrefixes.size > 0) {
+            let isFurnace = false;
+            for (const prefix of furnacePrefixes) {
+                if (entry.file.startsWith(prefix)) {
+                    isFurnace = true;
+                    break;
+                }
+            }
+            if (isFurnace) {
+                results.push({ ...entry, classification: 'furnace' });
+                continue;
+            }
+        }
         // Not in any patch → unmanaged
         if (!patchClaimedFiles.has(entry.file)) {
             results.push({ ...entry, classification: 'unmanaged' });
@@ -169,20 +186,74 @@ async function classifyFiles(files, engineDir, patchesDir, binaryName) {
     }
     return results;
 }
+/**
+ * Renders classified file status as machine-readable JSON to stdout.
+ */
+async function renderJsonStatus(files, paths, projectRoot, binaryName) {
+    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+    const classified = await classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
+    const output = classified.map((f) => ({
+        file: f.file,
+        status: f.status.trim(),
+        classification: f.classification,
+    }));
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+}
 /**
  * Runs the status command to show modified files.
  * @param projectRoot - Root directory of the project
  * @param options - Status display options
  */
 export async function statusCommand(projectRoot, options = {}) {
-    if (options.raw && options.unmanaged) {
-        throw new GeneralError('Cannot use --raw and --unmanaged together.');
+    const modeCount = [options.raw, options.unmanaged, options.ownership, options.json].filter((v) => v === true).length;
+    if (modeCount > 1) {
+        throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, and --json together. Pick at most one.');
     }
-    if (!options.raw) {
+    if (!options.raw && !options.json) {
         intro('FireForge Status');
     }
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
+    // Ownership mode is a flat file→patch table; sources are the manifest's
+    // filesAffected, any worktree drift, and the cross-patch
+    // duplicate-new-file-creation map produced by walking each patch
+    // body. The latter is the alignment fix between `status --ownership`
+    // and `fireforge verify` — see buildOwnershipTable's header comment.
+    // Runs before the default classify path so we can short-circuit
+    // without computing patch-backed state.
+    if (options.ownership) {
+        if (!(await pathExists(paths.engine))) {
+            throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+        }
+        const manifest = await loadPatchesManifest(paths.patches);
+        const rawFilesOwnership = (await isGitRepository(paths.engine))
+            ? await expandDirectoryEntries(await getStatusWithCodes(paths.engine), paths.engine)
+            : [];
+        // Only walk the patch bodies when the directory actually exists.
+        // Fresh projects with no patch queue yet pass through with an empty
+        // creators map, which degrades to the old filesAffected-only
+        // behavior for the empty case.
+        const newFileCreatorsByPath = (await pathExists(paths.patches))
+            ? collectNewFileCreatorsByPath(await buildPatchQueueContext(paths.patches))
+            : new Map();
+        const rows = buildOwnershipTable(manifest?.patches ?? [], rawFilesOwnership, newFileCreatorsByPath);
+        renderOwnershipTable(rows);
+        const conflictCount = rows.filter((r) => r.conflict).length;
+        const unmanagedCount = rows.filter((r) => r.unmanaged).length;
+        const managedCount = rows.filter((r) => !r.unmanaged).length;
+        const parts = [`${managedCount} managed`];
+        if (conflictCount > 0)
+            parts.push(`${conflictCount} conflict${conflictCount === 1 ? '' : 's'}`);
+        if (unmanagedCount > 0)
+            parts.push(`${unmanagedCount} unmanaged`);
+        outro(parts.join(', '));
+        if (conflictCount > 0) {
+            throw new GeneralError(`${conflictCount} path(s) are claimed by more than one patch. ` +
+                'Run "fireforge verify" for full details, then use "re-export --files" or ' +
+                '"patch delete" to resolve.');
+        }
+        return;
+    }
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
@@ -203,11 +274,18 @@ export async function statusCommand(projectRoot, options = {}) {
         renderRawStatus(files);
         return;
     }
+    // JSON mode and default mode both need classification
+    if (options.json) {
+        await renderJsonStatus(files, paths, projectRoot, config.binaryName);
+        return;
+    }
     // Patch-aware classification
-    const classified = await classifyFiles(files, paths.engine, paths.patches, config.binaryName);
+    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+    const classified = await classifyFiles(files, paths.engine, paths.patches, config.binaryName, furnacePrefixes);
     const unmanagedFiles = classified.filter((f) => f.classification === 'unmanaged');
     const patchBackedFiles = classified.filter((f) => f.classification === 'patch-backed');
     const brandingFiles = classified.filter((f) => f.classification === 'branding');
+    const furnaceFiles = classified.filter((f) => f.classification === 'furnace');
     // --unmanaged mode: only show unmanaged
     if (options.unmanaged) {
         info(`${unmanagedFiles.length} unmanaged file${unmanagedFiles.length === 1 ? '' : 's'} (${files.length} total modified):\n`);
@@ -242,7 +320,16 @@ export async function statusCommand(projectRoot, options = {}) {
         warn('Tool-managed branding changes:');
         printStatusGroups(brandingFiles);
     }
-    if (unmanagedFiles.length === 0 && patchBackedFiles.length === 0 && brandingFiles.length === 0) {
+    if (furnaceFiles.length > 0) {
+        if (unmanagedFiles.length > 0 || patchBackedFiles.length > 0 || brandingFiles.length > 0)
+            info('');
+        warn('Furnace-managed component changes:');
+        printStatusGroups(furnaceFiles);
+    }
+    if (unmanagedFiles.length === 0 &&
+        patchBackedFiles.length === 0 &&
+        brandingFiles.length === 0 &&
+        furnaceFiles.length === 0) {
         info('No changes');
     }
     const parts = [];
@@ -252,6 +339,8 @@ export async function statusCommand(projectRoot, options = {}) {
         parts.push(`${patchBackedFiles.length} patch-backed`);
     if (brandingFiles.length > 0)
         parts.push(`${brandingFiles.length} branding`);
+    if (furnaceFiles.length > 0)
+        parts.push(`${furnaceFiles.length} furnace`);
     outro(parts.join(', '));
 }
 /** Registers the status command on the CLI program. */
@@ -261,6 +350,8 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .description('Show modified files in engine/')
         .option('--raw', 'Show raw worktree status without patch classification')
         .option('--unmanaged', 'Show only unmanaged changes (not covered by patches or tools)')
+        .option('--ownership', 'Show a flat path → owning patch table (flags files claimed by multiple patches)')
+        .option('--json', 'Output classified file status as JSON')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);
     }));

package/dist/src/commands/test.js

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
-import { isBrandingSetup, setupBranding } from '../core/branding.js';
+import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { cleanStories } from '../core/furnace-stories.js';
-import { buildArtifactMismatchMessage, buildUI, generateMozconfig, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -53,38 +52,6 @@ function hasStaleBuildArtifactsSignal(output) {
         /resource:\/\/\/modules\/distribution\.sys\.mjs/i.test(output) ||
         /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
 }
-async function prepareIncrementalTestBuild(projectRoot) {
-    const config = await loadConfig(projectRoot);
-    const paths = getProjectPaths(projectRoot);
-    const brandingConfig = {
-        name: config.name,
-        vendor: config.vendor,
-        appId: config.appId,
-        binaryName: config.binaryName,
-    };
-    if (!(await isBrandingSetup(paths.engine, brandingConfig))) {
-        const brandingSpinner = spinner('Setting up branding...');
-        try {
-            await setupBranding(paths.engine, brandingConfig);
-            brandingSpinner.stop('Branding configured');
-        }
-        catch (error) {
-            brandingSpinner.error('Failed to set up branding');
-            throw error;
-        }
-    }
-    const mozconfigSpinner = spinner('Generating mozconfig...');
-    try {
-        await generateMozconfig(paths.configs, paths.engine, config);
-        mozconfigSpinner.stop('mozconfig generated');
-    }
-    catch (error) {
-        mozconfigSpinner.error('Failed to generate mozconfig');
-        throw error;
-    }
-    await cleanStories(paths.engine);
-    return { engineDir: paths.engine };
-}
 function handleNonZeroTestExit(result, normalizedPaths) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
@@ -133,9 +100,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     }
     // Run incremental build if requested
     if (options.build) {
-        const { engineDir } = await prepareIncrementalTestBuild(projectRoot);
+        const config = await loadConfig(projectRoot);
+        await prepareBuildEnvironment(projectRoot, paths, config);
         const s = spinner('Running incremental build...');
-        const buildExitCode = await buildUI(engineDir);
+        const buildExitCode = await buildUI(paths.engine);
         if (buildExitCode !== 0) {
             s.error('Pre-test build failed');
             throw new BuildError('Pre-test build failed', 'mach build faster');

package/dist/src/commands/verify.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `fireforge verify` — read-only fsck for the patch queue.
+ *
+ * Combines the manifest consistency check (orphan files, missing entries,
+ * files-affected mismatch, duplicate entries) with the cross-patch lint
+ * rules (duplicate /dev/null creation, forward imports). Does not run
+ * `planExport` per patch — that is intentionally out of scope because it
+ * would couple verify to engine state and make the command too slow to be
+ * useful as a pre-flight gate. Engine-level patch application issues are
+ * still covered by the existing `fireforge doctor` and `fireforge import`
+ * paths.
+ *
+ * Exits non-zero when any error-severity finding is reported so CI can
+ * treat the output as pass/fail.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/**
+ * Runs the `verify` command: manifest consistency + cross-patch lint.
+ * Read-only; exits non-zero on any error-severity finding.
+ *
+ * @param projectRoot - Project root directory
+ */
+export declare function verifyCommand(projectRoot: string): Promise<void>;
+/**
+ * Registers the `verify` command on the CLI program.
+ *
+ * @param program - Commander root program
+ * @param context - Shared CLI registration context
+ */
+export declare function registerVerify(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/verify.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge verify` — read-only fsck for the patch queue.
+ *
+ * Combines the manifest consistency check (orphan files, missing entries,
+ * files-affected mismatch, duplicate entries) with the cross-patch lint
+ * rules (duplicate /dev/null creation, forward imports). Does not run
+ * `planExport` per patch — that is intentionally out of scope because it
+ * would couple verify to engine state and make the command too slow to be
+ * useful as a pre-flight gate. Engine-level patch application issues are
+ * still covered by the existing `fireforge doctor` and `fireforge import`
+ * paths.
+ *
+ * Exits non-zero when any error-severity finding is reported so CI can
+ * treat the output as pass/fail.
+ */
+import { getProjectPaths } from '../core/config.js';
+import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
+import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, outro, success, warn } from '../utils/logger.js';
+/**
+ * Reports duplicate `filesAffected` entries across patches — the manifest
+ * consistency check only flags per-patch duplicates and orphan files, not
+ * the case where two different patches claim the same path. `verify`
+ * surfaces that here so it can be caught before `export`, `re-export`, or
+ * `rebase` hit it.
+ */
+function detectCrossPatchFileClaims(manifestPatches) {
+    const claims = new Map();
+    for (const patch of manifestPatches) {
+        for (const file of patch.filesAffected) {
+            const existing = claims.get(file) ?? [];
+            existing.push(patch.filename);
+            claims.set(file, existing);
+        }
+    }
+    const results = [];
+    for (const [path, filenames] of claims) {
+        if (filenames.length > 1) {
+            results.push({ path, filenames });
+        }
+    }
+    return results;
+}
+/**
+ * Runs the `verify` command: manifest consistency + cross-patch lint.
+ * Read-only; exits non-zero on any error-severity finding.
+ *
+ * @param projectRoot - Project root directory
+ */
+export async function verifyCommand(projectRoot) {
+    intro('FireForge Verify');
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        info('No patches directory. Nothing to verify.');
+        outro('Verify clean');
+        return;
+    }
+    let errorCount = 0;
+    let warningCount = 0;
+    // 1. Manifest consistency: orphan patch files, missing entries,
+    // files-affected mismatch, duplicate entries, unparseable manifest.
+    const consistencyIssues = await validatePatchesManifestConsistency(paths.patches);
+    if (consistencyIssues.length > 0) {
+        warn(`Manifest consistency issues (${consistencyIssues.length}):`);
+        for (const issue of consistencyIssues) {
+            warn(`  [${issue.code}] ${issue.message}`);
+            errorCount += 1;
+        }
+    }
+    // 2. Cross-patch file claims: two or more manifest entries listing the
+    // same path in filesAffected. Not caught by per-patch consistency.
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (manifest) {
+        const crossClaims = detectCrossPatchFileClaims(manifest.patches);
+        if (crossClaims.length > 0) {
+            warn(`Cross-patch filesAffected conflicts (${crossClaims.length}):`);
+            for (const claim of crossClaims) {
+                warn(`  ${claim.path}  claimed by: ${claim.filenames.join(', ')}`);
+                errorCount += 1;
+            }
+        }
+    }
+    // 3. Cross-patch lint: duplicate /dev/null creation + forward imports.
+    const ctx = await buildPatchQueueContext(paths.patches);
+    const lintIssues = lintPatchQueue(ctx);
+    if (lintIssues.length > 0) {
+        warn(`Cross-patch lint issues (${lintIssues.length}):`);
+        for (const issue of lintIssues) {
+            const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
+            warn(`  ${label} [${issue.check}] ${issue.file}: ${issue.message}`);
+            if (issue.severity === 'error')
+                errorCount += 1;
+            else
+                warningCount += 1;
+        }
+    }
+    if (errorCount === 0 && warningCount === 0) {
+        success('Patch queue is consistent.');
+        outro('Verify clean');
+        return;
+    }
+    info(`\nVerify: ${errorCount} error(s), ${warningCount} warning(s)`);
+    if (errorCount > 0) {
+        outro('Verify failed');
+        throw new GeneralError(`fireforge verify found ${errorCount} error(s). Fix these before running export/import/rebase.`);
+    }
+    outro('Verify passed with warnings');
+}
+/**
+ * Registers the `verify` command on the CLI program.
+ *
+ * @param program - Commander root program
+ * @param context - Shared CLI registration context
+ */
+export function registerVerify(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('verify')
+        .description('Read-only fsck for the patch queue (manifest + cross-patch lint)')
+        .action(withErrorHandling(async () => {
+        await verifyCommand(getProjectRoot());
+    }));
+}
+//# sourceMappingURL=verify.js.map

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

@@ -3,10 +3,13 @@
  * Shared pre-flight logic for build and package commands:
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
+import { FurnaceError } from '../errors/furnace.js';
+import { pathExists } from '../utils/fs.js';
 import { spinner, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
 import { applyAllComponents } from './furnace-apply.js';
-import { furnaceConfigExists, loadFurnaceConfig } from './furnace-config.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+import { runFurnaceMutation } from './furnace-operation.js';
 import { cleanStories } from './furnace-stories.js';
 import { generateMozconfig } from './mach.js';
 /**
@@ -22,6 +25,17 @@ import { generateMozconfig } from './mach.js';
  * @returns Preparation results
  */
 export async function prepareBuildEnvironment(projectRoot, paths, config) {
+    // Block the build if Furnace has an unresolved repair marker. This prevents
+    // building against an engine that may be in an inconsistent state after a
+    // failed rollback.
+    const furnaceStatePath = getFurnacePaths(projectRoot).furnaceState;
+    if (await pathExists(furnaceStatePath)) {
+        const furnaceState = await loadFurnaceState(projectRoot);
+        if (furnaceState.pendingRepair) {
+            throw new FurnaceError(`Furnace has an unresolved repair marker (from ${furnaceState.pendingRepair.operation}). ` +
+                'Run "fireforge doctor --repair-furnace" to reconcile engine state before building.');
+        }
+    }
     // Clean stories before build to ensure they don't leak into production binary
     await cleanStories(paths.engine);
     // Set up custom branding directory and patch moz.configure
@@ -50,19 +64,26 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
             Object.keys(furnaceConfig.custom).length > 0;
         if (hasComponents) {
             const furnaceSpinner = spinner('Applying Furnace components...');
+            let result;
             try {
-                const result = await applyAllComponents(projectRoot);
-                furnaceApplied = result.applied.length;
-                if (furnaceApplied > 0) {
-                    furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
-                }
-                else {
-                    furnaceSpinner.stop('Components up to date');
-                }
-                if (result.errors.length > 0) {
-                    for (const err of result.errors) {
-                        warn(`Furnace: ${err.name} — ${err.error}`);
-                    }
+                result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
+            }
+            catch (error) {
+                furnaceSpinner.error('Failed to apply Furnace components');
+                throw error;
+            }
+            furnaceApplied = result.applied.length;
+            // Count entries that were "applied" but recorded step-level errors
+            // mid-apply (e.g. a post-step failure after file writes succeeded).
+            // These are distinct from `result.errors`, which captures
+            // components that failed before reaching the applied list at all.
+            // The sum of the two is the total count of failed components.
+            const appliedWithStepErrorsCount = result.applied.filter((entry) => (entry.stepErrors?.length ?? 0) > 0).length;
+            const totalApplyFailures = result.errors.length + appliedWithStepErrorsCount;
+            if (totalApplyFailures > 0) {
+                furnaceSpinner.error('Failed to apply Furnace components');
+                for (const err of result.errors) {
+                    warn(`Furnace: ${err.name} — ${err.error}`);
                 }
                 for (const applied of result.applied) {
                     if (applied.stepErrors && applied.stepErrors.length > 0) {
@@ -71,10 +92,13 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
                         }
                     }
                 }
+                throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
             }
-            catch (error) {
-                furnaceSpinner.error('Failed to apply Furnace components');
-                throw error;
+            if (furnaceApplied > 0) {
+                furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
+            }
+            else {
+                furnaceSpinner.stop('Components up to date');
             }
         }
     }

package/dist/src/core/destructive.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared destructive-operation contract: interactive confirmation, non-TTY
+ * refusal, dry-run plumbing, hard-refusal on structural conflicts, and a
+ * JSONL audit log.
+ *
+ * This exists because the repair primitives (`patch delete`, `patch reorder`,
+ * `re-export --files`) and the new `export --dry-run`/`export --order` flags
+ * all share the same dance: build a change summary, gate it behind a prompt,
+ * accept a `--yes` bypass for CI, accept a `--dry-run` no-op, and refuse
+ * outright when the change would introduce a structural conflict (e.g. a
+ * forward-import that later-patch lint would then block). Without a single
+ * helper, every new destructive command would re-implement this and drift.
+ */
+/** Filename of the audit log, relative to the patches directory. */
+export declare const HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
+/**
+ * A structural conflict that must block the operation even under `--force`.
+ *
+ * Intended for cases like "reorder would introduce a forward-import" or
+ * "delete would orphan a later patch's import" — situations where the
+ * operator almost certainly wants a different fix (re-export --files, etc.)
+ * rather than a bypass. `--force-unsafe` is the escape hatch when the
+ * operator genuinely accepts the risk.
+ */
+export interface ConflictReport {
+    /** Short one-line reason the operation is refused. */
+    reason: string;
+    /** Specific conflicts (patch names, file paths, lint findings). */
+    details: string[];
+}
+/** Inputs to {@link confirmDestructive}. */
+export interface DestructiveOpInput {
+    /** Operation identifier, used in history entries (e.g. `patch-delete`). */
+    operation: string;
+    /** Short one-line title shown in the prompt. */
+    title: string;
+    /**
+     * Detailed change summary — every affected patch, file, or renumber row.
+     * Generic "proceed? [y/N]" is insufficient per the destructive-op contract;
+     * callers must list every concrete change here.
+     */
+    summary: string[];
+    /** Whether the caller passed `--yes`. */
+    yes: boolean;
+    /** Whether the caller passed `--dry-run`. */
+    dryRun: boolean;
+    /** Whether the caller passed `--force-unsafe`. Only this flag bypasses conflicts. */
+    unsafeOverride?: boolean;
+    /** Structural conflicts that should block the operation unless `unsafeOverride`. */
+    conflicts?: ConflictReport | null;
+}
+/** Outcome of {@link confirmDestructive}. */
+export type DestructiveOpResult = 'proceed' | 'dry-run' | 'cancelled';
+/**
+ * Inputs to {@link appendHistory}. Entries are appended as one JSON record
+ * per line. Callers should only append after a mutation succeeds so
+ * rolled-back failures never leave ghost entries.
+ */
+export interface HistoryEntry {
+    /** Operation identifier matching the DestructiveOpInput. */
+    operation: string;
+    /** Serializable argument payload (flags, targets, renumber map, etc.). */
+    args: Record<string, unknown>;
+    /** True if `--yes` was used. */
+    yes?: boolean;
+    /** True if `--force-unsafe` was used. */
+    unsafeOverride?: boolean;
+    /** Result: `'ok'` on success; other strings describe failure. */
+    result: string;
+}
+/**
+ * Executes the destructive-operation contract: summary → conflict refusal →
+ * dry-run / force / prompt / non-TTY refusal.
+ *
+ * Returns the decision for the caller to act on; callers must not execute the
+ * mutation when the result is `'dry-run'` or `'cancelled'`, and must call
+ * {@link appendHistory} only after the mutation succeeds (never on dry-run or
+ * cancellation).
+ *
+ * @param input - Operation description, flags, and optional conflict report
+ * @returns `'proceed'` to execute, `'dry-run'` to skip execution, or
+ *   `'cancelled'` when the user declined the prompt
+ */
+export declare function confirmDestructive(input: DestructiveOpInput): Promise<DestructiveOpResult>;
+/**
+ * Appends a single JSONL record to `patches/.fireforge-history.jsonl`.
+ *
+ * Call order matters: append only after the mutation succeeds, never
+ * pre-emptively, so rolled-back failures do not leave ghost entries. The log
+ * is append-only and advisory — no code path reads it back; it exists purely
+ * so operators have a post-hoc audit trail when something goes wrong.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param entry - Serializable history record
+ */
+export declare function appendHistory(patchesDir: string, entry: HistoryEntry): Promise<void>;