feat(key-shortcuts): declarative table with a generic engine

ns start's key handling becomes a declarative table over a
caller-supplied context, with state on the context and capabilities on
the injector; the key-command surface leaves the injector facade.
Failures from the spawned run children surface in the parent, and
NS_NO_OPEN keeps the CLI from launching a browser where nobody is
watching.

Author: edusperoni

lib/bootstrap.ts

@@ -243,6 +243,22 @@ registerBuiltInCommand<typeof import("./commands/run").visionRunCommand>(
 	"run|visionos",
 	() => require("./commands/run").visionRunCommand,
 );
+registerBuiltInCommand<typeof import("./commands/open").iosOpenCommand>(
+	"open|ios",
+	() => require("./commands/open").iosOpenCommand,
+);
+registerBuiltInCommand<typeof import("./commands/open").androidOpenCommand>(
+	"open|android",
+	() => require("./commands/open").androidOpenCommand,
+);
+registerBuiltInCommand<typeof import("./commands/open").visionOpenCommand>(
+	"open|visionos",
+	() => require("./commands/open").visionOpenCommand,
+);
+registerBuiltInCommand<typeof import("./commands/open").visionOpenCommand>(
+	"open|vision",
+	() => require("./commands/open").visionOpenCommand,
+);
 registerBuiltInCommand<
 	typeof import("./commands/typings").typingsCommandDefinition
 >("typings", () => require("./commands/typings").typingsCommandDefinition);
@@ -705,7 +721,7 @@ injector.require("tempService", "./services/temp-service");
 
 injector.require("sharedEventBus", "./shared-event-bus");
 
-injector.require("keyCommandHelper", "./helpers/key-command-helper");
+injector.require("keyShortcutService", "./services/key-shortcuts");
 
 registerBuiltInCommand<
 	typeof import("./commands/start").startCommandDefinition
@@ -744,4 +760,3 @@ registerBuiltInCommand<
 registerBuiltInCommand<
 	typeof import("./commands/widget").widgetIOSCommandDefinition
 >("widget|ios", () => require("./commands/widget").widgetIOSCommandDefinition);
-require("./key-commands/bootstrap");

lib/commands/open.ts

@@ -195,9 +195,20 @@ const openCommandOptions = {
 /**
  * `prepare` reads the options service rather than this command's context, so
  * the CLI-wide `--watch` has to be pinned there and not just defaulted here.
+ * It is restored afterwards because a key shortcut runs this inside a process
+ * whose own live sync is still watching.
  */
-const disableWatch = ($options: IOptions): void => {
+const withoutWatch = async <T>(
+	$options: IOptions,
+	work: () => Promise<T>,
+): Promise<T> => {
+	const previous = $options.watch;
 	$options.watch = false;
+	try {
+		return await work();
+	} finally {
+		$options.watch = previous;
+	}
 };
 
 export const iosOpenCommand = defineCommand({
@@ -212,8 +223,9 @@ export const iosOpenCommand = defineCommand({
 		};
 	},
 	async run(context, services): Promise<void> {
-		disableWatch(services.$options);
-		await openXcodeProject(services, "ios", false);
+		await withoutWatch(services.$options, () =>
+			openXcodeProject(services, "ios", false),
+		);
 	},
 });
 
@@ -229,8 +241,9 @@ export const visionOpenCommand = defineCommand({
 		};
 	},
 	async run(context, services): Promise<void> {
-		disableWatch(services.$options);
-		await openVisionOSProject(services, services.$options, false);
+		await withoutWatch(services.$options, () =>
+			openVisionOSProject(services, services.$options, false),
+		);
 	},
 });
 
@@ -246,7 +259,8 @@ export const androidOpenCommand = defineCommand({
 		};
 	},
 	async run(context, services): Promise<void> {
-		disableWatch(services.$options);
-		await openAndroidStudioProject(services, "Android", false);
+		await withoutWatch(services.$options, () =>
+			openAndroidStudioProject(services, "Android", false),
+		);
 	},
 });

lib/commands/run.ts

@@ -1,9 +1,5 @@
 import { ERROR_NO_VALID_SUBCOMMAND_FORMAT } from "../common/constants";
 import { IErrors, IHostInfo } from "../common/declarations";
-import {
-	IKeyCommandHelper,
-	IKeyCommandPlatform,
-} from "../common/definitions/key-commands";
 import {
 	booleanOption,
 	CommandContext,
@@ -21,6 +17,11 @@ import {
 import { IOptions, IPlatformValidationService } from "../declarations";
 import { IMigrateController } from "../definitions/migrate";
 import { IProjectData, IProjectDataService } from "../definitions/project";
+import {
+	DevicePlatformName,
+	IKeyShortcutService,
+	keyShortcuts,
+} from "../services/key-shortcuts";
 
 const runCommandOptions = {
 	force: booleanOption(),
@@ -43,7 +44,7 @@ export interface IRunCommandServices {
 	$devicePlatformsConstants: Mobile.IDevicePlatformsConstants;
 	$errors: IErrors;
 	$hostInfo: IHostInfo;
-	$keyCommandHelper: IKeyCommandHelper;
+	$keyShortcutService: IKeyShortcutService;
 	$liveSyncCommandHelper: ILiveSyncCommandHelper;
 	$migrateController: IMigrateController;
 	$options: IOptions;
@@ -60,7 +61,7 @@ export function setupRunCommand(): IRunCommandServices {
 		),
 		$errors: inject<IErrors>("errors"),
 		$hostInfo: inject<IHostInfo>("hostInfo"),
-		$keyCommandHelper: inject<IKeyCommandHelper>("keyCommandHelper"),
+		$keyShortcutService: inject<IKeyShortcutService>("keyShortcutService"),
 		$liveSyncCommandHelper: inject<ILiveSyncCommandHelper>(
 			"liveSyncCommandHelper",
 		),
@@ -126,10 +127,13 @@ export async function runRunCommand(
 	);
 
 	if (process.env.NS_IS_INTERACTIVE) {
-		services.$keyCommandHelper.attachKeyCommands(
-			<IKeyCommandPlatform>services.platform,
-			"run",
-		);
+		services.$keyShortcutService.attach({
+			context: {
+				platform: <DevicePlatformName>services.platform,
+				processType: "run",
+			},
+			shortcuts: keyShortcuts(),
+		});
 	}
 }
 

lib/common/contracts/index.ts

@@ -14,6 +14,5 @@ export type {
 	DeferredCommandRejection,
 	DeferredCommandResult,
 } from "./command-registry";
-export { KeyCommandRegistry } from "./key-command-registry";
 export { ModuleRegistry } from "./module-registry";
 export { PublicApiBuilder } from "./public-api-builder";

lib/common/contracts/key-command-registry.ts

@@ -2,7 +2,6 @@ import { IDictionary } from "../declarations";
 import { Injector } from "../di/injector";
 import { Provider } from "../di/providers";
 import { CommandRegistry } from "../contracts/command-registry";
-import { KeyCommandRegistry } from "../contracts/key-command-registry";
 import { ModuleRegistry } from "../contracts/module-registry";
 import { PublicApiBuilder } from "../contracts/public-api-builder";
 
@@ -13,12 +12,7 @@ import { PublicApiBuilder } from "../contracts/public-api-builder";
  * this; the interface survives until the hook/extension deprecation completes.
  */
 interface IInjector
-	extends
-		Injector,
-		CommandRegistry,
-		KeyCommandRegistry,
-		ModuleRegistry,
-		PublicApiBuilder {
+	extends Injector, CommandRegistry, ModuleRegistry, PublicApiBuilder {
 	/**
 	 * Resolves an implementation by constructor function.
 	 * The injector will create new instances for every call.

lib/common/definitions/key-commands.ts

@@ -2,8 +2,26 @@ import * as xopen from "open";
 import { IOpener } from "../declarations";
 import { injector } from "./yok";
 
+/**
+ * Launching a browser or an external app is unwanted wherever nobody is
+ * watching a desktop: CI, test runs, and agents driving the CLI. Opting out
+ * has to live here because this is the only place the CLI opens anything.
+ */
+export function isOpeningExternallyDisabled(): boolean {
+	const flag = (process.env.NS_NO_OPEN || "").toLowerCase();
+	if (flag) {
+		return !["0", "false", "off", "no"].includes(flag);
+	}
+
+	return !!(process.env.CI || process.env.JENKINS_HOME);
+}
+
 export class Opener implements IOpener {
 	public open(target: string, appname?: string): any {
+		if (isOpeningExternallyDisabled()) {
+			return undefined;
+		}
+
 		return xopen(target, {
 			app: {
 				name: appname,

lib/common/definitions/yok.d.ts

@@ -10,6 +10,7 @@ import {
 } from "../declarations";
 import { IInjector } from "../definitions/yok";
 import { injector } from "../yok";
+import { isOpeningExternallyDisabled } from "../opener";
 import { IExtensibilityService } from "../definitions/extensibility";
 import { IOpener } from "../../declarations";
 import * as _ from "lodash";
@@ -83,6 +84,12 @@ export class HelpService implements IHelpService {
 	public async openHelpForCommandInBrowser(
 		commandData: ICommandData,
 	): Promise<void> {
+		if (isOpeningExternallyDisabled()) {
+			// Nothing is watching a desktop, so the terminal is the only place
+			// this help can land.
+			return this.showCommandLineHelp(commandData);
+		}
+
 		const { commandName } = commandData;
 		const htmlPage =
 			(await this.convertCommandNameToFileName(commandData)) +