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

4
docs/consumers/guide.md
View File

@@ -120,8 +120,8 @@ conflicting rules are reported at installation. Identical rules are safe to
contribute from reusable helpers. The [core example](../../examples/core) and contribute from reusable helpers. The [core example](../../examples/core) and
[composed consumer](../../integrations/ckprompt/examples/composed) show complete [composed consumer](../../integrations/ckprompt/examples/composed) show complete
maintained wiring with ordinary command behavior alongside aliases. The maintained wiring with ordinary command behavior alongside aliases. The
[application-owned aliases roadmap](../roadmap/aliases.md) records the routing [Go declarations and GoDoc](../../command.go) own the public API contracts;
contract; the [CLI reference](../cli.md#application-owned-aliases) describes the [CLI reference](../cli.md#application-owned-aliases) owns routing and
operator-visible behavior. operator-visible behavior.
## ConfigKit scopes ## ConfigKit scopes

67
docs/roadmap/aliases.md
View File

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

14
docs/roadmap/remediation.md
View File

@@ -1,6 +1,6 @@
# Alias implementation review remediation # Alias implementation review remediation
Status: in progress; completed issues are marked individually below. Status: complete; R-1 through R-8 are addressed and marked individually below.
## Review scope and evidence ## Review scope and evidence
@@ -289,7 +289,7 @@ Go 1.26.8.
## R-8: Reconcile the completed feature roadmap's historical descriptions ## R-8: Reconcile the completed feature roadmap's historical descriptions
Status: open. Priority: P3. Category: documentation drift. Status: complete. Priority: P3. Category: documentation drift.
**Evidence:** [aliases.md](aliases.md) now declares implementation complete **Evidence:** [aliases.md](aliases.md) now declares implementation complete
but still has a `Current baseline` section saying the public model has no alias but still has a `Current baseline` section saying the public model has no alias
@@ -308,3 +308,13 @@ restart completed implementation stages or rewrite published release notes.
**Completion evidence:** Roadmap status, baseline, and API wording agree; **Completion evidence:** Roadmap status, baseline, and API wording agree;
consumer navigation identifies the canonical owners and the open remediation consumer navigation identifies the canonical owners and the open remediation
work is discoverable without claiming that these findings are already fixed. work is discoverable without claiming that these findings are already fixed.
**Completed:** The feature roadmap now labels its preimplementation baseline
and former short-option behavior as historical, identifies the APIs as
implemented, and links this completed review separately from the completed
implementation stages. Consumer navigation points to GoDoc and the maintained
CLI contract. Published release records and completed stage evidence were left
unchanged. Local links and fragment destinations in all three affected documents
resolve, and whitespace checks pass. Final uncached offline suites passed on
Go 1.26.8: root with the workspace disabled, plus both integration modules and
their maintained examples in the existing workspace against the local core.