feat(hooks): defineHook - typed hook authoring with ctx payload/wrap/fail/skip (#6100)

* feat(hooks): add defineHook with typed ctx (wrap/abort/payload)

Hook authors can now export a definition built with defineHook instead
of a plain function whose shape the CLI has to infer. The handler takes
a context object with the operation payload, an explicit wrap() for
middleware around the hooked method, and abort() for stopping the hook
as either a failure or a warning.

Definitions are marked with Symbol.for("nativescript:cli:hookDefinition")
so a duplicated CLI copy in an extension's dependency tree still
recognizes them. The definition path skips parameter-name resolution,
the projectData promotion hack and the deprecation report; plain
function hooks keep running through the existing path unchanged.

lib/common/define-hook.ts is import-free so a hook can load it without
booting a second runtime, and it is re-exported from
nativescript/contracts.

* refactor(hooks): the facade is the injection context

Yok extends Injector on the base branch, so definitions run in
runInInjectionContext(this.$injector, ...) directly and
inject(Injector) inside a hook returns the facade itself.

* fix(hooks): make the defineHook surface validate and refuse silent no-ops

Drops the `I` prefix from the new hook types, makes `run` the handler
field with `defineHook({ name, run })` canonical and the positional call
kept as sugar, and validates the definition at define time: a missing or
non-string name, a non-function run, and unknown fields all throw naming
the definition and both accepted forms.

The definition marker moves from a non-enumerable defineProperty to a
plain assignment so a spread-derived definition stays recognizable, and
`isHookDefinition` becomes a type predicate.

Behaviors that used to fail quietly now say so:

- `ctx.wrap()` only ever ran at the `@hook`-decorated before-points and
  was dropped everywhere else. Call sites now declare whether they
  consume middlewares, and `wrap()` throws elsewhere instead.
- a definition whose name disagrees with its hook point is skipped with
  a warning rather than run at a point it was not written for.
- `ctx.abort()` with no message produced `Error(undefined)`; it now
  falls back to a message naming the hook point.
- a definition whose run returns a function warns, since the legacy
  returned-middleware convention does not apply to definitions.
- an array export is rejected naming the file, reserving the form for a
  possible multi-definition module later.

`defineHook<TPayload>` / `HookContext<TPayload>` type the payload, as
`TPayload | undefined` because dispatch-fired hooks carry none, and
executeBeforeHooks is typed with the middleware array it already returns.

* docs(hooks): lead with the reworked defineHook API and correct the contract

Documents the bag form, define-time validation, the strict name match and
the one-definition-per-file rule; splits ctx into payload/wrap/abort
sections; states that dispatch-fired hook points carry no payload and
lists the hook points where wrap() is honored.

Corrects two long-standing errors: a hook named plainly `watch` never
fires (the points are `before-watch`/`after-watch`), and downgrading a
rejection to a warning needs `errorAsWarning === true` together with a
Boolean `stopExecution`, not `stopExecution: false` alone.

* refactor(hooks): split ctx.abort into ctx.fail and ctx.skip

`abort(message, { asWarning: true })` did not abort anything — it warned
and the command carried on, so one verb meant opposite things depending
on a flag. The two outcomes now have a verb each: `ctx.fail(message)`
fails the command, `ctx.skip(message)` warns and lets it continue.

Both still stop the handler by throwing, so both are typed `never` and
the "handler ends here" behavior is unchanged; only the command's fate
differs. A missing message falls back to one naming the hook point and
the method.

`abort` and the `asWarning` option are removed outright rather than
shimmed, as the API is unreleased and never exposed either name.

Author: NathanWalker

extending-cli.md

@@ -11,7 +11,7 @@ For the NativeScript CLI to execute your hooks, you must place them in the `hook
 
 You can attach the hook before or after `prepare` operations or to `--watch` operations. 
 
-Note that `watch` hooks can be executed only at the time of running `--watch` operations. The `watch` hooks are the last thing executed before launching the file system watcher which tracks for changes to your code.
+Note that `watch` hooks can be executed only at the time of running `--watch` operations. The `before-watch` hooks are the last thing executed before launching the file system watcher which tracks for changes to your code.
 
 Your hooks must conform to the following naming and placement conventions:
 
@@ -36,27 +36,29 @@ Your hooks must conform to the following naming and placement conventions:
             ├── hook1 (this is an executable file)
             └── hook2 (this is an executable file)
     ```
-* If you want to attach a hook for `--watch` operations, you must place the hook in the root of the `hooks` subdirectory. The file must be named `watch`. For example:
+* If you want to attach a hook for `--watch` operations, you must place the hook in the root of the `hooks` subdirectory. The file must be named `before-watch` or `after-watch`. For example:
 
     ```
     my-app/
     ├── index.js
     ├── package.json
     └── hooks/
-        └── watch.js (this is a Node.js script)
+        └── before-watch.js (this is a Node.js script)
     ```
-* If you want to attach multiple hooks for `--watch` operations, you must place them inside a `watch` subdirectory of the `hooks` subdirectory. You can specify any meaningful name for the the hooks inside the subdirectory. For example:
+* If you want to attach multiple hooks for `--watch` operations, you must place them inside a `before-watch` or `after-watch` subdirectory of the `hooks` subdirectory. You can specify any meaningful name for the the hooks inside the subdirectory. For example:
 
     ```
     my-app/
     ├── index.js
     ├── package.json
     └── hooks/
-        └── watch (a directory)
+        └── before-watch (a directory)
             ├── hook1 (this is an executable file)
             └── hook2 (this is an executable file)
     ```
 
+    A file named plainly `watch` is never executed: like every other hook point, the watch hooks are addressed by the `before-`/`after-` names above.
+
 > **NOTE:** When multiple hooks are attached to a single event (i.e. multiple hooks are stored in dedicated subdirectories), at the specified time, the CLI executes each hook one by one. However, the order of hook execution is not strict and might change over command executions.
 
 Execute Hooks as Child Process
@@ -77,11 +79,105 @@ 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.
+The CLI assumes that this is a CommonJS module and calls the hook it exports — either a hook definition (see below) or a plain function.
 
 ## Writing a hook
 
-Hooks run inside an injection context, so services come from `inject()` — the same API used everywhere else (see [dependency-injection.md](dependency-injection.md)). Declare a `hookArgs` parameter only if you need the payload of the operation being hooked.
+Export a hook definition built with `defineHook`. It takes the hook point in the usual naming convention (`before-prepare`, `after-watch`) and a `run` handler that receives a context object.
+
+```JavaScript
+const { defineHook, inject, DoctorService } = require("nativescript/contracts");
+
+module.exports = defineHook({
+	name: "before-prepare",
+	run: async (ctx) => {
+		const doctorService = inject(DoctorService);
+		await doctorService.canExecuteLocalBuild();
+	},
+});
+```
+
+`defineHook(name, run)` is shorthand for the same definition:
+
+```JavaScript
+module.exports = defineHook("before-prepare", async (ctx) => { /* ... */ });
+```
+
+`defineHook` validates its input immediately: a missing or non-string `name`, a missing or non-function `run`, and unknown fields all throw at definition time, naming the definition and both accepted forms.
+
+The `name` decides when the hook fires and must match the hook point the file is placed at. A definition whose `name` disagrees with its location is **skipped with a warning** rather than run at the wrong point. Export exactly one definition (or one plain function) per file — an array export is rejected.
+
+Services come from `inject()` — the same API used everywhere else (see [dependency-injection.md](dependency-injection.md)):
+
+* `inject()` is valid in the synchronous part of the handler — not after an `await`. Resolve what you need up front; for late lookups, grab the container first: `const injector = inject(Injector)` (`Injector` is exported from `nativescript/contracts` too), then `injector.get(...)` later.
+* 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); a service without a token is reachable by its registry name — `inject("logger")` — as a migration bridge.
+* If you build your hook in TypeScript, add `nativescript` as a `devDependency` and import the same names: `import { defineHook, inject, DoctorService } from "nativescript/contracts"`. An `.mjs` hook can `export default defineHook(...)`.
+
+### `ctx.payload`
+
+`ctx.payload` holds the parameters of the CLI operation being hooked; its shape depends on the hook point. It is the CLI's own object, so mutating it influences the operation:
+
+```JavaScript
+module.exports = defineHook("before-build-task-args", (ctx) => {
+	ctx.payload.args.push("--offline");
+});
+```
+
+Not every invocation carries one. The `before-<command>`/`after-<command>` hooks fired around command dispatch (`before-build`, `after-run`, …) pass no arguments at all, so `ctx.payload` is `undefined` there. Treat it as optional — in TypeScript it is typed `TPayload | undefined`:
+
+```TypeScript
+import { defineHook } from "nativescript/contracts";
+
+export default defineHook<{ args: string[] }>("before-build-task-args", (ctx) => {
+	ctx.payload?.args.push("--offline");
+});
+```
+
+### `ctx.wrap(middleware)`
+
+`ctx.wrap(middleware)` puts a middleware around the hooked method. The middleware receives the method's arguments and a `next` callback; call `next` to continue, or return without calling it to short-circuit the method entirely.
+
+```JavaScript
+module.exports = defineHook("before-prepare", (ctx) => {
+	ctx.wrap(async (args, next) => {
+		const result = await next(...args);
+		return result;
+	});
+});
+```
+
+Only a hook point that actually folds middlewares around a method can honor `wrap()`, so it is available **only in the before-phase of the wrappable hook points** listed below. Calling it anywhere else — from any `after-` hook, or from a before-hook at a non-wrappable point — throws an error naming the hook point instead of registering a middleware that would never run.
+
+The wrappable hook points are:
+
+`before-buildAndroid` · `before-buildAndroidPlugin` · `before-buildIOS` · `before-checkEnvironment` · `before-checkForChanges` · `before-install` · `before-prepare` · `before-prepareNativeApp` · `before-resolveCommand` · `before-watch` · `before-watchPatterns`
+
+### `ctx.fail(message)` and `ctx.skip(message)`
+
+Both end the handler immediately — nothing after the call runs — and differ in what happens to the command.
+
+`ctx.fail(message)` fails the command, printing `message` as the error:
+
+```JavaScript
+module.exports = defineHook("before-prepare", (ctx) => {
+	ctx.fail("The generated bundle is missing; run the bundler first.");
+});
+```
+
+`ctx.skip(message)` prints `message` as a warning and lets the command continue:
+
+```JavaScript
+module.exports = defineHook("before-prepare", (ctx) => {
+	ctx.skip("Nothing to prepare.");
+});
+```
+
+The message is required in practice — calling either without one falls back to a message naming the hook point and the method.
+
+### Plain function hooks
+
+Exporting a plain function is still supported. It runs in an injection context too, so `inject()` works the same way; declare a `hookArgs` parameter if you need the payload.
 
 ```JavaScript
 const { inject, DoctorService } = require("nativescript/contracts");
@@ -92,23 +188,21 @@ module.exports = function (hookArgs) {
 };
 ```
 
-* `inject()` is valid in the synchronous part of the hook body — not after an `await`. Resolve what you need up front; for late lookups, grab the container first: `const injector = inject(Injector)` (`Injector` is exported from `nativescript/contracts` too), then `injector.get(...)` later.
-* `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. A future typed hook API (`defineHook` with an explicit context object) will replace this parameter; it is the one remaining piece of the legacy convention.
-* 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); a service without a token is reachable by its registry name — `inject("logger")` — as a migration bridge.
-* If you build your hook in TypeScript, add `nativescript` as a `devDependency` and import the same names: `import { inject, DoctorService } from "nativescript/contracts"`.
-
 ## The hook contract
 
 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.
- 
+The hook can also reject the promise with an instance of Error. The returned error can carry two members that together downgrade the rejection to a warning.
+
 Member | Type | Description
 ---|---|---
-`stopExecution` | Boolean | Set this to `false` to let the CLI continue executing this command.
-`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.
+`errorAsWarning` | Boolean | Must be exactly `true`. The CLI prints the error.message colored as a warning and continues executing the current command.
+`stopExecution` | Boolean | Must be present and of type Boolean. It only enables the check — setting it alone, with either value, changes nothing.
+
+**Both** members are required: the CLI continues only when `errorAsWarning === true` *and* `stopExecution` is a Boolean. Otherwise it prints the returned error colored as a fatal error and stops executing the current command.
+
+A plain-function hook can also return a function, which the CLI folds into a middleware chain around the hooked method.
+
+With `defineHook` neither convention is needed, and neither applies: `ctx.fail`/`ctx.skip` replace throwing an error carrying `stopExecution`/`errorAsWarning`, and `ctx.wrap` replaces returning a function. A definition whose `run` returns a function is warned about — the returned function is not used as a middleware.
 
 ## Legacy: parameter-name injection
 

lib/common/declarations.d.ts

@@ -824,12 +824,23 @@ interface IAutoCompletionService {
 	isObsoleteAutoCompletionEnabled(): boolean;
 }
 
+interface IHookExecutionOptions {
+	/**
+	 * Set by call sites that fold the returned middlewares around a method (the
+	 * `@hook` decorator). Where nothing consumes them, `ctx.wrap()` rejects
+	 * instead of registering a middleware that would never run.
+	 */
+	consumesMiddlewares?: boolean;
+}
+
 interface IHooksService {
 	hookArgsName: string;
+	/** Resolves with the middlewares hooks registered through `ctx.wrap()`. */
 	executeBeforeHooks(
 		commandName: string,
 		hookArguments?: IDictionary<any>,
-	): Promise<void>;
+		options?: IHookExecutionOptions,
+	): Promise<import("./define-hook").HookMiddleware[]>;
 	executeAfterHooks(
 		commandName: string,
 		hookArguments?: IDictionary<any>,