run-controller.ts

import { HmrConstants, DeviceDiscoveryEventNames } from "../common/constants";
import {
	PREPARE_READY_EVENT_NAME,
	TrackActionNames,
	DEBUGGER_DETACHED_EVENT_NAME,
	RunOnDeviceEvents,
	USER_INTERACTION_NEEDED_EVENT_NAME,
} from "../constants";
import { cache, performanceLog } from "../common/decorators";
import { EventEmitter } from "events";
import * as util from "util";
import * as _ from "lodash";
import { IProjectDataService, IProjectData } from "../definitions/project";
import { IBuildController } from "../definitions/build";
import { IPlatformsDataService } from "../definitions/platform";
import { IDebugController } from "../definitions/debug";
import { IPluginsService } from "../definitions/plugins";
import {
	IAnalyticsService,
	IErrors,
	IHooksService,
	IDictionary,
} from "../common/declarations";
import { IInjector } from "../common/definitions/yok";
import { injector } from "../common/yok";

export class RunController extends EventEmitter implements IRunController {
	private prepareReadyEventHandler: any = null;
	private _syncInProgress = false;
	private _pendingSyncs: Map<
		string,
		{
			data: IFilesChangeEventData;
			projectData: IProjectData;
			liveSyncInfo: ILiveSyncInfo;
		}
	> = new Map();

	constructor(
		protected $analyticsService: IAnalyticsService,
		private $buildController: IBuildController,
		private $debugController: IDebugController,
		private $deviceInstallAppService: IDeviceInstallAppService,
		protected $devicesService: Mobile.IDevicesService,
		protected $errors: IErrors,
		protected $injector: IInjector,
		private $hmrStatusService: IHmrStatusService,
		public $hooksService: IHooksService,
		private $liveSyncServiceResolver: ILiveSyncServiceResolver,
		private $liveSyncProcessDataService: ILiveSyncProcessDataService,
		protected $logger: ILogger,
		protected $mobileHelper: Mobile.IMobileHelper,
		private $platformsDataService: IPlatformsDataService,
		private $pluginsService: IPluginsService,
		private $prepareController: IPrepareController,
		private $prepareDataService: IPrepareDataService,
		private $prepareNativePlatformService: IPrepareNativePlatformService,
		private $projectChangesService: IProjectChangesService,
		protected $projectDataService: IProjectDataService,
		private $staticConfig: Config.IStaticConfig,
	) {
		super();
	}

	public async run(runData: IRunData): Promise<void> {
		const { liveSyncInfo, deviceDescriptors } = runData;
		const { projectDir } = liveSyncInfo;

		const projectData = this.$projectDataService.getProjectData(projectDir);
		await this.initializeSetup(projectData);

		const deviceDescriptorsForInitialSync =
			this.getDeviceDescriptorsForInitialSync(projectDir, deviceDescriptors);
		const newPlatforms =
			this.$devicesService.getPlatformsFromDeviceDescriptors(deviceDescriptors);
		const oldPlatforms =
			this.$liveSyncProcessDataService.getPlatforms(projectDir);
		const platforms = _.uniq(_.concat(newPlatforms, oldPlatforms));

		this.$liveSyncProcessDataService.persistData(
			projectDir,
			deviceDescriptors,
			platforms,
		);

		const shouldStartWatcher =
			!liveSyncInfo.skipWatcher &&
			this.$liveSyncProcessDataService.hasDeviceDescriptors(projectDir);
		if (shouldStartWatcher && liveSyncInfo.useHotModuleReload) {
			this.$hmrStatusService.attachToHmrStatusEvent();
		}

		if (!this.prepareReadyEventHandler) {
			const handler = async (data: IFilesChangeEventData) => {
				if (data.hasNativeChanges) {
					const platformData = this.$platformsDataService.getPlatformData(
						data.platform,
						projectData,
					);
					const prepareData = this.$prepareDataService.getPrepareData(
						liveSyncInfo.projectDir,
						data.platform,
						{ ...liveSyncInfo, watch: !liveSyncInfo.skipWatcher },
					);
					const changesInfo = await this.$projectChangesService.checkForChanges(
						platformData,
						projectData,
						prepareData,
					);
					if (!changesInfo.hasChanges) {
						return;
					}
				}
				this.scheduleSyncOnDevices(data, projectData, liveSyncInfo);
			};

			this.prepareReadyEventHandler = handler.bind(this);
			this.$prepareController.on(
				PREPARE_READY_EVENT_NAME,
				this.prepareReadyEventHandler,
			);
		}
		await this.syncInitialDataOnDevices(
			projectData,
			liveSyncInfo,
			deviceDescriptorsForInitialSync,
		);

		this.attachDeviceLostHandler();
	}

	public async stop(data: IStopRunData): Promise<void> {
		const { projectDir, deviceIdentifiers, stopOptions } = data;
		const liveSyncProcessInfo =
			this.$liveSyncProcessDataService.getPersistedData(projectDir);
		if (liveSyncProcessInfo && !liveSyncProcessInfo.isStopped) {
			// In case we are coming from error during livesync, the current action is the one that erred (but we are still executing it),
			// so we cannot await it as this will cause infinite loop.
			const shouldAwaitPendingOperation =
				!stopOptions || stopOptions.shouldAwaitAllActions;

			const deviceIdentifiersToRemove =
				deviceIdentifiers && deviceIdentifiers.length
					? deviceIdentifiers
					: _.map(liveSyncProcessInfo.deviceDescriptors, (d) => d.identifier);

			const removedDeviceIdentifiers = _.remove(
				liveSyncProcessInfo.deviceDescriptors,
				(descriptor) =>
					_.includes(deviceIdentifiersToRemove, descriptor.identifier),
			).map((descriptor) => descriptor.identifier);

			// Handle the case when no more devices left for any of the persisted platforms

			for (let i = 0; i < liveSyncProcessInfo.platforms.length; i++) {
				const platform = liveSyncProcessInfo.platforms[i];
				const devices = this.$devicesService.getDevicesForPlatform(platform);
				if (!devices || !devices.length) {
					await this.$prepareController.stopWatchers(projectDir, platform);
				}
			}

			// In case deviceIdentifiers are not passed, we should stop the whole LiveSync.
			if (
				!deviceIdentifiers ||
				!deviceIdentifiers.length ||
				!liveSyncProcessInfo.deviceDescriptors ||
				!liveSyncProcessInfo.deviceDescriptors.length
			) {
				if (liveSyncProcessInfo.timer) {
					clearTimeout(liveSyncProcessInfo.timer as unknown as number);
				}

				for (let k = 0; k < liveSyncProcessInfo.platforms.length; k++) {
					await this.$prepareController.stopWatchers(
						projectDir,
						liveSyncProcessInfo.platforms[k],
					);
				}

				liveSyncProcessInfo.isStopped = true;

				if (liveSyncProcessInfo.actionsChain && shouldAwaitPendingOperation) {
					await liveSyncProcessInfo.actionsChain;
				}

				liveSyncProcessInfo.deviceDescriptors = [];

				if (this.prepareReadyEventHandler) {
					this.$prepareController.removeListener(
						PREPARE_READY_EVENT_NAME,
						this.prepareReadyEventHandler,
					);
					this.prepareReadyEventHandler = null;
				}

				const projectData = this.$projectDataService.getProjectData(projectDir);
				await this.$hooksService.executeAfterHooks("watch", {
					hookArgs: {
						projectData,
					},
				});
			} else if (
				liveSyncProcessInfo.currentSyncAction &&
				shouldAwaitPendingOperation
			) {
				await liveSyncProcessInfo.currentSyncAction;
			}

			// Emit RunOnDevice stopped when we've really stopped.
			_.each(removedDeviceIdentifiers, (deviceIdentifier) => {
				this.emitCore(RunOnDeviceEvents.runOnDeviceStopped, {
					projectDir,
					deviceIdentifier,
					keepProcessAlive: stopOptions?.keepProcessAlive,
				});
			});

			if (stopOptions?.keepProcessAlive) {
				this.removeAllListeners(RunOnDeviceEvents.runOnDeviceStopped);
			}
		}
	}

	public getDeviceDescriptors(data: {
		projectDir: string;
	}): ILiveSyncDeviceDescriptor[] {
		return this.$liveSyncProcessDataService.getDeviceDescriptors(
			data.projectDir,
		);
	}

	protected async refreshApplication(
		projectData: IProjectData,
		liveSyncResultInfo: ILiveSyncResultInfo,
		filesChangeEventData: IFilesChangeEventData,
		deviceDescriptor: ILiveSyncDeviceDescriptor,
		fullSyncAction?: () => Promise<void>,
	): Promise<IRestartApplicationInfo> {
		const result = deviceDescriptor.debuggingEnabled
			? await this.refreshApplicationWithDebug(
					projectData,
					liveSyncResultInfo,
					filesChangeEventData,
					deviceDescriptor,
				)
			: await this.refreshApplicationWithoutDebug(
					projectData,
					liveSyncResultInfo,
					filesChangeEventData,
					deviceDescriptor,
					undefined,
					fullSyncAction,
				);

		const device = liveSyncResultInfo.deviceAppData.device;

		this.emitCore(RunOnDeviceEvents.runOnDeviceExecuted, {
			projectDir: projectData.projectDir,
			deviceIdentifier: device.deviceInfo.identifier,
			applicationIdentifier:
				projectData.projectIdentifiers[
					device.deviceInfo.platform.toLowerCase()
				],
			syncedFiles: liveSyncResultInfo.modifiedFilesData.map((m) =>
				m.getLocalPath(),
			),
			isFullSync: liveSyncResultInfo.isFullSync,
		});

		return result;
	}

	protected async refreshApplicationWithDebug(
		projectData: IProjectData,
		liveSyncResultInfo: ILiveSyncResultInfo,
		filesChangeEventData: IFilesChangeEventData,
		deviceDescriptor: ILiveSyncDeviceDescriptor,
	): Promise<IRestartApplicationInfo> {
		const debugOptions = deviceDescriptor.debugOptions || {};

		liveSyncResultInfo.waitForDebugger = !!debugOptions.debugBrk;
		liveSyncResultInfo.forceRefreshWithSocket = true;

		const refreshInfo = await this.refreshApplicationWithoutDebug(
			projectData,
			liveSyncResultInfo,
			filesChangeEventData,
			deviceDescriptor,
			{
				shouldSkipEmitLiveSyncNotification: true,
				shouldCheckDeveloperDiscImage: true,
			},
		);

		// we do not stop the application when debugBrk is false, so we need to attach, instead of launch
		// if we try to send the launch request, the debugger port will not be printed and the command will timeout
		debugOptions.start = !debugOptions.debugBrk;
		debugOptions.forceDebuggerAttachedEvent = refreshInfo.didRestart;

		await this.$debugController.enableDebuggingCoreWithoutWaitingCurrentAction(
			projectData.projectDir,
			deviceDescriptor.identifier,
			debugOptions,
		);

		return refreshInfo;
	}

	@performanceLog()
	protected async refreshApplicationWithoutDebug(
		projectData: IProjectData,
		liveSyncResultInfo: ILiveSyncResultInfo,
		filesChangeEventData: IFilesChangeEventData,
		deviceDescriptor: ILiveSyncDeviceDescriptor,
		settings?: IRefreshApplicationSettings,
		fullSyncAction?: () => Promise<void>,
	): Promise<IRestartApplicationInfo> {
		const result = { didRestart: false };
		const platform = liveSyncResultInfo.deviceAppData.platform;
		const applicationIdentifier =
			projectData.projectIdentifiers[platform.toLowerCase()];
		const platformLiveSyncService =
			this.$liveSyncServiceResolver.resolveLiveSyncService(platform);

		try {
			const isFullSync =
				filesChangeEventData &&
				(filesChangeEventData.hasNativeChanges ||
					!filesChangeEventData.hasOnlyHotUpdateFiles);
			let shouldRestart = isFullSync;
			if (!shouldRestart) {
				shouldRestart = await platformLiveSyncService.shouldRestart(
					projectData,
					liveSyncResultInfo,
				);
			}

			if (!shouldRestart) {
				shouldRestart = !(await platformLiveSyncService.tryRefreshApplication(
					projectData,
					liveSyncResultInfo,
				));
			}

			if (!isFullSync && shouldRestart && fullSyncAction) {
				this.$logger.trace(
					`Syncing all files as the current app state does not support hot updates.`,
				);
				liveSyncResultInfo.didRecover = true;
				await fullSyncAction();
			}

			if (shouldRestart) {
				this.emit(DEBUGGER_DETACHED_EVENT_NAME, {
					deviceIdentifier:
						liveSyncResultInfo.deviceAppData.device.deviceInfo.identifier,
				});
				await platformLiveSyncService.restartApplication(
					projectData,
					liveSyncResultInfo,
				);
				result.didRestart = true;
			}
		} catch (err) {
			this.$logger.info(
				`Error while trying to start application ${applicationIdentifier} on device ${
					liveSyncResultInfo.deviceAppData.device.deviceInfo.identifier
				}. Error is: ${err.message || err}`,
			);
			const msg = `Unable to start application ${applicationIdentifier} on device ${liveSyncResultInfo.deviceAppData.device.deviceInfo.identifier}. Try starting it manually.`;
			this.$logger.warn(msg);

			const device = liveSyncResultInfo.deviceAppData.device;
			const deviceIdentifier = device.deviceInfo.identifier;

			if (!settings || !settings.shouldSkipEmitLiveSyncNotification) {
				this.emitCore(RunOnDeviceEvents.runOnDeviceNotification, {
					projectDir: projectData.projectDir,
					deviceIdentifier: device.deviceInfo.identifier,
					applicationIdentifier:
						projectData.projectIdentifiers[
							device.deviceInfo.platform.toLowerCase()
						],
					notification: msg,
				});
			}

			if (
				settings &&
				settings.shouldCheckDeveloperDiscImage &&
				(err.message || err) === "Could not find developer disk image"
			) {
				const attachDebuggerOptions: IAttachDebuggerData = {
					platform: device.deviceInfo.platform,
					isEmulator: device.isEmulator,
					projectDir: projectData.projectDir,
					deviceIdentifier,
					debugOptions: deviceDescriptor.debugOptions,
					outputPath: deviceDescriptor.buildData.outputPath,
				};
				this.emit(USER_INTERACTION_NEEDED_EVENT_NAME, attachDebuggerOptions);
			}
		}

		return result;
	}

	private getDeviceDescriptorsForInitialSync(
		projectDir: string,
		deviceDescriptors: ILiveSyncDeviceDescriptor[],
	) {
		const currentRunData =
			this.$liveSyncProcessDataService.getPersistedData(projectDir);
		const isAlreadyLiveSyncing = currentRunData && !currentRunData.isStopped;
		// Prevent cases where liveSync is called consecutive times with the same device, for example [ A, B, C ] and then [ A, B, D ] - we want to execute initialSync only for D.
		const deviceDescriptorsForInitialSync = isAlreadyLiveSyncing
			? _.differenceBy(
					deviceDescriptors,
					currentRunData.deviceDescriptors,
					"identifier",
				)
			: deviceDescriptors;

		return deviceDescriptorsForInitialSync;
	}

	private async initializeSetup(projectData: IProjectData): Promise<void> {
		try {
			await this.$pluginsService.ensureAllDependenciesAreInstalled(projectData);
		} catch (err) {
			this.$logger.trace(err);
			this.$errors.fail(
				`Unable to install dependencies. Make sure your package.json is valid and all dependencies are correct. Error is: ${err.message}`,
			);
		}
	}

	@cache()
	private attachDeviceLostHandler(): void {
		this.$devicesService.on(
			DeviceDiscoveryEventNames.DEVICE_LOST,
			async (device: Mobile.IDevice) => {
				this.$logger.trace(
					`Received ${DeviceDiscoveryEventNames.DEVICE_LOST} event in LiveSync service for ${device.deviceInfo.identifier}. Will stop LiveSync operation for this device.`,
				);

				for (const projectDir in this.$liveSyncProcessDataService.getAllPersistedData()) {
					try {
						const deviceDescriptors = this.getDeviceDescriptors({ projectDir });
						if (
							_.find(
								deviceDescriptors,
								(d) => d.identifier === device.deviceInfo.identifier,
							)
						) {
							await this.stop({
								projectDir,
								deviceIdentifiers: [device.deviceInfo.identifier],
							});
						}
					} catch (err) {
						this.$logger.warn(
							`Unable to stop LiveSync operation for ${device.deviceInfo.identifier}.`,
							err,
						);
					}
				}
			},
		);
	}

	private async syncInitialDataOnDevices(
		projectData: IProjectData,
		liveSyncInfo: ILiveSyncInfo,
		deviceDescriptors: ILiveSyncDeviceDescriptor[],
	): Promise<void> {
		const rebuiltInformation: IDictionary<{
			packageFilePath: string;
			platform: string;
			isEmulator: boolean;
		}> = {};

		const deviceAction = async (device: Mobile.IDevice) => {
			const deviceDescriptor = _.find(
				deviceDescriptors,
				(dd) => dd.identifier === device.deviceInfo.identifier,
			);
			const prepareData = this.$prepareDataService.getPrepareData(
				liveSyncInfo.projectDir,
				device.deviceInfo.platform,
				{
					...liveSyncInfo,
					...deviceDescriptor.buildData,
					nativePrepare: {
						skipNativePrepare: !!deviceDescriptor.skipNativePrepare,
					},
					watch: !liveSyncInfo.skipWatcher,
				},
			);

			// For Android + Vite HMR, own the `adb reverse` ourselves —
			// with our SDK-resolved adb, scoped to this exact serial, and
			// only after the device is up — then hand the bundler the
			// result via env vars. This MUST run before `prepare` (which
			// spawns the Vite bundler that inherits `process.env`) so the
			// bundler trusts the tunnel instead of racing us to spawn its
			// own adb during config-load. See packages/vite hardening.
			await this.setupAndroidViteHmrReverse(
				device,
				projectData,
				liveSyncInfo,
				"pre-build",
			);

			const prepareResultData =
				await this.$prepareController.prepare(prepareData);

			const buildData = {
				...deviceDescriptor.buildData,
				buildForDevice: !device.isEmulator,
			};
			const platformData = this.$platformsDataService.getPlatformData(
				device.deviceInfo.platform,
				projectData,
			);

			try {
				let packageFilePath: string = null;

				// Case where we have three devices attached, a change that requires build is found,
				// we'll rebuild the app only for the first device, but we should install new package on all three devices.
				if (
					rebuiltInformation[platformData.platformNameLowerCase] &&
					(this.$mobileHelper.isAndroidPlatform(
						platformData.platformNameLowerCase,
					) ||
						rebuiltInformation[platformData.platformNameLowerCase]
							.isEmulator === device.isEmulator)
				) {
					packageFilePath =
						rebuiltInformation[platformData.platformNameLowerCase]
							.packageFilePath;
					await this.$deviceInstallAppService.installOnDevice(
						device,
						buildData,
						packageFilePath,
					);
				} else {
					const shouldBuild =
						prepareResultData.hasNativeChanges ||
						buildData.nativePrepare.forceRebuildNativeApp ||
						(await this.$buildController.shouldBuild(buildData));
					if (shouldBuild) {
						packageFilePath = await deviceDescriptor.buildAction();
						rebuiltInformation[platformData.platformNameLowerCase] = {
							isEmulator: device.isEmulator,
							platform: platformData.platformNameLowerCase,
							packageFilePath,
						};
					} else {
						await this.$analyticsService.trackEventActionInGoogleAnalytics({
							action: TrackActionNames.LiveSync,
							device,
							projectDir: projectData.projectDir,
						});
					}

					await this.$deviceInstallAppService.installOnDeviceIfNeeded(
						device,
						buildData,
						packageFilePath,
					);
				}

				const platformLiveSyncService =
					this.$liveSyncServiceResolver.resolveLiveSyncService(
						platformData.platformNameLowerCase,
					);
				const { force, useHotModuleReload, skipWatcher } = liveSyncInfo;
				const liveSyncResultInfo = await platformLiveSyncService.fullSync({
					force,
					useHotModuleReload,
					projectData,
					device,
					watch: !skipWatcher,
					liveSyncDeviceData: deviceDescriptor,
				});

				// Re-establish the adb reverse on the CURRENT transport right
				// before launch — the transport can change during build/install
				// and drop the mapping set in `pre-build`, which would leave the
				// app unable to reach the Vite dev server at 127.0.0.1.
				await this.setupAndroidViteHmrReverse(
					device,
					projectData,
					liveSyncInfo,
					"pre-launch",
				);

				await this.refreshApplication(
					projectData,
					liveSyncResultInfo,
					null,
					deviceDescriptor,
				);

				this.$logger.info(
					`Successfully synced application ${liveSyncResultInfo.deviceAppData.appIdentifier} on device ${liveSyncResultInfo.deviceAppData.device.deviceInfo.identifier}.`,
				);

				this.emitCore(RunOnDeviceEvents.runOnDeviceStarted, {
					projectDir: projectData.projectDir,
					deviceIdentifier: device.deviceInfo.identifier,
					applicationIdentifier:
						projectData.projectIdentifiers[
							device.deviceInfo.platform.toLowerCase()
						],
				});
			} catch (err) {
				this.$logger.warn(
					`Unable to apply changes on device: ${device.deviceInfo.identifier}. Error is: ${err.message}.`,
				);
				this.$logger.trace(err);

				this.emitCore(RunOnDeviceEvents.runOnDeviceError, {
					projectDir: projectData.projectDir,
					deviceIdentifier: device.deviceInfo.identifier,
					applicationIdentifier:
						projectData.projectIdentifiers[
							device.deviceInfo.platform.toLowerCase()
						],
					error: err,
				});

				await this.stop({
					projectDir: projectData.projectDir,
					deviceIdentifiers: [device.deviceInfo.identifier],
					stopOptions: { shouldAwaitAllActions: false },
				});
			}
		};

		await this.addActionToChain(projectData.projectDir, () =>
			this.$devicesService.execute(deviceAction, (device: Mobile.IDevice) =>
				_.some(
					deviceDescriptors,
					(deviceDescriptor) =>
						deviceDescriptor.identifier === device.deviceInfo.identifier,
				),
			),
		);
	}

	/**
	 * Set up `adb reverse tcp:<port> tcp:<port>` for an Android device
	 * when the project bundles with Vite in HMR/watch mode, then export
	 * the result to the bundler subprocess via environment variables.
	 *
	 * The Vite dev-host helper prefers an ADB tunnel (device-side
	 * `127.0.0.1:<port>` → host) over the emulator's flaky slirp NAT
	 * (`10.0.2.2`). Historically the bundler tried to wire that tunnel
	 * itself at config-load time, racing this CLI's device discovery
	 * over the single global adb daemon and intermittently freezing the
	 * run at "Searching for devices…". The CLI is the right owner: it
	 * knows the exact target serial and when the device is ready, and it
	 * already drives a single, version-matched adb. We do the reverse
	 * here and signal the bundler with `NS_ADB_REVERSE_READY=1` so it
	 * never spawns adb on its own.
	 *
	 * Best-effort: any failure is logged at trace level and swallowed.
	 * The bundler then falls back to its own (now hardened) adb path, or
	 * ultimately to `10.0.2.2`, so a reverse hiccup never fails the run.
	 */
	private async setupAndroidViteHmrReverse(
		device: Mobile.IDevice,
		projectData: IProjectData,
		liveSyncInfo: ILiveSyncInfo,
		phase: "pre-build" | "pre-launch",
	): Promise<void> {
		try {
			if (!this.$mobileHelper.isAndroidPlatform(device.deviceInfo.platform)) {
				return;
			}
			if (projectData.bundler !== "vite") {
				return;
			}
			// HMR over the tunnel only matters for a live watch session.
			if (liveSyncInfo.skipWatcher || !liveSyncInfo.useHotModuleReload) {
				return;
			}
			// Respect the user's explicit opt-out — they want the
			// `10.0.2.2` / LAN path, so don't create a tunnel or claim one
			// exists.
			if (this.isTruthyEnvFlag(process.env.NS_HMR_NO_ADB_REVERSE)) {
				return;
			}
			// `NS_HMR_PREFER_LAN_HOST` means the dev wants LAN routing
			// (physical device over Wi-Fi); the dev-host resolver suppresses
			// the adb-reverse path for it, so don't bother wiring one.
			if (this.isTruthyEnvFlag(process.env.NS_HMR_PREFER_LAN_HOST)) {
				return;
			}

			const serial = device.deviceInfo.identifier;
			const port = this.getViteHmrPort();

			if (phase === "pre-build") {
				// Decide the origin baked into bundle.mjs. Hand the bundler our
				// exact adb (so any self-managed fallback can't version-mismatch
				// the daemon) and, if the tunnel comes up, tell it to emit
				// `127.0.0.1` and skip adb entirely.
				process.env.NS_ADB_PATH = await this.$staticConfig.getAdbFilePath();
				process.env.NS_DEVICE_SERIAL = serial;

				const ok = await this.ensureAndroidReverse(device, serial, port);
				if (ok) {
					process.env.NS_ADB_REVERSE_READY = "1";
					this.$logger.info(
						`Set up adb reverse tcp:${port} tcp:${port} for ${serial} (Vite HMR routes device-side 127.0.0.1:${port} through ADB).`,
					);
				} else {
					this.$logger.warn(
						`Could not confirm 'adb reverse tcp:${port}' on ${serial} (device adbd slow/unresponsive). Vite HMR will fall back to 10.0.2.2. If this persists, cold-boot/wipe the emulator, or set NS_HMR_NO_ADB_REVERSE=1.`,
					);
				}
				return;
			}

			// phase === "pre-launch": re-establish the mapping right before the
			// app boots. `adb reverse` mappings are bound to the device's adb
			// transport, and that transport can change during the (long) build
			// + install (fresh emulators reconnect as they settle), silently
			// dropping the early mapping. We only bother when we actually told
			// the bundle to use `127.0.0.1` (READY set during pre-build).
			if (!this.isTruthyEnvFlag(process.env.NS_ADB_REVERSE_READY)) {
				return;
			}
			const ok = await this.ensureAndroidReverse(device, serial, port);
			if (!ok) {
				this.$logger.warn(
					`adb reverse tcp:${port} was not active before launch on ${serial}; the app may fail to reach the Vite dev server at 127.0.0.1:${port}.`,
				);
			}
		} catch (err) {
			this.$logger.trace(
				`Setting up adb reverse for Vite HMR (${phase}) failed; leaving it to the bundler fallback. Error: ${err}`,
			);
		}
	}

	/**
	 * Apply `adb reverse tcp:<port> tcp:<port>` to the device and confirm
	 * via `adb reverse --list` that it actually landed, retrying a few
	 * times. Every device-side call is bounded with a Node `spawn` timeout
	 * + `SIGKILL` so a wedged/slow adbd (observed blocking 90s+ on some
	 * fresh-boot / API-36 arm64 emulators) can never hang the run — the
	 * hung adb child is reaped, not orphaned. Returns whether the mapping
	 * is confirmed present.
	 */
	private async ensureAndroidReverse(
		device: Mobile.IDevice,
		serial: string,
		port: number,
	): Promise<boolean> {
		const adb = (device as Mobile.IAndroidDevice).adb;
		const ADB_WAIT_MS = 15000;
		const ADB_REVERSE_MS = 20000;
		const bounded = (timeout: number) => ({
			deviceIdentifier: serial,
			treatErrorsAsWarnings: true,
			childProcessOptions: { timeout, killSignal: "SIGKILL" },
		});

		// `wait-for-device` only blocks until the transport is up; bounded so a
		// never-ready device can't stall us.
		await adb.executeCommand(["wait-for-device"], bounded(ADB_WAIT_MS));

		for (let attempt = 1; attempt <= 3; attempt++) {
			await adb.executeCommand(
				["reverse", `tcp:${port}`, `tcp:${port}`],
				bounded(ADB_REVERSE_MS),
			);
			// Verify it landed (a SIGKILL'd-on-timeout reverse resolves rather
			// than throws, so success of the call isn't proof).
			const list =
				(
					await adb.executeCommand(["reverse", "--list"], bounded(ADB_WAIT_MS))
				)?.toString?.() ?? "";
			if (list.includes(`tcp:${port}`)) {
				return true;
			}
		}
		return false;
	}

	private getViteHmrPort(): number {
		// The Vite dev server defaults to 5173; the bundler reads the same
		// default. If a project runs Vite on a different port, the dev sets
		// `NS_HMR_PORT` so the CLI reverses the matching port.
		const fromEnv = Number(process.env.NS_HMR_PORT);
		return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : 5173;
	}

	private isTruthyEnvFlag(value: string | undefined): boolean {
		if (typeof value !== "string") {
			return false;
		}
		const v = value.trim().toLowerCase();
		return !!v && v !== "0" && v !== "false" && v !== "off" && v !== "no";
	}

	private async syncChangedDataOnDevices(
		data: IFilesChangeEventData,
		projectData: IProjectData,
		liveSyncInfo: ILiveSyncInfo,
	): Promise<void> {
		const successfullySyncedMessageFormat = `Successfully synced application %s on device %s.`;
		const rebuiltInformation: IDictionary<{
			packageFilePath: string;
			platform: string;
			isEmulator: boolean;
		}> = {};

		const deviceAction = async (device: Mobile.IDevice) => {
			const deviceDescriptors =
				this.$liveSyncProcessDataService.getDeviceDescriptors(
					projectData.projectDir,
				);
			const deviceDescriptor = _.find(
				deviceDescriptors,
				(dd) => dd.identifier === device.deviceInfo.identifier,
			);
			const platformData = this.$platformsDataService.getPlatformData(
				data.platform,
				projectData,
			);
			const prepareData = this.$prepareDataService.getPrepareData(
				liveSyncInfo.projectDir,
				device.deviceInfo.platform,
				{
					...liveSyncInfo,
					...deviceDescriptor.buildData,
					nativePrepare: {
						skipNativePrepare: !!deviceDescriptor.skipNativePrepare,
					},
					watch: !liveSyncInfo.skipWatcher,
				},
			);

			try {
				const platformLiveSyncService =
					this.$liveSyncServiceResolver.resolveLiveSyncService(
						device.deviceInfo.platform,
					);
				const allAppFiles = data.hmrData?.fallbackFiles?.length
					? data.hmrData.fallbackFiles
					: data.files;
				const filesToSync = data.hasOnlyHotUpdateFiles
					? data.files
					: allAppFiles;
				const watchInfo = {
					liveSyncDeviceData: deviceDescriptor,
					projectData,
					// todo: remove stale files once everything is stable
					// currently, watcher fires multiple times & may clean up unsynced files
					// filesToRemove: data.staleFiles ?? [],
					filesToRemove: [] as string[],
					filesToSync,
					hmrData: data.hmrData,
					useHotModuleReload: liveSyncInfo.useHotModuleReload,
					force: liveSyncInfo.force,
					connectTimeout: 1000,
				};
				const deviceAppData = await platformLiveSyncService.getAppData(
					_.merge({ device, watch: true }, watchInfo),
				);

				if (data.hasNativeChanges) {
					const rebuiltInfo =
						rebuiltInformation[platformData.platformNameLowerCase] &&
						(this.$mobileHelper.isAndroidPlatform(
							platformData.platformNameLowerCase,
						) ||
							rebuiltInformation[platformData.platformNameLowerCase]
								.isEmulator === device.isEmulator);
					if (!rebuiltInfo) {
						await this.$prepareNativePlatformService.prepareNativePlatform(
							platformData,
							projectData,
							prepareData,
						);
						await deviceDescriptor.buildAction();
						rebuiltInformation[platformData.platformNameLowerCase] = {
							isEmulator: device.isEmulator,
							platform: platformData.platformNameLowerCase,
							packageFilePath: null,
						};
					}

					await this.$deviceInstallAppService.installOnDevice(
						device,
						deviceDescriptor.buildData,
						rebuiltInformation[platformData.platformNameLowerCase]
							.packageFilePath,
					);
					await platformLiveSyncService.syncAfterInstall(device, watchInfo);
					await this.refreshApplication(
						projectData,
						{
							deviceAppData,
							modifiedFilesData: [],
							isFullSync: false,
							useHotModuleReload: liveSyncInfo.useHotModuleReload,
						},
						data,
						deviceDescriptor,
					);
					this.$logger.info(
						util.format(
							successfullySyncedMessageFormat,
							deviceAppData.appIdentifier,
							device.deviceInfo.identifier,
						),
					);
				} else {
					const isInHMRMode =
						liveSyncInfo.useHotModuleReload &&
						data.hmrData &&
						data.hmrData.hash;
					if (isInHMRMode) {
						this.$hmrStatusService.watchHmrStatus(
							device.deviceInfo.identifier,
							data.hmrData.hash,
						);
					}

					const watchAction = async (): Promise<void> => {
						const liveSyncResultInfo =
							await platformLiveSyncService.liveSyncWatchAction(
								device,
								watchInfo,
							);
						const fullSyncAction = async () => {
							watchInfo.filesToSync = allAppFiles;
							const fullLiveSyncResultInfo =
								await platformLiveSyncService.liveSyncWatchAction(
									device,
									watchInfo,
								);
							// IMPORTANT: keep the same instance as we rely on side effects
							_.assign(liveSyncResultInfo, fullLiveSyncResultInfo);
						};
						await this.$hooksService.executeBeforeHooks("watchAction", {
							hookArgs: {
								liveSyncResultInfo,
								filesToSync,
								allAppFiles,
								isInHMRMode,
								filesChangedEvent: data,
							},
						});

						await this.refreshApplication(
							projectData,
							liveSyncResultInfo,
							data,
							deviceDescriptor,
							fullSyncAction,
						);

						if (!liveSyncResultInfo.didRecover && isInHMRMode) {
							const status = await this.$hmrStatusService.getHmrStatus(
								device.deviceInfo.identifier,
								data.hmrData.hash,
							);

							// the timeout is assumed OK as the app could be blocked on a breakpoint
							if (status === HmrConstants.HMR_ERROR_STATUS) {
								await fullSyncAction();
								liveSyncResultInfo.isFullSync = true;
								await this.refreshApplication(
									projectData,
									liveSyncResultInfo,
									data,
									deviceDescriptor,
								);
							}
						}
						await this.$hooksService.executeAfterHooks("watchAction", {
							liveSyncResultInfo,
							filesToSync,
							allAppFiles,
							filesChangedEvent: data,
							isInHMRMode,
						});

						this.$logger.info(
							util.format(
								successfullySyncedMessageFormat,
								deviceAppData.appIdentifier,
								device.deviceInfo.identifier,
							),
						);
					};

					if (liveSyncInfo.useHotModuleReload) {
						try {
							this.$logger.trace(
								"Try executing watch action without any preparation of files.",
							);
							await watchAction();
							this.$logger.trace(
								"Successfully executed watch action without any preparation of files.",
							);
							return;
						} catch (err) {
							this.$logger.trace(
								`Error while trying to execute fast sync. Now we'll check the state of the app and we'll try to resurrect from the error. The error is: ${err}`,
							);
						}
					}

					await this.$deviceInstallAppService.installOnDeviceIfNeeded(
						device,
						deviceDescriptor.buildData,
					);
					watchInfo.connectTimeout = null;
					await watchAction();
				}
			} catch (err: any) {
				this.$logger.warn(
					`Unable to apply changes for device: ${
						device.deviceInfo.identifier
					}. Error is: ${err && err.message}. Will retry on next change.`,
				);

				this.emitCore(RunOnDeviceEvents.runOnDeviceError, {
					projectDir: projectData.projectDir,
					deviceIdentifier: device.deviceInfo.identifier,
					applicationIdentifier:
						projectData.projectIdentifiers[
							device.deviceInfo.platform.toLowerCase()
						],
					error: err,
				});
			}
		};

		await this.addActionToChain(projectData.projectDir, () =>
			this.$devicesService.execute(deviceAction, (device: Mobile.IDevice) => {
				const liveSyncProcessInfo =
					this.$liveSyncProcessDataService.getPersistedData(
						projectData.projectDir,
					);
				return (
					data.platform.toLowerCase() ===
						device.deviceInfo.platform.toLowerCase() &&
					liveSyncProcessInfo &&
					_.some(
						liveSyncProcessInfo.deviceDescriptors,
						(deviceDescriptor) =>
							deviceDescriptor.identifier === device.deviceInfo.identifier,
					)
				);
			}),
		);
	}

	private scheduleSyncOnDevices(
		data: IFilesChangeEventData,
		projectData: IProjectData,
		liveSyncInfo: ILiveSyncInfo,
	): void {
		if (this._syncInProgress) {
			const platform = data.platform;
			const existing = this._pendingSyncs.get(platform);
			if (existing) {
				existing.data = this.mergeFilesChangeEvents(existing.data, data);
			} else {
				this._pendingSyncs.set(platform, { data, projectData, liveSyncInfo });
			}
			return;
		}

		this.executeSyncOnDevices(data, projectData, liveSyncInfo);
	}

	private async executeSyncOnDevices(
		data: IFilesChangeEventData,
		projectData: IProjectData,
		liveSyncInfo: ILiveSyncInfo,
	): Promise<void> {
		this._syncInProgress = true;
		try {
			await this.syncChangedDataOnDevices(data, projectData, liveSyncInfo);
		} catch (err: any) {
			this.$logger.trace(`Error during sync on devices: ${err.message || err}`);
		} finally {
			const nextEntry = this._pendingSyncs.entries().next();
			if (!nextEntry.done) {
				const [platform, pending] = nextEntry.value;
				this._pendingSyncs.delete(platform);
				this.executeSyncOnDevices(
					pending.data,
					pending.projectData,
					pending.liveSyncInfo,
				);
			} else {
				this._syncInProgress = false;
			}
		}
	}

	private mergeFilesChangeEvents(
		a: IFilesChangeEventData,
		b: IFilesChangeEventData,
	): IFilesChangeEventData {
		return {
			files: [...new Set([...a.files, ...b.files])],
			staleFiles: [
				...new Set([...(a.staleFiles || []), ...(b.staleFiles || [])]),
			],
			hasOnlyHotUpdateFiles: a.hasOnlyHotUpdateFiles && b.hasOnlyHotUpdateFiles,
			hasNativeChanges: a.hasNativeChanges || b.hasNativeChanges,
			hmrData: b.hmrData,
			platform: b.platform,
		};
	}

	private async addActionToChain<T>(
		projectDir: string,
		action: () => Promise<T>,
	): Promise<T> {
		const liveSyncInfo =
			this.$liveSyncProcessDataService.getPersistedData(projectDir);
		if (liveSyncInfo) {
			liveSyncInfo.actionsChain = liveSyncInfo.actionsChain
				.then(async () => {
					if (!liveSyncInfo.isStopped) {
						liveSyncInfo.currentSyncAction = action();
						const res = await liveSyncInfo.currentSyncAction;
						return res;
					}
				})
				.catch((err: any) => {
					this.$logger.warn(`Error in action chain: ${err.message || err}`);
				});

			const result = await liveSyncInfo.actionsChain;
			return result;
		}
	}

	private emitCore(event: string, data: ILiveSyncEventData): void {
		this.$logger.trace(`Will emit event ${event} with data`, data);
		this.emit(event, data);
	}
}
injector.register("runController", RunController);