feat(commands): provide the invocation context through an injection token

The adapter now builds a child injector per invocation providing
COMMAND_CONTEXT, and runs setup, canExecute, run, postRun and shortcuts
under it. Handler signatures are unchanged; the token is the way a
service or a field initializer reaches the context without threading it
through. The provider reads the stage's own context, and nothing outside
an invocation can resolve the token.

Author: edusperoni

lib/common/contracts/command-context.ts

@@ -0,0 +1,12 @@
+import { InjectionToken } from "../di/injection-token";
+import type { CommandContext } from "../define-command";
+
+/**
+ * The context of the command invocation that is running. Provided by a child
+ * injector the adapter builds per invocation, so it resolves inside `setup`,
+ * `canExecute`, `run`, `postRun` and `shortcuts` — and nowhere else. A service
+ * registered on the root injector never sees it.
+ */
+export const COMMAND_CONTEXT = new InjectionToken<CommandContext<any>>(
+	"commandContext",
+);

lib/common/contracts/index.ts

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

lib/common/services/command-definition-adapter.ts

@@ -5,6 +5,7 @@ import { getCurrentInjector, runInInjectionContext } from "../di/inject";
 import { Injector } from "../di/injector";
 import { IDictionary, IDashedOption, IErrors } from "../declarations";
 import { ICommand } from "../definitions/commands";
+import { COMMAND_CONTEXT } from "../contracts/command-context";
 import {
 	COMMAND_OWNER,
 	CommandRegistry,
@@ -335,13 +336,17 @@ export function createCommandFromDefinition<
 	// The state of one invocation. The command object itself is cached for the
 	// process, so nothing invocation-scoped may live outside one of these.
 	interface Invocation {
+		/** The context of the stage that is running; COMMAND_CONTEXT reads it. */
+		context: CommandContext<TSchema>;
+		injector: Injector;
 		setup: Promise<Awaited<TSetup>>;
 		hasRun: boolean;
 		runResult?: Awaited<TResult>;
 	}
 
 	const startSetup = (
 		context: CommandContext<TSchema>,
+		injector: Injector,
 	): Promise<Awaited<TSetup>> =>
 		// The executor runs synchronously, so setup keeps its injection context
 		// up to its first await, while a synchronous failure - ctx.fail() is one -
@@ -350,7 +355,7 @@ export function createCommandFromDefinition<
 			resolve(
 				definition.setup
 					? <any>(
-							runInInjectionContext(targetInjector, () =>
+							runInInjectionContext(injector, () =>
 								definition.setup.call(definition, context),
 							)
 						)
@@ -365,9 +370,25 @@ export function createCommandFromDefinition<
 	let currentInvocation: Invocation = null;
 
 	const beginInvocation = (context: CommandContext<TSchema>): Invocation => {
-		currentInvocation = { setup: startSetup(context), hasRun: false };
+		const invocation: Invocation = {
+			context,
+			// Each entry point builds its own context object, so the token reads
+			// the live one rather than a snapshot: a handler that injects it gets
+			// the very context it was handed.
+			injector: targetInjector.createChild([
+				{
+					provide: COMMAND_CONTEXT,
+					useFactory: () => invocation.context,
+					shared: false,
+				},
+			]),
+			setup: undefined,
+			hasRun: false,
+		};
+		invocation.setup = startSetup(context, invocation.injector);
+		currentInvocation = invocation;
 
-		return currentInvocation;
+		return invocation;
 	};
 
 	/**
@@ -377,6 +398,7 @@ export function createCommandFromDefinition<
 	 * take the host's keys with it.
 	 */
 	const attachShortcuts = (
+		invocation: Invocation,
 		context: CommandContext<TSchema>,
 		setupResult: Awaited<TSetup>,
 	): void => {
@@ -392,8 +414,9 @@ export function createCommandFromDefinition<
 			return;
 		}
 
-		const shortcuts: KeyShortcut[] = runInInjectionContext(targetInjector, () =>
-			definition.shortcuts.call(definition, context, setupResult),
+		const shortcuts: KeyShortcut[] = runInInjectionContext(
+			invocation.injector,
+			() => definition.shortcuts.call(definition, context, setupResult),
 		);
 		if (!shortcuts || !shortcuts.length) {
 			return;
@@ -428,8 +451,9 @@ export function createCommandFromDefinition<
 					postCommandAction: async (args: string[]): Promise<void> => {
 						const context = buildContext(args);
 						const invocation = currentInvocation || beginInvocation(context);
+						invocation.context = context;
 						const setupResult = await invocation.setup;
-						await runInInjectionContext(targetInjector, () =>
+						await runInInjectionContext(invocation.injector, () =>
 							definition.postRun.call(
 								definition,
 								context,
@@ -446,7 +470,8 @@ export function createCommandFromDefinition<
 			// arguments - so an argument validator can rely on it, and a command
 			// run in the wrong place still reports that before complaining about
 			// arity.
-			const setupResult = await beginInvocation(context).setup;
+			const invocation = beginInvocation(context);
+			const setupResult = await invocation.setup;
 
 			await enforceArguments(context);
 
@@ -457,7 +482,7 @@ export function createCommandFromDefinition<
 
 			// Same first-await rule as execute: runInInjectionContext is
 			// synchronous, so inject() is available up to the first await.
-			return await runInInjectionContext(targetInjector, () =>
+			return await runInInjectionContext(invocation.injector, () =>
 				refine.call(definition, context, setupResult),
 			);
 		},
@@ -467,15 +492,17 @@ export function createCommandFromDefinition<
 				currentInvocation && !currentInvocation.hasRun
 					? currentInvocation
 					: beginInvocation(context);
+			invocation.context = context;
 			invocation.hasRun = true;
 
 			const setupResult = await invocation.setup;
-			invocation.runResult = await runInInjectionContext(targetInjector, () =>
-				definition.run.call(definition, context, setupResult),
+			invocation.runResult = await runInInjectionContext(
+				invocation.injector,
+				() => definition.run.call(definition, context, setupResult),
 			);
 
 			if (definition.shortcuts) {
-				attachShortcuts(context, setupResult);
+				attachShortcuts(invocation, context, setupResult);
 			}
 		},
 	};

test/define-command.ts

@@ -8,6 +8,7 @@ import {
 	InjectionToken,
 	runInInjectionContext,
 } from "../lib/common/di";
+import { COMMAND_CONTEXT } from "../lib/common/contracts/command-context";
 import {
 	COMMAND_OWNER,
 	CommandRegistry,
@@ -2275,6 +2276,76 @@ describe("defineCommand", () => {
 		});
 	});
 
+	describe("COMMAND_CONTEXT", () => {
+		it("resolves to the context the handlers of the same stage receive", async () => {
+			const testInjector = createTestInjector();
+			let injectedInSetup: any;
+			let injectedInRun: any;
+			let setupContext: any;
+			let runContext: any;
+
+			const command = createCommandFromDefinition(
+				defineCommand({
+					name: "dctest-command-context",
+					setup: (ctx) => {
+						setupContext = ctx;
+						injectedInSetup = inject(COMMAND_CONTEXT);
+					},
+					run: (ctx) => {
+						runContext = ctx;
+						injectedInRun = inject(COMMAND_CONTEXT);
+					},
+				}),
+				testInjector,
+			);
+
+			await command.execute([]);
+
+			assert.strictEqual(injectedInSetup, setupContext);
+			assert.strictEqual(injectedInRun, runContext);
+		});
+
+		it("is scoped to the invocation, so the root injector never sees it", async () => {
+			const testInjector = createTestInjector();
+
+			const command = createCommandFromDefinition(
+				defineCommand({
+					name: "dctest-command-context-scope",
+					run: (): void => undefined,
+				}),
+				testInjector,
+			);
+
+			await command.execute([]);
+
+			assert.isNull(testInjector.get(COMMAND_CONTEXT, { optional: true }));
+			assert.throws(
+				() => testInjector.get(COMMAND_CONTEXT),
+				/unable to resolve/,
+			);
+		});
+
+		it("gives each invocation a context of its own", async () => {
+			const testInjector = createTestInjector();
+			const seen: any[] = [];
+
+			const command = createCommandFromDefinition(
+				defineCommand({
+					name: "dctest-command-context-per-invocation",
+					setup: () => seen.push(inject(COMMAND_CONTEXT)),
+					run: (): void => undefined,
+				}),
+				testInjector,
+			);
+
+			await command.execute([]);
+			await command.execute([]);
+
+			assert.lengthOf(seen, 2);
+			assert.notStrictEqual(seen[0], seen[1]);
+		});
+	});
+
 	describe("per-registration parameterization with a child injector", () => {
 		it("registers one definition per platform and resolves the child provider", async () => {
 			const PLATFORM = new InjectionToken<string>("dcTestCommandPlatform");