feat(commands): make the in-process dispatcher a contract

CommandsService is the API a command or plugin runs or consults another
command through: runCommand and canExecuteCommand take the registered
name or the definition or class it was registered from. The free helpers
stay as convenience over it; the *InProcess methods are deprecated.

Author: edusperoni

defining-commands.md

@@ -824,12 +824,20 @@ per-platform command subclasses a shared base to override one field.
 Running a command in process
 ----------------------------
 
-`runCommand` dispatches a registered command from inside the process that is
-already running:
+The `CommandsService` contract dispatches a registered command from inside the
+process that is already running. A class command injects it like any other
+service; an inline handler or a key shortcut may use the `runCommand`
+convenience, which only resolves the contract from the current context:
 
 ```ts
+import { CommandsService } from "../common/contracts/commands-service";
 import { runCommand } from "../common/services/command-definition-adapter";
 
+// in a class command
+private $commandsService = inject(CommandsService);
+await this.$commandsService.runCommand("autocomplete");
+
+// in an inline handler or a shortcut action
 await runCommand("open|ios");
 await runCommand("install", ["lodash"]);
 ```
@@ -857,14 +865,20 @@ declarations into it rewrites the values the host process is still running on
 — `open|ios` declares `watch: false`, which would otherwise leave an `ns start`
 out of watch mode for the rest of its life.
 
-Which injector it dispatches through follows the rule `registerCommand` does:
-the injector of the current injection context, and the CLI's own outside one.
-`runCommand` is a thin call onto `CommandsService.executeCommandInProcess`,
-where the pipeline itself lives.
+Which injector `runCommand` dispatches through follows the rule
+`registerCommand` does: the injector of the current injection context, and the
+CLI's own outside one. The pipeline itself lives on the contract, so a plugin
+that holds an injector can call `CommandsService.runCommand` directly.
 
 ### Asking another command
 
-`canExecuteCommand(name, args)` asks a registered command whether it *could*
+Both methods take the command's registered name, or — the typed way — the
+definition or `Command()` class it was registered from, whose first name is
+used: `runCommand(prepareCommandDefinition)` cannot go stale the way a string
+can.
+
+`CommandsService.canExecuteCommand(command, args)` — or the
+`canExecuteCommand` convenience — asks a registered command whether it *could*
 run, without running it:
 
 ```ts

lib/commands/embedding/embed.ts

@@ -7,7 +7,11 @@ import { IFileSystem } from "../../common/declarations";
 import { inject } from "../../common/di";
 import { canExecuteCommand } from "../../common/services/command-definition-adapter";
 import { platformArgument } from "../command-base";
-import { prepareCommandOptions, runPrepareCommand } from "../prepare";
+import {
+	prepareCommandDefinition,
+	prepareCommandOptions,
+	runPrepareCommand,
+} from "../prepare";
 
 function resolveHostProjectPath(
 	projectDir: string,
@@ -52,7 +56,12 @@ export class EmbedCommand extends Command({
 	public async canExecute(): Promise<boolean> {
 		// `prepare` takes the platform alone; the host project arguments are this
 		// command's own and it would reject them.
-		if (!(await canExecuteCommand("prepare", this.args.slice(0, 1)))) {
+		if (
+			!(await canExecuteCommand(
+				prepareCommandDefinition,
+				this.args.slice(0, 1),
+			))
+		) {
 			return false;
 		}
 

lib/commands/post-install.ts

@@ -6,6 +6,7 @@ import {
 	IHostInfo,
 	ISettingsService,
 } from "../common/declarations";
+import { CommandsService } from "../common/contracts/commands-service";
 import { Command } from "../common/define-command";
 import { inject } from "../common/di";
 import { doesCurrentNpmCommandMatch } from "../common/helpers";
@@ -16,7 +17,7 @@ export class PostInstallCliCommand extends Command({
 	disableAnalytics: true,
 }) {
 	private $fs = inject<IFileSystem>("fs");
-	private $commandsService = inject<ICommandsService>("commandsService");
+	private $commandsService = inject(CommandsService);
 	private $helpService = inject<IHelpService>("helpService");
 	private $settingsService = inject<ISettingsService>("settingsService");
 	private $analyticsService = inject<IAnalyticsService>("analyticsService");
@@ -47,7 +48,7 @@ export class PostInstallCliCommand extends Command({
 
 			// Explicitly ask for confirmation of usage-reporting:
 			await this.$analyticsService.checkConsent();
-			await this.$commandsService.tryExecuteCommand("autocomplete", []);
+			await this.$commandsService.runCommand("autocomplete");
 		}
 	}
 

lib/common/commands/device/device-log-stream.ts

@@ -1,4 +1,5 @@
 import { ICleanupService } from "../../../definitions/cleanup-service";
+import { CommandsService } from "../../contracts/commands-service";
 import { IErrors } from "../../declarations";
 import {
 	CommandOptionsSchema,
@@ -29,7 +30,7 @@ export const openDeviceLogStreamCommandDefinition = defineCommand({
 		inject<ICleanupService>("cleanupService").setShouldDispose(false);
 	},
 	async run(context): Promise<void> {
-		const $commandsService = inject<ICommandsService>("commandsService");
+		const $commandsService = inject(CommandsService);
 		const $deviceLogProvider =
 			inject<Mobile.IDeviceLogProvider>("deviceLogProvider");
 		const $devicesService = inject<Mobile.IDevicesService>("devicesService");
@@ -44,7 +45,7 @@ export const openDeviceLogStreamCommandDefinition = defineCommand({
 		});
 
 		if ($devicesService.deviceCount > 1) {
-			await $commandsService.tryExecuteCommand("device", []);
+			await $commandsService.runCommand("device");
 			$errors.failWithHelp(NOT_SPECIFIED_DEVICE_ERROR_MESSAGE);
 		}
 

lib/common/contracts/commands-service.ts

@@ -0,0 +1,45 @@
+import { Contract } from "../di/contract";
+import type { CommandReference } from "../define-command";
+
+/**
+ * Dispatches commands inside the running process: the surface a command, a
+ * key shortcut or a plugin uses to run or consult another command. The command
+ * line's own entry points into the dispatcher are not part of it.
+ */
+@Contract({ name: "commandsService" })
+export abstract class CommandsService {
+	/**
+	 * Whether the command running now was dispatched in process rather than by
+	 * the command line — what tells a command it is borrowing a host process
+	 * instead of owning one.
+	 */
+	abstract readonly isExecutingInProcess: boolean;
+
+	/**
+	 * Runs a registered command in the current process. The command gets what a
+	 * typed command line gives it — its declared options primed with their
+	 * defaults, the arguments policy, `canExecute`, hooks and `postRun` — and a
+	 * failure throws instead of exiting, so a process that has to keep running
+	 * can catch it. Analytics do not fire: this is not a new CLI invocation.
+	 *
+	 * `command` is the registered name, or the definition or `Command()` class
+	 * it was registered from — the typed way to refer to a command.
+	 */
+	abstract runCommand(
+		command: CommandReference,
+		args?: string[],
+	): Promise<void>;
+
+	/**
+	 * Asks a registered command whether it could run on `args`, without running
+	 * it. The command is resolved and its options primed exactly as for
+	 * `runCommand`, and its own `canExecute` returns the verdict. The child
+	 * builds its own setup from its own services, so nothing crosses between
+	 * the two but the name and the arguments; pass only the arguments the
+	 * child's own `arguments` policy accepts.
+	 */
+	abstract canExecuteCommand(
+		command: CommandReference,
+		args?: string[],
+	): Promise<boolean>;
+}

lib/common/contracts/index.ts

@@ -15,5 +15,6 @@ export type {
 	DeferredCommandResult,
 } from "./command-registry";
 export { COMMAND_CONTEXT } from "./command-context";
+export { CommandsService } from "./commands-service";
 export { ModuleRegistry } from "./module-registry";
 export { PublicApiBuilder } from "./public-api-builder";

lib/common/define-command.ts

@@ -762,6 +762,28 @@ export function toCommandDefinition(
 	return isCommandDefinition(value) ? value : null;
 }
 
+/**
+ * What a dispatcher accepts in place of a command name: the name itself, or
+ * the definition or class it was registered from, whose first name is used.
+ */
+export type CommandReference = string | RegisterableCommand;
+
+export function commandNameOf(command: CommandReference): string {
+	if (typeof command === "string") {
+		return command;
+	}
+
+	const definition = toCommandDefinition(command);
+	if (!definition) {
+		throw new Error(
+			`${describeDefinition(command)} is neither a command name, a ` +
+				`defineCommand() definition nor a Command() class.`,
+		);
+	}
+
+	return Array.isArray(definition.name) ? definition.name[0] : definition.name;
+}
+
 /**
  * The class authoring form: sugar over defineCommand, not a second execution
  * path. The returned base carries a `definition` that reads the class it is

lib/common/definitions/commands-service.d.ts

@@ -19,14 +19,24 @@ interface ICommandsService {
 	 * Runs a command inside the running process, throwing on failure rather
 	 * than exiting, so a long-lived host survives it.
 	 */
-	executeCommandInProcess(
-		commandName: string,
+	runCommand(
+		command: import("../define-command").CommandReference,
 		commandArguments?: string[],
 	): Promise<void>;
 	/**
 	 * Asks a command whether it could run, without running it. The command
 	 * builds its own setup from its own services.
 	 */
+	canExecuteCommand(
+		command: import("../define-command").CommandReference,
+		commandArguments?: string[],
+	): Promise<boolean>;
+	/** @deprecated Use `runCommand`. */
+	executeCommandInProcess(
+		commandName: string,
+		commandArguments?: string[],
+	): Promise<void>;
+	/** @deprecated Use `canExecuteCommand`. */
 	canExecuteCommandInProcess(
 		commandName: string,
 		commandArguments?: string[],

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

@@ -6,6 +6,7 @@ import { Injector } from "../di/injector";
 import { IDictionary, IDashedOption, IErrors } from "../declarations";
 import { ICommand } from "../definitions/commands";
 import { COMMAND_CONTEXT } from "../contracts/command-context";
+import { CommandsService } from "../contracts/commands-service";
 import {
 	COMMAND_OWNER,
 	CommandRegistry,
@@ -29,6 +30,7 @@ import {
 	CommandOptionSpec,
 	CommandOptionType,
 	CommandOptionsSchema,
+	CommandReference,
 	DefinedCommand,
 	RegisterableCommand,
 	defineCommand,
@@ -403,10 +405,9 @@ export function createCommandFromDefinition<
 			return;
 		}
 
-		const commandsService = targetInjector.get<ICommandsService>(
-			"commandsService",
-			{ optional: true },
-		);
+		const commandsService = targetInjector.get(CommandsService, {
+			optional: true,
+		});
 		if (commandsService && commandsService.isExecutingInProcess) {
 			return;
 		}
@@ -543,40 +544,28 @@ const contextInjector = (): Injector =>
 	getCurrentInjector() || <Injector>(<any>getRootInjector());
 
 /**
- * Runs a registered command in the current process. The command gets what a
- * typed command line gives it — its declared options primed with their
- * defaults, the arguments policy, `canExecute`, hooks and `postRun` — and a
- * failure throws instead of exiting, so a process that has to keep running
- * (`ns start`, dispatching a key shortcut) can catch it.
+ * Convenience over `CommandsService.runCommand` for code that has no injected
+ * service at hand, such as a key shortcut action or an inline handler; the
+ * contract is the API, this only resolves it from the current context.
  */
 export async function runCommand(
-	name: string,
+	command: CommandReference,
 	args: string[] = [],
 ): Promise<void> {
-	const commandsService =
-		contextInjector().get<ICommandsService>("commandsService");
-
-	await commandsService.executeCommandInProcess(name, args);
+	await contextInjector().get(CommandsService).runCommand(command, args);
 }
 
 /**
- * Asks a registered command whether it could run on `args`, without running it.
- * The named command is resolved and its options primed exactly as `runCommand`
- * does, and its own `canExecute` returns the verdict.
- *
- * This is how one command reuses another's precondition — `embed` asking
- * whether `prepare` would run. The child resolves its own services, so nothing
- * crosses between the two but the name and the arguments; pass only the
- * arguments the child's own `arguments` policy accepts.
+ * Convenience over `CommandsService.canExecuteCommand`, resolved from the
+ * current context the way `runCommand` is.
  */
 export async function canExecuteCommand(
-	name: string,
+	command: CommandReference,
 	args: string[] = [],
 ): Promise<boolean> {
-	const commandsService =
-		contextInjector().get<ICommandsService>("commandsService");
-
-	return commandsService.canExecuteCommandInProcess(name, args);
+	return contextInjector()
+		.get(CommandsService)
+		.canExecuteCommand(command, args);
 }
 
 /**