feat(commands): defineCommand — typed declarative commands via an ICommand adapter

[edusperoni]

Stacked on #6099 (feat/di-modernization-phase1).

PR Checklist

• The PR title follows our guidelines: https://github.com/NativeScript/NativeScript/blob/master/tools/notes/CONTRIBUTING.md#commit-messages.
• There is an issue for the bug/feature this PR is for. To avoid wasting your time, it's best to open a suggestion issue first and wait for approval before working on it.
• You have signed the CLA.
• All existing tests are passing: https://github.com/NativeScript/nativescript-cli/blob/master/CONTRIBUTING.md#contribute-to-the-code-base
• Tests for the changes are included.

What is the current behavior?

A command is a class implementing ICommand, registered under a stringly-typed key, reading flags off the untyped global $options object. The validation semantics carry a trap: declaring canExecute silently disables allowedParameters validation, and an empty allowedParameters means "reject all positional arguments" — none of which the types express.

What is the new behavior?

defineCommand — a declarative, typed command definition that plugs into the existing registry through an adapter (createCommandFromDefinition / registerCommandDefinition). Fully additive: routing, validation, help, hooks, and analytics behavior are untouched, and legacy ICommand classes remain fully supported.

export default defineCommand({
	name: "widget|add",
	options: { verbose: booleanOption({ default: false }), output: stringOption({ alias: "o" }) },
	arguments: "none",
	async run(ctx) {
		// ctx.options.verbose is a boolean — inferred from the schema
	},
});

• Option schemas compile to dashedOptions, riding the CLI's existing option validation (declared flags accepted; unknown flags hard-fail with help, exactly as today). ctx.options is a typed view with real inference (pinned by an exactness type test, not a strict-off-friendly assignment).
• The canExecute trap is handled explicitly and documented as a constraint in the adapter: arguments: "none" (default) omits canExecute so the framework's own no-parameters validation applies; arguments: "any" or a user canExecute takes validation ownership wholesale.
• run executes in an injection context, so inject() works inside commands the same as everywhere else.
• lib/common/define-command.ts is side-effect-free and exported from nativescript/contracts; definitions carry a Symbol.for marker so duplicated CLI copies interoperate.
• 18 new tests, including two end-to-end through CommandsService.tryExecuteCommand.
• New authoring guide: defining-commands.md.

Two pre-existing registry quirks surfaced while testing, unchanged by this PR and worth their own issues: the synthesized hierarchical parent registers via the module-level global injector rather than the instance it was called on, and registerCommand alone never populates hierarchicalCommands routing state (only requireCommand does).

Full suite: 110 files, 1616 passed / 38 skipped; yok oracle, public-API test, and compat fixtures untouched.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 23dc3228-9431-4bc8-9319-adc51984694e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}