fix: address the first review round on the command API and shortcuts

- A legacy command's `skipOptionsValidation` still counts, as the deprecated
  spelling of `allowUnknownOptions`.
- Option priming puts the parser back when validation throws, and an error
  is reported once however many dispatch levels rethrow it.
- `open` passes IDE paths as arguments instead of shell strings, resets the
  visionOS platform override in a `finally`, and logs a failed launch.
- `preview` no longer falls through from the bun case to npm.
- The prepare controller removes its bundler listener even while the watcher
  is paused; a restart re-reads the session's device descriptors so a device
  stopped meanwhile is left alone; `waitForExit` answers at once for a child
  that has already exited.
- The `c` shortcut spawns the CLI through `process.execPath` and reports a
  spawn failure instead of crashing; shortcuts attach over IPC only when an
  IPC channel exists; a visionOS child receives forwarded keys and is
  stopped by `c`.
- The guide no longer names the removed in-process aliases and describes the
  argument specs a definition accepts.

Author: edusperoni

defining-commands.md

@@ -57,9 +57,9 @@ Validation happens where you can see it
 
 A definition is checked at the moment `defineCommand` is called, not when the
 command eventually runs. A misspelled field, a missing `run`, an option
-declared with something other than the five helpers, an `arguments` value
-outside `"none" | "any"` — each throws immediately, naming the command and the
-accepted form. The class form's meta is checked the same way at the
+declared with something other than the five helpers, an `arguments` value that
+is neither `"none"`, `"any"` nor a list of argument specs — each throws
+immediately, naming the command and the accepted form. The class form's meta is checked the same way at the
 `Command({ ... })` call, which also rejects handlers passed there; only a
 missing `run` method waits until the definition is first read:
 
@@ -1047,8 +1047,6 @@ argument list to a child that declares fewer is a rejection, not a wider check.
 
 `canExecuteCommand` follows `runCommand` in everything else: the same option
 priming and restoration, the same routing of a parent name to its subcommand.
-The deprecated `canExecuteCommandInProcess` and `executeCommandInProcess`
-call the two methods with a name.
 
 ### Key shortcuts
 

lib/commands/open.ts

@@ -89,15 +89,14 @@ async function openAndroidStudioProject(
 
 	const os = currentPlatform();
 	if (os === "darwin") {
-		$childProcess.exec(`open -a "${studioPath}" ${androidDir}`);
-	} else if (os === "win32") {
+		$childProcess.execFile("open", ["-a", studioPath, androidDir]);
+	} else if (os === "win32" || os === "linux") {
 		const child = $childProcess.spawn(studioPath, [androidDir], {
 			detached: true,
 			stdio: "ignore",
 		});
+		child.on("error", (error: Error) => $logger.error(error.message));
 		child.unref();
-	} else if (os === "linux") {
-		$childProcess.exec(`${studioPath} ${androidDir}`);
 	}
 }
 
@@ -142,7 +141,7 @@ async function openXcodeProject(
 	if (fs.existsSync(xcprojectFile)) {
 		$xcodeSelectService
 			.getDeveloperDirectoryPath()
-			.then(() => $childProcess.exec(`open ${xcprojectFile}`, {}))
+			.then(() => $childProcess.execFile("open", [xcprojectFile]))
 			.catch((e) => {
 				$logger.error(e.message);
 			});
@@ -157,8 +156,11 @@ async function openVisionOSProject(
 	isInteractive: boolean,
 ): Promise<void> {
 	$options.platformOverride = "visionOS";
-	await openXcodeProject(context, "visionos", isInteractive);
-	$options.platformOverride = null;
+	try {
+		await openXcodeProject(context, "visionos", isInteractive);
+	} finally {
+		$options.platformOverride = null;
+	}
 }
 
 const openCommandOptions = {

lib/commands/preview.ts

@@ -81,6 +81,7 @@ export class PreviewCommand extends Command({
 				break;
 			case PackageManagers.bun:
 				installCommand = "bun add --dev @nativescript/preview-cli";
+				break;
 			case PackageManagers.npm:
 			default:
 				installCommand = "npm install --save-dev @nativescript/preview-cli";

lib/common/definitions/commands.d.ts

@@ -25,6 +25,8 @@ interface ICommand extends ICommandOptions {
 	 * own declared options are still merged and checked.
 	 */
 	allowUnknownOptions?: boolean;
+	/** @deprecated Use allowUnknownOptions. */
+	skipOptionsValidation?: boolean;
 
 	/**
 	 * Describes the action that will be executed after the command succeeds.

lib/common/errors.ts

@@ -9,6 +9,10 @@ import { ErrorCodes } from "./enums";
 import { IInjector } from "./definitions/yok";
 import { injector } from "./yok";
 
+const COMMAND_ERROR_REPORTED = Symbol.for(
+	"nativescript:cli:commandErrorReported",
+);
+
 // we need this to overwrite .stack property (read-only in Error)
 function Exception() {
 	/* intentionally left blank */
@@ -217,6 +221,16 @@ export class Errors implements IErrors {
 		error: any,
 		printCommandHelpSuggestion: () => Promise<void>,
 	): Promise<void> {
+		// A nested in-process dispatch reports and rethrows, and so does each
+		// level above it up to the command line, so the same error reaches here
+		// once per level.
+		if (error && typeof error === "object") {
+			if (error[COMMAND_ERROR_REPORTED]) {
+				return;
+			}
+			error[COMMAND_ERROR_REPORTED] = true;
+		}
+
 		const logger = this.$injector.resolve("logger");
 		const loggerLevel: string = logger.getLevel().toUpperCase();
 		const printCallStack =

lib/common/services/commands-service.ts

@@ -32,6 +32,9 @@ interface IInProcessDispatch {
 	commandName: string;
 }
 
+const allowsUnknownOptions = (command: ICommand): boolean =>
+	command.allowUnknownOptions ?? command.skipOptionsValidation ?? false;
+
 class CommandArgumentsValidationHelper {
 	constructor(
 		public isValid: boolean,
@@ -259,7 +262,7 @@ export class CommandsService
 			const dashedOptions = command ? command.dashedOptions : null;
 			this.$options.validateOptions(
 				dashedOptions,
-				command && command.allowUnknownOptions,
+				command && allowsUnknownOptions(command),
 			);
 		}
 
@@ -547,16 +550,24 @@ export class CommandsService
 	private primeOptions(command: ICommand): () => void {
 		const declaredOptions = { ...this.$options.options };
 		const parsedArgv = this.$options.argv;
-
-		this.$options.validateOptions(
-			command.dashedOptions,
-			command.allowUnknownOptions,
-		);
-
-		return () => {
+		const restore = (): void => {
 			this.$options.options = declaredOptions;
 			this.$options.argv = parsedArgv;
 		};
+
+		// validateOptions merges the command's declarations into the live table
+		// before it can throw, so a failed priming has to be undone here.
+		try {
+			this.$options.validateOptions(
+				command.dashedOptions,
+				allowsUnknownOptions(command),
+			);
+		} catch (error) {
+			restore();
+			throw error;
+		}
+
+		return restore;
 	}
 
 	private async canExecuteResolvedCommand(

lib/common/test/unit-tests/errors.ts

@@ -32,6 +32,27 @@ describe("errors", () => {
 		return testInjector;
 	};
 
+	describe("reportCommandError", () => {
+		it("reports one error once, whichever dispatch level asks", async () => {
+			const testInjector = getTestInjector();
+			const errors: IErrors = testInjector.resolve("errors");
+			const logger: CommonLoggerStub = testInjector.resolve("logger");
+			const error = Object.assign(new Error("Unable to open the project."), {
+				suggestCommandHelp: true,
+			});
+			let suggestions = 0;
+			const suggest = async (): Promise<void> => {
+				suggestions++;
+			};
+
+			await errors.reportCommandError(error, suggest);
+			await errors.reportCommandError(error, suggest);
+
+			assert.equal(logger.errorOutput, "Unable to open the project.\n");
+			assert.equal(suggestions, 1);
+		});
+	});
+
 	describe("beginCommand", () => {
 		let testInjector: IInjector;
 		let errors: IErrors;

lib/controllers/prepare-controller.ts

@@ -126,16 +126,19 @@ export class PrepareController
 			this.watchersData[projectDir][platformLowerCase] &&
 			this.watchersData[projectDir][platformLowerCase].hasWebpackCompilerProcess
 		) {
-			const watcherData = this.watchersData[projectDir][platformLowerCase];
 			await this.$bundlerCompilerService.stopBundlerCompiler(platformLowerCase);
-			if (watcherData.bundlerCompilerHandler) {
-				this.$bundlerCompilerService.removeListener(
-					BUNDLER_COMPILATION_COMPLETE,
-					watcherData.bundlerCompilerHandler,
-				);
-				watcherData.bundlerCompilerHandler = null;
-			}
-			watcherData.hasWebpackCompilerProcess = false;
+			this.watchersData[projectDir][
+				platformLowerCase
+			].hasWebpackCompilerProcess = false;
+		}
+
+		const watcherData = this.watchersData?.[projectDir]?.[platformLowerCase];
+		if (watcherData?.bundlerCompilerHandler) {
+			this.$bundlerCompilerService.removeListener(
+				BUNDLER_COMPILATION_COMPLETE,
+				watcherData.bundlerCompilerHandler,
+			);
+			watcherData.bundlerCompilerHandler = null;
 		}
 	}
 

lib/controllers/run-controller.ts

@@ -272,12 +272,21 @@ export class RunController extends EventEmitter implements IRunController {
 		const useHotModuleReload =
 			!!liveSyncProcessInfo.liveSyncInfo?.useHotModuleReload;
 
-		const deviceAction = async (device: Mobile.IDevice) => {
-			const deviceDescriptor = _.find(
-				deviceDescriptors,
-				(dd) => dd.identifier === device.deviceInfo.identifier,
+		// A device stopped while this action waited in the chain must not be restarted.
+		const findCurrentDescriptor = (device: Mobile.IDevice) =>
+			_.find(
+				this.$liveSyncProcessDataService.getDeviceDescriptors(projectDir),
+				(dd) =>
+					dd.identifier === device.deviceInfo.identifier &&
+					_.some(deviceDescriptors, (d) => d.identifier === dd.identifier),
 			);
 
+		const deviceAction = async (device: Mobile.IDevice) => {
+			const deviceDescriptor = findCurrentDescriptor(device);
+			if (!deviceDescriptor) {
+				return;
+			}
+
 			try {
 				const platformLiveSyncService =
 					this.$liveSyncServiceResolver.resolveLiveSyncService(
@@ -330,12 +339,9 @@ export class RunController extends EventEmitter implements IRunController {
 		};
 
 		await this.addActionToChain(projectDir, () =>
-			this.$devicesService.execute(deviceAction, (device: Mobile.IDevice) =>
-				_.some(
-					deviceDescriptors,
-					(deviceDescriptor) =>
-						deviceDescriptor.identifier === device.deviceInfo.identifier,
-				),
+			this.$devicesService.execute(
+				deviceAction,
+				(device: Mobile.IDevice) => !!findCurrentDescriptor(device),
 			),
 		);
 	}

lib/services/bundler/bundler-compiler-service.ts

@@ -1080,6 +1080,10 @@ export class BundlerCompilerService
 		childProcess: child_process.ChildProcess,
 		timeoutMs: number,
 	): Promise<boolean> {
+		if (childProcess.exitCode !== null || childProcess.signalCode !== null) {
+			return Promise.resolve(true);
+		}
+
 		return new Promise<boolean>((resolve) => {
 			const settle = (exited: boolean) => {
 				clearTimeout(timer);