Skip to main content

Module output

doiget_cli::commands

Module output 

Source
Expand description

Output-mode resolution for the doiget CLI (ADR-0017, #144; Amendment 1 = #219/#220).

ADR-0017 specifies the precedence ladder --mode > --json/--quiet > DOIGET_MODE env > subcommand-implicit > TTY > quiet. CONFIG.md §5 additionally pins doiget serve to mcp mode regardless of flags — a load-bearing security invariant (the stdout-purity Slice 9 CI job already enforces “MCP mode forbids non-JSON stdout”). The forced_implicit parameter to resolve expresses that override: when Some(_), it overrides everything else.

resolve returns a ResolvedOutput carrying the OutputMode plus a quiet_was_explicit discriminator. The distinction is load-bearing per ADR-0017 Amendment 1: artifact-producing commands (bib / csl / capabilities / audit-log --verify --mode json) suppress only on explicit Quiet (--quiet / -q / DOIGET_MODE=quiet / --mode quiet), not on the non-TTY default. Informational commands continue to suppress on any Quiet.

Resolution is split into a pure function (resolve) plus a thin TTY-detection wrapper (stdout_is_tty) so the ladder is fully unit-testable without environment manipulation.

§Per-mode honoring across the CLI surface

  • Human — default for TTY stdout. Human-readable text, the pre-#144 behaviour.
  • Quiet — informational stdout suppressed across the six info-emitting commands (audit-log / info / list-recent / search / config show / config path / provenance migrate) per #203. Errors (stderr) and exit codes are unaffected. Product-output commands (bib / csl / graph / *-dry-run / batch JSONL) are NOT suppressed.
  • Json — structured JSON bodies for the human-table commands (#204) plus the ERRORS.md §3 JSON-Lines per-ref shape for batch (#205). Single-value-per-stdout for the table commands; line-oriented for batch.
  • Mcp — JSON-RPC framing on stdout (only reachable via doiget serve; forced by forced_implicit_for in main.rs).

§JSON wire conventions (a single-line note)

Two intentional conventions live side-by-side in the codebase, and they are different on purpose:

  1. Pretty-printed single value for the table commands’ --mode json bodies (info / list-recent / search / config show / audit-log / provenance migrate). Optimised for | jq . and human-on-a-screen reading.
  2. Compact JSON-Lines for batch --mode json per the ERRORS.md §3 CI persona — one record per stdout line, no embedded newlines, so a consumer can split('\n').map(json.loads).

Future-maintainer reminder: do NOT unify these by accident — they serve different consumers.

Structs§

ResolvedOutput
The resolved output state per ADR-0017 Amendment 1: the OutputMode the resolution ladder picked, plus a quiet_was_explicit discriminator that distinguishes the user’s explicit request for silence (--quiet / -q / DOIGET_MODE=quiet / --mode quiet) from the resolver’s implicit fallback to Quiet when stdout is not a TTY.

Enums§

FlagInput
Which short-form implication, if any, was given on the command line.
OutputMode
The four output modes from docs/CONFIG.md §3 / ADR-0017.

Functions§

is_artifact_command
true if name identifies an artifact-producing subcommand whose stdout output IS the deliverable (per ADR-0017 Amendment 1). Artifact commands suppress only on explicit Quiet (ResolvedOutput::quiet_was_explicit == true).
parse_env_mode
Parse a DOIGET_MODE env-var value. Recognises the four CONFIG.md §3 modes case-insensitively; returns None for empty, whitespace-only, or unrecognised input (the resolution ladder then falls through to TTY detection).
resolve
Resolve the effective OutputMode per ADR-0017 and the quiet_was_explicit discriminator per ADR-0017 Amendment 1.
stdout_is_tty
true if stdout is attached to a terminal. Wraps the standard library’s std::io::IsTerminal probe; the trait is in scope only here so test code can call resolve with a synthetic is_tty boolean without linking to IsTerminal.