80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
# ADR 0014: Share command-line presentation within each invocation
|
|
|
|
## Status
|
|
|
|
Accepted. Extends [ADR 0005](0005-invocation-outcomes.md) 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](../cli.md) define the implemented API, flags,
|
|
message formats, and delivery details. Those details can evolve within this
|
|
ownership model.
|