feat(commands): add defineCommand with typed options via an ICommand adapter

Commands can now be declared as plain objects: a name, an option schema
built from booleanOption/stringOption/numberOption/arrayOption, and a run
function whose context carries the positional args plus the declared
options, typed by inference from the schema.

lib/common/define-command holds the types and the pure factories only, so
it stays side-effect-free and can be re-exported from
nativescript/contracts. The runtime bridge lives in
lib/common/services/command-definition-adapter, which compiles a
definition into the ICommand the legacy registry expects and runs it
inside an injection context.

canExecute is emitted only when the definition supplies one or opts into
arguments: "any"; CommandsService skips all parameter validation as soon
as canExecute exists, so omitting it is what lets the framework reject
stray positional arguments for arguments: "none".

Fully additive — existing ICommand classes are untouched.

Author: edusperoni

defining-commands.md

@@ -0,0 +1,251 @@
+Defining Commands
+=================
+
+`defineCommand` is the declarative way to add a command to the NativeScript
+CLI. A definition is a plain object: a name, an option schema, and a `run`
+function. The CLI compiles it into the command shape its registry expects, so a
+definition gets the same option parsing, hooks, analytics and help wiring as a
+hand-written command class — without a class, a constructor, or an
+`allowedParameters` array.
+
+This is purely additive. The legacy `ICommand` classes registered through
+`$injector.registerCommand` keep working exactly as before, and the two styles
+coexist in the same registry.
+
+At a glance
+-----------
+
+```ts
+import {
+	defineCommand,
+	booleanOption,
+	stringOption,
+} from "nativescript/contracts";
+
+export default defineCommand({
+	name: "widget|add",
+	description: "Adds a widget to the project",
+	options: {
+		verbose: booleanOption({ default: false }),
+		output: stringOption({ alias: "o" }),
+	},
+	arguments: "any",
+	async run(ctx) {
+		// ctx.args    -> string[] of positional arguments
+		// ctx.options -> { verbose: boolean; output: string }
+		if (ctx.options.verbose) {
+			console.log(`adding ${ctx.args.join(", ")} to ${ctx.options.output}`);
+		}
+	},
+});
+```
+
+`defineCommand` returns the definition, tagged with a marker symbol so that any
+copy of the CLI can recognise it (`isCommandDefinition(value)` is the exported
+predicate). It does not register anything by itself — see
+[Registering a definition](#registering-a-definition).
+
+Names and the command hierarchy
+-------------------------------
+
+`name` is either a single string or an array of strings, in which case every
+entry becomes an alias for the same command.
+
+The CLI's command registry is flat; the hierarchy the user types on the command
+line is encoded in the name with a `|` separator. `"widget|add"` is the command
+invoked as `ns widget add`, and `"widget|template|list"` is `ns widget template
+list`. Registering a hierarchical name automatically synthesises the parent
+dispatcher (`widget`), which routes to the right subcommand or prints help.
+
+A leading `*` on the last segment marks a **default subcommand**: `"widget|*add"`
+runs both for `ns widget add` and for a bare `ns widget`. This is the convention
+the CLI's own commands use (`run|*all`, `debug|*all`); the encoding is
+user-visible because it feeds shell autocompletion and generated help.
+
+Options
+-------
+
+`options` is a schema keyed by the long option name — `verbose` is passed as
+`--verbose`. Declare each entry with one of the four helpers, which fix the
+value type:
+
+| Helper          | Value type on `ctx.options` |
+| --------------- | --------------------------- |
+| `booleanOption` | `boolean`                   |
+| `stringOption`  | `string`                    |
+| `numberOption`  | `number`                    |
+| `arrayOption`   | `string[]`                  |
+
+Each helper takes an optional spec:
+
+```ts
+options: {
+	// --release, absent means false
+	release: booleanOption({ default: false }),
+	// --output <dir>, also accepted as -o <dir>
+	output: stringOption({ alias: "o", description: "Output directory" }),
+	// --retries <n>
+	retries: numberOption({ default: 3 }),
+	// --file a.ts --file b.ts
+	file: arrayOption(),
+	// kept out of analytics and logs
+	token: stringOption({ hasSensitiveValue: true }),
+}
+```
+
+- `default` — value used when the flag is absent.
+- `alias` — single-dash shorthand, or an array of them.
+- `hasSensitiveValue` — defaults to `false`; set it for anything that must not
+  be recorded. There is no reason not to be explicit about credentials, paths
+  containing user directories, and tokens.
+- `description` — shown in generated help.
+
+The schema types `ctx.options` and nothing else: `ctx.options` carries exactly
+the declared keys, with the types the helpers imply. Values that the CLI parses
+globally (`--path`, `--log`, …) are not exposed there; resolve the `options`
+service if you need them.
+
+### How validation behaves
+
+Option validation is the CLI's existing behaviour, not something the definition
+opts into. Before a command runs, the parser is re-primed with that command's
+declared options and the command line is re-parsed:
+
+- Declared options are accepted and appear on `ctx.options`.
+- An option the CLI does not know — neither global nor declared by this command
+  — is a **hard error**: the command does not run, and the CLI prints
+  `The option '<name>' is not supported.` followed by a help suggestion.
+
+So adding an option is exactly a matter of adding a schema entry; forgetting to
+declare one that users pass is a failure, not a silent `undefined`.
+
+Positional arguments
+--------------------
+
+`arguments` declares whether the command takes positional arguments at all:
+
+- `"none"` (the default) — the command accepts no positional arguments. Passing
+  any is rejected with `This command doesn't accept parameters.`
+- `"any"` — positional arguments are accepted and handed to `run` as
+  `ctx.args`.
+
+Anything finer than that belongs in `canExecute`.
+
+### `canExecute` owns validation
+
+```ts
+defineCommand({
+	name: "widget|add",
+	arguments: "any",
+	async canExecute(ctx) {
+		return ctx.args.length === 1;
+	},
+	async run(ctx) {
+		/* ... */
+	},
+});
+```
+
+`canExecute` receives the same context as `run` and returns a boolean (or a
+promise of one). Returning `false` aborts the command and prints a help
+suggestion; throwing surfaces your own error message, which is usually the
+friendlier choice.
+
+There is one rule to internalise: **the moment a command supplies
+`canExecute`, it owns argument validation completely.** The framework returns
+that verdict and skips every built-in parameter check, including the
+"no parameters" rule implied by `arguments: "none"`. A definition with a
+`canExecute` that only inspects options will therefore accept stray positional
+arguments unless it checks `ctx.args` itself. If you do not need custom
+validation, omit `canExecute` and let `arguments` do the work.
+
+The run context
+---------------
+
+`run(ctx)` receives:
+
+- `ctx.args` — `string[]`, the positional arguments left after the command name
+  (including any subcommand segments) has been consumed.
+- `ctx.options` — the current value of each declared option, read at the moment
+  the command executes.
+
+`run` may be synchronous or `async`; the CLI awaits the result and treats a
+rejection as a command failure.
+
+`run` starts inside a dependency-injection context, so `inject()` works
+directly:
+
+```ts
+import { defineCommand, inject } from "nativescript/contracts";
+import { DoctorService } from "nativescript/contracts";
+
+export default defineCommand({
+	name: "widget|check",
+	async run() {
+		const doctorService = inject(DoctorService);
+		await doctorService.printWarnings();
+	},
+});
+```
+
+The injection context is synchronous: `inject()` is valid up to the first
+`await` in `run`, and not after it. Capture what you need at the top of `run`,
+or inject the `Injector` itself and use `injector.get()` for late lookups. See
+`dependency-injection.md`.
+
+Other flags
+-----------
+
+- `disableAnalytics: true` — skips analytics tracking for this command.
+- `enableHooks: false` — skips the before/after hooks that normally run around
+  the command. Hooks are enabled by default.
+
+Both are simply passed through to the command the CLI executes; omitting them
+leaves the CLI's defaults in place.
+
+Registering a definition
+------------------------
+
+Inside the CLI, a definition is registered with `registerCommandDefinition`:
+
+```ts
+import { registerCommandDefinition } from "../common/services/command-definition-adapter";
+import addWidgetCommand from "./add-widget";
+
+registerCommandDefinition(addWidgetCommand);
+```
+
+It registers the definition under every name it declares, on the CLI's injector
+by default; pass a second argument to target a different injector (tests do
+this). The command instance is created on first resolution and cached.
+
+`registerCommandDefinition` lives in
+`lib/common/services/command-definition-adapter` rather than in
+`nativescript/contracts`, because it reaches into the CLI runtime — the
+side-effect-free contracts entry point deliberately does not pull it in.
+`defineCommand`, the option helpers and all the types are exported from both
+`nativescript/contracts` and `lib/common/define-command`.
+
+Declaring commands from an extension manifest, so that an extension does not
+have to call a registration function at load time, is being added separately.
+Until then, extensions register definitions the same way the CLI does.
+
+Relationship to `ICommand`
+--------------------------
+
+A definition is compiled into an ordinary `ICommand`, so nothing downstream —
+the registry, the router, hooks, help, analytics — knows the difference. The
+mapping is:
+
+| Definition                        | `ICommand`                                 |
+| --------------------------------- | ------------------------------------------ |
+| `options`                         | `dashedOptions`                            |
+| `run`                             | `execute`, wrapped in an injection context |
+| `arguments`, `canExecute`         | `canExecute` (see the rule above)          |
+| —                                 | `allowedParameters`, always `[]`           |
+| `disableAnalytics`, `enableHooks` | passed through unchanged                   |
+
+Existing command classes need no migration. Reach for a definition when a
+command is mostly "parse these flags and do this"; a class still makes sense
+when a command needs constructor-injected collaborators shared across several
+methods, custom `ICommandParameter` validators, or a `postCommandAction`.

lib/common/define-command.ts

@@ -0,0 +1,104 @@
+/**
+ * The declarative command API. Types and pure factories only — this module is
+ * re-exported from `nativescript/contracts` and must stay side-effect-free, so
+ * it may not import lib/common/yok (whose import creates global.$injector).
+ * The runtime bridge onto the legacy registry lives in
+ * lib/common/services/command-definition-adapter.
+ */
+
+/**
+ * Symbol.for so that a definition produced by one copy of the CLI is still
+ * recognised by another — extensions bundle their own node_modules.
+ */
+export const COMMAND_DEFINITION_MARKER = Symbol.for(
+	"nativescript:cli:commandDefinition",
+);
+
+export type CommandOptionType = "boolean" | "string" | "number" | "array";
+
+export interface ICommandOptionSpec<TValue = any> {
+	type: CommandOptionType;
+	/** Value used when the flag is absent from the command line. */
+	default?: TValue;
+	/** Single-dash shorthand, e.g. `-o` for `--output`. */
+	alias?: string | string[];
+	/** Keeps the value out of analytics and logs. Defaults to false. */
+	hasSensitiveValue?: boolean;
+	description?: string;
+}
+
+/** The parts of an option spec a caller supplies; `type` comes from the helper. */
+export type CommandOptionSpecInit<TValue = any> = Omit<
+	ICommandOptionSpec<TValue>,
+	"type"
+>;
+
+export interface ICommandOptionsSchema {
+	[optionName: string]: ICommandOptionSpec;
+}
+
+export type CommandOptionValues<TSchema extends ICommandOptionsSchema> = {
+	[K in keyof TSchema]: TSchema[K] extends ICommandOptionSpec<infer TValue>
+		? TValue
+		: any;
+};
+
+export interface ICommandContext<
+	TSchema extends ICommandOptionsSchema = ICommandOptionsSchema,
+> {
+	/** Positional arguments, after the command name has been consumed. */
+	args: string[];
+	/** Current value of every option declared in the schema, and nothing else. */
+	options: CommandOptionValues<TSchema>;
+}
+
+export interface ICommandDefinition<
+	TSchema extends ICommandOptionsSchema = ICommandOptionsSchema,
+> {
+	/** `"widget|add"`; `|` separates hierarchy levels. Several names alias one command. */
+	name: string | string[];
+	description?: string;
+	options?: TSchema;
+	/**
+	 * `"none"` (the default) rejects positional arguments; `"any"` accepts them.
+	 * Anything finer belongs in `canExecute`.
+	 */
+	arguments?: "none" | "any";
+	canExecute?(context: ICommandContext<TSchema>): Promise<boolean> | boolean;
+	disableAnalytics?: boolean;
+	enableHooks?: boolean;
+	run(context: ICommandContext<TSchema>): Promise<void> | void;
+}
+
+const optionSpec = <TValue>(
+	type: CommandOptionType,
+	init: CommandOptionSpecInit<TValue>,
+): ICommandOptionSpec<TValue> => ({ ...init, type });
+
+export const booleanOption = (
+	init: CommandOptionSpecInit<boolean> = {},
+): ICommandOptionSpec<boolean> => optionSpec("boolean", init);
+
+export const stringOption = (
+	init: CommandOptionSpecInit<string> = {},
+): ICommandOptionSpec<string> => optionSpec("string", init);
+
+export const numberOption = (
+	init: CommandOptionSpecInit<number> = {},
+): ICommandOptionSpec<number> => optionSpec("number", init);
+
+export const arrayOption = (
+	init: CommandOptionSpecInit<string[]> = {},
+): ICommandOptionSpec<string[]> => optionSpec("array", init);
+
+export function defineCommand<TSchema extends ICommandOptionsSchema>(
+	definition: ICommandDefinition<TSchema>,
+): ICommandDefinition<TSchema> {
+	const marked: ICommandDefinition<TSchema> = { ...definition };
+	(<any>marked)[COMMAND_DEFINITION_MARKER] = true;
+	return marked;
+}
+
+export function isCommandDefinition(value: any): value is ICommandDefinition {
+	return !!value && (<any>value)[COMMAND_DEFINITION_MARKER] === true;
+}