feat(commands): add registerDeferredCommand to the command registry

Claiming a command name and loading its implementation are now separate: the
registry builds routing — the command record, the parent's subcommand list and
the parent dispatcher — from the name alone, and runs the loader only when that
one command is resolved. A sibling's dispatch no longer drags in the first
claimant's module, and the outcome comes back as a structured result instead of
a thrown message callers have to match on.

Names that are not lower case are rejected: dispatch lower-cases what the user
typed, so they could never be reached. A loader that throws, or that leaves the
command without a resolver, fails naming the owner and the source.

Extract registerDefinitionAs so a definition registered under a name chosen by
its registrant is built exactly like one registered under its own.

Author: edusperoni

lib/common/contracts/command-registry.ts

@@ -1,6 +1,43 @@
 import { Contract } from "../di/contract";
 import type { ICommand } from "../definitions/commands";
 
+export interface DeferredCommandOptions {
+	/**
+	 * Names the registrant in conflict and failure reports. Re-registering the
+	 * same command under the same owner is a no-op rather than a conflict.
+	 */
+	owner: string;
+	/** Where the implementation comes from; named when loading it fails. */
+	source: string;
+	/**
+	 * Runs on first resolution of the command. It must leave a real resolver on
+	 * the command name — by exporting a definition the caller registers, or by
+	 * registering the command itself.
+	 */
+	load: () => void;
+}
+
+/** Why a deferred registration did not take effect. */
+export type DeferredCommandRejection =
+	/** The name can never be dispatched; `detail` says why. */
+	| { reason: "invalid-name"; detail: string }
+	/** Another owner registered the same command first. */
+	| { reason: "claimed"; owner: string }
+	/** The CLI itself provides the command. */
+	| { reason: "built-in" }
+	/** The name is in use as the dispatcher for subcommands under it. */
+	| { reason: "subcommand-parent" };
+
+/**
+ * Outcome of a deferred registration. Callers branch on `rejection.reason`
+ * rather than on message text, so the wording of the report stays theirs.
+ */
+export interface DeferredCommandResult {
+	registered: boolean;
+	/** Set exactly when `registered` is false. */
+	rejection?: DeferredCommandRejection;
+}
+
 /**
  * The command-registry face of the injector facade. Transitional contract: it
  * mirrors what consumers call today, so that extracting the registry from the
@@ -10,11 +47,20 @@ import type { ICommand } from "../definitions/commands";
 @Contract({ name: "commandRegistry" })
 export abstract class CommandRegistry {
 	/**
-	 * @deprecated Path-based command registration; slated for replacement by
-	 * manifest-declared commands.
+	 * @deprecated Path-based command registration; use registerDeferredCommand,
+	 * which routes without loading and reports conflicts structurally.
 	 */
 	abstract requireCommand(names: string | string[], file: string): void;
 	abstract registerCommand(names: string | string[], resolver: any): void;
+	/**
+	 * Claims a command name for an owner without loading anything: routing —
+	 * including the dispatcher of a hierarchical parent — is built from the name
+	 * alone, and `load` runs only when that one command is resolved.
+	 */
+	abstract registerDeferredCommand(
+		name: string,
+		options: DeferredCommandOptions,
+	): DeferredCommandResult;
 	abstract resolveCommand(name: string): ICommand;
 	abstract getRegisteredCommandsNames(includeDev: boolean): string[];
 	abstract getChildrenCommandsNames(commandName: string): string[];

lib/common/contracts/index.ts

@@ -5,6 +5,11 @@
 // physically extracted — at which point the provider is swapped and consumers
 // keep working unchanged.
 export { CommandRegistry } from "./command-registry";
+export type {
+	DeferredCommandOptions,
+	DeferredCommandRejection,
+	DeferredCommandResult,
+} from "./command-registry";
 export { KeyCommandRegistry } from "./key-command-registry";
 export { ModuleRegistry } from "./module-registry";
 export { PublicApiBuilder } from "./public-api-builder";

lib/common/services/command-definition-adapter.ts

@@ -203,6 +203,26 @@ export function createCommandFromDefinition<
 	};
 }
 
+/**
+ * Registers a definition under an externally chosen command name. Extension
+ * manifests route by their own key, which need not be the definition's own
+ * name, so the name is a parameter rather than read off the definition.
+ */
+export function registerDefinitionAs<TSchema extends CommandOptionsSchema>(
+	name: string,
+	definition: DefinedCommand<TSchema>,
+	targetInjector: IInjector = injector,
+): void {
+	// The registry facet rather than the injector itself, so a child injector
+	// that provides its own CommandRegistry receives the registration.
+	const registry = targetInjector.get(CommandRegistry);
+	// A prototype-less zero-parameter function registers as a useFactory
+	// provider, so the command is built on first resolution and cached.
+	registry.registerCommand(name, () =>
+		createCommandFromDefinition(definition, targetInjector),
+	);
+}
+
 export function registerCommandDefinition<TSchema extends CommandOptionsSchema>(
 	definition: DefinedCommand<TSchema>,
 	targetInjector: IInjector = injector,
@@ -214,18 +234,11 @@ export function registerCommandDefinition<TSchema extends CommandOptionsSchema>(
 		);
 	}
 
-	// The registry facet rather than the injector itself, so a child injector
-	// that provides its own CommandRegistry receives the registration.
-	const registry = targetInjector.get(CommandRegistry);
 	const names = Array.isArray(definition.name)
 		? definition.name
 		: [definition.name];
 
 	for (const name of names) {
-		// A prototype-less zero-parameter function registers as a useFactory
-		// provider, so the command is built on first resolution and cached.
-		registry.registerCommand(name, () =>
-			createCommandFromDefinition(definition, targetInjector),
-		);
+		registerDefinitionAs(name, definition, targetInjector);
 	}
 }

lib/common/yok.ts

@@ -16,6 +16,11 @@ import {
 	ModuleRegistry,
 	PublicApiBuilder,
 } from "./contracts";
+import type {
+	DeferredCommandOptions,
+	DeferredCommandRejection,
+	DeferredCommandResult,
+} from "./contracts";
 
 /**
  * The legacy global facade binding. New code should obtain the container via
@@ -24,6 +29,10 @@ import {
  */
 export let injector: IInjector;
 
+function rejected(rejection: DeferredCommandRejection): DeferredCommandResult {
+	return { registered: false, rejection };
+}
+
 function forEachName(names: any, action: (name: string) => void): void {
 	if (_.isString(names)) {
 		action(names);
@@ -95,10 +104,12 @@ export class Yok extends Injector implements IInjector {
 	private placeholderParents = new Set<string>();
 	private KEY_COMMANDS_NAMESPACE: string = "keyCommands";
 	private hierarchicalCommands: IDictionary<string[]> = {};
+	/** Deferred command name -> the owner that claimed it first. */
+	private deferredCommandOwners: IDictionary<string> = {};
 
 	/**
-	 * @deprecated Path-based command registration; slated for replacement by
-	 * manifest-declared commands.
+	 * @deprecated Path-based command registration; use registerDeferredCommand,
+	 * which routes without loading and reports conflicts structurally.
 	 */
 	public requireCommand(names: any, file: string): void {
 		forEachName(names, (commandName) => {
@@ -145,6 +156,86 @@ export class Yok extends Injector implements IInjector {
 		});
 	}
 
+	public registerDeferredCommand(
+		name: string,
+		options: DeferredCommandOptions,
+	): DeferredCommandResult {
+		if (name !== name.toLowerCase()) {
+			return rejected({
+				reason: "invalid-name",
+				detail:
+					`command names are matched in lower case, so '${name}' can never ` +
+					`be dispatched; declare it as '${name.toLowerCase()}'`,
+			});
+		}
+
+		const claimedBy = this.deferredCommandOwners[name];
+		if (claimedBy) {
+			return claimedBy === options.owner
+				? { registered: true }
+				: rejected({ reason: "claimed", owner: claimedBy });
+		}
+
+		const commandRecordName = this.createCommandName(name);
+		if (this.has(commandRecordName)) {
+			return rejected(
+				this.synthesizedParents.has(name)
+					? { reason: "subcommand-parent" }
+					: { reason: "built-in" },
+			);
+		}
+
+		super.register({
+			provide: commandRecordName,
+			useLazyRequire: () => {
+				try {
+					options.load();
+				} catch (err) {
+					throw new Error(
+						`Unable to load command '${name}' of ${options.owner} from ` +
+							`${options.source}: ${err.message}`,
+					);
+				}
+
+				if (!this.hasResolver(commandRecordName)) {
+					throw new Error(
+						`Command '${name}' of ${options.owner} was not registered when ` +
+							`${options.source} loaded. The module must export a ` +
+							`defineCommand() definition or register the command itself.`,
+					);
+				}
+			},
+		});
+		this.deferredCommandOwners[name] = options.owner;
+
+		const commands = name.split(CommandsDelimiters.HierarchicalCommand);
+		if (commands.length > 1) {
+			const parentCommandName = commands[0];
+			const subCommandName = _.tail(commands).join(
+				CommandsDelimiters.HierarchicalCommand,
+			);
+
+			if (!this.hierarchicalCommands[parentCommandName]) {
+				this.hierarchicalCommands[parentCommandName] = [];
+			}
+
+			if (
+				!_.includes(
+					this.hierarchicalCommands[parentCommandName],
+					subCommandName,
+				)
+			) {
+				this.hierarchicalCommands[parentCommandName].push(subCommandName);
+			}
+
+			// The dispatcher routes off the recorded subcommand names alone, so
+			// reaching a sibling never loads this entry's module.
+			this.createHierarchicalCommand(parentCommandName, name);
+		}
+
+		return { registered: true };
+	}
+
 	/**
 	 * @deprecated Use provideLazy() from lib/common/di (via `Yok.di`) — the same
 	 * deferred loading, token-based.
@@ -227,7 +318,7 @@ export class Yok extends Injector implements IInjector {
 			// Yok replaced the whole record on an allowed re-require, dropping any
 			// resolver and cached instances with it — preserved via remove().
 			this.remove(name);
-			this.register({
+			super.register({
 				provide: name,
 				useLazyRequire: () => require(dependencyPath),
 			});