docs: lead with the typed API for hooks and demote string tokens

extending-cli.md's in-process section now opens with the recommended
hook pattern (hookArgs parameter + $injector.di.get(Token)) and moves
parameter-name injection into a labeled legacy section. String-token
lookups are framed as the migration bridge throughout, not a co-equal
API.

Author: edusperoni

dependency-injection.md

@@ -22,14 +22,17 @@ import { inject, DoctorService } from "nativescript/contracts";
 
 class PlatformChecker {
 	private doctorService = inject(DoctorService); // typed, no decorators needed
-	private logger = inject("logger");             // string tokens still work
 
 	async check(projectDir: string): Promise<boolean> {
 		return this.doctorService.canExecuteLocalBuild({ projectDir });
 	}
 }
 ```
 
+Services that have no typed token yet remain reachable by their registry name —
+`inject("logger")` — but that is the migration bridge, not the API: prefer the
+token wherever one exists, and mint a token rather than a new string name.
+
 Tokens: `@Contract`
 -------------------
 
@@ -88,7 +91,9 @@ class EnvironmentChecker {
 ```
 
 `Injector.get()` accepts a contract class, a string name, or a `$`-prefixed
-string name — all three return the same instance.
+string name — all three return the same instance. The string forms exist for
+interoperability with the legacy registry; use the class token whenever one
+exists.
 
 Registering: providers
 ----------------------
@@ -103,8 +108,8 @@ const injector = new Injector([
 	// deferred loading: the module is require()d on first resolution only
 	provideLazy(DoctorService, () => require("./doctor-service").DoctorServiceImpl),
 
-	{ provide: "config", useValue: { DISABLE_HOOKS: false } },
-	{ provide: "dispatcher", useFactory: () => createDispatcher(), shared: false },
+	{ provide: Config, useValue: { DISABLE_HOOKS: false } },
+	{ provide: Dispatcher, useFactory: () => createDispatcher(), shared: false },
 ]);
 
 // registration is also allowed after construction; re-registering a token
@@ -125,6 +130,11 @@ Provider kinds:
 instance. Transient instances are still retained by the container so
 `dispose()` reaches them.
 
+String keys are accepted anywhere a token is (`{ provide: "logger", useValue }`)
+— that is how the legacy facade registers, and how per-call overrides address
+not-yet-migrated dependencies. New registrations should mint a `@Contract`
+token instead of a new string name.
+
 For per-call construction with overrides (a fresh instance of a class with some
 dependencies replaced), use `createInstance`:
 

extending-cli.md

@@ -77,15 +77,34 @@ Execute Hooks In-Process
 
 When your hook is a Node.js script, the CLI executes it in-process. This gives you access to the entire internal state of the CLI and all of its functions.
 
-The CLI assumes that this is a CommonJS module and calls its single exported function with four parameters. The type of the parameters is described in the `.d.ts` files which are part of the CLI source code  [here](https://github.com/NativeScript/nativescript-cli/tree/master/lib/definitions) and  [here](https://github.com/telerik/mobile-cli-lib/tree/master/definitions).
+The CLI assumes that this is a CommonJS module and calls its single exported function.
+
+## Writing a hook
+
+Declare a `hookArgs` parameter if you need the payload of the operation being hooked, and resolve CLI services through the typed injection API: `global.$injector.di` is the CLI's container, and the `nativescript/contracts` subpath exports its tokens. See [dependency-injection.md](dependency-injection.md) for the full API.
+
+```JavaScript
+const { DoctorService } = require("nativescript/contracts");
+
+module.exports = function (hookArgs) {
+	const di = global.$injector.di;
+
+	const doctorService = di.get(DoctorService); // typed token
+	const logger = di.get("logger"); // no typed token yet — registry name
+
+	logger.info("running my hook");
+	return doctorService.canExecuteLocalBuild();
+};
+```
+
+* `hookArgs` contains the parameters of the CLI function being hooked; its shape depends on the hook point. Declare it only when you need it — a hook may also take no parameters at all.
+* Tokens resolve by class first and by their canonical name on a miss, so this works even if your dependency tree carries its own copy of `nativescript` — a duplicated token class still resolves to the running CLI's service.
+* Only a first tranche of services has typed tokens so far ([dependency-injection.md](dependency-injection.md#available-contracts) lists them); every other service is reachable by name — `di.get("logger")` returns the same instance as the legacy `$injector.resolve("logger")`.
+* If you build your hook in TypeScript, add `nativescript` as a `devDependency` and import the same names: `import { DoctorService } from "nativescript/contracts"`.
+* `inject()` itself requires an injection context, which hook invocation does not provide — use `di.get(...)` as above. A typed hook API that also replaces the `hookArgs` parameter with an explicit context is planned.
+
+## The hook contract
 
-Parameter | Type | Description
----|---|---
-`$logger` | ILogger | Use the members of this class to show messages to the user cooperating with the CLI internal state.
-`$projectData` | IProjectData | Contains data about the project, such as project directory, ID, dependencies, etc.
-`$usbLiveSyncService` | ILiveSyncService | Use this variable to check whether a LiveSync or normal build is in progress.
-`hookArgs` | Any | Contains all the parameters of the original function in the CLI which is being hooked.
- 
 The hook must return a Promise. If the hook succeeds, it must fullfil the promise, but the fullfilment value is ignored.
 The hook can also reject the promise with an instance of Error. The returned error can have two optional members controlling the CLI.
 
@@ -95,33 +114,19 @@ Member | Type | Description
 `errorAsWarning` | Boolean | Set this to treat the returned error as warning. The CLI prints the error.message colored as a warning and continues executing the current command.
 
 If these two members are not set, the CLI prints the returned error colored as fatal error and stops executing the current command.
- 
-Furthermore, the global variable `$injector` of type `IInjector` provides access to the CLI Dependency Injector, through which all code services are available.
-
-Using the Typed Injection API
-==============================
 
-The CLI also ships a typed, token-based injection API from the `nativescript/contracts` subpath, backed by the same container as `$injector` — a service resolved through a token is the identical instance you get by parameter name. See [dependency-injection.md](dependency-injection.md) for the full API.
+## Legacy: parameter-name injection
 
-From a hook, access it through the injector's `di` container:
+Historically, a hook received CLI services by naming them as parameters: the CLI parses the exported function's parameter names and injects the service registered under each name. Existing hooks written this way keep working unchanged, but **new hooks should use the pattern above** — parameter-name service injection is slated for deprecation, and hooks that use it are reported through the CLI's deprecation tracer (visible with `--log trace`, or as warnings with `NS_DEPRECATIONS=warn`).
 
-```JavaScript
-const { DoctorService } = require("nativescript/contracts");
-
-module.exports = function ($injector, $projectData) {
-	const doctorService = $injector.di.get(DoctorService);
-	return doctorService.canExecuteLocalBuild({
-		projectDir: $projectData.projectDir,
-	});
-};
-```
-
-Notes:
+Parameter | Type | Description
+---|---|---
+`$logger` | ILogger | Use the members of this class to show messages to the user cooperating with the CLI internal state.
+`$projectData` | IProjectData | Contains data about the project, such as project directory, ID, dependencies, etc.
+`$usbLiveSyncService` | ILiveSyncService | Use this variable to check whether a LiveSync or normal build is in progress.
+`hookArgs` | Any | Contains all the parameters of the original function in the CLI which is being hooked.
 
-* Tokens resolve by class first and by their canonical name on a miss, so this works even if your dependency tree carries its own copy of `nativescript` — a duplicated token class still resolves to the running CLI's service.
-* If you build your hook in TypeScript, add `nativescript` as a `devDependency` and import the same names: `import { DoctorService } from "nativescript/contracts"`.
-* `inject()` itself requires an injection context, which the current hook invocation does not provide — hooks should use `$injector.di.get(...)` as above. A typed hook API that removes the parameter-name convention entirely is planned; until then, parameter-name injection remains fully supported, though its usage is traced for eventual deprecation (run the CLI with `--log trace` to see the reports, or set `NS_DEPRECATIONS=warn` to surface them).
-* Only a first tranche of services has typed tokens so far ([dependency-injection.md](dependency-injection.md#available-contracts) lists them); every other service remains reachable by name — `$injector.di.get("logger")` and `$injector.resolve("logger")` are equivalent.
+The type of the parameters is described in the `.d.ts` files which are part of the CLI source code [here](https://github.com/NativeScript/nativescript-cli/tree/master/lib/definitions). Any registered service name is injectable, not only the ones listed; the global variable `$injector` of type `IInjector` likewise remains available. A parameter the CLI cannot resolve causes the hook to be skipped with a warning.
 
 Commands with Hooking Support
 ==============================