refactor(commands): declare the project with provideProject()

Every command that needs a project called initializeProjectData() on the
process-wide project object, from a constructor, a setup or a handler,
and a command that forgot - preview - worked only when another service
had happened to initialize it first.

provideProject() contributes a COMMAND_PRECONDITIONS entry that resolves
the project the command line names before the command's setup and
arguments policy, failing with the usual "no project found" error when
there is none. The 42 commands that need a project declare it in their
providers and inject the ProjectData contract; the initializer call is
gone from all of them, along with the constructors and setups that only
existed to make it. The four commands for which a project is optional -
clean and the device file commands - resolve it behind their own check.

The gradle build-args service resolves the project of the build's
directory through the project-data service instead of initializing the
shared object.

Author: edusperoni

defining-commands.md

@@ -446,16 +446,53 @@ A handler resolves what it needs itself, at the top of its own body:
 export default defineCommand({
 	name: "widget|add",
 	arguments: "any",
+	providers: [provideProject()],
 	async run(ctx) {
 		const widgets = inject(WidgetService);
 		const projectData = inject(ProjectData);
 
-		projectData.initializeProjectData();
-		await widgets.add(ctx.args);
+		await widgets.add(ctx.args, projectData);
 	},
 });
 ```
 
+### Declaring what the command needs: `providers` and preconditions
+
+A definition may carry `providers`, added to each invocation's own injector
+next to the context, so a factory or class among them can inject the
+invocation and is built once per invocation. One token in that list is
+special: `COMMAND_PRECONDITIONS` is a multi token, and every
+`{ provide: COMMAND_PRECONDITIONS, multi: true, useValue: check }` contributes
+a **precondition** — a check on the environment the command runs in, as
+opposed to `canExecute`, which judges the arguments. Preconditions run when
+the invocation opens, in declaration order, before `setup` and before the
+arguments policy, inside the injection context, and a throw fails the
+invocation. That fixed order is the point: being outside a project is what a
+bad invocation reports first.
+
+The precondition every project command declares comes from a helper:
+
+```ts
+import { provideProject } from "../command-base";
+
+export default defineCommand({
+	name: "platform|clean",
+	providers: [provideProject()],
+	run(ctx) {
+		const projectData = inject(ProjectData); // the project the command line names
+	},
+});
+```
+
+`provideProject()` resolves the project from `--path` or the working
+directory and fails the invocation with the usual "no project found" error
+when there is none. A command that does not declare it — `doctor`, `create`,
+the `device` family — pays nothing, and a command that needs the project only
+when it is there, like `clean`, resolves it itself behind its own check. Never
+call `initializeProjectData()` from a command; declare the provider. A plugin
+adds its own preconditions the same way, with its own helper returning a
+multi provider for the token.
+
 The injection context is synchronous, so the `inject()` calls belong **above
 the first `await`** — see [Injection, and the first
 `await`](#injection-and-the-first-await). Resolve everything the handler needs
@@ -552,16 +589,12 @@ export class PlatformCleanCommand extends Command({
 	description: "Removes and adds again the selected platform.",
 	options: { frameworkPath: stringOption() },
 	arguments: "any",
+	providers: [provideProject()],
 }) {
 	private $platformCommandHelper = inject<IPlatformCommandHelper>(
 		"platformCommandHelper",
 	);
-	private $projectData = inject<IProjectData>("projectData");
-
-	constructor() {
-		super();
-		this.$projectData.initializeProjectData();
-	}
+	private $projectData = inject(ProjectData);
 
 	public async run(): Promise<void> {
 		await this.$platformCommandHelper.cleanPlatforms(
@@ -625,16 +658,14 @@ across invocations, and resolves nothing outside a running one.
 read as `this.$x`:
 
 ```ts
-export class PlatformAddCommand extends Command({ name: "platform|add" }) {
-	private $projectData = inject<IProjectData>("projectData");
+export class PlatformAddCommand extends Command({
+	name: "platform|add",
+	providers: [provideProject()],
+}) {
+	private $projectData = inject(ProjectData);
 	private $platformHelper = inject<IPlatformCommandHelper>(
 		"platformCommandHelper",
 	);
-
-	constructor() {
-		super();
-		this.$projectData.initializeProjectData();
-	}
 	// ...
 }
 ```
@@ -700,8 +731,8 @@ the registry. It claims every name the definition declares, through the
 is built by a factory on first resolution and cached.
 
 Pass providers as the second argument to add them to each invocation's child
-injector, the one `ctx.injector` names — how a definition is parameterized per
-registration:
+injector, the one `ctx.injector` names, next to the definition's own
+`providers` — how a definition is parameterized per registration:
 
 ```ts
 for (const [name, platform] of buildCommandPlatforms) {

lib/commands/add-platform.ts

@@ -1,15 +1,15 @@
-import { canExecuteCommandBase } from "./command-base";
+import { canExecuteCommandBase, provideProject } from "./command-base";
 import {
 	IPlatformCommandHelper,
 	IPlatformValidationService,
 } from "../declarations";
-import { IProjectData } from "../definitions/project";
 import {
 	Command,
 	CommandOptionsSchema,
 	stringOption,
 } from "../common/define-command";
 import { inject } from "../common/di";
+import { ProjectData } from "../contracts/project-data";
 
 const addPlatformCommandOptions = {
 	frameworkPath: stringOption(),
@@ -21,19 +21,15 @@ export class AddPlatformCommand extends Command({
 		"Configures the current project to target the selected platform.",
 	options: addPlatformCommandOptions,
 	arguments: "any",
+	providers: [provideProject()],
 }) {
 	private $platformCommandHelper = inject<IPlatformCommandHelper>(
 		"platformCommandHelper",
 	);
 	private $platformValidationService = inject<IPlatformValidationService>(
 		"platformValidationService",
 	);
-	private $projectData = inject<IProjectData>("projectData");
-
-	constructor() {
-		super();
-		this.$projectData.initializeProjectData();
-	}
+	private $projectData = inject(ProjectData);
 
 	public async canExecute(): Promise<boolean> {
 		const args = this.args;

lib/commands/appstore-list.ts

@@ -6,11 +6,12 @@ import {
 import { inject } from "../common/di";
 import { createTable } from "../common/helpers";
 import { IPlatformValidationService } from "../declarations";
-import { IProjectData } from "../definitions/project";
 import {
 	IApplePortalApplicationService,
 	IApplePortalSessionService,
 } from "../services/apple-portal/definitions";
+import { ProjectData } from "../contracts/project-data";
+import { provideProject } from "./command-base";
 
 const listiOSAppsCommandOptions = {
 	appleSessionBase64: stringOption(),
@@ -21,6 +22,7 @@ export class ListiOSAppsCommand extends Command({
 	description: "Lists the applications in App Store Connect.",
 	options: listiOSAppsCommandOptions,
 	arguments: [{ name: "appleId" }, { name: "password" }],
+	providers: [provideProject()],
 }) {
 	private $applePortalApplicationService =
 		inject<IApplePortalApplicationService>("applePortalApplicationService");
@@ -34,14 +36,9 @@ export class ListiOSAppsCommand extends Command({
 	private $platformValidationService = inject<IPlatformValidationService>(
 		"platformValidationService",
 	);
-	private $projectData = inject<IProjectData>("projectData");
+	private $projectData = inject(ProjectData);
 	private $prompter = inject<IPrompter>("prompter");
 
-	constructor() {
-		super();
-		this.$projectData.initializeProjectData();
-	}
-
 	public async run(): Promise<void> {
 		if (
 			!this.$platformValidationService.isPlatformSupportedForOS(

lib/commands/appstore-upload.ts

@@ -15,8 +15,9 @@ import {
 	IOptions,
 	IPlatformValidationService,
 } from "../declarations";
-import { IProjectData } from "../definitions/project";
 import { IApplePortalSessionService } from "../services/apple-portal/definitions";
+import { ProjectData } from "../contracts/project-data";
+import { provideProject } from "./command-base";
 
 const publishIOSCommandOptions = {
 	appleApplicationSpecificPassword: stringOption(),
@@ -33,6 +34,7 @@ export class PublishIOSCommand extends Command({
 	options: publishIOSCommandOptions,
 	// Arguments have never been rejected here, only ignored past the third.
 	arguments: "any",
+	providers: [provideProject()],
 }) {
 	private $applePortalSessionService = inject<IApplePortalSessionService>(
 		"applePortalSessionService",
@@ -50,14 +52,9 @@ export class PublishIOSCommand extends Command({
 	private $platformValidationService = inject<IPlatformValidationService>(
 		"platformValidationService",
 	);
-	private $projectData = inject<IProjectData>("projectData");
+	private $projectData = inject(ProjectData);
 	private $prompter = inject<IPrompter>("prompter");
 
-	constructor() {
-		super();
-		this.$projectData.initializeProjectData();
-	}
-
 	public canExecute(): boolean {
 		if (!this.$hostInfo.isDarwin) {
 			this.context.fail("iOS publishing is only available on macOS.", {

lib/commands/build.ts

@@ -5,6 +5,7 @@ import {
 import {
 	canExecuteCommandBase,
 	platformSigningOptions,
+	provideProject,
 	validatePlatformOptions,
 } from "./command-base";
 import { hasValidAndroidSigning } from "../common/helpers";
@@ -15,7 +16,6 @@ import {
 } from "../declarations";
 import { IBuildController, IBuildDataService } from "../definitions/build";
 import { IMigrateController } from "../definitions/migrate";
-import { IProjectData } from "../definitions/project";
 import {
 	booleanOption,
 	CommandName,
@@ -24,6 +24,7 @@ import {
 	stringOption,
 } from "../common/define-command";
 import { inject } from "../common/di";
+import { ProjectData } from "../contracts/project-data";
 
 /**
  * Which `$devicePlatformsConstants` entry a command builds for. The constants
@@ -53,6 +54,7 @@ const defineBuildCommand = <const TName extends CommandName>(
 		description: "Builds the project for the selected target platform.",
 		options: buildCommandOptions,
 		arguments: "none",
+		providers: [provideProject()],
 		async canExecute(context): Promise<boolean> {
 			const $devicePlatformsConstants =
 				inject<Mobile.IDevicePlatformsConstants>("devicePlatformsConstants");
@@ -61,14 +63,13 @@ const defineBuildCommand = <const TName extends CommandName>(
 			const $platformValidationService = inject<IPlatformValidationService>(
 				"platformValidationService",
 			);
-			const $projectData = inject<IProjectData>("projectData");
+			const $projectData = inject(ProjectData);
 			const platform = $devicePlatformsConstants[buildPlatform];
 			const isAndroid = $devicePlatformsConstants.isAndroid(platform);
 			// Only the android build checks the runtime version.
 			const $androidBundleValidatorHelper = isAndroid
 				? inject<IAndroidBundleValidatorHelper>("androidBundleValidatorHelper")
 				: null;
-			$projectData.initializeProjectData();
 
 			if (!context.options.force) {
 				await $migrateController.validate({
@@ -112,10 +113,9 @@ const defineBuildCommand = <const TName extends CommandName>(
 				inject<Mobile.IDevicePlatformsConstants>("devicePlatformsConstants");
 			const $logger = inject<ILogger>("logger");
 			const $options = inject<IOptions>("options");
-			const $projectData = inject<IProjectData>("projectData");
+			const $projectData = inject(ProjectData);
 			const platform = $devicePlatformsConstants[buildPlatform];
 			const isAndroid = $devicePlatformsConstants.isAndroid(platform);
-			$projectData.initializeProjectData();
 
 			const buildData = $buildDataService.getBuildData(
 				$projectData.projectDir,

lib/commands/clean.ts

@@ -18,13 +18,13 @@ import {
 	IProjectCleanupResult,
 	IProjectCleanupService,
 	IProjectConfigService,
-	IProjectData,
 	IProjectService,
 } from "../definitions/project";
 import {
 	ITerminalSpinner,
 	ITerminalSpinnerService,
 } from "../definitions/terminal-spinner-service";
+import { ProjectData } from "../contracts/project-data";
 
 function bytesToHumanReadable(bytes: number): string {
 	const units = ["B", "KB", "MB", "GB", "TB"];
@@ -323,7 +323,6 @@ export const cleanCommandDefinition = defineCommand({
 		const $projectConfigService = inject<IProjectConfigService>(
 			"projectConfigService",
 		);
-		const $projectData = inject<IProjectData>("projectData");
 		const $projectService = inject<IProjectService>("projectService");
 		const $terminalSpinnerService = inject<ITerminalSpinnerService>(
 			"terminalSpinnerService",
@@ -340,6 +339,11 @@ export const cleanCommandDefinition = defineCommand({
 			return cleanMultipleProjects(context, spinner);
 		}
 
+		// The project is optional: outside one the command cleans the projects
+		// below, so it is resolved behind the check rather than declared.
+		const $projectData = inject(ProjectData);
+		$projectData.initializeProjectData();
+
 		spinner.start("Cleaning project...\n");
 
 		let pathsToClean = [

lib/commands/command-base.ts

@@ -11,7 +11,13 @@ import {
 	CommandOptionsSchema,
 	objectOption,
 } from "../common/define-command";
-import { Injector } from "../common/di";
+import { Injector, inject } from "../common/di";
+import type { Provider } from "../common/di/providers";
+import { ProjectData } from "../contracts/project-data";
+import {
+	COMMAND_PRECONDITIONS,
+	CommandPrecondition,
+} from "../common/contracts/command-preconditions";
 
 /**
  * The CLI-wide signing options `validatePlatformOptions` checks. A command
@@ -31,17 +37,36 @@ type PlatformSigningContext = Pick<
 >;
 
 /**
- * The declarative form of `$platformCommandParameter`. Initializing the
- * project data is what makes the platform check possible, so it stays part of
- * validating the argument instead of moving to the command's own handlers,
- * which the adapter runs only after argument enforcement.
+ * Declares that a command runs inside a project: the project the command line
+ * names, through `--path` or the working directory, is resolved before the
+ * command's setup and arguments policy, and its absence fails the invocation
+ * with the "no project found" error. `inject(ProjectData)` then reads it.
+ */
+export function provideProject(): Provider {
+	return {
+		provide: COMMAND_PRECONDITIONS,
+		multi: true,
+		useValue: requireProject,
+	};
+}
+
+const requireProject: CommandPrecondition = () => {
+	const projectData = inject<IProjectData>("projectData");
+	if (typeof projectData.initializeProjectData === "function") {
+		projectData.initializeProjectData();
+	}
+};
+
+/**
+ * The declarative form of `$platformCommandParameter`. The command declares
+ * `provideProject()`, so resolving the project here is what makes the
+ * platform check possible before the command's own handlers run.
  */
 export function validatePlatformArgument(
 	targetInjector: Injector,
 	platform: string,
 ): void {
-	const projectData = targetInjector.get<IProjectData>("projectData");
-	projectData.initializeProjectData();
+	const projectData = targetInjector.get(ProjectData);
 	targetInjector
 		.get<IPlatformValidationService>("platformValidationService")
 		.validatePlatform(platform, projectData);
@@ -60,7 +85,7 @@ export function validatePlatformOptions(
 	context: PlatformSigningContext,
 	platform: string,
 ): Promise<boolean> {
-	const $projectData = context.injector.get<IProjectData>("projectData");
+	const $projectData = context.injector.get(ProjectData);
 
 	return context.injector
 		.get<IPlatformValidationService>("platformValidationService")
@@ -78,7 +103,7 @@ async function validatePlatformBase(
 	notConfiguredEnvOptions: INotConfiguredEnvOptions,
 ): Promise<IValidatePlatformOutput> {
 	const $options = context.injector.get<IOptions>("options");
-	const $projectData = context.injector.get<IProjectData>("projectData");
+	const $projectData = context.injector.get(ProjectData);
 	const platformData = context.injector
 		.get<IPlatformsDataService>("platformsDataService")
 		.getPlatformData(platform, $projectData);