diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index 0e061dd..3ca32f3 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -45,9 +45,10 @@ and the internal backend coordinate parsing, help, and execution through one invocation lifecycle. The current public model has no application alias layer. PromptKit already -exposes the collection catalog and smoke-test commands used in the examples -below. These examples illustrate alternate routes to existing capabilities; -they do not introduce new PromptKit operations. +exposes the collection catalog and smoke-test command used in the examples +below. `promptkit test` takes a `KIND` operand, including `all`; those values +are not registered child commands. These examples illustrate alternate routes +to existing capabilities; they do not introduce new PromptKit operations. The [CLI reference](../cli.md) owns current grammar. Options follow the complete command path, can be interspersed with operands, and use `--` to terminate @@ -170,7 +171,7 @@ executable name is not part of either path: | Alias path | Target path | | --- | --- | | `list collections` | `promptkit list collections` | -| `promptkit test full` | `promptkit test all` | +| `promptkit list bundles` | `promptkit list collections` | | `list` | `promptkit list` | Aliases can target individual commands or groups. A group alias preserves @@ -212,13 +213,13 @@ boundary rules below. A group shortcut provides access to routes beneath its target, including aliases: ```text -pk → promptkit -promptkit test full → promptkit test all +pk → promptkit +promptkit list bundles → promptkit list collections ``` -Here, `pk test full` resolves through `promptkit test full` to -`promptkit test all`. An explicitly declared `pk test full` alias would take -precedence over `pk` at the initial lookup. Ordinary chains follow the same +Here, `pk list bundles` resolves through `promptkit list bundles` to +`promptkit list collections`. An explicitly declared `pk list bundles` alias +would take precedence over `pk` at the initial lookup. Ordinary chains follow the same rules, for example `collections → list collections → promptkit list collections`. Validate composition during installation and reject cycles and nonterminating @@ -253,6 +254,13 @@ without leftover operand tokens. For example, reject `Alias("fast", "run production")` when canonical `run` takes `production` as an operand. Command aliases do not inject fixed operands. +Likewise, `promptkit test full → promptkit test all` is invalid: `all` is an +operand of canonical `promptkit test KIND`, and the source would intercept +that command's operand space. A command-path shortcut such as +`smoke → promptkit test` is valid; `smoke all` preserves the operator-supplied +`all` operand. Synonyms for operand values require a separate capability and +are outside this delivery. + An alias cannot conflict with or overload a canonical command path. Reject such a declaration during installation as invalid application configuration. Apply the same protection when later registration adds a canonical command conflicting @@ -271,7 +279,7 @@ operand space of runnable commands. | Canonical declaration | Proposed alias | Result | | --- | --- | --- | -| `promptkit test all` | `promptkit test full` → `promptkit test all` | Allow the distinct route beneath the shared prefix. | +| `promptkit list collections` | `promptkit list bundles` → `promptkit list collections` | Allow the distinct route beneath the shared prefix. | | `list projects` | `list collections` → `promptkit list collections` | Allow the distinct route beneath the shared prefix. | | `list` group | `list` → `promptkit list` | Reject replacement of the canonical group path. | | `run` accepts an operand | `run full` → another command | Reject interception of `full` in the canonical command's operand space. | @@ -305,7 +313,8 @@ and help do not invoke application input/state factories or acquisition callback Expose the original entered command path and final resolved canonical command path as read-only invocation metadata. Both paths exclude the executable name, flags, and operands. For a direct canonical invocation the paths are equal; -for `app pk test full`, they can be `pk test full` and `promptkit test all`. +for `app pk list bundles`, they can be `pk list bundles` and +`promptkit list collections`. Retain the endpoints through a chain; intermediate rewrites are not part of the selected public metadata. @@ -335,8 +344,8 @@ canonical targets. Ordinary help need not show intermediate chain mappings or enumerate every route reachable through group shortcuts. Group help includes relevant aliases separately from canonical children. For -example, `help promptkit test` shows `full → promptkit test all`. Help reached -through a group alias uses that spelling in usage examples and presents the +example, `help promptkit list` shows `bundles → promptkit list collections`. +Help reached through a group alias uses that spelling in usage examples and presents the routes available through it, including applicable aliases beneath the target. Account for more-specific mappings so displayed destinations match routing. @@ -596,6 +605,9 @@ dynamic value completion remain future design work. Include discovery-help contexts without canonical commands, longer aliases beneath operand-taking command shortcuts, rejection of operand-bearing targets, and canonical flag endpoints alongside inactive global mappings. + Verify rejection of `promptkit test full → promptkit test all` and + preservation of the supplied `all` operand through the valid + `smoke → promptkit test` shortcut. 6. Add maintained consumer examples and update GoDoc, the CLI reference, consumer guidance, and internal documentation when implementation lands. Validate the affected modules under the [developer guide](../development.md).