@hominis/fireforge 0.30.1 → 0.31.0

package/dist/src/commands/patch/split-plan.js

@@ -0,0 +1,178 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Planning helpers for `fireforge patch split`: ownership guards, diff
+ * construction from the worktree, staged-dependency owner-rewrite
+ * discovery, cross-patch lint projection, and policy-manifest projection.
+ * Split out of `split.ts` to keep both files within the per-file line
+ * budget; consumed only by the split command.
+ */
+import { join } from 'node:path';
+import { getDiffForFilesAgainstHead } from '../../core/git-diff.js';
+import { computeProjectedLintRegressions } from '../../core/lint-projection.js';
+import { extractAffectedFiles } from '../../core/patch-apply.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
+import { rewriteStagedDependencyOwners } from '../../core/patch-manifest.js';
+import { applyRenameMapToManifest, buildProjectedManifest } from '../../core/patch-policy.js';
+import { buildPatchSourceMetadata } from '../../core/patch-source-metadata.js';
+import { extractNewFileContentFromDiff } from '../../core/patch-transform.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { pathExists } from '../../utils/fs.js';
+import { warn } from '../../utils/logger.js';
+/**
+ *
+ */
+export function assertSourceOwnsFiles(source, files) {
+    const owned = new Set(source.filesAffected);
+    const missing = files.filter((file) => !owned.has(file));
+    if (missing.length > 0) {
+        throw new InvalidArgumentError(`${source.filename} does not currently own ${missing.length} requested file(s): ${missing.join(', ')}. ` +
+            'Run "fireforge status --ownership" to inspect current ownership.', '--files');
+    }
+}
+/**
+ *
+ */
+export async function buildSplitDiff(engineDir, files, label, sourceFilename) {
+    for (const file of files) {
+        if (!(await pathExists(join(engineDir, file)))) {
+            throw new GeneralError(`Cannot split ${sourceFilename}: ${label} file is missing from the engine worktree: ${file}. ` +
+                'Run "fireforge import" (or restore the file) so the worktree reflects the patch content first.');
+        }
+    }
+    const diff = await getDiffForFilesAgainstHead(engineDir, [...files]);
+    if (!diff.trim()) {
+        throw new GeneralError(`Cannot split ${sourceFilename}: the ${label} file set produces an empty diff against HEAD. ` +
+            'The worktree must currently carry the patch content (run "fireforge import" first).');
+    }
+    const actual = new Set(extractAffectedFiles(diff));
+    const noHunks = files.filter((file) => !actual.has(file));
+    if (noHunks.length > 0) {
+        throw new GeneralError(`Cannot split ${sourceFilename}: ${noHunks.length} ${label} file(s) produced no diff hunks ` +
+            `(${noHunks.join(', ')}). The worktree does not carry their patch content.`);
+    }
+    return diff;
+}
+/**
+ * Finds patches declaring a staged-dependency forward-import whose `owner`
+ * is the source patch and whose `creates` path moves to the new patch.
+ */
+export function findOwnerRewriteHolders(patches, sourceFilename, movedSet) {
+    return patches
+        .filter((patch) => (patch.stagedDependencies?.forwardImports ?? []).some((fi) => fi.owner === sourceFilename && movedSet.has(fi.creates)))
+        .map((patch) => patch.filename);
+}
+/** Rewrites split-affected owners on one manifest row. */
+export function rewriteSplitOwners(patch, sourceFilename, movedSet, newFilename) {
+    const forwardImports = patch.stagedDependencies?.forwardImports;
+    if (!forwardImports?.some((fi) => fi.owner === sourceFilename && movedSet.has(fi.creates))) {
+        return patch;
+    }
+    return {
+        ...patch,
+        stagedDependencies: {
+            ...patch.stagedDependencies,
+            forwardImports: forwardImports.map((fi) => fi.owner === sourceFilename && movedSet.has(fi.creates) ? { ...fi, owner: newFilename } : fi),
+        },
+    };
+}
+function buildEntryProjection(diff) {
+    const newFiles = new Map();
+    for (const path of detectNewFilesInDiff(diff)) {
+        newFiles.set(path, extractNewFileContentFromDiff(diff, path));
+    }
+    return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
+}
+/**
+ * Projects the full split (renumber + shrunken source + synthetic new
+ * patch + owner rewrites) through cross-patch lint, reporting only the
+ * regressions the split itself would introduce.
+ */
+export async function runProjectedSplitLint(patchesDir, plan) {
+    const movedSet = new Set(plan.movedFiles);
+    const ownerLookup = (old) => plan.placement.renameMap.get(old)?.newFilename;
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const projectedEntries = baseCtx.entries.map((entry) => {
+        let metadata = entry.metadata;
+        if (metadata) {
+            metadata = rewriteStagedDependencyOwners(metadata, ownerLookup);
+            metadata = rewriteSplitOwners(metadata, plan.source.filename, movedSet, plan.placement.newFilename);
+        }
+        const rename = plan.placement.renameMap.get(entry.filename);
+        const base = rename
+            ? { ...entry, metadata, filename: rename.newFilename, order: rename.newOrder }
+            : { ...entry, metadata };
+        if (entry.filename !== plan.source.filename)
+            return base;
+        return { ...base, ...buildEntryProjection(plan.remainingDiff) };
+    });
+    projectedEntries.push({
+        filename: plan.placement.newFilename,
+        order: plan.placement.insertionOrder,
+        metadata: null,
+        ...buildEntryProjection(plan.movedDiff),
+    });
+    projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    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 split. Run "fireforge verify" to list them.');
+    }
+    if (regressions.length === 0)
+        return null;
+    return {
+        reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
+        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+    };
+}
+/** Builds the projected manifest for policy enforcement. */
+export function projectSplitManifest(manifest, plan, newMetadata) {
+    const movedSet = new Set(plan.movedFiles);
+    const renamed = applyRenameMapToManifest(manifest, plan.placement.renameMap);
+    const effectiveSourceFilename = plan.placement.renameMap.get(plan.source.filename)?.newFilename ?? plan.source.filename;
+    const patched = renamed.patches.map((patch) => {
+        const withOwners = rewriteSplitOwners(patch, effectiveSourceFilename, movedSet, plan.placement.newFilename);
+        if (patch.filename !== effectiveSourceFilename)
+            return withOwners;
+        return { ...withOwners, filesAffected: plan.remainingFiles };
+    });
+    return buildProjectedManifest(renamed, [...patched, newMetadata]);
+}
+/**
+ *
+ */
+export function buildNewPatchMetadata(plan, config) {
+    return {
+        filename: plan.placement.newFilename,
+        order: plan.placement.insertionOrder,
+        category: plan.category,
+        name: plan.name,
+        description: plan.description,
+        createdAt: new Date().toISOString(),
+        ...buildPatchSourceMetadata(config.firefox),
+        filesAffected: plan.movedFiles,
+    };
+}
+/**
+ *
+ */
+export function buildSplitSummary(plan) {
+    const summary = [
+        `split ${plan.source.filename}`,
+        `moved files (${plan.movedFiles.length}): ${plan.movedFiles.join(', ')}`,
+        `source keeps (${plan.remainingFiles.length}): ${plan.remainingFiles.join(', ')}`,
+        `new patch: ${plan.placement.newFilename} (order ${plan.placement.insertionOrder})`,
+    ];
+    if (plan.placement.renameMap.size > 0) {
+        summary.push(`${plan.placement.renameMap.size} existing patch(es) renumbered to make room:`);
+        for (const [oldName, entry] of [...plan.placement.renameMap.entries()].sort((a, b) => a[1].newOrder - b[1].newOrder)) {
+            summary.push(`  ${oldName}  →  ${entry.newFilename}`);
+        }
+    }
+    if (plan.ownerRewrites.length > 0) {
+        summary.push(`staged-dependency owners re-pointed to the new patch in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    return summary;
+}
+//# sourceMappingURL=split-plan.js.map

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

@@ -0,0 +1,30 @@
+/**
+ * `fireforge patch split <source> --files <p...> --name <n>` — moves files
+ * out of an existing patch into a brand-new patch as one transaction
+ * (field report A4).
+ *
+ * Before this command, splitting a patch whose files have inbound
+ * forward-imports required a precise manual order: re-point each
+ * staged-dependency owner at a not-yet-created patch, shrink the source
+ * via `re-export --files --allow-shrink`, then `export --order` — any
+ * other order refused or needed `--force-unsafe`. Split performs the
+ * shrink, the new-patch creation, and the dependent owner rewrites under
+ * one patch-directory lock with rollback, validating only the final
+ * projection.
+ *
+ * Preconditions match `re-export`: the engine worktree must currently
+ * reflect both patches' content, because both bodies are regenerated from
+ * the worktree.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchSplitOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch split` command: plans the split, lints the projection,
+ * confirms, and commits transactionally.
+ */
+export declare function patchSplitCommand(projectRoot: string, sourceId: string, options: PatchSplitOptions): Promise<void>;
+/**
+ * Registers the `patch split` subcommand on the `patch` parent.
+ */
+export declare function registerPatchSplit(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch split <source> --files <p...> --name <n>` — moves files
+ * out of an existing patch into a brand-new patch as one transaction
+ * (field report A4).
+ *
+ * Before this command, splitting a patch whose files have inbound
+ * forward-imports required a precise manual order: re-point each
+ * staged-dependency owner at a not-yet-created patch, shrink the source
+ * via `re-export --files --allow-shrink`, then `export --order` — any
+ * other order refused or needed `--force-unsafe`. Split performs the
+ * shrink, the new-patch creation, and the dependent owner rewrites under
+ * one patch-directory lock with rollback, validating only the final
+ * projection.
+ *
+ * Preconditions match `re-export`: the engine worktree must currently
+ * reflect both patches' content, because both bodies are regenerated from
+ * the worktree.
+ */
+import { join } from 'node:path';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
+import { enforcePatchPolicy } from '../../core/patch-policy.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { readText, removeFile, writeText } from '../../utils/fs.js';
+import { info, intro, outro, success, warn } from '../../utils/logger.js';
+import { pickDefined } from '../../utils/options.js';
+import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
+import { runPatchLint } from '../export-shared.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
+/**
+ * Commits a confirmed split under the patch directory lock: renumber →
+ * write new patch body → write shrunken source body → single manifest
+ * rewrite (new row + shrunken source row + owner rewrites). On any
+ * failure the steps are rolled back in reverse order.
+ */
+async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            throw new GeneralError('Manifest disappeared while waiting for lock.');
+        const current = manifest.patches.find((p) => p.filename === plan.source.filename);
+        if (!current || current.filesAffected.join('\n') !== plan.source.filesAffected.join('\n')) {
+            throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
+        }
+        const currentPlacement = await resolvePlacementPlan(patchesDir, plan.placementOptions, plan.category, plan.name);
+        if (!placementPlansEqual(currentPlacement, plan.placement)) {
+            throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
+        }
+        const movedSet = new Set(plan.movedFiles);
+        const effectiveSourceFilename = plan.placement.renameMap.get(plan.source.filename)?.newFilename ?? plan.source.filename;
+        const newPatchPath = join(patchesDir, plan.placement.newFilename);
+        const sourcePathBefore = join(patchesDir, plan.source.filename);
+        const sourcePathAfter = join(patchesDir, effectiveSourceFilename);
+        const originalSourceBody = await readText(sourcePathBefore);
+        let renumberApplied = false;
+        let newPatchWritten = false;
+        let sourceRewritten = false;
+        try {
+            if (plan.placement.renameMap.size > 0) {
+                await renumberPatchesInManifest(patchesDir, plan.placement.renameMap);
+                renumberApplied = true;
+            }
+            await writeText(newPatchPath, normalizePatchArtifact(plan.movedDiff));
+            newPatchWritten = true;
+            await writeText(sourcePathAfter, normalizePatchArtifact(plan.remainingDiff));
+            sourceRewritten = true;
+            const fresh = await loadPatchesManifest(patchesDir);
+            if (!fresh)
+                throw new GeneralError('Manifest disappeared during split commit.');
+            const updatedPatches = fresh.patches.map((patch) => {
+                const withOwners = rewriteSplitOwners(patch, effectiveSourceFilename, movedSet, plan.placement.newFilename);
+                if (patch.filename !== effectiveSourceFilename)
+                    return withOwners;
+                return { ...withOwners, filesAffected: plan.remainingFiles };
+            });
+            updatedPatches.push(newMetadata);
+            updatedPatches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+            const updated = validatePatchesManifest({ ...fresh, patches: updatedPatches });
+            await savePatchesManifest(patchesDir, updated);
+            try {
+                await appendHistory(patchesDir, {
+                    operation: 'patch-split',
+                    args: {
+                        source: effectiveSourceFilename,
+                        newFilename: plan.placement.newFilename,
+                        order: plan.placement.insertionOrder,
+                        files: plan.movedFiles,
+                        ownerRewrites: plan.ownerRewrites,
+                        renames: [...plan.placement.renameMap.entries()].map(([from, entry]) => ({
+                            from,
+                            to: entry.newFilename,
+                        })),
+                    },
+                    ...(options.yes === true ? { yes: true } : {}),
+                    ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
+                    result: 'ok',
+                });
+            }
+            catch (historyError) {
+                warn(`History log append failed after patch split committed: ${toError(historyError).message}`);
+            }
+        }
+        catch (error) {
+            // Reverse-order rollback; each step warns on its own failure so the
+            // original error stays visible.
+            if (sourceRewritten) {
+                try {
+                    await writeText(sourcePathAfter, originalSourceBody);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore source body: ${toError(rollbackError).message}`);
+                }
+            }
+            if (newPatchWritten) {
+                try {
+                    await removeFile(newPatchPath);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not remove new patch file: ${toError(rollbackError).message}`);
+                }
+            }
+            if (renumberApplied) {
+                const inverseMap = new Map([...plan.placement.renameMap.entries()].map(([oldFilename, entry]) => [
+                    entry.newFilename,
+                    {
+                        newOrder: parseInt(oldFilename.split('-')[0] ?? '0', 10),
+                        newFilename: oldFilename,
+                    },
+                ]));
+                try {
+                    await renumberPatchesInManifest(patchesDir, inverseMap);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not invert renumber: ${toError(rollbackError).message}`);
+                }
+            }
+            try {
+                await savePatchesManifest(patchesDir, manifest);
+            }
+            catch (rollbackError) {
+                warn(`Rollback warning: could not restore manifest: ${toError(rollbackError).message}`);
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Runs the `patch split` command: plans the split, lints the projection,
+ * confirms, and commits transactionally.
+ */
+export async function patchSplitCommand(projectRoot, sourceId, options) {
+    intro(options.dryRun ? 'FireForge patch split (dry run)' : 'FireForge patch split');
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const source = resolvePatchIdentifier(sourceId, manifest.patches);
+    if (!source) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(sourceId, manifest.patches), 'patch split');
+    }
+    const movedFiles = [...new Set(options.files.map((f) => f.trim()).filter(Boolean))].sort();
+    if (movedFiles.length === 0) {
+        throw new InvalidArgumentError('patch split requires at least one --files path.', '--files');
+    }
+    assertSourceOwnsFiles(source, movedFiles);
+    const movedSet = new Set(movedFiles);
+    const remainingFiles = source.filesAffected.filter((f) => !movedSet.has(f));
+    if (remainingFiles.length === 0) {
+        throw new InvalidArgumentError(`Splitting every file out of ${source.filename} would leave it empty. ` +
+            'Use "fireforge patch rename" / "fireforge patch reorder" to repurpose or move the whole patch instead.', '--files');
+    }
+    const movedDiff = await buildSplitDiff(paths.engine, movedFiles, 'moved', source.filename);
+    const remainingDiff = await buildSplitDiff(paths.engine, remainingFiles, 'remaining', source.filename);
+    const category = options.category ?? source.category;
+    const placementOptions = pickDefined({
+        order: options.order,
+        before: options.before,
+        after: options.after ??
+            (options.order === undefined && options.before === undefined ? source.filename : undefined),
+    });
+    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name);
+    const plan = {
+        source,
+        movedFiles,
+        remainingFiles,
+        movedDiff,
+        remainingDiff,
+        placement,
+        placementOptions,
+        category,
+        name: options.name,
+        description: options.description ?? '',
+        ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
+    };
+    // Per-patch lint both projected bodies, threading the source patch's
+    // tier/lintIgnore so an intentional-advisory patch can still split.
+    const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
+    await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
+    await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
+    const conflicts = await runProjectedSplitLint(paths.patches, plan);
+    const newMetadata = buildNewPatchMetadata(plan, config);
+    enforcePatchPolicy({
+        config,
+        manifest: projectSplitManifest(manifest, plan, newMetadata),
+        command: 'patch split',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+    const decision = await confirmDestructive({
+        operation: 'patch-split',
+        title: `Split ${plan.movedFiles.length} file(s) out of ${source.filename} into ${placement.newFilename}`,
+        summary: buildSplitSummary(plan),
+        yes: options.yes === true,
+        dryRun: options.dryRun === true,
+        unsafeOverride: options.forceUnsafe === true,
+        conflicts,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Split cancelled');
+        return;
+    }
+    await commitPatchSplit(paths.patches, plan, newMetadata, options);
+    success(`Split ${source.filename}: ${placement.newFilename} now owns ${plan.movedFiles.length} file(s)`);
+    if (plan.ownerRewrites.length > 0) {
+        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    outro('Split complete');
+}
+/**
+ * Registers the `patch split` subcommand on the `patch` parent.
+ */
+export function registerPatchSplit(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('split <source>')
+        .description('Move files out of a patch into a new patch as one transaction (shrink + create + staged-dependency owner rewrites)')
+        .requiredOption('--files <path...>', 'Engine-relative files to move from the source patch to the new patch')
+        .requiredOption('--name <name>', 'Name for the new patch')
+        .option('--category <category>', "Category for the new patch (default: the source patch's)")
+        .option('--description <desc>', 'Description for the new patch')
+        .option('--order <n>', 'Exact sparse order for the new patch', (raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new InvalidArgumentError(`--order must be a positive integer, got "${raw}".`, '--order');
+        }
+        return n;
+    })
+        .option('--before <patch>', 'Place the new patch before this patch')
+        .option('--after <patch>', 'Place the new patch after this patch (default: the source patch)')
+        .option('--dry-run', 'Show what would happen without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--force-unsafe', 'Bypass projected-lint refusals')
+        .option('--skip-lint', 'Skip per-patch lint of the projected bodies')
+        .action(withErrorHandling(async (sourceId, options) => {
+        await patchSplitCommand(getProjectRoot(), sourceId, {
+            files: options.files,
+            name: options.name,
+            ...pickDefined({
+                category: options.category,
+                description: options.description,
+                order: options.order,
+                before: options.before,
+                after: options.after,
+                dryRun: options.dryRun,
+                yes: options.yes,
+                forceUnsafe: options.forceUnsafe,
+                skipLint: options.skipLint,
+            }),
+        });
+    }));
+}
+//# sourceMappingURL=split.js.map

package/dist/src/commands/patch/staged-dependency.d.ts

@@ -4,12 +4,7 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
-import type { PatchStagedDependencyOptions, PatchStagedForwardImport } from '../../types/commands/index.js';
-type StagedDependencyMode = 'add' | 'remove' | 'clear';
-/**
- * Renders a one-line summary of a staged-dependency metadata change.
- */
-export declare function describeStagedDependencyChange(before: readonly PatchStagedForwardImport[], after: readonly PatchStagedForwardImport[], mode: StagedDependencyMode, dependency: PatchStagedForwardImport | undefined): string;
+import type { PatchStagedDependencyOptions } from '../../types/commands/index.js';
 /**
  * Runs the metadata-only staged-dependency mutation command.
  *
@@ -25,4 +20,3 @@ export declare function patchStagedDependencyCommand(projectRoot: string, identi
  * @param context - Shared CLI registration context
  */
 export declare function registerPatchStagedDependency(parent: Command, context: CommandContext): void;
-export {};

package/dist/src/commands/patch/staged-dependency.js

@@ -3,15 +3,12 @@
  * `fireforge patch staged-dependency <name>` — edits
  * PatchMetadata.stagedDependencies without rewriting the .patch body.
  */
-import { getProjectPaths } from '../../core/config.js';
 import { appendHistory } from '../../core/destructive.js';
 import { mutatePatchMetadata } from '../../core/patch-export.js';
-import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.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 { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 function modeFromOptions(options) {
     const adding = options.add === true;
     const removing = options.remove === true;
@@ -69,7 +66,7 @@ function applyMode(existing, mode, dependency) {
 /**
  * Renders a one-line summary of a staged-dependency metadata change.
  */
-export function describeStagedDependencyChange(before, after, mode, dependency) {
+function describeStagedDependencyChange(before, after, mode, dependency) {
     if (mode === 'clear') {
         return before.length === 0
             ? 'stagedDependencies was already empty — no change'
@@ -98,18 +95,8 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
     const mode = modeFromOptions(options);
     const dependency = mode === 'clear' ? undefined : requireForwardImportOptions(options, mode);
-    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) {
-        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
-    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const target = requirePatchTarget(identifier, manifest.patches);
     const existing = target.stagedDependencies?.forwardImports ?? [];
     const projected = applyMode(existing, mode, dependency);
     const summary = describeStagedDependencyChange(existing, projected, mode, dependency);

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

@@ -15,16 +15,13 @@
  * `--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 { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
-import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
-import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { 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';
+import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Runs the `patch tier` command: updates `PatchMetadata.tier` on the
  * named patch (or clears the field) and writes the manifest.
@@ -47,18 +44,8 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
     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) {
-        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
-    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const target = requirePatchTarget(identifier, manifest.patches);
     const before = target.tier;
     const after = setting ? options.tier : undefined;
     if (before === after) {

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

@@ -47,9 +47,16 @@ async function scanPatchFiles(args) {
         for (const f of [...modifiedFiles, ...untrackedFiles])
             discoveredFiles.add(f);
     }
+    // Git pathspecs recurse, so a claimed file in a shallow directory would
+    // sweep entire subtrees into the candidate set — with several patches
+    // sharing a parent directory, every unmanaged file in the tree gets
+    // offered to whichever patch is scanned first. Constrain the broad scan
+    // to the patch's exact directory footprint; deeper paths need an
+    // explicit --scan-file / --scan-files assignment.
+    const parentDirSet = new Set(parentDirs);
     const currentSet = new Set(currentFilesAffected);
     const added = [...discoveredFiles]
-        .filter((f) => !currentSet.has(f) && !claimedByOthers.has(f))
+        .filter((f) => parentDirSet.has(dirname(f)) && !currentSet.has(f) && !claimedByOthers.has(f))
         .sort();
     const removed = await findRemovedFiles(currentFilesAffected, engineDir);
     return reportScanResult(currentFilesAffected, patchFilename, isDryRun, added, removed);

package/dist/src/commands/rebase/summary.d.ts

@@ -1,11 +1,7 @@
 /**
  * Rebase summary and status label formatting.
  */
-import type { RebasePatchEntry, RebaseSession } from '../../core/rebase-session.js';
-/**
- * Formats a status label for a rebase patch entry.
- */
-export declare function statusLabel(status: RebasePatchEntry['status'], fuzzFactor?: number): string;
+import type { RebaseSession } from '../../core/rebase-session.js';
 /**
  * Prints the rebase summary table.
  */

package/dist/src/commands/rebase/summary.js

@@ -6,7 +6,7 @@ import { info } from '../../utils/logger.js';
 /**
  * Formats a status label for a rebase patch entry.
  */
-export function statusLabel(status, fuzzFactor) {
+function statusLabel(status, fuzzFactor) {
     switch (status) {
         case 'applied-clean':
             return 'applied cleanly';