base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 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
[composed consumer](../../integrations/ckprompt/examples/composed) show complete
maintained wiring with ordinary command behavior alongside aliases. The
[application-owned aliases roadmap](../roadmap/aliases.md) records the routing
contract; the [CLI reference](../cli.md#application-owned-aliases) describes
[Go declarations and GoDoc](../../command.go) own the public API contracts;
the [CLI reference](../cli.md#application-owned-aliases) owns routing and
operator-visible behavior.
## ConfigKit scopes

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.

14
docs/roadmap/remediation.md
View File

@@ -1,6 +1,6 @@
# 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
@@ -289,7 +289,7 @@ Go 1.26.8.
## 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
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;
consumer navigation identifies the canonical owners and the open remediation
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.