2.9 KiB
ADR 0005: Separate application alias routing from canonical command ownership
Status
Accepted. Renumbered during the alpha ADR cleanup.
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.
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. 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 own exact API shapes, resolution rules, and presentation choices. Those details can evolve within this architectural separation.