3.5 KiB
ADR 0013: Separate application alias routing from canonical command ownership
Status
Accepted. Refines ADR 0011 by extending its shared installation boundary to application routing rules. Its canonical command ownership and declaration principles remain in force.
Date
2026-10-19
Context
Applications need alternate command paths and flag spellings that suit their operator vocabulary. These conveniences should reuse the behavior supplied by application commands and optional integrations. Canonical command families already establish ownership of handlers, namespaces, inputs, and invocation behavior.
A routing layer allows applications to choose alternate spellings while preserving those ownership boundaries. Commands and routing rules have distinct roles, and their relationships require validation during application assembly.
Decision
CommandKit core owns alias declaration, resolution, and coordination with parsing and help. Applications choose their alias mappings. Alias infrastructure is available independently of optional integrations under the module boundaries established by ADR 0010.
Aliases belong to an application routing layer that directs invocations to canonical commands and flags. Canonical definitions retain ownership of their handlers, inputs, and namespaces. An alternate path within an integration's namespace remains an application routing rule; the integration continues to own the canonical command family and its operations.
Canonical commands and routing rules are distinct declaration kinds installed through a common core assembly boundary. Installation validates their relationships together, preserves canonical definitions and namespace ownership, and applies the batch-atomicity and retained-error model of ADR 0011 to both layers. Declaration capture and reuse follow that existing model.
An invocation through an alias uses the canonical target's parsing, typed bindings, validation, and ordinary invocation lifecycle. Execution behavior remains with the canonical command and its owning application or integration. Core coordinates alternate routing and presentation through the same command infrastructure.
Alternatives considered
| Alternative | Analysis |
|---|---|
| Install aliases as wrapper commands | Reuses the command tree for discovery, but introduces additional command nodes and handler delegation into namespace ownership and invocation lifetimes. |
| Have applications rewrite arguments before dispatch | Gives applications direct control over shortcuts, but repeats routing infrastructure and separates alias handling from target validation, parsing, and help. |
| Register aliases through a separate assembly API | Makes routing declarations explicit, but splits validation of commands and their alternate routes across installation boundaries. Distinct declaration kinds express the separation within one atomic batch. |
Consequences
Applications can tailor operator vocabulary while reusing canonical behavior. Core maintains the relationship between routing rules and canonical definitions as declarations are installed. Optional integrations continue to supply their command families through the existing ownership model.
Routing, parsing, and help must coordinate across the two layers. Exact API shapes, resolution rules, and presentation choices belong in GoDoc and the CLI reference when implemented. Those details can evolve within this architectural separation.