2026-11-07 02:42:54 +00:00
|
|
|
# ADR 0005: Separate application alias routing from canonical command ownership
|
|
|
|
|
|
|
|
|
|
## Status
|
|
|
|
|
|
2026-11-07 02:49:13 +00:00
|
|
|
Accepted.
|
2026-11-07 02:42:54 +00:00
|
|
|
|
|
|
|
|
## Date
|
|
|
|
|
|
|
|
|
|
2026-11-07; original decision made on 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
|
|
|
|
|
[ADR 0004](0004-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 the common assembly boundary in [ADR 0001](0001-command-dispatch-and-inputs.md).
|
|
|
|
|
Installation validates their relationships together and preserves canonical
|
|
|
|
|
ownership. Declaration capture, retained errors, and batch validation follow that
|
|
|
|
|
shared 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
|
|
|
|
|
|
|
|
|
|
- Wrapper commands would introduce additional nodes and handler delegation into
|
|
|
|
|
namespace ownership and invocation lifetimes.
|
|
|
|
|
- Application argument rewriting would repeat routing infrastructure and separate
|
|
|
|
|
alias handling from target validation, parsing, and help.
|
|
|
|
|
- A separate alias assembly API would split validation of commands and their
|
|
|
|
|
alternate routes across installation boundaries.
|
|
|
|
|
|
|
|
|
|
## Consequences
|
|
|
|
|
|
|
|
|
|
Applications can tailor vocabulary while reusing canonical behavior. Core must
|
|
|
|
|
coordinate routing, parsing, and help across those layers, while optional
|
|
|
|
|
integrations retain ownership of their command families.
|
|
|
|
|
|
|
|
|
|
GoDoc and the [CLI reference](../cli.md#application-owned-aliases) own exact API
|
|
|
|
|
shapes, resolution rules, and presentation choices. Those details can evolve
|
|
|
|
|
within this architectural separation.
|
