refactor(commands): infer command services from setup

A command's services type is now read off its setup function with
ReturnType instead of being declared beside it and kept in sync by hand.

Author: edusperoni

defining-commands.md

@@ -169,11 +169,11 @@ options: {
 
 So a redeclaration of the same name with the same type is silent. What the CLI
 still warns about at registration is a redeclaration that changes what the
-spelling *means*:
+spelling _means_:
 
 - a declared option whose name matches a CLI-wide one but whose type differs —
   `verbose: stringOption()` against the CLI's boolean `--verbose`;
-- an alias that belongs to a *different* CLI-wide option — `output:
+- an alias that belongs to a _different_ CLI-wide option — `output:
 stringOption({ alias: "p" })` steals `--path`'s shorthand. Restating an
   option's own shorthand (`path: stringOption({ alias: "p" })`) is fine.
 
@@ -449,6 +449,40 @@ top of `run`; nothing else changes. "Once per invocation" means once across
 `canExecute`, `run` and `postRun` together — whichever of them the CLI reaches
 first triggers it, and the rest reuse the value.
 
+When several commands share a setup, or a helper outside the definition takes
+the services as a parameter, lift it into a named function and derive the type
+from it instead of writing the shape out by hand:
+
+```ts
+export function setupWidgetAddCommand() {
+	const projectData = inject(ProjectData);
+	projectData.initializeProjectData();
+	return { projectData, widgets: inject(WidgetService) };
+}
+export type IWidgetAddCommandServices = ReturnType<
+	typeof setupWidgetAddCommand
+>;
+
+export function canAddWidget(services: IWidgetAddCommandServices): boolean {
+	return !!services.projectData.projectDir;
+}
+
+export default defineCommand({
+	name: "widget|add",
+	arguments: "any",
+	setup: setupWidgetAddCommand,
+	canExecute: (ctx, services) => canAddWidget(services),
+	async run(ctx, { widgets }) {
+		await widgets.add(ctx.args);
+	},
+});
+```
+
+Leave the setup function's return type off: the alias reads what the body
+infers, so annotating the function with the alias makes the pair circular. Read
+a setup curried over a parameter — `setupX(platform)` returning the setup
+itself — through its inner function, `ReturnType<ReturnType<typeof setupX>>`.
+
 `run`'s return value, and `postRun`
 -----------------------------------
 
@@ -504,7 +538,7 @@ all — or the definition itself, which it defines on your behalf, so registerin
 a command is one call. Either way the definition is validated before it reaches
 the registry. It claims every name the definition declares, through the
 `CommandRegistry` the target injector provides, and returns a
-`DeferredCommandResult` — see *The owner is ambient* below. The command instance
+`DeferredCommandResult` — see _The owner is ambient_ below. The command instance
 is built by a factory on first resolution and cached.
 
 Pass providers as the second argument to scope the command to a child injector
@@ -523,7 +557,7 @@ That is how one definition serves several commands that differ only in data —
 the platform each one targets — instead of one command subclassing another.
 
 **Which injector it registers against is not a parameter.** It is the injector
-of the current injection context — see *The owner is ambient* below — and the
+of the current injection context — see _The owner is ambient_ below — and the
 CLI's own injector outside one. To register against some other injector, run
 the call in its context:
 
@@ -722,16 +756,16 @@ A definition is compiled into an ordinary `ICommand`, so nothing downstream —
 the registry, the router, hooks, help, analytics — knows the difference. The
 mapping is:
 
-| Definition                        | `ICommand`                                          |
-| --------------------------------- | --------------------------------------------------- |
-| `options`                         | `dashedOptions`                                     |
-| `run`                             | `execute`, wrapped in an injection context          |
-| `arguments`, `canExecute`         | `canExecute`: policy enforced, then the refinement  |
-| `setup`                           | — run inside `canExecute`/`execute`, memoised       |
-| `postRun`                         | `postCommandAction`, with `run`'s return value      |
-| `allowUnknownOptions`             | `skipOptionsValidation`                             |
-| —                                 | `allowedParameters`, always `[]`                    |
-| `disableAnalytics`, `enableHooks` | passed through unchanged                            |
+| Definition                        | `ICommand`                                         |
+| --------------------------------- | -------------------------------------------------- |
+| `options`                         | `dashedOptions`                                    |
+| `run`                             | `execute`, wrapped in an injection context         |
+| `arguments`, `canExecute`         | `canExecute`: policy enforced, then the refinement |
+| `setup`                           | — run inside `canExecute`/`execute`, memoised      |
+| `postRun`                         | `postCommandAction`, with `run`'s return value     |
+| `allowUnknownOptions`             | `skipOptionsValidation`                            |
+| —                                 | `allowedParameters`, always `[]`                   |
+| `disableAnalytics`, `enableHooks` | passed through unchanged                           |
 
 The compiled command always exposes `canExecute`, because `CommandsService`
 stops consulting `allowedParameters` as soon as a command has one — the adapter

lib/commands/add-platform.ts

@@ -1,7 +1,6 @@
 import {
 	canExecuteCommandBase,
 	injectPlatformCommandServices,
-	IPlatformCommandServices,
 } from "./command-base";
 import { IPlatformCommandHelper } from "../declarations";
 import { IErrors } from "../common/declarations";
@@ -21,12 +20,7 @@ export type AddPlatformCommandContext = CommandContext<
 	typeof addPlatformCommandOptions
 >;
 
-export interface IAddPlatformCommandServices extends IPlatformCommandServices {
-	$errors: IErrors;
-	$platformCommandHelper: IPlatformCommandHelper;
-}
-
-export function setupAddPlatformCommand(): IAddPlatformCommandServices {
+export function setupAddPlatformCommand() {
 	const services = {
 		...injectPlatformCommandServices(),
 		$errors: inject<IErrors>("errors"),
@@ -39,6 +33,10 @@ export function setupAddPlatformCommand(): IAddPlatformCommandServices {
 	return services;
 }
 
+export type IAddPlatformCommandServices = ReturnType<
+	typeof setupAddPlatformCommand
+>;
+
 export async function canExecuteAddPlatformCommand(
 	context: AddPlatformCommandContext,
 	services: IAddPlatformCommandServices,

lib/commands/apple-login.ts

@@ -5,14 +5,7 @@ import { IApplePortalSessionService } from "../services/apple-portal/definitions
 
 export type AppleLoginCommandContext = CommandContext;
 
-export interface IAppleLoginCommandServices {
-	$applePortalSessionService: IApplePortalSessionService;
-	$errors: IErrors;
-	$logger: ILogger;
-	$prompter: IPrompter;
-}
-
-export function setupAppleLoginCommand(): IAppleLoginCommandServices {
+export function setupAppleLoginCommand() {
 	return {
 		$applePortalSessionService: inject<IApplePortalSessionService>(
 			"applePortalSessionService",
@@ -23,6 +16,10 @@ export function setupAppleLoginCommand(): IAppleLoginCommandServices {
 	};
 }
 
+export type IAppleLoginCommandServices = ReturnType<
+	typeof setupAppleLoginCommand
+>;
+
 export async function runAppleLoginCommand(
 	context: AppleLoginCommandContext,
 	services: IAppleLoginCommandServices,

lib/commands/appstore-list.ts

@@ -22,18 +22,7 @@ export type ListiOSAppsCommandContext = CommandContext<
 	typeof listiOSAppsCommandOptions
 >;
 
-export interface IListiOSAppsCommandServices {
-	$applePortalApplicationService: IApplePortalApplicationService;
-	$applePortalSessionService: IApplePortalSessionService;
-	$devicePlatformsConstants: Mobile.IDevicePlatformsConstants;
-	$errors: IErrors;
-	$logger: ILogger;
-	$platformValidationService: IPlatformValidationService;
-	$projectData: IProjectData;
-	$prompter: IPrompter;
-}
-
-export function setupListiOSAppsCommand(): IListiOSAppsCommandServices {
+export function setupListiOSAppsCommand() {
 	const services = {
 		$applePortalApplicationService: inject<IApplePortalApplicationService>(
 			"applePortalApplicationService",
@@ -57,6 +46,10 @@ export function setupListiOSAppsCommand(): IListiOSAppsCommandServices {
 	return services;
 }
 
+export type IListiOSAppsCommandServices = ReturnType<
+	typeof setupListiOSAppsCommand
+>;
+
 export async function runListiOSAppsCommand(
 	context: ListiOSAppsCommandContext,
 	services: IListiOSAppsCommandServices,

lib/commands/appstore-upload.ts

@@ -32,21 +32,7 @@ export type PublishIOSCommandContext = CommandContext<
 	typeof publishIOSCommandOptions
 >;
 
-export interface IPublishIOSCommandServices {
-	$applePortalSessionService: IApplePortalSessionService;
-	$buildController: BuildController;
-	$devicePlatformsConstants: Mobile.IDevicePlatformsConstants;
-	$errors: IErrors;
-	$hostInfo: IHostInfo;
-	$itmsTransporterService: IITMSTransporterService;
-	$logger: ILogger;
-	$options: IOptions;
-	$platformValidationService: IPlatformValidationService;
-	$projectData: IProjectData;
-	$prompter: IPrompter;
-}
-
-export function setupPublishIOSCommand(): IPublishIOSCommandServices {
+export function setupPublishIOSCommand() {
 	const services = {
 		$applePortalSessionService: inject<IApplePortalSessionService>(
 			"applePortalSessionService",
@@ -73,6 +59,10 @@ export function setupPublishIOSCommand(): IPublishIOSCommandServices {
 	return services;
 }
 
+export type IPublishIOSCommandServices = ReturnType<
+	typeof setupPublishIOSCommand
+>;
+
 export function canExecutePublishIOSCommand(
 	context: PublishIOSCommandContext,
 	services: IPublishIOSCommandServices,

lib/commands/build.ts

@@ -5,7 +5,6 @@ import {
 import {
 	canExecuteCommandBase,
 	injectPlatformCommandServices,
-	IPlatformCommandServices,
 	validatePlatformOptions,
 } from "./command-base";
 import { hasValidAndroidSigning } from "../common/helpers";
@@ -40,17 +39,6 @@ const buildCommandOptions = {
 	keyStoreAliasPassword: stringOption(),
 } satisfies CommandOptionsSchema;
 
-interface IBuildCommandServices extends IPlatformCommandServices {
-	platform: string;
-	isAndroid: boolean;
-	$errors: IErrors;
-	$logger: ILogger;
-	$buildController: IBuildController;
-	$buildDataService: IBuildDataService;
-	$migrateController: IMigrateController;
-	$androidBundleValidatorHelper: IAndroidBundleValidatorHelper;
-}
-
 const defineBuildCommand = <const TName extends CommandName>(
 	name: TName,
 	buildPlatform: BuildPlatform,
@@ -60,7 +48,7 @@ const defineBuildCommand = <const TName extends CommandName>(
 		description: "Builds the project for the selected target platform.",
 		options: buildCommandOptions,
 		arguments: "none",
-		setup(): IBuildCommandServices {
+		setup() {
 			const devicePlatformsConstants = inject<Mobile.IDevicePlatformsConstants>(
 				"devicePlatformsConstants",
 			);

lib/commands/clean.ts

@@ -88,19 +88,7 @@ const cleanCommandOptions = {
 
 export type CleanCommandContext = CommandContext<typeof cleanCommandOptions>;
 
-export interface ICleanCommandServices {
-	$childProcess: IChildProcess;
-	$logger: ILogger;
-	$projectCleanupService: IProjectCleanupService;
-	$projectConfigService: IProjectConfigService;
-	$projectData: IProjectData;
-	$projectService: IProjectService;
-	$prompter: IPrompter;
-	$staticConfig: IStaticConfig;
-	$terminalSpinnerService: ITerminalSpinnerService;
-}
-
-export function setupCleanCommand(): ICleanCommandServices {
+export function setupCleanCommand() {
 	return {
 		$childProcess: inject<IChildProcess>("childProcess"),
 		$logger: inject<ILogger>("logger"),
@@ -120,6 +108,8 @@ export function setupCleanCommand(): ICleanCommandServices {
 	};
 }
 
+export type ICleanCommandServices = ReturnType<typeof setupCleanCommand>;
+
 async function getNSProjectPathsInDirectory(
 	services: ICleanCommandServices,
 	dir = process.cwd(),

lib/commands/command-base.ts

@@ -9,20 +9,8 @@ import {
 import { ArgumentSpec } from "../common/define-command";
 import { inject, Injector } from "../common/di";
 
-/**
- * What the platform-validation helpers below need. A command definition's
- * `setup` returns this shape (see `injectPlatformCommandServices`), so its
- * result can be handed straight to them.
- */
-export interface IPlatformCommandServices {
-	$options: IOptions;
-	$platformsDataService: IPlatformsDataService;
-	$platformValidationService: IPlatformValidationService;
-	$projectData: IProjectData;
-}
-
 /** Callable from `setup` and from `canExecute` before their first `await`. */
-export function injectPlatformCommandServices(): IPlatformCommandServices {
+export function injectPlatformCommandServices() {
 	return {
 		$options: inject<IOptions>("options"),
 		$platformsDataService: inject<IPlatformsDataService>(
@@ -35,6 +23,15 @@ export function injectPlatformCommandServices(): IPlatformCommandServices {
 	};
 }
 
+/**
+ * What the platform-validation helpers below need. A command definition's
+ * `setup` returns this shape (see `injectPlatformCommandServices`), so its
+ * result can be handed straight to them.
+ */
+export type IPlatformCommandServices = ReturnType<
+	typeof injectPlatformCommandServices
+>;
+
 /**
  * The declarative form of `$platformCommandParameter`. Initializing the
  * project data is what makes the platform check possible, so it stays part of

lib/commands/config.ts

@@ -5,13 +5,7 @@ import { CommandContext, defineCommand } from "../common/define-command";
 import { inject } from "../common/di";
 import { color } from "../color";
 
-export interface IConfigCommandServices {
-	$projectConfigService: IProjectConfigService;
-	$logger: ILogger;
-	$errors: IErrors;
-}
-
-export function injectConfigCommandServices(): IConfigCommandServices {
+export function injectConfigCommandServices() {
 	return {
 		$projectConfigService: inject<IProjectConfigService>(
 			"projectConfigService",
@@ -21,6 +15,10 @@ export function injectConfigCommandServices(): IConfigCommandServices {
 	};
 }
 
+export type IConfigCommandServices = ReturnType<
+	typeof injectConfigCommandServices
+>;
+
 function getValueString(value: SupportedConfigValues, depth = 0): string {
 	const indent = () => "  ".repeat(depth);
 	if (typeof value === "object") {

lib/commands/create-project.ts

@@ -53,20 +53,18 @@ export type CreateProjectCommandContext = CommandContext<
 	typeof createProjectCommandOptions
 >;
 
-export interface ICreateProjectCommandServices {
-	$projectService: IProjectService;
-	$logger: ILogger;
-	$prompter: IPrompter;
-}
-
-export function setupCreateProjectCommand(): ICreateProjectCommandServices {
+export function setupCreateProjectCommand() {
 	return {
 		$projectService: inject<IProjectService>("projectService"),
 		$logger: inject<ILogger>("logger"),
 		$prompter: inject<IPrompter>("prompter"),
 	};
 }
 
+export type ICreateProjectCommandServices = ReturnType<
+	typeof setupCreateProjectCommand
+>;
+
 interface ITemplateChoice {
 	key?: string;
 	value: string;