feat(di): add contracts for the core service tranche

Twelve services gain a typed token: Logger, Errors, FileSystem,
ChildProcess, HostInfo, HttpClient, TempService, Prompter, ProjectData,
ProjectDataService, PackageManager and DevicesService. Resolution is
class-first with a fallback to the token's registry name, so each
contract is an alias over the existing registration - no implementation
or registration changes.

The contracts entry point stays side-effect-free: every import but the
Contract decorator itself is type-only, so an extension carrying a
duplicated CLI copy cannot boot a second runtime by loading it.

Author: edusperoni

dependency-injection.md

@@ -258,12 +258,31 @@ import { inject, DoctorService } from "nativescript/contracts";
 Available contracts
 -------------------
 
-The first tranche, growing as services migrate:
+Growing as services migrate. Every token below is a typed alias onto the
+registration it names — resolving by token and resolving by the legacy name
+return the same instance.
+
+The contract is also the single source of truth for the service's shape: the
+ambient interface the CLI has always published extends it (`interface ILogger
+extends Logger {}`), so the two cannot drift apart. Add a member to the
+contract and every existing caller sees it.
 
 | Token | Legacy name |
 |---|---|
+| `ChildProcess` | `childProcess` |
+| `DevicesService` | `devicesService` |
 | `DoctorService` | `doctorService` |
+| `Errors` | `errors` |
+| `FileSystem` | `fs` |
+| `HostInfo` | `hostInfo` |
+| `HttpClient` | `httpClient` |
+| `Logger` | `logger` |
+| `PackageManager` | `packageManager` |
+| `ProjectData` | `projectData` |
+| `ProjectDataService` | `projectDataService` |
 | `ProjectNameService` | `projectNameService` |
+| `Prompter` | `prompter` |
+| `TempService` | `tempService` |
 
 Related guides
 --------------

lib/contracts/child-process.ts

@@ -0,0 +1,78 @@
+import { Contract } from "../common/di/contract";
+import type * as child_process from "child_process";
+import type {
+	IExecOptions,
+	ISpawnFromEventOptions,
+	ISpawnResult,
+} from "../common/declarations";
+
+/**
+ * Promise-based wrapper around Node's `child_process` module.
+ */
+@Contract({ name: "childProcess" })
+export abstract class ChildProcess {
+	abstract exec(
+		command: string,
+		options?: any,
+		execOptions?: IExecOptions,
+	): Promise<any>;
+
+	abstract execFile<T>(command: string, args: string[]): Promise<T>;
+
+	abstract spawn(
+		command: string,
+		args?: string[],
+		options?: any,
+	): child_process.ChildProcess;
+
+	abstract spawnFromEvent(
+		command: string,
+		args: string[],
+		event: string,
+		options?: any,
+		spawnFromEventOptions?: ISpawnFromEventOptions,
+	): Promise<ISpawnResult>;
+
+	abstract trySpawnFromCloseEvent(
+		command: string,
+		args: string[],
+		options?: any,
+		spawnFromEventOptions?: ISpawnFromEventOptions,
+	): Promise<ISpawnResult>;
+
+	abstract tryExecuteApplication(
+		command: string,
+		args: string[],
+		event: string,
+		errorMessage: string,
+		condition?: (childProcess: any) => boolean,
+	): Promise<any>;
+
+	/**
+	 * This is a special case of the child_process.spawn() functionality for spawning Node.js processes.
+	 * In addition to having all the methods in a normal ChildProcess instance, the returned object has a communication channel built-in.
+	 * Note: Unlike the fork() POSIX system call, child_process.fork() does not clone the current process.
+	 * @param {string} modulePath String The module to run in the child
+	 * @param {string[]} args Array List of string arguments You can access them in the child with 'process.argv'.
+	 * @param {string} options Object
+	 * @return {child_process} ChildProcess object.
+	 */
+	abstract fork(
+		modulePath: string,
+		args?: string[],
+		options?: {
+			cwd?: string;
+			env?: any;
+			execPath?: string;
+			execArgv?: string[];
+			silent?: boolean;
+			uid?: number;
+			gid?: number;
+		},
+	): any;
+}
+
+// The event-emitter surface is merged in rather than inherited: `extends
+// EventEmitter` would need a runtime import, and everything reachable from
+// lib/contracts must stay side-effect-free.
+export interface ChildProcess extends NodeJS.EventEmitter {}

lib/contracts/devices-service.ts

@@ -0,0 +1,176 @@
+import { Contract } from "../common/di/contract";
+import type { IAppInstalledInfo } from "../common/declarations";
+
+/**
+ * The EventEmitter surface is merged in rather than redeclared as abstract
+ * members: the contract must stay free of runtime imports, so it cannot extend
+ * `EventEmitter`, and merging keeps the signatures (including the `this`
+ * returns) tied to the ambient definition instead of a hand-copied snapshot.
+ */
+export interface DevicesService extends NodeJS.EventEmitter {}
+
+/**
+ * Discovers connected devices and emulators and executes actions against them.
+ */
+@Contract({ name: "devicesService" })
+export abstract class DevicesService {
+	/** The platform the service has been initialized for. */
+	abstract platform: string;
+
+	/** Whether any device matching the current initialization options is attached. */
+	abstract hasDevices: boolean;
+
+	/** The number of devices matching the current initialization options. */
+	abstract deviceCount: number;
+
+	abstract execute<T>(
+		action: (device: Mobile.IDevice) => Promise<T>,
+		canExecute?: (dev: Mobile.IDevice) => boolean,
+		options?: { allowNoDevices?: boolean },
+	): Promise<Mobile.IDeviceActionResult<T>[]>;
+
+	/**
+	 * Initializes DevicesService, so after that device operations could be executed.
+	 * @param {IDevicesServicesInitializationOptions} data Defines the options which will be used for whole devicesService.
+	 * @return {Promise<void>}
+	 */
+	abstract initialize(
+		data?: Mobile.IDevicesServicesInitializationOptions,
+	): Promise<void>;
+
+	/**
+	 * Add an IDeviceDiscovery instance which will from now on report devices. The instance should implement IDeviceDiscovery and raise "deviceFound" and "deviceLost" events.
+	 * @param {IDeviceDiscovery} deviceDiscovery Instance, implementing IDeviceDiscovery and raising raise "deviceFound" and "deviceLost" events.
+	 * @return {void}
+	 */
+	abstract addDeviceDiscovery(deviceDiscovery: Mobile.IDeviceDiscovery): void;
+
+	abstract getDevices(): Mobile.IDeviceInfo[];
+
+	/**
+	 * Gets device instance by specified identifier or number.
+	 * @param {string} deviceOption The specified device identifier or number.
+	 * @returns {Promise<Mobile.IDevice>} Instance of IDevice.
+	 */
+	abstract getDevice(deviceOption: string): Promise<Mobile.IDevice>;
+
+	abstract getDevicesForPlatform(platform: string): Mobile.IDevice[];
+
+	abstract getDeviceInstances(): Mobile.IDevice[];
+
+	abstract getDeviceByDeviceOption(): Mobile.IDevice;
+
+	abstract isAndroidDevice(device: Mobile.IDevice): boolean;
+
+	abstract isiOSDevice(device: Mobile.IDevice): boolean;
+
+	abstract isiOSSimulator(device: Mobile.IDevice): boolean;
+
+	abstract isOnlyiOSSimultorRunning(): boolean;
+
+	abstract isAppInstalledOnDevices(
+		deviceIdentifiers: string[],
+		appIdentifier: string,
+		framework: string,
+		projectDir: string,
+	): Promise<IAppInstalledInfo>[];
+
+	abstract setLogLevel(logLevel: string, deviceIdentifier?: string): void;
+
+	abstract deployOnDevices(
+		deviceIdentifiers: string[],
+		packageFile: string,
+		packageName: string,
+		framework: string,
+		projectDir: string,
+	): Promise<void>[];
+
+	abstract getDeviceByIdentifier(identifier: string): Mobile.IDevice;
+
+	abstract mapAbstractToTcpPort(
+		deviceIdentifier: string,
+		appIdentifier: string,
+		framework: string,
+	): Promise<string>;
+
+	abstract getDebuggableApps(
+		deviceIdentifiers: string[],
+	): Promise<Mobile.IDeviceApplicationInformation[]>[];
+
+	abstract getDebuggableViews(
+		deviceIdentifier: string,
+		appIdentifier: string,
+	): Promise<Mobile.IDebugWebViewInfo[]>;
+
+	/**
+	 * Returns all applications installed on the specified device.
+	 * @param {string} deviceIdentifer The identifier of the device for which to get installed applications.
+	 * @returns {Promise<string[]>} Array of all application identifiers of the apps installed on device.
+	 */
+	abstract getInstalledApplications(
+		deviceIdentifier: string,
+	): Promise<string[]>;
+
+	/**
+	 * Returns all available iOS and/or Android emulators.
+	 * @param options The options that can be passed to filter the result.
+	 * @returns {Promise<Mobile.IListEmulatorsOutput>} Dictionary with the following format: { ios: { devices: Mobile.IDeviceInfo[], errors: string[] }, android: { devices: Mobile.IDeviceInfo[], errors: string[]}}.
+	 */
+	abstract getEmulatorImages(
+		options?: Mobile.IListEmulatorsOptions,
+	): Promise<Mobile.IListEmulatorsOutput>;
+
+	/**
+	 * Starts an emulator by provided options.
+	 * @param options
+	 * @returns {Promise<string[]>} - Returns array of errors.
+	 */
+	abstract startEmulator(
+		options?: Mobile.IStartEmulatorOptions,
+	): Promise<string[]>;
+
+	/**
+	 * Starts polling for attached devices, raising the deviceFound/deviceLost
+	 * events as the set of attached devices changes. Calling it while a poll
+	 * is already running is a no-op.
+	 * @param {Mobile.IDeviceLookingOptions} deviceInitOpts Options describing which devices to look for and how often to poll.
+	 * @returns {void}
+	 */
+	abstract startDeviceDetectionInterval(
+		deviceInitOpts?: Mobile.IDeviceLookingOptions,
+	): void;
+
+	/**
+	 * Stops the poll started by startDeviceDetectionInterval.
+	 * @returns {void}
+	 */
+	abstract stopDeviceDetectionInterval(): void;
+
+	/**
+	 * Starts polling for available emulator images, raising the
+	 * emulatorImageFound/emulatorImageLost events as the set changes.
+	 * @param {Mobile.IHasDetectionInterval} opts Options describing how often to poll.
+	 * @returns {void}
+	 */
+	abstract startEmulatorDetectionInterval(
+		opts?: Mobile.IHasDetectionInterval,
+	): void;
+
+	/**
+	 * Stops the poll started by startEmulatorDetectionInterval.
+	 * @returns {void}
+	 */
+	abstract stopEmulatorDetectionInterval(): void;
+
+	/**
+	 * Returns a single device based on the specified options. If more than one devices are matching,
+	 * prompts the user for a manual choice or returns the first one for non interactive terminals.
+	 */
+	abstract pickSingleDevice(
+		options: Mobile.IPickSingleDeviceOptions,
+	): Promise<Mobile.IDevice>;
+
+	abstract getPlatformsFromDeviceDescriptors(
+		deviceDescriptors: ILiveSyncDeviceDescriptor[],
+	): string[];
+}

lib/contracts/errors.ts

@@ -0,0 +1,33 @@
+import { Contract } from "../common/di/contract";
+import type { IFailOptions } from "../common/declarations";
+
+/**
+ * Raises CLI failures and wraps command execution so they are reported and
+ * turned into a process exit code.
+ */
+@Contract({ name: "errors" })
+export abstract class Errors {
+	abstract fail(formatStr: string, ...args: any[]): never;
+	abstract fail(opts: IFailOptions, ...args: any[]): never;
+
+	/**
+	 * @deprecated use `fail` instead
+	 */
+	abstract failWithoutHelp(message: string, ...args: any[]): never;
+	/**
+	 * @deprecated use `fail` instead
+	 */
+	abstract failWithoutHelp(opts: IFailOptions, ...args: any[]): never;
+
+	abstract failWithHelp(formatStr: string, ...args: any[]): never;
+	abstract failWithHelp(opts: IFailOptions, ...args: any[]): never;
+
+	abstract beginCommand(
+		action: () => Promise<boolean>,
+		printCommandHelp: () => Promise<void>,
+	): Promise<boolean>;
+
+	abstract verifyHeap(message: string): void;
+
+	abstract printCallStack: boolean;
+}