refactor(extensions): inject the injector; keep globals to the legacy seam

The service takes $injector as a constructor dependency instead of the
module-level import, so manifest registration and the definition-aware
loaders target the instance that resolved it. Tests assert on their own
per-test injector; the process-wide injector is swapped only because
legacy-shape fixture modules register through the published global
surface at load, and that seam is labeled as such.

extensions.md no longer teaches the global-injector patterns: the legacy
array path and self-registering modules are described under their
deprecation framing without runnable samples.

Author: edusperoni

extensions.md

@@ -88,21 +88,14 @@ The array is a discovery aid only — it lists the names the CLI may suggest you
 extension for, but it says nothing about where the implementations live. An
 extension declaring commands this way (or declaring no commands at all) is
 loaded the old way: the CLI `require()`s the package's main entry on **every**
-invocation and expects the module's top-level code to register everything.
+invocation and expects the module's top-level code to register everything
+through the injector global.
 
-```js
-// index.js of a legacy extension
-const path = require("path");
-
-global.$injector.requireCommand(
-	"hello|world",
-	path.join(__dirname, "commands", "hello-world"),
-);
-```
-
-This path remains supported, but it is tracked for eventual deprecation. Run any
-command with `--log trace` to see which installed extensions still rely on it,
-or set `NS_DEPRECATIONS=warn` to have those reports printed as warnings.
+This path remains supported for published extensions, but it is tracked for
+eventual deprecation and new extensions should not use it — declare the map
+instead. Run any command with `--log trace` to see which installed extensions
+still rely on it, or set `NS_DEPRECATIONS=warn` to have those reports printed
+as warnings.
 
 ## Writing a command module
 
@@ -124,31 +117,12 @@ module.exports = defineCommand({
 });
 ```
 
-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
-`require`.
-
-```js
-// dist/commands/hello-world.js
-class HelloWorldCommand {
-	constructor($logger) {
-		this.$logger = $logger;
-		this.allowedParameters = [];
-	}
-
-	async execute(args) {
-		this.$logger.info(`Hello, ${args[0] || "world"}!`);
-	}
-}
-
-global.$injector.registerCommand("hello|world", HelloWorldCommand);
-```
-
-Constructor parameters are injected by name: a parameter called `$logger`
-receives the CLI's logger, `$fs` its file system service, and so on. A command
-class must expose `allowedParameters` and an `execute(args)` method.
+Legacy modules — command classes that register themselves at load time through
+the injector global, with parameter-name constructor injection — keep working
+when a manifest entry points at them, so existing extensions can adopt the map
+without rewriting their commands. Both of those mechanisms are deprecated
+(see [dependency-injection.md](dependency-injection.md)); write new modules as
+definitions.
 
 ## Command names
 

lib/services/extensibility-service.ts

@@ -18,6 +18,7 @@ import {
 	IGetExtensionCommandInfoParams,
 } from "../common/definitions/extensibility";
 import { injector } from "../common/yok";
+import { IInjector } from "../common/definitions/yok";
 import { CommandsDelimiters } from "../common/constants";
 import { isCommandDefinition } from "../common/define-command";
 import { createCommandFromDefinition } from "../common/services/command-definition-adapter";
@@ -77,6 +78,7 @@ export class ExtensibilityService implements IExtensibilityService {
 		private $packageManager: INodePackageManager,
 		private $settingsService: ISettingsService,
 		private $requireService: IRequireService,
+		private $injector: IInjector,
 	) {}
 
 	public async installExtension(
@@ -362,12 +364,12 @@ export class ExtensibilityService implements IExtensibilityService {
 			const parentName = commandName.split(
 				CommandsDelimiters.HierarchicalCommand,
 			)[0];
-			const container = (<any>injector).di;
+			const container = (<any>this.$injector).di;
 			const parentWasAbsent =
 				parentName !== commandName && !container.has(`commands.${parentName}`);
 
 			try {
-				injector.requireCommand(commandName, absoluteModulePath);
+				this.$injector.requireCommand(commandName, absoluteModulePath);
 			} catch (err) {
 				const owner = this.manifestCommandOwners[commandName];
 				const ownerInfo = owner
@@ -389,7 +391,7 @@ export class ExtensibilityService implements IExtensibilityService {
 				const exported = require(absoluteModulePath);
 				const candidate = (exported && exported.default) ?? exported;
 				if (isCommandDefinition(candidate)) {
-					injector.registerCommand(commandName, () =>
+					this.$injector.registerCommand(commandName, () =>
 						createCommandFromDefinition(<any>candidate),
 					);
 				}

test/extension-manifests.ts

@@ -3,23 +3,24 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { ExtensibilityService } from "../lib/services/extensibility-service";
-import { Yok } from "../lib/common/yok";
+import { Yok, getInjector, setGlobalInjector } from "../lib/common/yok";
 import { LoggerStub } from "./stubs";
 import { clearReportedDeprecations } from "../lib/common/deprecation";
 import { CommandsDelimiters } from "../lib/common/constants";
-import { ICliGlobal } from "../lib/common/definitions/cli-global";
 import { IInjector } from "../lib/common/definitions/yok";
 import {
 	IExtensibilityService,
 	IExtensionData,
 } from "../lib/common/definitions/extensibility";
 import { IStringDictionary } from "../lib/common/declarations";
 
-// The service registers commands on the global injector imported by
-// lib/common/yok, so every assertion about registered commands goes through it.
-// That injector is shared by the whole file, so command names must be unique per
-// test - a name reused across tests would collide like a real conflict does.
-const cliGlobal = <ICliGlobal>(<unknown>global);
+// Every assertion about registered commands goes through the per-test
+// injector: the service takes $injector as a constructor dependency. The
+// process-wide injector is pointed at that same instance for each test's
+// duration ONLY because legacy-shape fixture modules register through the
+// published global surface when they load - that swap is the legacy-compat
+// seam, not the assertion path. Command names stay unique per test since the
+// module require cache outlives a test.
 
 interface ITestCapture {
 	loadedModules: string[];
@@ -32,9 +33,14 @@ describe("extension manifests", () => {
 	let profileDir: string;
 	let requiredPaths: string[];
 	let capture: ITestCapture;
+	let testInjector: IInjector;
+	let previousProcessInjector: IInjector;
 
 	beforeEach(() => {
 		profileDir = fs.mkdtempSync(path.join(os.tmpdir(), "ns-ext-manifest-"));
+		testInjector = getTestInjector();
+		previousProcessInjector = getInjector();
+		setGlobalInjector(testInjector);
 		requiredPaths = [];
 		capture = (<any>global).__nsmCapture = {
 			loadedModules: [],
@@ -48,6 +54,7 @@ describe("extension manifests", () => {
 	});
 
 	afterEach(() => {
+		setGlobalInjector(previousProcessInjector);
 		fs.rmSync(profileDir, { recursive: true, force: true });
 		delete (<any>global).__nsmCapture;
 	});
@@ -195,7 +202,6 @@ describe("extension manifests", () => {
 				},
 			);
 
-			const testInjector = getTestInjector();
 			const extensibilityService = resolveService(testInjector);
 			const extensionData =
 				await extensibilityService.loadExtension(extensionName);
@@ -212,7 +218,7 @@ describe("extension manifests", () => {
 				"nsmlazy|clean",
 			]);
 
-			const command = cliGlobal.$injector.resolveCommand("nsmlazy|run");
+			const command = testInjector.resolveCommand("nsmlazy|run");
 			assert.isOk(command);
 			assert.deepStrictEqual(capture.loadedModules, ["lazy-run"]);
 
@@ -244,7 +250,6 @@ describe("extension manifests", () => {
 				},
 			);
 
-			const testInjector = getTestInjector();
 			const extensibilityService = resolveService(testInjector);
 			await extensibilityService.loadExtension(extensionName);
 
@@ -253,9 +258,9 @@ describe("extension manifests", () => {
 			assert.include(warnOutput, "nsmbad|empty");
 			assert.include(warnOutput, extensionName);
 
-			assert.isOk(cliGlobal.$injector.resolveCommand("nsmbad|good"));
-			assert.isNull(cliGlobal.$injector.resolveCommand("nsmbad|number"));
-			assert.isNull(cliGlobal.$injector.resolveCommand("nsmbad|empty"));
+			assert.isOk(testInjector.resolveCommand("nsmbad|good"));
+			assert.isNull(testInjector.resolveCommand("nsmbad|number"));
+			assert.isNull(testInjector.resolveCommand("nsmbad|empty"));
 			assert.deepStrictEqual(capture.loadedModules, ["malformed-good"]);
 		});
 
@@ -279,7 +284,6 @@ describe("extension manifests", () => {
 				},
 			);
 
-			const testInjector = getTestInjector();
 			const extensibilityService = resolveService(testInjector);
 			await extensibilityService.loadExtension(firstExtension);
 			await extensibilityService.loadExtension(secondExtension);
@@ -289,7 +293,7 @@ describe("extension manifests", () => {
 			assert.include(warnOutput, firstExtension);
 			assert.include(warnOutput, secondExtension);
 
-			const command = cliGlobal.$injector.resolveCommand("nsmconflict|run");
+			const command = testInjector.resolveCommand("nsmconflict|run");
 			await command.execute([]);
 			assert.deepStrictEqual(capture.executed, [
 				{ marker: "first-run", args: [] },
@@ -309,7 +313,6 @@ describe("extension manifests", () => {
 				},
 			);
 
-			const testInjector = getTestInjector();
 			const extensibilityService = resolveService(testInjector);
 			const extensionData =
 				await extensibilityService.loadExtension(extensionName);
@@ -325,7 +328,7 @@ describe("extension manifests", () => {
 			assert.include(traceOutput, extensionName);
 
 			assert.deepStrictEqual(extensionData.commands, ["nsmeager|run"]);
-			assert.isOk(cliGlobal.$injector.resolveCommand("nsmeager|run"));
+			assert.isOk(testInjector.resolveCommand("nsmeager|run"));
 		});
 
 		it("keeps the eager path when the extension declares no commands", async () => {
@@ -336,7 +339,6 @@ describe("extension manifests", () => {
 				{ "main.js": mainModule("no-commands-main") },
 			);
 
-			const testInjector = getTestInjector();
 			const extensibilityService = resolveService(testInjector);
 			const extensionData =
 				await extensibilityService.loadExtension(extensionName);
@@ -357,7 +359,6 @@ describe("extension manifests", () => {
 			writeExtension("nsm-data-array-ext", { commands: ["nsmdata|three"] }, {});
 			writeExtension("nsm-data-plain-ext", {}, {});
 
-			const testInjector = getTestInjector();
 			const extensibilityService = resolveService(testInjector);
 			const extensionsData = extensibilityService.getInstalledExtensionsData();
 			const dataByName: { [name: string]: IExtensionData } = {};
@@ -382,7 +383,6 @@ describe("extension manifests", () => {
 			inputStrings: string[],
 		): Promise<any> => {
 			const extensionName = "nsm-registry-ext";
-			const testInjector = getTestInjector();
 			const packageManager = testInjector.resolve<any>("packageManager");
 			packageManager.searchNpms = async (keyword: string): Promise<any> => {
 				assert.equal(keyword, "nativescript:extension");
@@ -485,13 +485,12 @@ describe("extension manifests", () => {
 				},
 			);
 
-			const testInjector = getTestInjector();
 			const extensibilityService = resolveService(testInjector);
 			await extensibilityService.loadExtension(extensionName);
 
 			assert.deepEqual(capture.loadedModules, []);
 
-			const command = cliGlobal.$injector.resolveCommand("nsmdef|hello");
+			const command = testInjector.resolveCommand("nsmdef|hello");
 			assert.isOk(command);
 			assert.deepEqual(capture.loadedModules, ["def-hello"]);
 
@@ -512,18 +511,17 @@ describe("extension manifests", () => {
 				},
 			);
 
-			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");
+			const parent = <any>testInjector.resolveCommand("nsmdefp");
 			assert.isOk(parent);
 			assert.isTrue(parent.isHierarchicalCommand);
 			assert.include(capture.loadedModules, "defp-go");
 
-			const child = cliGlobal.$injector.resolveCommand("nsmdefp|go");
+			const child = testInjector.resolveCommand("nsmdefp|go");
 			assert.isOk(child);
 		});
 	});