@hominis/fireforge 0.50.0 → 0.52.0

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

@@ -28,6 +28,7 @@ import { info, intro, outro } from '../../utils/logger.js';
 import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { deleteCreatedFiles, planClaimedFiles, withCreatedFileLock, } from './removal-created-files.js';
 import { collectRemovalDependents, queueSnapshot, removalConflict, warnDanglingStagedOwners, } from './removal-dependents.js';
 /**
  * Runs the `patch retire` command.
@@ -49,16 +50,14 @@ export async function patchRetireCommand(projectRoot, identifier, options = {})
     });
     warnDanglingStagedOwners(baseCtx, target, 'retire');
     const order = formatPatchOrder(target.order);
+    const claimed = await planClaimedFiles(baseCtx, target, paths.engine, options.deleteCreated === true);
     const summary = [
         `retire ${target.filename}  (category: ${target.category}, order: ${order})`,
         `description: ${target.description || '(none)'}`,
         `order ${order} stays spent as a retired slot in patches.json; ` +
             `"fireforge export --order ${order}" can fill it later`,
-        `files currently claimed by this patch (${target.filesAffected.length}):`,
+        ...claimed.summary,
     ];
-    for (const file of target.filesAffected) {
-        summary.push(`  ${file}  → will become unmanaged`);
-    }
     const decision = await confirmDestructive({
         operation: 'patch-retire',
         title: `Retire ${target.filename}`,
@@ -80,25 +79,30 @@ export async function patchRetireCommand(projectRoot, identifier, options = {})
     // Same locking and history contract as `patch delete`: the dependency
     // scan approved before the prompt is re-checked under the lock, and the
     // history record is appended inside it.
-    await withPatchDirectoryLock(paths.patches, async () => {
+    const waitLockSeconds = resolveWaitLockSeconds(options.waitLock);
+    await withCreatedFileLock(projectRoot, 'patch retire', claimed, waitLockSeconds, () => withPatchDirectoryLock(paths.patches, async () => {
         const current = await buildPatchQueueContext(paths.patches);
         if (queueSnapshot(current) !== queueSnapshot(baseCtx)) {
             throw new GeneralError('Patch queue changed while waiting for confirmation or the lock. Re-run patch retire to review the current dependencies.');
         }
         await removePatchFileAndManifest(paths.patches, target.filename, slot);
+        await deleteCreatedFiles(paths.engine, claimed.deleteOnCommit);
         await appendHistoryBestEffort(paths.patches, {
             operation: 'patch-retire',
             args: {
                 filename: target.filename,
                 order: target.order,
                 filesAffected: target.filesAffected,
+                ...(claimed.deleteOnCommit.length > 0
+                    ? { deletedCreatedFiles: claimed.deleteOnCommit }
+                    : {}),
                 ...(options.reason !== undefined ? { reason: options.reason } : {}),
             },
             ...(options.yes === true ? { yes: true } : {}),
             ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
             result: 'ok',
         }, `patch retire committed (${target.filename})`);
-    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch retire' });
+    }, { waitLockSeconds, command: 'patch retire' }));
     info(`Retired ${target.filename}; order ${order} is kept as a retired slot.`);
     if ((await loadConfig(projectRoot)).patchPolicy?.allowGaps !== false) {
         info('patchPolicy.allowGaps is not false, so no check reads the retired slot; ' +
@@ -121,6 +125,7 @@ export function registerPatchRetire(parent, context) {
         .option('--reason <text>', 'Rationale recorded on the retired slot')
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--delete-created', 'Also delete the engine files this patch creates that are still on disk, instead of leaving them unmanaged')
         .option('--force-unsafe', 'Bypass the refusal when a later patch depends on this patch (last resort)');
     addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
         await patchRetireCommand(getProjectRoot(), name, pickDefined(options));

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

@@ -7,9 +7,10 @@
  */
 import { type ConflictReport } from '../../core/destructive.js';
 import type { PatchQueueContext } from '../../core/patch-lint-cross.js';
-import type { PatchStagedForwardImport } from '../../types/commands/index.js';
+import type { PatchLintIssue, PatchStagedForwardImport } from '../../types/commands/index.js';
 import type { PatchCategory, PatchesManifest, PatchMetadata } from '../../types/commands/index.js';
 import type { FireForgeConfig } from '../../types/config.js';
+import type { DeclarationRenamer } from '../declarations-report.js';
 import { type PlacementPlan } from '../export-flow.js';
 import { type SplitStagedMaintenance } from './split-staged.js';
 /** Everything the commit step needs, computed and confirmed up front. */
@@ -68,6 +69,7 @@ export declare function mergeStagedForwardImports(patch: PatchMetadata, decls: r
  */
 export declare function runProjectedSplitLint(plan: SplitPlan, baseCtx: PatchQueueContext): {
     conflicts: ConflictReport | null;
+    regressions: PatchLintIssue[];
     stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
     stagedMaintenance: SplitStagedMaintenance;
 };
@@ -86,3 +88,10 @@ export declare function buildNewPatchMetadata(plan: SplitPlan, config: FireForge
  * shown by `--dry-run` and by the destructive-operation confirmation prompt.
  */
 export declare function buildSplitSummary(plan: SplitPlan): string[];
+/**
+ * Maps a declaration the split projection proposes back onto the queue as
+ * it stands: renumbered patches take their current names, and an owner
+ * that is the patch the split would create is dropped (it does not exist
+ * until the split runs).
+ */
+export declare function splitDeclarationRenamer(plan: SplitPlan): DeclarationRenamer;

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

@@ -215,7 +215,7 @@ export function runProjectedSplitLint(plan, baseCtx) {
             reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
             details: regressions.map(formatPatchLintIssue),
         };
-    return { conflicts, stagedDependencyAdditions, stagedMaintenance };
+    return { conflicts, regressions, stagedDependencyAdditions, stagedMaintenance };
 }
 /** Builds the projected manifest for policy enforcement. */
 export function projectSplitManifest(manifest, plan, newMetadata) {
@@ -272,3 +272,18 @@ export function buildSplitSummary(plan) {
     summary.push(...describeStagedMaintenance(plan.stagedMaintenance, plan.source.filename, plan.placement.newFilename));
     return summary;
 }
+/**
+ * Maps a declaration the split projection proposes back onto the queue as
+ * it stands: renumbered patches take their current names, and an owner
+ * that is the patch the split would create is dropped (it does not exist
+ * until the split runs).
+ */
+export function splitDeclarationRenamer(plan) {
+    const oldNameByNew = new Map([...plan.placement.renameMap].map(([oldName, entry]) => [entry.newFilename, oldName]));
+    const current = (name) => oldNameByNew.get(name) ?? name;
+    return ({ owner, ...declaration }) => ({
+        ...declaration,
+        patch: current(declaration.patch),
+        ...(owner !== plan.placement.newFilename ? { owner: current(owner) } : {}),
+    });
+}

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

@@ -33,10 +33,11 @@ import { readText, removeFile, writeText } from '../../utils/fs.js';
 import { info, intro, outro, success, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
 import { normalizePatchDisplayName, parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { withDeclarationsReport } from '../declarations-report.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, mergeStagedForwardImports, projectSplitManifest, runProjectedSplitLint, } from './split-plan.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, mergeStagedForwardImports, projectSplitManifest, runProjectedSplitLint, splitDeclarationRenamer, } from './split-plan.js';
 import { describeStagedMaintenance, emptyStagedMaintenance, findOwnerRewriteHolders, rewriteSplitOwners, withoutDroppedDeclarations, withoutRelocatedDeclarations, } from './split-staged.js';
 /**
  * History payload for the declarations a split re-homed or dropped, omitted
@@ -285,9 +286,15 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         ignoreChecks,
         patchTier: source.tier,
     });
-    const { conflicts, stagedDependencyAdditions, stagedMaintenance } = runProjectedSplitLint(plan, patchQueueCtx);
-    plan.stagedDependencyAdditions = stagedDependencyAdditions;
-    plan.stagedMaintenance = stagedMaintenance;
+    const projected = runProjectedSplitLint(plan, patchQueueCtx);
+    plan.stagedDependencyAdditions = projected.stagedDependencyAdditions;
+    plan.stagedMaintenance = projected.stagedMaintenance;
+    const conflicts = await withDeclarationsReport(projected.conflicts, {
+        projectRoot,
+        regressions: projected.regressions,
+        out: options.declarationsOut,
+        rename: splitDeclarationRenamer(plan),
+    });
     const newMetadata = buildNewPatchMetadata(plan, config);
     const decision = await confirmDestructive({
         operation: 'patch-split',
@@ -323,7 +330,8 @@ export function registerPatchSplit(parent, context) {
         .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');
+        .option('--skip-lint', 'Skip per-patch lint of the projected bodies')
+        .option('--declarations-out <path>', 'Where a refusal writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json)');
     addWaitLockOption(command).action(withErrorHandling(async (sourceId, options) => {
         await patchSplitCommand(getProjectRoot(), sourceId, {
             files: options.files,
@@ -338,6 +346,7 @@ export function registerPatchSplit(parent, context) {
                 yes: options.yes,
                 forceUnsafe: options.forceUnsafe,
                 skipLint: options.skipLint,
+                declarationsOut: options.declarationsOut,
                 waitLock: options.waitLock,
             }),
         });

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

@@ -0,0 +1,34 @@
+/**
+ * `fireforge patch stage <name>...`: stages the named patches' `.patch`
+ * files and only their rows of `patches/patches.json` in the project
+ * repository's git index.
+ *
+ * The case it exists for: several sessions edit one checkout's queue, and
+ * each must commit only its own patches. Staging the whole manifest takes
+ * every session's rows; staging one owner's hunks of it with
+ * `git apply --cached --unidiff-zero` placed a kept insertion at its
+ * new-side line number once a dropped hunk above had shifted the file, and
+ * an invalid manifest was committed. This command builds the staged
+ * manifest from HEAD's rows plus the named working rows (see
+ * `core/patch-manifest-stage.ts`), validates it, and writes it straight to
+ * the index with `git hash-object` + `git update-index`. The working copy
+ * is never touched, and nothing is committed.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchStageOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch stage` command.
+ *
+ * @param projectRoot - Project root directory (a git working tree)
+ * @param identifiers - Patch filenames, ordinals or names to stage
+ * @param options - Command options
+ */
+export declare function patchStageCommand(projectRoot: string, identifiers: readonly string[], options?: PatchStageOptions): Promise<void>;
+/**
+ * Registers the `patch stage` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchStage(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch stage <name>...`: stages the named patches' `.patch`
+ * files and only their rows of `patches/patches.json` in the project
+ * repository's git index.
+ *
+ * The case it exists for: several sessions edit one checkout's queue, and
+ * each must commit only its own patches. Staging the whole manifest takes
+ * every session's rows; staging one owner's hunks of it with
+ * `git apply --cached --unidiff-zero` placed a kept insertion at its
+ * new-side line number once a dropped hunk above had shifted the file, and
+ * an invalid manifest was committed. This command builds the staged
+ * manifest from HEAD's rows plus the named working rows (see
+ * `core/patch-manifest-stage.ts`), validates it, and writes it straight to
+ * the index with `git hash-object` + `git update-index`. The working copy
+ * is never touched, and nothing is committed.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { Command } from 'commander';
+import { getProjectPaths } from '../../core/config.js';
+import { git } from '../../core/git-base.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifestForWrite, resolvePatchIdentifier, validatePatchesManifest, } from '../../core/patch-manifest.js';
+import { mergeStagedManifest, serializeStagedManifest, } from '../../core/patch-manifest-stage.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro } from '../../utils/logger.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { exec } from '../../utils/process.js';
+/** A project-relative path in git's separator. */
+function gitPath(projectRoot, path) {
+    return relative(projectRoot, path).split(sep).join('/');
+}
+/** HEAD's manifest, or null when HEAD has none (or there is no HEAD yet). */
+async function readHeadManifest(projectRoot, manifestPath) {
+    const shown = await exec('git', ['show', `HEAD:./${manifestPath}`], { cwd: projectRoot });
+    if (shown.exitCode !== 0)
+        return null;
+    try {
+        return validatePatchesManifest(JSON.parse(shown.stdout));
+    }
+    catch (error) {
+        throw new GeneralError(`HEAD's ${manifestPath} is not a valid manifest (${toError(error).message}); stage it by hand.`);
+    }
+}
+/** Resolves each identifier to a filename, against the working rows then HEAD's. */
+function resolveFilenames(identifiers, working, head) {
+    const filenames = new Set();
+    for (const identifier of identifiers) {
+        const live = resolvePatchIdentifier(identifier, working.patches);
+        // A patch deleted (or renamed away) in the working copy is named by its
+        // HEAD filename, so its row can be staged as removed.
+        const gone = (head?.patches ?? []).find((row) => row.filename === identifier || row.filename === `${identifier}.patch`);
+        const filename = live?.filename ?? gone?.filename;
+        if (filename === undefined) {
+            throw new InvalidArgumentError(`No patch "${identifier}" in the working manifest or at HEAD.`, identifier);
+        }
+        filenames.add(filename);
+    }
+    return filenames;
+}
+/** Stages one `.patch` file: its content, or its removal when it is gone. */
+async function stagePatchFile(projectRoot, patchPath) {
+    if (await pathExists(join(projectRoot, patchPath))) {
+        await git(['add', '--', patchPath], projectRoot);
+        return;
+    }
+    const tracked = await exec('git', ['ls-files', '--error-unmatch', '--', patchPath], {
+        cwd: projectRoot,
+    });
+    if (tracked.exitCode === 0) {
+        await git(['rm', '--cached', '--quiet', '--', patchPath], projectRoot);
+    }
+}
+/** Writes `content` as a blob and points the index entry at it. */
+async function stageBlob(projectRoot, path, content) {
+    const scratch = await mkdtemp(join(tmpdir(), 'fireforge-stage-'));
+    try {
+        const file = join(scratch, 'patches.json');
+        await writeFile(file, content);
+        const sha = (await git(['hash-object', '-w', '--no-filters', file], projectRoot)).trim();
+        await git(['update-index', '--add', '--cacheinfo', `100644,${sha},${path}`], projectRoot);
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * Runs the `patch stage` command.
+ *
+ * @param projectRoot - Project root directory (a git working tree)
+ * @param identifiers - Patch filenames, ordinals or names to stage
+ * @param options - Command options
+ */
+export async function patchStageCommand(projectRoot, identifiers, options = {}) {
+    intro(options.dryRun ? 'FireForge patch stage (dry run)' : 'FireForge patch stage');
+    const probe = await exec('git', ['rev-parse', '--is-inside-work-tree'], { cwd: projectRoot });
+    if (probe.exitCode !== 0 || probe.stdout.trim() !== 'true') {
+        throw new GeneralError('patch stage needs the project to be a git working tree.');
+    }
+    const { patches: patchesDir } = getProjectPaths(projectRoot);
+    const manifestPath = gitPath(projectRoot, join(patchesDir, 'patches.json'));
+    // Under the patch lock, so the rows and `.patch` files staged are one
+    // consistent snapshot rather than a peer's half-finished write.
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const working = await loadPatchesManifestForWrite(patchesDir);
+        if (working === null) {
+            throw new GeneralError(`No ${manifestPath} to stage.`);
+        }
+        const head = await readHeadManifest(projectRoot, manifestPath);
+        const filenames = resolveFilenames(identifiers, working, head);
+        let staged;
+        try {
+            staged = mergeStagedManifest(head, working, filenames);
+        }
+        catch (error) {
+            throw new GeneralError(`Refusing to stage: ${toError(error).message}.`);
+        }
+        const prefix = options.dryRun === true ? '[dry-run] ' : '';
+        for (const { filename, change } of staged.changes) {
+            info(`${prefix}${filename}: row ${change}; .patch file staged`);
+        }
+        if (options.dryRun === true)
+            return;
+        await stageBlob(projectRoot, manifestPath, serializeStagedManifest(staged.manifest));
+        for (const filename of filenames) {
+            await stagePatchFile(projectRoot, gitPath(projectRoot, join(patchesDir, filename)));
+        }
+        info(`Staged ${filenames.size} patch(es) and their ${manifestPath} rows. Other rows stay as at HEAD; ` +
+            'nothing was committed.');
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch stage' });
+    outro(options.dryRun ? 'Dry run complete — nothing staged' : 'Patch stage complete');
+}
+/**
+ * Registers the `patch stage` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchStage(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const command = parent
+        .command('stage <names...>')
+        .description("Stage the named patches' .patch files and only their patches.json rows in the git index " +
+        "(HEAD's rows for every other patch); validates the staged manifest, commits nothing")
+        .option('--dry-run', 'Show which rows would be staged without touching the index');
+    addWaitLockOption(command).action(withErrorHandling(async (names, options) => {
+        await patchStageCommand(getProjectRoot(), names, pickDefined(options));
+    }));
+}

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

@@ -0,0 +1,31 @@
+/**
+ * `--remove` target selection for `patch staged-dependency`. Split out of
+ * `staged-dependency.ts` for the per-file line budget.
+ *
+ * A removal names its entries by any of `--file`, `--specifier`/`--line`,
+ * `--creates` and `--owner`, and must give at least `--creates` or the
+ * `--file` + matcher pair. Registration lines compare whitespace-
+ * insensitively (runs of whitespace collapse, ends trimmed), the way the
+ * lint compares them, so a line copied from a patch hunk matches the stored
+ * one whatever its padding. A selection that matches nothing is refused
+ * rather than reported as a no-op.
+ */
+import type { PatchStagedDependencies, PatchStagedDependencyOptions } from '../../types/commands/index.js';
+import { type StagedDependencyKind, type StagedEntryView } from './staged-dependency-entries.js';
+/**
+ * Resolves the staged entries a `--remove` invocation names. The returned
+ * views are the stored entries themselves, so the removal matches them
+ * exactly.
+ *
+ * - `--file` + matcher identifying one entry infers `--creates`.
+ * - `--file` + matcher identifying several entries without `--creates`
+ *   refuses with the candidate list.
+ * - `--creates` alone selects every declaration for that created path.
+ *
+ * @param kind - Declaration kind (`--kind`)
+ * @param options - Command options
+ * @param staged - The target patch's current staged dependencies
+ * @returns The matching stored entries (never empty)
+ * @throws InvalidArgumentError when the selectors are insufficient or match nothing
+ */
+export declare function selectRemovalEntries(kind: StagedDependencyKind, options: PatchStagedDependencyOptions, staged: PatchStagedDependencies | undefined): StagedEntryView[];

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

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `--remove` target selection for `patch staged-dependency`. Split out of
+ * `staged-dependency.ts` for the per-file line budget.
+ *
+ * A removal names its entries by any of `--file`, `--specifier`/`--line`,
+ * `--creates` and `--owner`, and must give at least `--creates` or the
+ * `--file` + matcher pair. Registration lines compare whitespace-
+ * insensitively (runs of whitespace collapse, ends trimmed), the way the
+ * lint compares them, so a line copied from a patch hunk matches the stored
+ * one whatever its padding. A selection that matches nothing is refused
+ * rather than reported as a no-op.
+ */
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { info } from '../../utils/logger.js';
+import { dependencyLabel, importView, registrationView, } from './staged-dependency-entries.js';
+/** Collapses whitespace runs and trims, for registration-line comparison. */
+function normalizeRegistrationLine(line) {
+    return line.trim().replace(/\s+/g, ' ');
+}
+function stagedViews(kind, staged) {
+    return kind === 'import'
+        ? (staged?.forwardImports ?? []).map(importView)
+        : (staged?.registrations ?? []).map(registrationView);
+}
+/**
+ * Resolves the staged entries a `--remove` invocation names. The returned
+ * views are the stored entries themselves, so the removal matches them
+ * exactly.
+ *
+ * - `--file` + matcher identifying one entry infers `--creates`.
+ * - `--file` + matcher identifying several entries without `--creates`
+ *   refuses with the candidate list.
+ * - `--creates` alone selects every declaration for that created path.
+ *
+ * @param kind - Declaration kind (`--kind`)
+ * @param options - Command options
+ * @param staged - The target patch's current staged dependencies
+ * @returns The matching stored entries (never empty)
+ * @throws InvalidArgumentError when the selectors are insufficient or match nothing
+ */
+export function selectRemovalEntries(kind, options, staged) {
+    const matcherFlag = kind === 'import' ? '--specifier' : '--line';
+    const matcher = kind === 'import' ? options.specifier : options.line;
+    const hasPair = Boolean(options.file) && Boolean(matcher);
+    if (!options.creates && !hasPair) {
+        throw new InvalidArgumentError(`--remove${kind === 'registration' ? ' --kind registration' : ''} requires --creates, ` +
+            `or --file with ${matcherFlag}; --creates alone removes every declaration for that path.`, matcher && !options.file
+            ? '--file'
+            : options.file && !matcher
+                ? matcherFlag
+                : `--creates or --file + ${matcherFlag}`);
+    }
+    const wanted = matcher === undefined ? undefined : comparableMatcher(kind, matcher);
+    const views = stagedViews(kind, staged);
+    const candidates = views.filter((view) => (!options.file || view.file === options.file) &&
+        (wanted === undefined || comparableMatcher(kind, view.matcher) === wanted) &&
+        (!options.creates || view.creates === options.creates) &&
+        (options.owner === undefined || view.owner === options.owner));
+    if (candidates.length === 0) {
+        const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
+        const existing = views.length === 0
+            ? `This patch has no ${noun}s.`
+            : `This patch's ${noun}s:\n${views.map((view) => `  - ${dependencyLabel(kind, view)}`).join('\n')}`;
+        throw new InvalidArgumentError(`--remove matched no ${noun}. ${existing}`, '--remove');
+    }
+    if (candidates.length > 1 && !options.creates) {
+        const list = candidates.map((view) => `  - ${dependencyLabel(kind, view)}`).join('\n');
+        const noun = kind === 'import' ? 'staged forward-imports' : 'staged registrations';
+        throw new GeneralError(`--remove matches ${candidates.length} ${noun} on this patch; pass --creates to pick one:\n${list}`);
+    }
+    const single = candidates.length === 1 ? candidates[0] : undefined;
+    if (single !== undefined && !options.creates) {
+        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
+    }
+    return candidates;
+}
+function comparableMatcher(kind, matcher) {
+    return kind === 'registration' ? normalizeRegistrationLine(matcher) : matcher;
+}