69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
|
# ADR 0013: Separate application alias routing from canonical command ownership
|
||
|
|
|
||
|
|
## Status
|
||
|
|
|
||
|
|
Accepted. Refines [ADR 0011](0011-captured-declarations-and-installation.md)
|
||
|
|
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](0010-optional-integration-modules.md).
|
||
|
|
|
||
|
|
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](../cli.md) when implemented. Those details can evolve within
|
||
|
|
this architectural separation.
|