feat(commands): option groups, invocation scopes and the invocation record

[edusperoni]

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.

Stacked on #6153; merge that first. Draft: this is the machinery the service-side options migration builds on, with the extension surface (a manifest-level way to contribute options) deliberately left for a later design.

What is the current behavior?

A command declares its options as one schema object, and only the command reads the parsed values, through ctx.options. Services read the process-wide options object. There is no way for an option set to be shared between commands and injected by a service, no scope between a root singleton and a per-invocation provider, and nothing records which invocation is running for code that resolves by name outside an injection context (hooks, plugin callbacks).

What is the new behavior?

Six pieces of machinery, each with tests, documented in defining-commands.md and extensions.md:

1. Option groups. defineOptions(name, schema) returns a group that is both a schema and an injection token typed as the parsed values. options on a definition or a Command() meta takes a schema or a list of groups and schemas; ctx.options is typed as the merged values.
2. Per-invocation provision. Every non-root group a command declares is provided in the invocation injector with its slice of the parsed values, so a service in reach of the invocation injects the group instead of the options object. CliOptions is the process-level group (log, verbose, version, help, profileDir, analyticsClient, path, config); it is provided at the root, and the option table derives its global entries from it.
3. Collision rules. One spelling may be declared by several parts only with the same spec; an alias may not equal another option's spelling; a command may not redeclare a process-level spelling, but may list CliOptions to read those values typed. The six built-ins that redeclared --path or --help now list CliOptions.
4. Contribution seams. The OptionContributions contract adds groups to a command by name, or to the root, before the parse that targets them. No manifest surface yet.
5. providedIn scopes. A provider, an implementation class (@ProvidedIn) or a contract (@Contract({ providedIn })) can declare "invocation"; the instance lives on the nearest invocation injector and is disposed when the invocation ends. Resolving one from the root is an error, optional or not.
6. The invocation record. currentInvocationInjector() resolves, in order, the synchronous injection context, the invocation's asynchronous flow, the most recently opened invocation, then null. Hooks resolve their by-name dependencies against it, and runCommand(definition) defaults its scope to it. An in-process dispatch closes what it opened.

No service is migrated onto a group in this PR.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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.}