193 lines
8.7 KiB
Markdown
193 lines
8.7 KiB
Markdown
# Application-owned aliases
|
|
|
|
Status: command-alias direction accepted; implementation has not started.
|
|
Public API and remaining routing details are open. Flag aliasing is under
|
|
discussion. This roadmap records the target and work needed before implementation.
|
|
|
|
## Purpose and ownership
|
|
|
|
Make alternate command spellings and shorter paths simple for consuming
|
|
applications to declare. CommandKit core owns alias registration, resolution,
|
|
and integration with routing and help. Applications choose their aliases.
|
|
Integrated libraries continue to own their canonical command behavior.
|
|
|
|
Aliases occupy a separate application routing layer above installed canonical
|
|
commands:
|
|
|
|
```text
|
|
CLI argument tokens
|
|
→ command-path alias resolution
|
|
→ canonical command routing and parsing
|
|
→ ordinary invocation lifecycle
|
|
```
|
|
|
|
Alias declarations do not install new handlers or modify the canonical command
|
|
tree. An alias spelled inside `promptkit` therefore does not add an
|
|
application-owned operation to the integration's namespace. The ownership and
|
|
placement rules in [ADR 0011](../adr/0011-captured-declarations-and-installation.md)
|
|
and the [architecture policy](../policy/architecture.md) continue to govern
|
|
canonical command installation.
|
|
|
|
## Current baseline
|
|
|
|
Core captures reusable `Command` declarations and installs them through `New`
|
|
and `App.Register`. Installation validates a batch before registry mutation.
|
|
Optional standard families own their installed root namespaces. Core routing
|
|
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.
|
|
|
|
The [CLI reference](../cli.md) owns current grammar. Options follow the complete
|
|
command path, can be interspersed with operands, and use `--` to terminate
|
|
option parsing. Aliasing preserves the target's grammar and typed binding
|
|
contracts.
|
|
|
|
## Selected command-alias behavior
|
|
|
|
### Paths and resolution
|
|
|
|
Declare mappings between command paths relative to the application root. The
|
|
executable name is not part of either path:
|
|
|
|
| Alias path | Target path |
|
|
| --- | --- |
|
|
| `list collections` | `promptkit list collections` |
|
|
| `promptkit test full` | `promptkit test all` |
|
|
| `list` | `promptkit list` |
|
|
|
|
Aliases can target individual commands or groups. A group alias preserves
|
|
remaining subcommand tokens. For example, `list collections` can reach
|
|
`promptkit list collections` through the `list` group alias.
|
|
|
|
Match complete argument tokens at the beginning of the command path. Resolve
|
|
overlapping alias paths using the longest match. Preserve trailing arguments,
|
|
including flags, operands, explicit empty values, and `--`, for canonical
|
|
parsing. Values and operands are not searched for alias text.
|
|
|
|
Support alias chains and resolve them to their canonical target. Validate
|
|
targets and reject cycles during installation. Resolution must terminate;
|
|
the treatment of group-prefix composition is part of the remaining detailed
|
|
design.
|
|
|
|
The initial command-alias feature maps command paths. Preset flags, operand
|
|
transformation, and arbitrary argument rewriting are outside this delivery.
|
|
|
|
### Installation and collisions
|
|
|
|
Provide a small core API for aliases that composes with installation of
|
|
application and integration commands. The public declaration and registration
|
|
shape remains open; earlier illustrative `Alias` calls are not a settled Go API.
|
|
|
|
An alias target may already be installed or be supplied in the same installation
|
|
batch. Declaration order within that batch does not affect resolution. Missing
|
|
targets, collisions, and cycles produce installation errors with useful path
|
|
context. Failed installation preserves the existing application registry and
|
|
alias mappings under the existing batch-atomicity model.
|
|
|
|
Reject aliases that shadow existing canonical command paths. Preserve that
|
|
protection when later registration adds commands. Detailed prefix interactions
|
|
remain open below. Aliases do not create canonical parent groups, merge
|
|
integration trees, or replace handlers.
|
|
|
|
### Execution and help
|
|
|
|
An invocation through an alias uses the canonical target's flags, operands,
|
|
defaults, typed bindings, input preparation, providers, diagnostics, and
|
|
outcomes. Execute the ordinary lifecycle once. Alias registration, resolution,
|
|
and help do not invoke application input/state factories or acquisition callbacks.
|
|
|
|
Retain the entered alias path and resolved canonical path for routing and
|
|
presentation. Whether this identity is exposed through the public invocation
|
|
API remains open.
|
|
|
|
Support both help forms:
|
|
|
|
```text
|
|
scriptorium help list collections
|
|
scriptorium list collections --help
|
|
```
|
|
|
|
Alias help describes the canonical target's inputs using the alias invocation
|
|
path and identifies the canonical command. Root help presents aliases separately
|
|
from canonical commands. Group help and discovery details remain to be specified.
|
|
|
|
## Work needed from the baseline
|
|
|
|
1. Settle the public alias API and the open routing details with consumer examples
|
|
covering a command shortcut, a synonym inside an integration namespace, and
|
|
a group shortcut.
|
|
2. Capture the durable separation between application alias routing and canonical
|
|
namespace ownership in an ADR. Keep exact API, matching, and presentation
|
|
details in their appropriate contracts. No relaxation of canonical namespace
|
|
ownership is selected.
|
|
3. Extend installation to validate aliases and commands against the complete
|
|
candidate batch, preserving retained errors and atomicity. Keep aliases
|
|
independent of optional-library dependencies and backend-specific exports.
|
|
4. Integrate alias resolution with canonical routing, help, and invocation
|
|
identity. Reuse the existing parser and typed execution machinery.
|
|
5. Add focused behavioral evidence for both example mappings, group aliases,
|
|
longest matches, chains and cycles, collisions, missing targets, same-batch
|
|
resolution, later registration, argument preservation, help without
|
|
acquisition, and a single execution lifecycle.
|
|
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).
|
|
|
|
Completion means consumers can declare alternate paths with minimal wiring,
|
|
receive installation-time feedback, and invoke canonical behavior and help
|
|
through those paths while canonical namespace ownership stays intact.
|
|
|
|
## Flag aliasing under discussion
|
|
|
|
The same application routing concept may support alternate flag spellings,
|
|
such as `--hlep` mapping to `--help`, while leaving canonical flags and bindings
|
|
unchanged. The user-facing API should be comparably simple to command aliases.
|
|
Scope, token handling, registration, and help behavior need further discussion;
|
|
no specific flag-alias API or resolution policy is selected here.
|
|
|
|
## Open Decisions
|
|
|
|
### OD-1: Public declaration and registration API
|
|
|
|
What are the exact alias declaration, path representation, and installation
|
|
signatures? How do alias declarations compose with groups, reusable declarations,
|
|
and later `App.Register` calls? What are the duplicate-declaration semantics?
|
|
|
|
### OD-2: Prefix interactions and canonical reachability
|
|
|
|
How are collisions determined when alias sources or targets overlap canonical
|
|
groups or runnable commands with children? How does longest matching interact
|
|
with operand boundaries? Which later registrations conflict with existing
|
|
aliases? How are ambiguous paths reported?
|
|
|
|
### OD-3: Chains and group aliases
|
|
|
|
How do group aliases compose with more specific aliases and with aliases inside
|
|
their target paths? At what boundaries is resolution repeated? How are cycles
|
|
and nonterminating prefix expansion detected without confusing operands with
|
|
command-path tokens?
|
|
|
|
### OD-4: Help and discovery
|
|
|
|
How are aliases listed, grouped, and described in help? What happens when an
|
|
operator requests a parent of an alias path that has no canonical group? How
|
|
does group-alias help present descendants? How are entered and canonical paths
|
|
shown in usage errors?
|
|
|
|
### OD-5: Invocation identity
|
|
|
|
Does the public invocation API expose entered and canonical command paths?
|
|
What identity is retained through a chain, and how is it represented for help
|
|
and diagnostic presentation?
|
|
|
|
### OD-6: Flag alias scope and composition
|
|
|
|
What is the flag-alias API and its installation scope? How does it compose with
|
|
command aliases, canonical local flags, and built-in help? Which long and short
|
|
flag forms are supported? How are values, `--`, chains, collisions, missing
|
|
targets, help, and diagnostic spelling handled?
|