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

Reconcile alias documentation with the completed implementation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-20 00:30:53 +00:00
parent 520d7e125b
commit f42aefe02d
3 changed files with 50 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/roadmap/aliases.md
View File

@@ -1,10 +1,12 @@
# Application-owned aliases
Status: implementation complete; core v0.3.0 release note prepared and
publication pending. OD-1 through OD-6 are resolved. This roadmap records the
target and selected behavior. The
[staged implementation plan](implementation.md) owns delivery sequencing and
stage-specific validation.
Status: implementation and [review remediation](remediation.md) complete;
core v0.3.0 release note prepared and publication pending. OD-1 through OD-6
are resolved. This roadmap records the target and selected behavior. The
[completed implementation plan](implementation.md) preserves delivery sequencing
and stage-specific validation. Current contracts belong to the
[Go declarations and GoDoc](../../command.go) and
[CLI reference](../cli.md#application-owned-aliases).
[ADR 0013](../adr/0013-application-alias-routing.md) records the accepted
architectural ownership and shared installation decisions.
@@ -38,19 +40,19 @@ Flag aliases likewise leave canonical flag definitions and typed bindings
unchanged. This is one conceptual routing layer; its internal implementation
cooperates with the existing parser to preserve token interpretation.
## Current baseline
## Preimplementation 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.
At the planning baseline, core captured reusable `Command` declarations and
installed them through `New` and `App.Register`. Installation validated a batch
before registry mutation. Optional standard families owned their installed root
namespaces. Core routing and the internal backend coordinated 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 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.
That public model had no application alias layer. PromptKit already exposed
the collection catalog and smoke-test command used in the examples below.
`promptkit test` took a `KIND` operand, including `all`; those values were not
registered child commands. The 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
@@ -66,8 +68,8 @@ API is needed.
### Installation types and composition
Introduce a common `Declaration` interface with an unexported marker method.
CommandKit supplies its implementations through public factories. `Command`
The delivered API has a common `Declaration` interface with an unexported marker
method. CommandKit supplies its implementations through public factories. `Command`
represents canonical commands; a separate opaque `RoutingRule` represents
aliases. Both satisfy `Declaration`:
@@ -120,7 +122,7 @@ app, err := commandkit.New(
)
```
These are planned APIs. Later registration uses the same model and validation.
These APIs are implemented. Later registration uses the same model and validation.
Accept identical duplicate alias mappings as harmless, including when reusable
helpers contribute them. Identity includes the alias kind, source, target, and
@@ -513,11 +515,11 @@ A spelling such as `-color` follows short-option parsing; long aliases use
the `--` prefix. Options still follow the complete command path, and `--`
ends option parsing.
Correct explicit empty-value handling for both canonical short spellings and
aliases: `-c=` supplies an empty string, consistently with `--color=` and
`-c ""`. The current backend instead passes the literal string `"="` for `-c=`;
this delivery corrects that behavior. Likewise, `-v=` supplies an empty value
to boolean conversion and fails conversion. This correction preserves the
Explicit empty-value handling was corrected for both canonical short spellings
and aliases: `-c=` supplies an empty string, consistently with `--color=` and
`-c ""`. The preimplementation backend passed the literal string `"="` for `-c=`;
the delivered implementation corrects that behavior. Likewise, `-v=` supplies an
empty value to boolean conversion and fails conversion. This correction preserves the
distinction between an omitted value and an explicitly supplied empty value.
### Flag help and diagnostics
@@ -574,8 +576,10 @@ dynamic value completion remain future design work.
## Delivery and compatibility
The [implementation plan](implementation.md) defines the ordered work from the
current baseline, implementation choices, and evidence for the selected behavior.
The [completed implementation plan](implementation.md) records the ordered work
from the planning baseline, implementation choices, and stage evidence for the
selected behavior. The [review remediation](remediation.md) records subsequent
findings, corrections, and validation without restarting those stages.
The delivered feature includes maintained consumer examples, GoDoc, CLI and
consumer guidance, and internal documentation matching the implemented owners.
@@ -583,11 +587,12 @@ Consumer guidance and release notes explain migration from `...Command` to
`...Declaration`, including slice conversion, and the explicit short-option
empty-value correction under the
[release policy](../policy/release.md#versioning-and-compatibility). Nil and zero
declaration handling is specified by the implementation plan alongside the
existing invalid-zero and explicit-absence command contracts.
declaration handling is documented in the
[Go declarations and GoDoc](../../command.go) alongside the invalid-zero and
explicit-absence command contracts.
This delivery is complete when consumers can declare alternate command paths
and flag spellings with minimal wiring and invoke canonical behavior and help through
them while canonical ownership and binding semantics stay intact. Installation
The delivery goal was to let consumers declare alternate command paths
and flag spellings with minimal wiring and invoke canonical behavior and help
through them while canonical ownership and binding semantics stay intact. Installation
rejects conflicts with canonical commands and applicable flags in either
registration order.