3.8 KiB
ADR 0014: Share command-line presentation within each invocation
Status
Accepted. Extends ADR 0005 with shared reporting for each invocation. Its outcome classifications, standard status meanings, output channels, error-cause preservation, and application ownership of process exit remain in force.
Date
2026-10-25
Context
Applications need consistent control over command results, messages shown during a run, and messages shown at its end. Sharing that control reduces repeated output code across applications and integrations.
An application decides what an error means for its work. It may recover silently, show a warning, or end the invocation. CommandKit needs the chosen outcome and messages to present that decision to the operator.
Decision
CommandKit core provides one reporting facility for each invocation. Application commands, integration commands, and core commands use it for results, immediate messages, and deferred messages. Core applies shared rules for visibility, formatting, and delivery, and completes reporting when the invocation ends. Callers choose the output destinations.
Applications decide how to respond to domain-specific errors and choose their outcomes and messages. CommandKit may provide shared helpers for carrying, inspecting, and presenting errors while leaving those decisions with the application.
Applications supply explicit outcomes and explanations for failures. They may also supply a Go error cause. CommandKit keeps that error unchanged for the caller to inspect. Supplying a cause alone does not select an outcome or generate an operator-facing message. CommandKit remains responsible for handling its own errors, including routing, parsing, and presentation failures.
Integrations adapt upstream results and diagnostics into command outcomes and messages. The upstream libraries retain ownership of their meanings and rules for safe disclosure.
An Error message explains a failed invocation with a non-zero status. Its explanation is presented at the end of the invocation, after normal reporting finishes. The returned outcome carries that explanation. The application entry point decides how to exit the process.
CommandKit reports rendering and delivery failures separately from the command's explanation. A presentation failure produces an operational failure for standard outcomes under ADR 0005. Application-defined domain classifications are preserved, along with an already non-zero domain status. A successful domain outcome receives a non-zero status if presentation fails. The original explanation and any supplied cause remain available to the caller. Intentionally suppressed output is not a delivery failure.
Reporting keeps the state needed to deliver messages and return the invocation outcome. Logging and message history remain application concerns.
Alternatives considered
| Alternative | Analysis |
|---|---|
| Let each application manage all presentation | Gives applications full control, but repeats visibility and delivery code across commands and integrations. |
| Have core decide whether domain-specific errors require recovery, a warning, or failure | Reduces some caller code, but gives core decisions that depend on application behavior. |
| Use separate facilities for results, immediate messages, and deferred messages | Lets each facility serve one purpose, but spreads visibility and final delivery across several paths. |
Consequences
Applications and integrations share presentation behavior while choosing their own results and messages. Core handles reporting failures consistently and keeps them visible in the returned outcome.
GoDoc and the CLI reference define the implemented API, flags, message formats, and delivery details. Those details can evolve within this ownership model.