base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Correct alias examples to respect smoke-test operand grammar

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-19 14:26:49 +00:00
parent fae8c4dafa
commit f3b8a129d9
1 changed files with 25 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/roadmap/aliases.md
View File

@@ -45,9 +45,10 @@ and the internal backend coordinate parsing, help, and execution through one
invocation lifecycle. invocation lifecycle.
The current public model has no application alias layer. PromptKit already The current public model has no application alias layer. PromptKit already
exposes the collection catalog and smoke-test commands used in the examples exposes the collection catalog and smoke-test command used in the examples
below. These examples illustrate alternate routes to existing capabilities; below. `promptkit test` takes a `KIND` operand, including `all`; those values
they do not introduce new PromptKit operations. 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 The [CLI reference](../cli.md) owns current grammar. Options follow the complete
command path, can be interspersed with operands, and use `--` to terminate 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 | | Alias path | Target path |
| --- | --- | | --- | --- |
| `list collections` | `promptkit list collections` | | `list collections` | `promptkit list collections` |
| `promptkit test full` | `promptkit test all` | | `promptkit list bundles` | `promptkit list collections` |
| `list` | `promptkit list` | | `list` | `promptkit list` |
Aliases can target individual commands or groups. A group alias preserves 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: A group shortcut provides access to routes beneath its target, including aliases:
```text ```text
pk → promptkit pk → promptkit
promptkit test full → promptkit test all promptkit list bundles → promptkit list collections
``` ```
Here, `pk test full` resolves through `promptkit test full` to Here, `pk list bundles` resolves through `promptkit list bundles` to
`promptkit test all`. An explicitly declared `pk test full` alias would take `promptkit list collections`. An explicitly declared `pk list bundles` alias
precedence over `pk` at the initial lookup. Ordinary chains follow the same would take precedence over `pk` at the initial lookup. Ordinary chains follow the same
rules, for example `collections → list collections → promptkit list collections`. rules, for example `collections → list collections → promptkit list collections`.
Validate composition during installation and reject cycles and nonterminating 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 `Alias("fast", "run production")` when canonical `run` takes `production` as
an operand. Command aliases do not inject fixed operands. 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 An alias cannot conflict with or overload a canonical command path. Reject such
a declaration during installation as invalid application configuration. Apply a declaration during installation as invalid application configuration. Apply
the same protection when later registration adds a canonical command conflicting 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 | | 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 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. | | `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. | | `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 Expose the original entered command path and final resolved canonical command
path as read-only invocation metadata. Both paths exclude the executable name, path as read-only invocation metadata. Both paths exclude the executable name,
flags, and operands. For a direct canonical invocation the paths are equal; 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 Retain the endpoints through a chain; intermediate rewrites are not part of
the selected public metadata. 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. enumerate every route reachable through group shortcuts.
Group help includes relevant aliases separately from canonical children. For Group help includes relevant aliases separately from canonical children. For
example, `help promptkit test` shows `full → promptkit test all`. Help reached example, `help promptkit list` shows `bundles → promptkit list collections`.
through a group alias uses that spelling in usage examples and presents the 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. routes available through it, including applicable aliases beneath the target.
Account for more-specific mappings so displayed destinations match routing. 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 Include discovery-help contexts without canonical commands, longer aliases
beneath operand-taking command shortcuts, rejection of operand-bearing beneath operand-taking command shortcuts, rejection of operand-bearing
targets, and canonical flag endpoints alongside inactive global mappings. 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 6. Add maintained consumer examples and update GoDoc, the CLI reference, consumer
guidance, and internal documentation when implementation lands. Validate the guidance, and internal documentation when implementation lands. Validate the
affected modules under the [developer guide](../development.md). affected modules under the [developer guide](../development.md).