@hominis/fireforge 0.10.1 → 0.11.0

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

@@ -7,7 +7,7 @@ export { PatchError } from '../errors/patch.js';
 export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
 export { withPatchDirectoryLock } from './patch-lock.js';
 export { extractAffectedFiles, extractOrder, isNewFileInPatch, parseHunksForFile, } from './patch-parse.js';
-export { applyPatchToContent, extractNewFileContent } from './patch-transform.js';
+export { applyPatchToContent, extractNewFileContent, extractNewFileContentFromDiff, } from './patch-transform.js';
 /**
  * Applies all patches in order. Rolls back all successfully applied
  * patches when one fails so the engine directory stays clean.
@@ -26,16 +26,30 @@ export declare function validatePatches(patchesDir: string, engineDir: string):
     valid: boolean;
     errors: string[];
 }>;
+/**
+ * Options for {@link applyPatchesWithContinue}.
+ */
+export interface ApplyPatchesOptions {
+    /** Continue applying patches even after one fails. */
+    continueOnFailure?: boolean;
+    /**
+     * Stop applying patches after this filename has been processed
+     * (successfully or not). Any patches after it in apply order are left
+     * untouched. Accepts either the bare filename (with or without .patch)
+     * or the numeric ordinal as a string. Unknown identifiers throw.
+     */
+    untilFilename?: string | undefined;
+}
 /**
  * Enhanced patch application with continue mode.
  * When continueOnFailure is false, rolls back all previously applied patches
  * on the first failure to keep the engine directory in a clean state.
  * @param patchesDir - Path to the patches directory
  * @param engineDir - Path to the engine directory
- * @param continueOnFailure - Whether to continue after failures
+ * @param optionsOrContinue - Options object, or the legacy continueOnFailure boolean
  * @returns Import summary with all results
  */
-export declare function applyPatchesWithContinue(patchesDir: string, engineDir: string, continueOnFailure?: boolean): Promise<ImportSummary>;
+export declare function applyPatchesWithContinue(patchesDir: string, engineDir: string, optionsOrContinue?: ApplyPatchesOptions | boolean): Promise<ImportSummary>;
 /**
  * Computes the cumulative patched content for a file.
  * @param patchesDir - Path to the patches directory

package/dist/src/core/patch-apply.js

@@ -21,7 +21,7 @@ export { PatchError } from '../errors/patch.js';
 export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
 export { withPatchDirectoryLock } from './patch-lock.js';
 export { extractAffectedFiles, extractOrder, isNewFileInPatch, parseHunksForFile, } from './patch-parse.js';
-export { applyPatchToContent, extractNewFileContent } from './patch-transform.js';
+export { applyPatchToContent, extractNewFileContent, extractNewFileContentFromDiff, } from './patch-transform.js';
 /**
  * Applies a single patch.
  * @param patch - Patch info
@@ -164,21 +164,99 @@ function validatePatchTargets(patch, affectedFiles) {
         }
     }
 }
+/**
+ * Decides whether a patch filename matches an `--until` identifier.
+ *
+ * The identifier is one of three shapes and the three shapes must stay
+ * disjoint so the operator can reason about which patch they picked:
+ *
+ *   1. **Exact filename** — `005-foo.patch`. Matches only that filename.
+ *   2. **Filename without extension** — `005-foo`. Matches `005-foo.patch`.
+ *   3. **Bare numeric ordinal** — `5` or `005`. Matches the patch whose
+ *      order prefix parses to the same integer (so `5` and `005` both
+ *      match `005-foo.patch`, and `05` matches too because parseInt
+ *      normalizes leading zeros).
+ *
+ * A purely-numeric identifier is treated **only** as an ordinal: it does
+ * not also match a filename that happens to literally equal the digits.
+ * That would require a patch literally named `5` or `005` — which would
+ * collide with the filename prefix anyway — and we prefer the explicit
+ * ordinal interpretation. The earlier form's `patchFilename === needle`
+ * short-circuit was kept behind the numeric gate so the match stays
+ * single-meaning per identifier.
+ */
+function matchesUntilFilename(patchFilename, needle) {
+    const isNumeric = /^\d+$/.test(needle);
+    if (isNumeric) {
+        const order = parseInt(needle, 10);
+        const prefixMatch = /^(\d+)-/.exec(patchFilename);
+        return prefixMatch !== null && parseInt(prefixMatch[1] ?? '0', 10) === order;
+    }
+    if (patchFilename === needle)
+        return true;
+    if (patchFilename === `${needle}.patch`)
+        return true;
+    return false;
+}
 /**
  * Enhanced patch application with continue mode.
  * When continueOnFailure is false, rolls back all previously applied patches
  * on the first failure to keep the engine directory in a clean state.
  * @param patchesDir - Path to the patches directory
  * @param engineDir - Path to the engine directory
- * @param continueOnFailure - Whether to continue after failures
+ * @param optionsOrContinue - Options object, or the legacy continueOnFailure boolean
  * @returns Import summary with all results
  */
-export async function applyPatchesWithContinue(patchesDir, engineDir, continueOnFailure = false) {
+export async function applyPatchesWithContinue(patchesDir, engineDir, optionsOrContinue = false) {
+    // Accept both the legacy boolean positional and the new options object so
+    // existing call sites (tests and rebase) keep working without a rewrite.
+    const options = typeof optionsOrContinue === 'boolean'
+        ? { continueOnFailure: optionsOrContinue }
+        : optionsOrContinue;
+    const continueOnFailure = options.continueOnFailure ?? false;
+    const untilFilename = options.untilFilename;
     const patches = await discoverPatches(patchesDir);
+    // Resolve the --until stop index up front so callers get an immediate
+    // error on an unknown identifier instead of a silent no-op. Detect
+    // ambiguity (two patches matching the same needle — should never happen
+    // in a well-formed manifest but surfaces queue corruption loudly
+    // instead of silently picking the first match).
+    let stopIndex = patches.length - 1;
+    if (untilFilename !== undefined) {
+        const matchingIndexes = [];
+        for (let i = 0; i < patches.length; i++) {
+            const patch = patches[i];
+            if (patch && matchesUntilFilename(patch.filename, untilFilename)) {
+                matchingIndexes.push(i);
+            }
+        }
+        if (matchingIndexes.length === 0) {
+            throw new PatchError(`--until identifier "${untilFilename}" does not match any patch. ` +
+                `Available: ${patches.map((p) => p.filename).join(', ')}`);
+        }
+        if (matchingIndexes.length > 1) {
+            const matches = matchingIndexes
+                .map((idx) => patches[idx]?.filename ?? '<unknown>')
+                .join(', ');
+            throw new PatchError(`--until identifier "${untilFilename}" is ambiguous: matches ${matchingIndexes.length} ` +
+                `patches (${matches}). Use the full filename to disambiguate.`);
+        }
+        stopIndex = matchingIndexes[0] ?? patches.length - 1;
+    }
     const succeeded = [];
     const failed = [];
     const skipped = [];
-    for (const patch of patches) {
+    for (let i = 0; i < patches.length; i++) {
+        const patch = patches[i];
+        if (!patch)
+            continue;
+        if (i > stopIndex) {
+            // Patches beyond the --until cutoff are intentionally skipped. They
+            // are not failures — record them in `skipped` so the summary still
+            // reflects what the full queue contained.
+            skipped.push(patch);
+            continue;
+        }
         const result = await applySinglePatch(patch, engineDir);
         if (result.success) {
             succeeded.push(result);
@@ -193,10 +271,10 @@ export async function applyPatchesWithContinue(patchesDir, engineDir, continueOn
                     verbose(`Rolling back ${succeeded.length} previously applied patch(es)…`);
                     await rollbackPatches(succeeded, engineDir);
                 }
-                // Mark remaining patches as skipped
-                const currentIndex = patches.indexOf(patch);
-                for (let i = currentIndex + 1; i < patches.length; i++) {
-                    const remainingPatch = patches[i];
+                // Mark remaining patches as skipped (including anything that was
+                // already past the --until cutoff, which stays skipped).
+                for (let j = i + 1; j < patches.length; j++) {
+                    const remainingPatch = patches[j];
                     if (remainingPatch) {
                         skipped.push(remainingPatch);
                     }

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

@@ -1,4 +1,4 @@
-import type { PatchCategory, PatchInfo, PatchMetadata } from '../types/commands/index.js';
+import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '../types/commands/index.js';
 /**
  * Gets the next patch number for a new patch.
  * @param patchesDir - Path to the patches directory
@@ -28,8 +28,12 @@ export interface CommitExportedPatchResult {
     superseded: PatchInfo[];
 }
 /**
- * Commits a freshly generated patch file and manifest update under an exclusive
- * patch directory lock so concurrent exports cannot allocate the same number.
+ * Commits a freshly generated patch file and manifest update under an
+ * exclusive patch directory lock so concurrent exports cannot allocate the
+ * same number. Shares {@link computeExportPlanUnderLock} with
+ * {@link planExport} so the dry-run preview cannot drift from the real
+ * write: both paths go through the same planning helper, and any bug fix
+ * to filename allocation or supersede detection lands in both automatically.
  */
 export declare function commitExportedPatch(input: CommitExportedPatchInput): Promise<CommitExportedPatchResult>;
 /**
@@ -58,6 +62,32 @@ export declare function findExistingPatchForFile(patchesDir: string, filePath: s
  * @param newContent - New patch content
  */
 export declare function updatePatch(patchPath: string, newContent: string): Promise<void>;
+/**
+ * Optional post-commit hook for {@link updatePatchAndMetadata}. Runs inside
+ * the patch directory lock after the mutation has succeeded but before the
+ * lock is released. Intended for history-log appends so the audit record
+ * lands atomically with the mutation. Hook failures are warned but never
+ * re-thrown: by the time the hook runs the mutation is already committed,
+ * so there is nothing meaningful to roll back.
+ */
+export type UpdatePatchCommittedHook = () => Promise<void>;
+/**
+ * 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.
+ *
+ * If the manifest write fails after the patch body has been rewritten, the
+ * original patch content is restored best-effort before the error is
+ * re-thrown.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Target patch filename
+ * @param newContent - New patch body
+ * @param updates - Metadata fields to merge into the existing row
+ * @param onCommitted - Optional hook that runs inside the same lock after
+ *   the mutation succeeds. See {@link UpdatePatchCommittedHook}.
+ */
+export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook): Promise<void>;
 /**
  * Updates metadata for a patch in the manifest.
  * @param patchesDir - Path to the patches directory
@@ -80,14 +110,28 @@ export declare function findSupersededPatches(patchesDir: string, newPatchFiles:
  * @param filename - Patch filename to delete
  */
 export declare function deletePatch(patchesDir: string, filename: string): Promise<void>;
+/**
+ * Report whether a patch is fully covered by a new export, and which of its
+ * files caused the coverage.
+ *
+ * Widened from a bare boolean to `{covered, byFiles}` so that `export
+ * --supersede --dry-run` can tell the operator which files in each existing
+ * patch triggered its supersession — the opaque "this export would
+ * supersede N patches" message was the primary reason `--supersede` was
+ * unsafe before this change.
+ */
+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 True when the existing patch is fully covered
+ * @returns Coverage report with the triggering file list when `covered` is true
  */
-export declare function isPatchFullyCovered(patchFiles: string[], targetFiles: string[]): boolean;
+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.
@@ -97,3 +141,73 @@ export declare function isPatchFullyCovered(patchFiles: string[], targetFiles: s
  * @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 {@link 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. Mirrors {@link findAllPatchesForFiles} but returns the
+ * widened {@link PatchCoverage.byFiles} list per match so callers can render
+ * a per-patch breakdown.
+ */
+export declare function findAllPatchesForFilesWithDetails(patchesDir: string, targetFiles: string[], excludeFilename?: string): Promise<{
+    patch: PatchInfo;
+    coverage: PatchCoverage;
+    metadata: PatchMetadata;
+}[]>;
+/**
+ * Fully computed plan for a pending export. Returned from
+ * {@link planExport} so that `--dry-run` previews can render the full
+ * outcome of the hypothetical write without touching disk.
+ *
+ * Dry-run and the real write both go through {@link computeExportPlanUnderLock}
+ * so their filename allocation, supersede detection, and projected
+ * post-write manifest cannot drift. `planExport` exposes the rich coverage
+ * form for preview rendering; {@link commitExportedPatch} consumes the bare
+ * `PatchInfo[]` form of the same underlying data.
+ */
+export interface ExportPlan {
+    /** Allocated patch filename (e.g. `005-ui-sidebar.patch`). */
+    patchFilename: string;
+    /** Full metadata row that would be written to the manifest. */
+    metadata: PatchMetadata;
+    /** Existing patches that would be superseded by this export. */
+    superseded: SupersedeCoverageDetail[];
+    /** Manifest state as it existed when the plan was computed. */
+    manifestBefore: PatchesManifest | null;
+    /**
+     * Manifest state the plan would write. Always includes the new patch
+     * metadata and excludes any superseded filenames.
+     */
+    manifestAfter: PatchesManifest;
+}
+export interface PlanExportInput {
+    patchesDir: string;
+    category: PatchCategory;
+    name: string;
+    description: string;
+    filesAffected: string[];
+    sourceEsrVersion: string;
+}
+/**
+ * Read-only planning function — computes everything a real export would
+ * do without writing anything to disk. Takes the patch directory lock
+ * briefly, runs {@link computeExportPlanUnderLock}, releases the lock,
+ * and returns the plan for preview rendering.
+ *
+ * Shares {@link computeExportPlanUnderLock} with {@link commitExportedPatch}
+ * so the dry-run preview cannot drift from the real write. The real write
+ * path does NOT reuse a prior plan object (another export may have landed
+ * between dry-run and commit, which would stale the filename allocation);
+ * it re-runs the same helper under a fresh lock. The guarantee is "same
+ * code, possibly different data," not "same plan object."
+ */
+export declare function planExport(input: PlanExportInput): Promise<ExportPlan>;

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

@@ -47,37 +47,35 @@ export async function getNextPatchFilename(patchesDir, category, name) {
     return `${patchNumber}-${category}-${sanitizedName}.patch`;
 }
 /**
- * Commits a freshly generated patch file and manifest update under an exclusive
- * patch directory lock so concurrent exports cannot allocate the same number.
+ * Commits a freshly generated patch file and manifest update under an
+ * exclusive patch directory lock so concurrent exports cannot allocate the
+ * same number. Shares {@link computeExportPlanUnderLock} with
+ * {@link planExport} so the dry-run preview cannot drift from the real
+ * write: both paths go through the same planning helper, and any bug fix
+ * to filename allocation or supersede detection lands in both automatically.
  */
 export async function commitExportedPatch(input) {
     return withPatchDirectoryLock(input.patchesDir, async () => {
-        const patchFilename = await getNextPatchFilename(input.patchesDir, input.category, input.name);
-        const patchPath = join(input.patchesDir, patchFilename);
-        const metadata = {
-            filename: patchFilename,
-            order: parseInt(patchFilename.split('-')[0] ?? '0', 10),
+        const plan = await computeExportPlanUnderLock({
+            patchesDir: input.patchesDir,
             category: input.category,
             name: input.name,
             description: input.description,
-            createdAt: new Date().toISOString(),
-            sourceEsrVersion: input.sourceEsrVersion,
             filesAffected: input.filesAffected,
-        };
-        const superseded = await findAllPatchesForFiles(input.patchesDir, input.filesAffected, patchFilename);
-        const supersededFilenames = superseded.map((patch) => patch.filename);
-        const originalManifest = await loadPatchesManifest(input.patchesDir);
+            sourceEsrVersion: input.sourceEsrVersion,
+        });
+        const patchPath = plan.patchPath;
         const originalPatchContent = (await pathExists(patchPath)) ? await readText(patchPath) : null;
         const removedPatchContents = new Map();
-        for (const oldPatch of superseded) {
+        for (const oldPatch of plan.supersededPatches) {
             if (await pathExists(oldPatch.path)) {
                 removedPatchContents.set(oldPatch.path, await readText(oldPatch.path));
             }
         }
         try {
             await writeText(patchPath, input.diff);
-            await addPatchToManifest(input.patchesDir, metadata, supersededFilenames);
-            for (const oldPatch of superseded) {
+            await addPatchToManifest(input.patchesDir, plan.metadata, plan.supersededPatches.map((p) => p.filename));
+            for (const oldPatch of plan.supersededPatches) {
                 await removeFile(oldPatch.path);
             }
         }
@@ -104,8 +102,8 @@ export async function commitExportedPatch(input) {
                 }
             }
             try {
-                if (originalManifest) {
-                    await savePatchesManifest(input.patchesDir, originalManifest);
+                if (plan.manifestBefore) {
+                    await savePatchesManifest(input.patchesDir, plan.manifestBefore);
                 }
                 else {
                     await removeFile(join(input.patchesDir, PATCHES_MANIFEST));
@@ -117,9 +115,9 @@ export async function commitExportedPatch(input) {
             throw error;
         }
         return {
-            patchFilename,
-            metadata,
-            superseded,
+            patchFilename: plan.patchFilename,
+            metadata: plan.metadata,
+            superseded: plan.supersededPatches,
         };
     });
 }
@@ -177,6 +175,67 @@ export async function findExistingPatchForFile(patchesDir, filePath) {
 export async function updatePatch(patchPath, newContent) {
     await writeText(patchPath, newContent);
 }
+/**
+ * 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.
+ *
+ * If the manifest write fails after the patch body has been rewritten, the
+ * original patch content is restored best-effort before the error is
+ * re-thrown.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Target patch filename
+ * @param newContent - New patch body
+ * @param updates - Metadata fields to merge into the existing row
+ * @param onCommitted - Optional hook that runs inside the same lock after
+ *   the mutation succeeds. See {@link UpdatePatchCommittedHook}.
+ */
+export async function updatePatchAndMetadata(patchesDir, filename, newContent, updates, onCommitted) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest) {
+            throw new Error('Cannot update patch metadata: patches.json is missing.');
+        }
+        const patchIndex = manifest.patches.findIndex((p) => p.filename === filename);
+        if (patchIndex === -1) {
+            throw new Error(`Cannot update patch metadata: ${filename} not found in patches.json.`);
+        }
+        const patchPath = join(patchesDir, filename);
+        if (!(await pathExists(patchPath))) {
+            throw new Error(`Cannot update patch: patch file is missing on disk: ${filename}`);
+        }
+        const originalContent = await readText(patchPath);
+        const existingPatch = manifest.patches[patchIndex];
+        manifest.patches[patchIndex] = { ...existingPatch, ...updates };
+        let patchWritten = false;
+        try {
+            await writeText(patchPath, newContent);
+            patchWritten = true;
+            await savePatchesManifest(patchesDir, manifest);
+        }
+        catch (error) {
+            if (patchWritten) {
+                try {
+                    await writeText(patchPath, originalContent);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore ${filename} after metadata write failed: ${toError(rollbackError).message}`);
+                }
+            }
+            throw error;
+        }
+        if (onCommitted) {
+            try {
+                await onCommitted();
+            }
+            catch (hookError) {
+                warn(`History log append failed after updatePatchAndMetadata committed (${filename}): ` +
+                    toError(hookError).message);
+            }
+        }
+    });
+}
 /**
  * Updates metadata for a patch in the manifest.
  * @param patchesDir - Path to the patches directory
@@ -275,14 +334,18 @@ export async function deletePatch(patchesDir, filename) {
  * 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 True when the existing patch is fully covered
+ * @returns Coverage report with the triggering file list when `covered` is true
  */
 export function isPatchFullyCovered(patchFiles, targetFiles) {
     if (patchFiles.length === 0) {
-        return false;
+        return { covered: false, byFiles: [] };
     }
     const targetFileSet = new Set(targetFiles);
-    return patchFiles.every((file) => targetFileSet.has(file));
+    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.
@@ -302,7 +365,7 @@ export async function findAllPatchesForFiles(patchesDir, targetFiles, excludeFil
         // Skip the new patch itself
         if (excludeFilename && metadata.filename === excludeFilename)
             continue;
-        if (isPatchFullyCovered(metadata.filesAffected, targetFiles)) {
+        if (isPatchFullyCovered(metadata.filesAffected, targetFiles).covered) {
             const patch = patches.find((p) => p.filename === metadata.filename);
             if (patch) {
                 superseded.push(patch);
@@ -311,4 +374,99 @@ export async function findAllPatchesForFiles(patchesDir, targetFiles, excludeFil
     }
     return superseded;
 }
+/**
+ * Resolves coverage details for every existing patch that the new export
+ * would fully cover. Mirrors {@link findAllPatchesForFiles} but returns the
+ * widened {@link PatchCoverage.byFiles} list per match so callers can render
+ * a per-patch breakdown.
+ */
+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;
+}
+/**
+ * Internal planning helper. Does NOT take the patch directory lock — the
+ * caller must already hold it — because the two public entry points
+ * ({@link planExport} and {@link commitExportedPatch}) each take their own
+ * lock for the full operation. Sharing this single pure computation is how
+ * dry-run previews and real writes stay in lockstep by construction
+ * instead of by parallel implementations that can drift.
+ */
+async function computeExportPlanUnderLock(input) {
+    const patchFilename = await getNextPatchFilename(input.patchesDir, input.category, input.name);
+    const patchPath = join(input.patchesDir, patchFilename);
+    const metadata = {
+        filename: patchFilename,
+        order: parseInt(patchFilename.split('-')[0] ?? '0', 10),
+        category: input.category,
+        name: input.name,
+        description: input.description,
+        createdAt: new Date().toISOString(),
+        sourceEsrVersion: input.sourceEsrVersion,
+        filesAffected: input.filesAffected,
+    };
+    const supersedeMatches = await findAllPatchesForFilesWithDetails(input.patchesDir, input.filesAffected, patchFilename);
+    const supersededDetails = supersedeMatches.map((m) => ({
+        filename: m.patch.filename,
+        coveredByFiles: m.coverage.byFiles,
+    }));
+    const supersededPatches = supersedeMatches.map((m) => m.patch);
+    const manifestBefore = await loadPatchesManifest(input.patchesDir);
+    const supersededSet = new Set(supersededDetails.map((s) => s.filename));
+    const afterPatches = (manifestBefore?.patches ?? []).filter((p) => !supersededSet.has(p.filename) && p.filename !== patchFilename);
+    afterPatches.push(metadata);
+    afterPatches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    return {
+        patchFilename,
+        patchPath,
+        metadata,
+        supersededDetails,
+        supersededPatches,
+        manifestBefore: manifestBefore ?? null,
+        manifestAfter: {
+            version: 1,
+            patches: afterPatches,
+        },
+    };
+}
+/**
+ * Read-only planning function — computes everything a real export would
+ * do without writing anything to disk. Takes the patch directory lock
+ * briefly, runs {@link computeExportPlanUnderLock}, releases the lock,
+ * and returns the plan for preview rendering.
+ *
+ * Shares {@link computeExportPlanUnderLock} with {@link commitExportedPatch}
+ * so the dry-run preview cannot drift from the real write. The real write
+ * path does NOT reuse a prior plan object (another export may have landed
+ * between dry-run and commit, which would stale the filename allocation);
+ * it re-runs the same helper under a fresh lock. The guarantee is "same
+ * code, possibly different data," not "same plan object."
+ */
+export async function planExport(input) {
+    return withPatchDirectoryLock(input.patchesDir, async () => {
+        const plan = await computeExportPlanUnderLock(input);
+        return {
+            patchFilename: plan.patchFilename,
+            metadata: plan.metadata,
+            superseded: plan.supersededDetails,
+            manifestBefore: plan.manifestBefore,
+            manifestAfter: plan.manifestAfter,
+        };
+    });
+}
 //# sourceMappingURL=patch-export.js.map