feat(commands): ask another command whether it can execute

canExecuteCommand(name, args) resolves a registered command and primes its
options exactly as runCommand does, then returns its own canExecute verdict.
The child builds its setup from its own services, so a command can reuse
another's precondition without importing its handlers.

Author: edusperoni

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

@@ -23,6 +23,14 @@ interface ICommandsService {
 		commandName: string,
 		commandArguments?: string[],
 	): Promise<void>;
+	/**
+	 * Asks a command whether it could run, without running it. The command
+	 * builds its own setup from its own services.
+	 */
+	canExecuteCommandInProcess(
+		commandName: string,
+		commandArguments?: string[],
+	): Promise<boolean>;
 }
 
 /**

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

@@ -559,6 +559,26 @@ export async function runCommand(
 	await commandsService.executeCommandInProcess(name, 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.
+ */
+export async function canExecuteCommand(
+	name: string,
+	args: string[] = [],
+): Promise<boolean> {
+	const commandsService =
+		contextInjector().get<ICommandsService>("commandsService");
+
+	return commandsService.canExecuteCommandInProcess(name, args);
+}
+
 /**
  * Registers a command with the CLI. Takes a Command() class, the result of
  * defineCommand(), or a bare definition, which it defines on the caller's

lib/common/services/commands-service.ts

@@ -283,6 +283,39 @@ export class CommandsService implements ICommandsService {
 		}
 	}
 
+	/**
+	 * The `canExecute` half of {@link executeCommandInProcess}: the named command
+	 * is resolved and its options are primed the same way, and its own
+	 * `canExecute` returns the verdict. The child builds its own setup from its
+	 * own services — nothing is threaded in from the caller — which is what lets
+	 * one command reuse another's precondition without importing its handlers.
+	 */
+	public async canExecuteCommandInProcess(
+		commandName: string,
+		commandArguments: string[] = [],
+	): Promise<boolean> {
+		this.inProcessDepth++;
+		try {
+			const command = this.$injector.resolveCommand(commandName);
+			if (!command) {
+				this.$errors.failWithHelp(
+					`Unknown command '${helpers.stringReplaceAll(commandName, "|", " ")}'.`,
+				);
+			}
+
+			this.commands.push({ commandName, commandArguments });
+			const restoreOptions = this.primeOptions(command);
+			try {
+				return await this.canExecuteCommand(commandName, commandArguments);
+			} finally {
+				restoreOptions();
+				this.commands.pop();
+			}
+		} finally {
+			this.inProcessDepth--;
+		}
+	}
+
 	/**
 	 * Merging a command's options into the parser rewrites the values the host
 	 * process is still running on: a declared default replaces the CLI-wide one

test/define-command.ts

@@ -29,6 +29,7 @@ import {
 	stringOption,
 } from "../lib/common/define-command";
 import {
+	canExecuteCommand,
 	createCommandFromDefinition,
 	registerBuiltInCommand,
 	registerCommand,
@@ -1344,6 +1345,128 @@ describe("defineCommand", () => {
 		});
 	});
 
+	describe("canExecuteCommand", () => {
+		const createInProcessInjector = (): IInjector => {
+			const testInjector = new Yok();
+			testInjector.register("errors", {
+				beginCommand: async (action: () => Promise<boolean>) => action(),
+				failWithHelp: (message: string) => {
+					throw new Error(message);
+				},
+				fail: (message: string) => {
+					throw new Error(message);
+				},
+				reportCommandError: async (ex: Error) => {
+					throw ex;
+				},
+			});
+			testInjector.register("hooksService", HooksServiceStub);
+			testInjector.register("logger", LoggerStub);
+			testInjector.register("staticConfig", {
+				disableAnalytics: true,
+				disableCommandHooks: true,
+			});
+			testInjector.register("extensibilityService", {});
+			testInjector.register("optionsTracker", {});
+			testInjector.register("options", {
+				validateOptions: (): void => undefined,
+			});
+			testInjector.register("commandsService", CommandsService);
+			return testInjector;
+		};
+
+		it("returns the named command's own verdict without running it", async () => {
+			const testInjector = createInProcessInjector();
+			let ran = false;
+
+			runInInjectionContext(testInjector, () => {
+				registerCommand(
+					defineCommand({
+						name: "dctest-can-yes",
+						arguments: "any",
+						canExecute: (context) => context.args[0] === "ok",
+						run: () => {
+							ran = true;
+						},
+					}),
+				);
+			});
+
+			const verdicts = [
+				await runInInjectionContext(testInjector, () =>
+					canExecuteCommand("dctest-can-yes", ["ok"]),
+				),
+				await runInInjectionContext(testInjector, () =>
+					canExecuteCommand("dctest-can-yes", ["nope"]),
+				),
+			];
+
+			assert.deepEqual(verdicts, [true, false]);
+			assert.isFalse(ran);
+		});
+
+		it("enforces the child's arguments policy before its canExecute", async () => {
+			const testInjector = createInProcessInjector();
+			let consulted = false;
+
+			runInInjectionContext(testInjector, () =>
+				registerCommand(
+					defineCommand({
+						name: "dctest-can-none",
+						canExecute: () => {
+							consulted = true;
+							return true;
+						},
+						run: (): void => undefined,
+					}),
+				),
+			);
+
+			await assert.isRejected(
+				runInInjectionContext(testInjector, () =>
+					canExecuteCommand("dctest-can-none", ["stray"]),
+				),
+				/doesn't accept parameters/,
+			);
+			assert.isFalse(consulted);
+		});
+
+		it("builds the child's setup from the child's own services", async () => {
+			const testInjector = createInProcessInjector();
+			testInjector.register("gadgetService", { ready: true });
+
+			runInInjectionContext(testInjector, () =>
+				registerCommand(
+					defineCommand({
+						name: "dctest-can-setup",
+						setup: () => ({
+							$gadgetService: inject<any>("gadgetService"),
+						}),
+						canExecute: (context, services) => services.$gadgetService.ready,
+						run: (): void => undefined,
+					}),
+				),
+			);
+
+			assert.isTrue(
+				await runInInjectionContext(testInjector, () =>
+					canExecuteCommand("dctest-can-setup"),
+				),
+			);
+		});
+
+		it("fails by name for a command that is not registered", async () => {
+			const testInjector = createInProcessInjector();
+
+			await assert.isRejected(
+				runInInjectionContext(testInjector, () =>
+					canExecuteCommand("dctest-can-missing"),
+				),
+				/Unknown command 'dctest-can-missing'/,
+			);
+		});
+	});
+
 	describe("positional argument specs", () => {
 		const platformCommand = (extra: any = {}) =>
 			createCommandFromDefinition(

test/stubs.ts

@@ -1335,6 +1335,13 @@ export class CommandsService implements ICommandsService {
 		return Promise.resolve();
 	}
 
+	public canExecuteCommandInProcess(
+		commandName: string,
+		commandArguments?: string[],
+	): Promise<boolean> {
+		return Promise.resolve(true);
+	}
+
 	public completeCommand(): Promise<boolean> {
 		return Promise.resolve(true);
 	}