@hominis/fireforge 0.36.0 → 0.38.0

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Command, Option } from 'commander';
 import { withEngineSessionLock } from '../../core/engine-session-lock.js';
-import { pickDefined } from '../../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
 import { furnaceApplyCommand } from './apply.js';
 import { furnaceChromeDocCreateCommand } from './chrome-doc.js';
 import { furnaceChromeDocRemoveCommand } from './chrome-doc-remove.js';
@@ -19,61 +19,66 @@ import { furnaceScanCommand } from './scan.js';
 import { furnaceStatusCommand } from './status.js';
 import { furnaceSyncCommand } from './sync.js';
 import { furnaceValidateCommand } from './validate.js';
-async function runEngineLockedFurnaceCommand(context, command, operation) {
+async function runEngineLockedFurnaceCommand(context, command, operation, waitLockSeconds) {
     const projectRoot = context.getProjectRoot();
-    await withEngineSessionLock(projectRoot, command, () => operation(projectRoot));
+    await withEngineSessionLock(projectRoot, command, () => operation(projectRoot), {
+        waitLockSeconds,
+    });
 }
 function registerFurnaceApplyCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const apply = furnace
         .command('apply [name]')
         .description('Apply components to the engine (optionally a single component)')
         .option('--dry-run', 'Show what would be changed without writing (reads may overlap concurrent mutations)')
         .option('--force', 'Proceed despite baseVersion drift (stale overrides)')
-        .option('-w, --watch', 'Watch component directories and re-apply on changes')
-        .action(withErrorHandling(async (name, options) => {
-        const parsed = pickDefined(options ?? {});
+        .option('-w, --watch', 'Watch component directories and re-apply on changes');
+    addWaitLockOption(apply).action(withErrorHandling(async (name, options) => {
+        const { waitLock, ...rest } = options ?? {};
+        const parsed = pickDefined(rest);
         const run = (projectRoot) => furnaceApplyCommand(projectRoot, name, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace apply', run);
+        await runEngineLockedFurnaceCommand(context, 'furnace apply', run, resolveWaitLockSeconds(waitLock));
     }));
 }
 function registerFurnaceDeployCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const deploy = furnace
         .command('deploy [name]')
         .description('Apply components and validate in one step')
         .option('--dry-run', 'Show what would be changed without writing (reads may overlap concurrent mutations)')
         .option('--force', 'Proceed despite baseVersion drift (stale overrides)')
-        .option('--skip-validate', 'Skip the validation step (apply only)')
-        .action(withErrorHandling(async (name, options) => {
-        const parsed = pickDefined(options ?? {});
+        .option('--skip-validate', 'Skip the validation step (apply only)');
+    addWaitLockOption(deploy).action(withErrorHandling(async (name, options) => {
+        const { waitLock, ...rest } = options ?? {};
+        const parsed = pickDefined(rest);
         const run = (projectRoot) => furnaceDeployCommand(projectRoot, name, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace deploy', run);
+        await runEngineLockedFurnaceCommand(context, 'furnace deploy', run, resolveWaitLockSeconds(waitLock));
     }));
 }
 function registerFurnaceSyncCommand(furnace, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    furnace
+    const sync = furnace
         .command('sync')
         .description('Refresh drifted overrides and re-apply all components (recommended after fireforge download)')
         .option('--dry-run', 'Show what would change without modifying files (reads may overlap concurrent mutations)')
-        .addOption(new Option('-s, --strategy <strategy>', 'Auto-resolve merge conflicts (ours = keep local, theirs = accept upstream)').choices(['ours', 'theirs']))
-        .action(withErrorHandling(async (options) => {
-        const parsed = pickDefined(options);
+        .addOption(new Option('-s, --strategy <strategy>', 'Auto-resolve merge conflicts (ours = keep local, theirs = accept upstream)').choices(['ours', 'theirs']));
+    addWaitLockOption(sync).action(withErrorHandling(async (options) => {
+        const { waitLock, ...rest } = options;
+        const parsed = pickDefined(rest);
         const run = (projectRoot) => furnaceSyncCommand(projectRoot, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace sync', run);
+        await runEngineLockedFurnaceCommand(context, 'furnace sync', run, resolveWaitLockSeconds(waitLock));
     }));
 }
 /**

package/dist/src/commands/patch/move-files-create.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `fireforge patch move-files <from> <to> --create --order <n>` — creates
+ * the target patch at the requested sparse order and moves the files into
+ * it as one transaction. This is the transactional bootstrap of a split:
+ * without it, moving files into a not-yet-existing patch required a manual
+ * shrink-then-export dance with hand-repointed staged-dependency owners.
+ *
+ * Mirrors `patch split` end-to-end (same planning, projection lint,
+ * policy enforcement, and locked commit); the `<to>` argument becomes the
+ * new patch's name/slug the way `split --name` does.
+ */
+import type { PatchMoveFilesOptions } from '../../types/commands/index.js';
+/**
+ * Runs `patch move-files --create --order <n>`: plans the create+move as a
+ * split, lints the projection, confirms, and commits transactionally.
+ */
+export declare function patchMoveFilesCreateCommand(projectRoot: string, fromIdentifier: string, newPatchName: string, options: PatchMoveFilesOptions & {
+    order: number;
+}): Promise<void>;

package/dist/src/commands/patch/move-files-create.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch move-files <from> <to> --create --order <n>` — creates
+ * the target patch at the requested sparse order and moves the files into
+ * it as one transaction. This is the transactional bootstrap of a split:
+ * without it, moving files into a not-yet-existing patch required a manual
+ * shrink-then-export dance with hand-repointed staged-dependency owners.
+ *
+ * Mirrors `patch split` end-to-end (same planning, projection lint,
+ * policy enforcement, and locked commit); the `<to>` argument becomes the
+ * new patch's name/slug the way `split --name` does.
+ */
+import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { confirmDestructive } from '../../core/destructive.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { enforcePatchPolicy } from '../../core/patch-policy.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { info, intro, outro, success } from '../../utils/logger.js';
+import { resolvePlacementPlan } from '../export-flow.js';
+import { runPatchLint } from '../export-shared.js';
+import { commitPatchSplit } from './split.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, projectSplitManifest, runProjectedSplitLint, } from './split-plan.js';
+/**
+ * Runs `patch move-files --create --order <n>`: plans the create+move as a
+ * split, lints the projection, confirms, and commits transactionally.
+ */
+export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, newPatchName, options) {
+    intro(options.dryRun === true
+        ? 'FireForge patch move-files --create (dry run)'
+        : 'FireForge patch move-files --create');
+    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(fromIdentifier, manifest.patches);
+    if (!source) {
+        throw new InvalidArgumentError(formatPatchNotFoundError(fromIdentifier, manifest.patches), 'patch move-files');
+    }
+    const existingTarget = resolvePatchIdentifier(newPatchName, manifest.patches);
+    if (existingTarget) {
+        throw new InvalidArgumentError(`--create target "${newPatchName}" already exists as ${existingTarget.filename}. ` +
+            'Omit --create to preview a move into the existing patch, or pick a new patch name.', '--create');
+    }
+    const movedFiles = [...new Set((options.file ?? []).map((f) => f.trim()).filter(Boolean))].sort();
+    if (movedFiles.length === 0) {
+        throw new InvalidArgumentError('Specify at least one --file path to move.', '--file');
+    }
+    assertSourceOwnsFiles(source, movedFiles);
+    const movedSet = new Set(movedFiles);
+    const remainingFiles = source.filesAffected.filter((f) => !movedSet.has(f));
+    if (remainingFiles.length === 0) {
+        throw new InvalidArgumentError(`Moving 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.', '--file');
+    }
+    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 = { order: options.order };
+    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, newPatchName, config);
+    const plan = {
+        source,
+        movedFiles,
+        remainingFiles,
+        movedDiff,
+        remainingDiff,
+        placement,
+        placementOptions,
+        category,
+        name: newPatchName,
+        description: options.description ?? '',
+        ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
+        // Populated by runProjectedSplitLint below (forward edges into the new patch).
+        stagedDependencyAdditions: new Map(),
+    };
+    // Per-patch lint both projected bodies, threading the source patch's
+    // tier/lintIgnore so an intentional-advisory patch can still move files.
+    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, stagedDependencyAdditions } = await runProjectedSplitLint(paths.patches, plan);
+    plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    const newMetadata = buildNewPatchMetadata(plan, config);
+    enforcePatchPolicy({
+        config,
+        manifest: projectSplitManifest(manifest, plan, newMetadata),
+        command: 'patch move-files --create',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+    const decision = await confirmDestructive({
+        operation: 'patch-move-files-create',
+        title: `Create ${placement.newFilename} (order ${placement.insertionOrder}) and move ${movedFiles.length} file(s) out of ${source.filename}`,
+        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('Move cancelled');
+        return;
+    }
+    await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
+    success(`Created ${placement.newFilename} (order ${String(placement.insertionOrder).padStart(3, '0')}) ` +
+        `and moved ${plan.movedFiles.length} file(s) out of ${source.filename}`);
+    if (plan.ownerRewrites.length > 0) {
+        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    outro('Move complete');
+}

package/dist/src/commands/patch/move-files.d.ts

@@ -1,6 +1,8 @@
 /**
  * `fireforge patch move-files <from> <to>` previews the explicit
- * re-export choreography needed to move file ownership between two patches.
+ * re-export choreography needed to move file ownership between two
+ * patches. With `--create --order <n>` the target patch is created and
+ * the files move into it as one transaction (see move-files-create.ts).
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';

package/dist/src/commands/patch/move-files.js

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * `fireforge patch move-files <from> <to>` previews the explicit
- * re-export choreography needed to move file ownership between two patches.
+ * re-export choreography needed to move file ownership between two
+ * patches. With `--create --order <n>` the target patch is created and
+ * the files move into it as one transaction (see move-files-create.ts).
  */
 import { relative } from 'node:path';
 import { Command } from 'commander';
@@ -11,6 +13,8 @@ import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-ma
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, note, outro, warn } from '../../utils/logger.js';
+import { commanderArgParser, pickDefined } from '../../utils/options.js';
+import { patchMoveFilesCreateCommand } from './move-files-create.js';
 function collectOption(value, previous) {
     previous.push(value);
     return previous;
@@ -67,6 +71,19 @@ function computeFileMovePlan(source, target, files) {
  * @param options - Files to move and display mode
  */
 export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdentifier, options = {}) {
+    if (options.create === true && options.order === undefined) {
+        throw new InvalidArgumentError('--create requires --order <n> to place the new patch.', '--create');
+    }
+    if (options.create !== true && options.order !== undefined) {
+        throw new InvalidArgumentError('--order is only valid together with --create.', '--order');
+    }
+    if (options.create === true && options.order !== undefined) {
+        await patchMoveFilesCreateCommand(projectRoot, fromIdentifier, toIdentifier, {
+            ...options,
+            order: options.order,
+        });
+        return;
+    }
     intro('FireForge patch move-files');
     if (fromIdentifier === toIdentifier) {
         throw new InvalidArgumentError('Source and target patch identifiers must be different.', 'patch move-files');
@@ -118,7 +135,8 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     note(`${dryRunSource}\n${dryRunTarget}`, 'Preview commands');
     note(`${applySource}\n${applyTarget}`, 'Apply commands');
     info('Tip: to move files into a brand-new patch in one transaction (including ' +
-        'staged-dependency owner rewrites), use "fireforge patch split" instead.');
+        'staged-dependency owner rewrites), re-run with --create --order <n> to create ' +
+        'the target patch and move the files in one step, or use "fireforge patch split".');
     outro('Move plan complete - no changes made');
 }
 /**
@@ -131,9 +149,36 @@ export function registerPatchMoveFiles(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
     parent
         .command('move-files <from> <to>')
-        .description('Preview the re-export commands needed to move file ownership between patches.')
+        .description('Preview the re-export commands needed to move file ownership between patches, ' +
+        'or create the target patch and move the files in one transaction with --create --order <n>.')
         .option('--file <path>', 'File path relative to engine/ to move (repeatable)', collectOption, [])
+        .option('--create', 'Create <to> as a new patch and move the files into it (requires --order)')
+        .option('--order <n>', 'Exact sparse order for the created patch (only valid with --create)', commanderArgParser((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('--category <category>', "Category for the created patch (default: the source patch's)")
+        .option('--description <desc>', 'Description for the created 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 (from, to, options) => {
-        await patchMoveFilesCommand(getProjectRoot(), from, to, options);
+        await patchMoveFilesCommand(getProjectRoot(), from, to, {
+            ...pickDefined({
+                file: options.file,
+                create: options.create,
+                order: options.order,
+                category: options.category,
+                description: options.description,
+                dryRun: options.dryRun,
+                yes: options.yes,
+                forceUnsafe: options.forceUnsafe,
+                skipLint: options.skipLint,
+            }),
+        });
     }));
 }

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

@@ -18,7 +18,17 @@
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';
-import type { PatchSplitOptions } from '../../types/commands/index.js';
+import type { PatchMetadata, PatchSplitOptions } from '../../types/commands/index.js';
+import type { FireForgeConfig } from '../../types/config.js';
+import { type SplitPlan } 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. Exported for
+ * `patch move-files --create`, which commits the same transaction shape.
+ */
+export declare function commitPatchSplit(patchesDir: string, plan: SplitPlan, newMetadata: PatchMetadata, options: Pick<PatchSplitOptions, 'yes' | 'forceUnsafe'>, config: FireForgeConfig): Promise<void>;
 /**
  * Runs the `patch split` command: plans the split, lints the projection,
  * confirms, and commits transactionally.

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

@@ -38,9 +38,10 @@ import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSpli
  * 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.
+ * failure the steps are rolled back in reverse order. Exported for
+ * `patch move-files --create`, which commits the same transaction shape.
  */
-async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
+export async function commitPatchSplit(patchesDir, plan, newMetadata, options, config) {
     await withPatchDirectoryLock(patchesDir, async () => {
         const manifest = await loadPatchesManifest(patchesDir);
         if (!manifest)
@@ -49,7 +50,7 @@ async function commitPatchSplit(patchesDir, plan, newMetadata, options) {
         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);
+        const currentPlacement = await resolvePlacementPlan(patchesDir, plan.placementOptions, plan.category, plan.name, config);
         if (!placementPlansEqual(currentPlacement, plan.placement)) {
             throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
         }
@@ -193,7 +194,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         after: options.after ??
             (options.order === undefined && options.before === undefined ? source.filename : undefined),
     });
-    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name);
+    const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name, config);
     const plan = {
         source,
         movedFiles,
@@ -240,7 +241,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         outro('Split cancelled');
         return;
     }
-    await commitPatchSplit(paths.patches, plan, newMetadata, options);
+    await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     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(', ')}`);

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

@@ -10,7 +10,7 @@ import type { PatchStagedDependencyOptions } from '../../types/commands/index.js
  *
  * @param projectRoot - Project root directory
  * @param identifier - Patch filename, ordinal, or manifest name
- * @param options - Mutation mode and forward-import fields
+ * @param options - Mutation mode, entry kind, and declaration fields
  */
 export declare function patchStagedDependencyCommand(projectRoot: string, identifier: string, options?: PatchStagedDependencyOptions): Promise<void>;
 /**

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

@@ -23,6 +23,19 @@ function modeFromOptions(options) {
     }
     return adding ? 'add' : removing ? 'remove' : 'clear';
 }
+function kindFromOptions(options) {
+    const kind = options.kind ?? 'import';
+    if (kind !== 'import' && kind !== 'registration') {
+        throw new InvalidArgumentError(`--kind must be "import" or "registration" (got "${kind}").`, 'patch staged-dependency');
+    }
+    if (kind === 'import' && options.line !== undefined) {
+        throw new InvalidArgumentError('--line only applies to --kind registration; import declarations use --specifier.', 'patch staged-dependency');
+    }
+    if (kind === 'registration' && options.specifier !== undefined) {
+        throw new InvalidArgumentError('--specifier only applies to --kind import; registration declarations use --line.', 'patch staged-dependency');
+    }
+    return kind;
+}
 function requireForwardImportOptions(options, mode) {
     if (!options.file || !options.specifier || !options.creates) {
         throw new InvalidArgumentError(`--${mode} requires --file, --specifier, and --creates.`, 'patch staged-dependency');
@@ -38,102 +51,149 @@ function requireForwardImportOptions(options, mode) {
         dependency.reason = options.reason;
     return dependency;
 }
-function dependencyKey(dependency) {
-    return [dependency.file, dependency.specifier, dependency.creates, dependency.owner ?? ''].join('\0');
+function requireRegistrationOptions(options, mode) {
+    if (!options.file || !options.line || !options.creates) {
+        throw new InvalidArgumentError(`--${mode} --kind registration requires --file, --line, and --creates.`, 'patch staged-dependency');
+    }
+    const dependency = {
+        file: options.file,
+        line: options.line,
+        creates: options.creates,
+    };
+    if (options.owner !== undefined)
+        dependency.owner = options.owner;
+    if (options.reason !== undefined)
+        dependency.reason = options.reason;
+    return dependency;
+}
+function importView(dependency) {
+    return { ...dependency, matcher: dependency.specifier };
 }
-function dependencyLabel(dependency) {
-    const owner = dependency.owner ? ` owner=${dependency.owner}` : '';
-    const reason = dependency.reason ? ` reason="${dependency.reason}"` : '';
-    return `${dependency.file} imports "${dependency.specifier}" from ${dependency.creates}${owner}${reason}`;
+function registrationView(dependency) {
+    return { ...dependency, matcher: dependency.line };
 }
-function removeMatching(existing, target) {
-    return existing.filter((dependency) => dependency.file !== target.file ||
-        dependency.specifier !== target.specifier ||
-        dependency.creates !== target.creates ||
-        (target.owner !== undefined && dependency.owner !== target.owner));
+function dependencyKey(view) {
+    return [view.file, view.matcher, view.creates, view.owner ?? ''].join('\0');
 }
-function applyMode(existing, mode, dependency) {
+function dependencyLabel(kind, view) {
+    const owner = view.owner ? ` owner=${view.owner}` : '';
+    const reason = view.reason ? ` reason="${view.reason}"` : '';
+    if (kind === 'import') {
+        return `${view.file} imports "${view.matcher}" from ${view.creates}${owner}${reason}`;
+    }
+    return `${view.file} registers "${view.matcher}" for ${view.creates}${owner}${reason}`;
+}
+function matchesTarget(view, target) {
+    return (view.file === target.file &&
+        view.matcher === target.matcher &&
+        view.creates === target.creates &&
+        (target.owner === undefined || view.owner === target.owner));
+}
+function applyMode(existing, mode, target, toView, addition) {
     if (mode === 'clear')
         return [];
-    if (!dependency)
+    if (!target)
         return [...existing];
     if (mode === 'remove')
-        return removeMatching(existing, dependency);
-    const seen = new Set(existing.map(dependencyKey));
-    if (seen.has(dependencyKey(dependency)))
+        return existing.filter((entry) => !matchesTarget(toView(entry), target));
+    const seen = new Set(existing.map((entry) => dependencyKey(toView(entry))));
+    if (seen.has(dependencyKey(target)) || addition === undefined)
         return [...existing];
-    return [...existing, dependency];
+    return [...existing, addition];
 }
 /**
  * Renders a one-line summary of a staged-dependency metadata change.
  */
-function describeStagedDependencyChange(before, after, mode, dependency) {
+function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, target) {
+    const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
     if (mode === 'clear') {
-        return before.length === 0
+        return beforeCount === 0
             ? 'stagedDependencies was already empty — no change'
-            : `cleared ${before.length} staged forward-import declaration(s)`;
+            : `cleared ${beforeCount} staged dependency declaration(s)`;
     }
-    if (!dependency)
+    if (!target)
         return 'stagedDependencies unchanged';
     if (mode === 'add') {
-        return after.length === before.length
-            ? `staged forward-import already present: ${dependencyLabel(dependency)}`
-            : `added staged forward-import: ${dependencyLabel(dependency)}`;
+        return afterCount === beforeCount
+            ? `${noun} already present: ${dependencyLabel(kind, target)}`
+            : `added ${noun}: ${dependencyLabel(kind, target)}`;
     }
-    return after.length === before.length
-        ? `no staged forward-import matched: ${dependencyLabel(dependency)}`
-        : `removed ${before.length - after.length} staged forward-import declaration(s): ${dependencyLabel(dependency)}`;
+    return afterCount === beforeCount
+        ? `no ${noun} matched: ${dependencyLabel(kind, target)}`
+        : `removed ${beforeCount - afterCount} ${noun} declaration(s): ${dependencyLabel(kind, target)}`;
+}
+function countStagedEntries(staged) {
+    return (staged?.forwardImports?.length ?? 0) + (staged?.registrations?.length ?? 0);
 }
 /**
  * Runs the metadata-only staged-dependency mutation command.
  *
  * @param projectRoot - Project root directory
  * @param identifier - Patch filename, ordinal, or manifest name
- * @param options - Mutation mode and forward-import fields
+ * @param options - Mutation mode, entry kind, and declaration fields
  */
 export async function patchStagedDependencyCommand(projectRoot, identifier, options = {}) {
     const isDryRun = options.dryRun === true;
     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 kind = kindFromOptions(options);
+    const importDependency = mode === 'clear' || kind !== 'import' ? undefined : requireForwardImportOptions(options, mode);
+    const registrationDependency = mode === 'clear' || kind !== 'registration'
+        ? undefined
+        : requireRegistrationOptions(options, mode);
+    const target = importDependency !== undefined
+        ? importView(importDependency)
+        : registrationDependency !== undefined
+            ? registrationView(registrationDependency)
+            : undefined;
     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);
+    const targetPatch = requirePatchTarget(identifier, manifest.patches);
+    const applyToStaged = (staged) => {
+        if (mode === 'clear')
+            return {};
+        const forwardImports = applyMode(staged?.forwardImports ?? [], kind === 'import' ? mode : 'add', kind === 'import' ? target : undefined, importView, importDependency);
+        const registrations = applyMode(staged?.registrations ?? [], kind === 'registration' ? mode : 'add', kind === 'registration' ? target : undefined, registrationView, registrationDependency);
+        return {
+            ...(forwardImports.length > 0 ? { forwardImports } : {}),
+            ...(registrations.length > 0 ? { registrations } : {}),
+        };
+    };
+    const existing = targetPatch.stagedDependencies;
+    const projected = applyToStaged(existing);
+    const summary = describeStagedDependencyChange(countStagedEntries(existing), countStagedEntries(projected), mode, kind, target);
     if (isDryRun) {
-        info(`[dry-run] ${target.filename}: ${summary}.`);
+        info(`[dry-run] ${targetPatch.filename}: ${summary}.`);
         outro('Dry run complete — no changes made');
         return;
     }
-    const result = await mutatePatchMetadata(paths.patches, target.filename, (current) => {
-        const before = current.stagedDependencies?.forwardImports ?? [];
-        const after = applyMode(before, mode, dependency);
-        if (after.length === 0)
+    const result = await mutatePatchMetadata(paths.patches, targetPatch.filename, (current) => {
+        const after = applyToStaged(current.stagedDependencies);
+        if (countStagedEntries(after) === 0)
             return { unset: ['stagedDependencies'] };
-        return { set: { stagedDependencies: { forwardImports: after } } };
+        return { set: { stagedDependencies: after } };
     });
     if (!result) {
-        throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during the update. Re-run after investigating.`);
+        throw new GeneralError(`Patch ${targetPatch.filename} disappeared from the manifest during the update. Re-run after investigating.`);
     }
-    const before = result.before.stagedDependencies?.forwardImports ?? [];
-    const after = result.after.stagedDependencies?.forwardImports ?? [];
-    info(`${target.filename}: ${describeStagedDependencyChange(before, after, mode, dependency)}.`);
+    const before = result.before.stagedDependencies;
+    const after = result.after.stagedDependencies;
+    info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, target)}.`);
     try {
         await appendHistory(paths.patches, {
             operation: 'patch-staged-dependency',
             args: {
-                filename: target.filename,
+                filename: targetPatch.filename,
                 mode,
-                before,
-                after,
+                kind,
+                before: before ?? {},
+                after: after ?? {},
             },
             ...(options.yes === true ? { yes: true } : {}),
             result: 'ok',
         });
     }
     catch (historyError) {
-        warn(`History log append failed after patch staged-dependency committed (${target.filename}): ${toError(historyError).message}`);
+        warn(`History log append failed after patch staged-dependency committed (${targetPatch.filename}): ${toError(historyError).message}`);
     }
     outro('Patch staged-dependency complete');
 }
@@ -148,11 +208,13 @@ export function registerPatchStagedDependency(parent, context) {
     parent
         .command('staged-dependency <name>')
         .description('Edit PatchMetadata.stagedDependencies on a single patch (no .patch body rewrite).')
-        .option('--add', 'Add a staged forward-import declaration')
-        .option('--remove', 'Remove matching staged forward-import declaration(s)')
+        .option('--add', 'Add a staged dependency declaration')
+        .option('--remove', 'Remove matching staged dependency declaration(s)')
         .option('--clear', 'Drop the stagedDependencies field entirely')
-        .option('--file <path>', 'Importing file path relative to engine/')
-        .option('--specifier <specifier>', 'Exact import specifier as it appears in source')
+        .option('--kind <kind>', 'Declaration shape: "import" (forward import, the default) or "registration" (jar.mn packaging line, customElements or actor registration)')
+        .option('--file <path>', 'Declaring file path relative to engine/')
+        .option('--specifier <specifier>', 'Exact import specifier as it appears in source (--kind import)')
+        .option('--line <text>', 'Registration/packaging line as the patch adds it, compared whitespace-trimmed (--kind registration)')
         .option('--creates <path>', 'Later-created file path relative to engine/')
         .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
         .option('--reason <text>', 'Human-readable rationale stored with the declaration')