Repository navigation
feat(commands): option groups, invocation scopes and the invocation record - #6156
Draft
edusperoni wants to merge 20 commits into
Draft
edusperoni wants to merge 20 commits into
edusperoni wants to merge 20 commits into
Conversation
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.
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.
… 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.
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.
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.
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).
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.
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.
`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.
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.
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.
`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.
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.
- 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.
…iew 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.
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.
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
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. Comment |
- 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.
edusperoni
force-pushed
the
feat/options-machinery
branch
from
September 23, 2026 15:14
66a2708 to
d9f9735
Compare
…s `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.
…ecord - `defineOptions(name, schema)` declares an option group: a schema that is also an injection token typed as its parsed values. `options` takes a schema or a list of groups and schemas, and `ctx.options` is typed as the merged values. Spellings collide only with different specs; an alias may not equal another option's spelling. - Every non-root group a command declares is provided in the invocation injector with its slice of the parsed values. `CliOptions` is the process-level group, provided at the root; the option table derives its global entries from it, and a command may list it but not redeclare its spellings. The built-ins that redeclared `--path` or `--help` list it. - `OptionContributions` adds groups to a command by any of its names, own or registered, or to the root, ahead of the parse that targets them. - `providedIn` on a provider, an implementation class (`@ProvidedIn`) or a contract puts the instance on the nearest injector of that scope in the resolving chain; the adapter opens each invocation's injector in the `invocation` scope and disposes it when the invocation ends. Resolving a scoped record from outside its scope is an error, `optional` or not. - `currentInvocationInjector()` resolves the synchronous injection context, then the invocation's asynchronous flow, then the most recently opened invocation. Hooks resolve their by-name dependencies against it, and a definition run as given defaults its scope to it. An in-process dispatch closes the invocations it opened.
…invocation record Option groups and the list form of `options`, the collision rules, `CliOptions` and the spellings it protects, contributions and their timing, `providedIn` with its disposal, and `currentInvocationInjector()` with its lookup order. extensions.md states what an extension can use today and that a manifest-level contribution does not exist yet.
edusperoni
force-pushed
the
feat/options-machinery
branch
from
September 23, 2026 16:11
d9f9735 to
75009b0
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Checklist
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.mdandextensions.md:defineOptions(name, schema)returns a group that is both a schema and an injection token typed as the parsed values.optionson a definition or aCommand()meta takes a schema or a list of groups and schemas;ctx.optionsis typed as the merged values.CliOptionsis 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.CliOptionsto read those values typed. The six built-ins that redeclared--pathor--helpnow listCliOptions.OptionContributionscontract adds groups to a command by name, or to the root, before the parse that targets them. No manifest surface yet.providedInscopes. 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,optionalor not.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, andrunCommand(definition)defaults its scope to it. An in-process dispatch closes what it opened.No service is migrated onto a group in this PR.