From fae8c4dafac20298a894b5c90cf32e0fbb5b309d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 19 Oct 2026 14:21:12 +0000 Subject: [PATCH] Accept ADR 0013 for application alias routing --- docs/adr/0013-application-alias-routing.md | 68 ++++++++++++++++++++++ docs/roadmap/aliases.md | 18 +++--- 2 files changed, 76 insertions(+), 10 deletions(-) create mode 100644 docs/adr/0013-application-alias-routing.md diff --git a/docs/adr/0013-application-alias-routing.md b/docs/adr/0013-application-alias-routing.md new file mode 100644 index 0000000..b1a96f2 --- /dev/null +++ b/docs/adr/0013-application-alias-routing.md @@ -0,0 +1,68 @@ +# 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. diff --git a/docs/roadmap/aliases.md b/docs/roadmap/aliases.md index a77b99e..0e061dd 100644 --- a/docs/roadmap/aliases.md +++ b/docs/roadmap/aliases.md @@ -3,6 +3,8 @@ Status: command- and flag-alias behavior and consumer API direction accepted; implementation has not started. OD-1 through OD-6 are resolved. This roadmap records the target and work needed before implementation. +[ADR 0013](../adr/0013-application-alias-routing.md) records the accepted +architectural ownership and shared installation decisions. ## Purpose and ownership @@ -565,28 +567,24 @@ dynamic value completion remain future design work. covering a command shortcut, a synonym inside an integration namespace, and a group shortcut, an application-wide help flag alias, and a command-scoped flag alias reached through a command shortcut. -2. Capture the durable separation between application alias routing and canonical - command and flag ownership in an ADR. Keep exact API, matching, and presentation - details in their appropriate contracts. No relaxation of canonical namespace - ownership is selected. -3. Establish termination-validation behavior with focused evidence for valid +2. Establish termination-validation behavior with focused evidence for valid repetitions, suffix-dependent cycles, and growing prefix expansions before building the rest of routing around the algorithm. -4. Implement the selected declaration types and shared path primitives. Define +3. Implement the selected declaration types and shared path primitives. Define and verify installation handling for nil declarations and zero `RoutingRule` values alongside the existing invalid-zero and explicit-absence command contracts. Validate flag declarations as individual spellings. Extend installation to validate aliases and commands against the complete candidate batch, preserving retained errors and atomicity. Keep aliases independent of optional-library dependencies and backend-specific exports. -5. Integrate command and flag alias resolution with canonical routing, help, and +4. Integrate command and flag alias resolution with canonical routing, help, and invocation identity. Use canonical flag metadata and the existing parser to preserve values and operands, and reuse typed execution machinery. Apply the selected short-option grammar and correct explicit empty values for canonical short spellings and aliases together. Keep metadata lookup separate from execution and help rendering as described under future shell completion, without implementing completion in this delivery. -6. Add focused behavioral evidence for both example mappings, group aliases, +5. Add focused behavioral evidence for both example mappings, group aliases, longest matches, chains, group composition, cycles and nonterminating prefix expansion, collisions, missing targets, same-batch resolution, later registration, argument preservation, help without @@ -598,10 +596,10 @@ dynamic value completion remain future design work. Include discovery-help contexts without canonical commands, longer aliases beneath operand-taking command shortcuts, rejection of operand-bearing targets, and canonical flag endpoints alongside inactive global mappings. -7. Add maintained consumer examples and update GoDoc, the CLI reference, consumer +6. Add maintained consumer examples and update GoDoc, the CLI reference, consumer guidance, and internal documentation when implementation lands. Validate the affected modules under the [developer guide](../development.md). -8. Document migration from `...Command` to `...Declaration`, including slice +7. Document migration from `...Command` to `...Declaration`, including slice conversion, and the explicit empty-value correction. Include the compatibility impact and required consumer action in release notes under the [release policy](../policy/release.md#versioning-and-compatibility).