feat(extensions): load defineCommand modules from manifest entries

A manifest entry may now point at a module that exports a defineCommand
definition instead of registering itself on load: the deferred loader
adapts and registers the export under the manifest key. The override
also lands on a parent record the entry just created, because dispatch
resolves the hierarchical parent before any child module has loaded and
the dispatcher only comes into existence once a child registers.

Also cross-links the authoring guides from dependency-injection.md.

Author: edusperoni

defining-commands.md

@@ -226,9 +226,10 @@ side-effect-free contracts entry point deliberately does not pull it in.
 `defineCommand`, the option helpers and all the types are exported from both
 `nativescript/contracts` and `lib/common/define-command`.
 
-Declaring commands from an extension manifest, so that an extension does not
-have to call a registration function at load time, is being added separately.
-Until then, extensions register definitions the same way the CLI does.
+Extensions do not need `registerCommandDefinition` at all: a
+`nativescript.commands` manifest entry may point straight at a module that
+exports a definition, and the CLI adapts and registers it lazily under the
+manifest key (see [extensions.md](extensions.md)).
 
 Relationship to `ICommand`
 --------------------------

dependency-injection.md

@@ -241,6 +241,13 @@ The first tranche, growing as services migrate:
 | `DoctorService` | `doctorService` |
 | `ProjectNameService` | `projectNameService` |
 
+Related guides
+--------------
+
+- [defining-commands.md](defining-commands.md) — declarative, typed commands via `defineCommand`.
+- [extensions.md](extensions.md) — extension authoring, including the `nativescript.commands` manifest.
+- [extending-cli.md](extending-cli.md) — hooks, including the typed `defineHook` API.
+
 Legacy → new quick reference
 ----------------------------
 

extensions.md

@@ -106,7 +106,25 @@ or set `NS_DEPRECATIONS=warn` to have those reports printed as warnings.
 
 ## Writing a command module
 
-A command module must register itself when it is loaded, by calling
+The recommended shape is a module exporting a `defineCommand` definition (see
+[defining-commands.md](defining-commands.md)) — the CLI adapts and registers it
+under the manifest key when the command is first executed, and the module needs
+no registration side effects at all:
+
+```js
+// dist/commands/hello-world.js
+const { defineCommand, inject } = require("nativescript/contracts");
+
+module.exports = defineCommand({
+	name: "hello|world",
+	arguments: "any",
+	async run(ctx) {
+		inject("logger").info(`Hello, ${ctx.args[0] || "world"}!`);
+	},
+});
+```
+
+Alternatively, a module may register itself when it is loaded, by calling
 `$injector.registerCommand` at the top level with the same name it is declared
 under in the manifest. The CLI resolves the command through the injector right
 after loading the module, so registration has to happen as a side effect of the

lib/services/extensibility-service.ts

@@ -18,6 +18,9 @@ import {
 	IGetExtensionCommandInfoParams,
 } from "../common/definitions/extensibility";
 import { injector } from "../common/yok";
+import { CommandsDelimiters } from "../common/constants";
+import { isCommandDefinition } from "../common/define-command";
+import { createCommandFromDefinition } from "../common/services/command-definition-adapter";
 
 function isNonEmptyString(value: any): boolean {
 	return typeof value === "string" && value.trim().length > 0;
@@ -333,8 +336,10 @@ export class ExtensibilityService implements IExtensibilityService {
 	/**
 	 * Registers each declared command as a deferred require of its own module, so
 	 * nothing from the extension is loaded until one of its commands is executed.
-	 * Each module is expected to register itself on load, by calling
-	 * `$injector.registerCommand(<name>, <class>)` at the top level.
+	 * A module may either register itself on load (a legacy-style
+	 * `$injector.registerCommand(<name>, <class>)` at the top level) or export a
+	 * `defineCommand` definition, which the deferred loader adapts and registers
+	 * under the manifest key.
 	 */
 	private registerDeclaredCommands(
 		extensionName: string,
@@ -353,11 +358,16 @@ export class ExtensibilityService implements IExtensibilityService {
 				continue;
 			}
 
+			const absoluteModulePath = path.join(pathToExtension, modulePath);
+			const parentName = commandName.split(
+				CommandsDelimiters.HierarchicalCommand,
+			)[0];
+			const container = (<any>injector).di;
+			const parentWasAbsent =
+				parentName !== commandName && !container.has(`commands.${parentName}`);
+
 			try {
-				injector.requireCommand(
-					commandName,
-					path.join(pathToExtension, modulePath),
-				);
+				injector.requireCommand(commandName, absoluteModulePath);
 			} catch (err) {
 				const owner = this.manifestCommandOwners[commandName];
 				const ownerInfo = owner
@@ -369,6 +379,32 @@ export class ExtensibilityService implements IExtensibilityService {
 				continue;
 			}
 
+			// requireCommand's own loader only require()s the module for its side
+			// effects, which covers self-registering modules but not definition
+			// exports. The override must also land on a parent record this entry
+			// just created: dispatch resolves the parent BEFORE any child module
+			// has loaded, and the parent dispatcher only comes into existence once
+			// a child's registerCommand runs.
+			const loader = () => {
+				const exported = require(absoluteModulePath);
+				const candidate = (exported && exported.default) ?? exported;
+				if (isCommandDefinition(candidate)) {
+					injector.registerCommand(commandName, () =>
+						createCommandFromDefinition(<any>candidate),
+					);
+				}
+			};
+			container.register({
+				provide: `commands.${commandName}`,
+				useLazyRequire: loader,
+			});
+			if (parentWasAbsent) {
+				container.register({
+					provide: `commands.${parentName}`,
+					useLazyRequire: loader,
+				});
+			}
+
 			this.manifestCommandOwners[commandName] = extensionName;
 		}
 	}

test/extension-manifests.ts

@@ -457,4 +457,74 @@ describe("extension manifests", () => {
 			assert.isNull(result);
 		});
 	});
+
+	describe("commands declared as defineCommand modules", () => {
+		const contractsPath = require.resolve("../lib/contracts");
+
+		const definitionModule = (commandName: string, marker: string): string =>
+			`const { defineCommand } = require(${JSON.stringify(contractsPath)});
+			global.__nsmCapture.loadedModules.push(${JSON.stringify(marker)});
+			module.exports = defineCommand({
+				name: ${JSON.stringify(commandName)},
+				arguments: "any",
+				async run(ctx) {
+					global.__nsmCapture.executed.push({ marker: ${JSON.stringify(
+						marker,
+					)}, args: ctx.args });
+				},
+			});`;
+
+		it("adapts and registers a pure definition module lazily", async () => {
+			const extensionName = "nsm-def-ext";
+			writeExtension(
+				extensionName,
+				{ commands: { "nsmdef|hello": "./dist/hello.js" } },
+				{
+					"main.js": mainModule("def-main"),
+					"dist/hello.js": definitionModule("nsmdef|hello", "def-hello"),
+				},
+			);
+
+			const testInjector = getTestInjector();
+			const extensibilityService = resolveService(testInjector);
+			await extensibilityService.loadExtension(extensionName);
+
+			assert.deepEqual(capture.loadedModules, []);
+
+			const command = cliGlobal.$injector.resolveCommand("nsmdef|hello");
+			assert.isOk(command);
+			assert.deepEqual(capture.loadedModules, ["def-hello"]);
+
+			await command.execute(["fast"]);
+			assert.deepEqual(capture.executed, [
+				{ marker: "def-hello", args: ["fast"] },
+			]);
+		});
+
+		it("resolves the hierarchical parent dispatcher before any child module has loaded", async () => {
+			const extensionName = "nsm-defp-ext";
+			writeExtension(
+				extensionName,
+				{ commands: { "nsmdefp|go": "./dist/go.js" } },
+				{
+					"main.js": mainModule("defp-main"),
+					"dist/go.js": definitionModule("nsmdefp|go", "defp-go"),
+				},
+			);
+
+			const testInjector = getTestInjector();
+			const extensibilityService = resolveService(testInjector);
+			await extensibilityService.loadExtension(extensionName);
+
+			// Dispatch hits the parent first; its record must load the child module
+			// so the dispatcher the child's registration synthesizes exists.
+			const parent = <any>cliGlobal.$injector.resolveCommand("nsmdefp");
+			assert.isOk(parent);
+			assert.isTrue(parent.isHierarchicalCommand);
+			assert.include(capture.loadedModules, "defp-go");
+
+			const child = cliGlobal.$injector.resolveCommand("nsmdefp|go");
+			assert.isOk(child);
+		});
+	});
 });