feat(commands)!: defineCommand migration, lazy registration, in-process dispatch and command-owned key shortcuts (#6153)

* feat(commands): extend defineCommand for the CLI's own commands

Options and arguments are declared on the definition and validated
before run. Setup runs ahead of argument enforcement so a definition can
derive its arguments; a redeclared CLI option keeps whatever it leaves
unspecified; unknown options are tolerated instead of skipping
validation; objectOption covers --env.* style values; a missing required
argument keeps the command's preamble in the error.

* refactor(commands): migrate every command to defineCommand

Platform validation, dynamic delegation, native-add and widget, test,
create/install/post-install-cli/help, enforced-parameter, device,
self-contained, platform, plugin and hooks, open|*, and the rest.
Class-based surfaces the migration left without callers are deprecated
rather than removed, since extensions may import them.

* feat(commands): register commands lazily against a checked definition type

registerCommand takes one shape and registers in one call, off the
global binding and into the loading context's injector; built-in
commands load on first use through a shared helper; getInjector becomes
getRootInjector. Package-manager commands register from their real
path, dev-post-install is reachable again, and a mistyped subcommand
shows help in the terminal.

* feat(commands)!: dispatch in process, rename ctx.arguments to ctx.params

A command can run another in process without exiting on failure; a
definition's setup state is scoped to one invocation;
DeferredCommandResult is a discriminated union; the command-name types
an extension needs are exported from the contracts.

BREAKING CHANGE: ctx.arguments is now ctx.params on the command context.

* feat(key-shortcuts): declarative table with a generic engine

ns start's key handling becomes a declarative table over a
caller-supplied context, with state on the context and capabilities on
the injector; the key-command surface leaves the injector facade.
Failures from the spawned run children surface in the parent, and
NS_NO_OPEN keeps the CLI from launching a browser where nobody is
watching.

* feat(key-shortcuts): registry contract and command-declared shortcuts

KeyShortcutRegistry is a contract with disposable registrations; the
engine resolves help and dispatch through it, so an entry registered at
runtime takes effect immediately. The shared entries become builders, a
defineCommand may declare the keys it answers to, and ns run and ns
debug get their own tables behind NS_COMMAND_SHORTCUTS (default off).

* fix(bundler): tear the bundler down before starting another one

Stopping a bundler only sent SIGINT and returned, so a restart could spawn
a replacement while the old watcher was still alive. The stale child's exit
then evicted the replacement's map entry, and a compilation finishing on it
still reached the prepare controller.

Await the child's exit (escalating to SIGKILL), detach its output and IPC
handlers, and key every eviction on process identity. The prepare
controller now keeps its compilation handler per platform, so stopping one
platform no longer leaves the other's listener attached.

* feat(key-shortcuts): r/R/B restart ladder, hint reprint, session scoping

r restarts the app of the running session without preparing, building
or syncing; R prepares again first and rebuilds the native app only if
needed; B always rebuilds it. The help hint is repeated once a burst of
syncs settles, and a restart stays on the devices the session was given
instead of every device attached to the platform.

* feat(commands): a class form built on defineCommand

`class X extends Command({ name, options, ... })` is sugar over the object
form: the definition is read through a static getter, `this.options` and
`this.args` are typed, and a command's services are typed from its setup. The
invocation context is provided under COMMAND_CONTEXT, which is what the class
form's field initializers read.

* refactor(commands): one context per invocation and the class-form sweep

Each invocation builds one context object that every stage shares. The
structured commands move to the class form, whose result type is inferred from
`run` and whose meta is validated eagerly; the simple ones are inlined as
object definitions; cross-command checks go through canExecuteCommand. The
guide describes where a handler gets its services.

* feat(commands): the in-process dispatcher as a contract

CommandsService is the contract a command, a key shortcut or a plugin runs or
consults another command through. It takes a registered name or a definition
run as given, routes a parent name to its subcommand and fires the full hook
name, rejects a dispatch that overlaps a running one while letting them nest,
and replaces the free runCommand and canExecuteCommand helpers. `ctx.injector`
is the invocation's own injector.

* refactor(commands): fail through the context and read options from it

`ctx.fail(message, { help })` replaces the commands' direct use of $errors,
and signing and install options are read from the typed `ctx.options` instead
of the global options object.

* feat(commands): definition providers, multi providers and preconditions

A definition declares `providers` for its invocation injector; the container
takes `multi: true` providers, which shadow per level as in Angular; and
COMMAND_PRECONDITIONS is a multi token run before setup and before the
arguments policy. `provideProject()` is how a command declares that it runs
inside a project.

* fix(commands): close the review gaps in the command API

- A bare class in `providers` provides itself, as in Angular; the container
  expands it to `{ provide: Cls, useClass: Cls }` and the definition rejects
  anything that is neither a class nor a `provide` object.
- A COMMAND_PRECONDITIONS entry is a function or a list of functions, checked
  with the command's name; the list form is what lets a command keep the
  scope's preconditions next to its own.
- An argument's `validate` runs inside the invocation's injection context.
- `runCommand` and `canExecuteCommand` take `{ injector }` for a definition
  run as given, defaulting to the caller's injection context, then the root;
  a registered name rejects it.
- Option priming happens inside the guarded block, so a throwing
  `validateOptions` leaves no command entry behind.
- `getInjector()` stays as a deprecated alias of `getRootInjector()`, and the
  compat tests carry their original lines again.
- `provideProject` lives under lib/contracts and is exported from
  nativescript/contracts with `CommandReference` and `CommandDispatchOptions`.
- The guide follows the API on every point above.

* refactor(commands): drop what never shipped and the leftovers the review found

`executeCommandInProcess` and `canExecuteCommandInProcess` were renamed on
this branch before any release, so they go rather than stay deprecated; the
same for the `getInjector()` alias of `getRootInjector()`. The dispatcher's
hierarchical branch in option priming was unreachable once parent names were
routed to their leaf, the adapter shares `define-command`'s `isPlainObject`
instead of carrying a second one, the options service is typed in the
adapter, and `classCommandDefinition` is no longer exported.

* chore: leave declarations.d.ts untouched

The deprecation note on disableCommandHelpSuggestion said only that nothing references it, which the declaration already shows; the file goes back to its merge-base content.

* fix: address the first review round on the command API and shortcuts

- A legacy command's `skipOptionsValidation` still counts, as the deprecated
  spelling of `allowUnknownOptions`.
- Option priming puts the parser back when validation throws, and an error
  is reported once however many dispatch levels rethrow it.
- `open` passes IDE paths as arguments instead of shell strings, resets the
  visionOS platform override in a `finally`, and logs a failed launch.
- `preview` no longer falls through from the bun case to npm.
- The prepare controller removes its bundler listener even while the watcher
  is paused; a restart re-reads the session's device descriptors so a device
  stopped meanwhile is left alone; `waitForExit` answers at once for a child
  that has already exited.
- The `c` shortcut spawns the CLI through `process.execPath` and reports a
  spawn failure instead of crashing; shortcuts attach over IPC only when an
  IPC channel exists; a visionOS child receives forwarded keys and is
  stopped by `c`.
- The guide no longer names the removed in-process aliases and describes the
  argument specs a definition accepts.

* feat(commands)!: declare positional parameters as `params`, options as `required`

`arguments` cannot be bound as an identifier in strict code, so a definition
could never be destructured or written with property shorthand; the field is
now `params`, the word the context already uses for the same values, and a
stale `arguments` key is rejected with a message naming the fix. `ParamSpec`,
`ParamsPolicy` and `CommandParamValues` replace the argument-named types,
which stay as deprecated aliases; `platformArgument` is `platformParam`.

An option spec takes `required: true`: its absence fails the invocation after
the params policy and before `canExecute`, and the handler's value type
drops `| undefined`, as a `default` already does. The two do not combine.

* docs(commands): name the reserved word the params spelling avoids

Author: edusperoni

defining-commands.md

@@ -178,7 +178,7 @@ const { defineCommand, inject } = require("nativescript/contracts");
 
 module.exports = defineCommand({
 	name: "hello|world",
-	arguments: "any",
+	params: "any",
 	async run(ctx) {
 		inject("logger").info(`Hello, ${ctx.args[0] || "world"}!`);
 	},
@@ -218,7 +218,7 @@ rejected with a warning.
 **The manifest key decides how a command is invoked.** It has to: the CLI routes
 `ns hello world` to your module before that module has been loaded, so the key
 is the only name it can know. A `name` inside the definition is metadata — it is
-what `registerCommandDefinition` uses when a module registers itself, and it is
+what `registerCommand` uses when a module registers itself, and it is
 useful documentation, but a manifest entry overrides it. If the two disagree the
 CLI warns, naming both, and runs the command under the manifest key.