Module output 

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

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 (extended by Amendment 2, #301): artifact-producing commands — export/inventory (bib / csl / capabilities) and read/inspection (info / list-recent / search / link / text), plus 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. See is_artifact_command.

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 — stdout suppressed for informational commands whose stdout is a status report (audit-log Human / config show / config path / provenance migrate / fetch + batch status) per #203. Errors (stderr) and exit codes are unaffected. Artifact commands — whose stdout IS the requested product — suppress ONLY on explicit Quiet, never on the non-TTY implicit fallback: export/inventory (bib / csl / capabilities) per Amendment 1, and read/inspection (info / list-recent / search / link / text) per Amendment 2 (#301). See is_artifact_command.
• 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, extended by Amendment 2). Artifact commands suppress only on explicit Quiet (ResolvedOutput::quiet_was_explicit == true), never on the non-TTY implicit fallback.

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).

print_err

Stderr sink for the docs/ERRORS.md §3 human lines — errors, = note: advisories, progress and skip notes.

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.