Define a Global CLI Output Contract for the Tracker (ADR)

[josecelano]

Goal

Write a repository-wide Architectural Decision Record (ADR) that establishes a single, canonical command-line output contract for every first-party, operator-facing CLI entrypoint in the torrust-tracker repository, aligning with the approach adopted by torrust-index (ADR-T-010) and reflecting the reality that AI agents are the dominant CLI consumers today.

This ADR is prescriptive. The current codebase does not yet comply with the rules it establishes. Existing binaries will be migrated progressively in a separate follow-up issue.

Key rules (to be codified in the ADR)

• Both stdout and stderr are machine-readable JSON — no plain text on either channel.
• Stdout = result data (one JSON object + newline on success; empty on failure).
• Stderr = diagnostics — internal tracing records and user-facing progress events, both as NDJSON (filterable by record kind/type).
• TTY refusal adopted: commands with stdout result data refuse when stdout is a TTY (exit 2 + JSON stderr diagnostic).
• Exit codes: 0 success, 1 runtime failure, 2 usage/TTY/argv failure.
• Shared Rust infrastructure package (packages/tracker-cli-common) to be decided.
• Workspace lint guards clippy::print_stdout / clippy::print_stderr (interacts with chore: migrate lint configuration to [workspace.lints] in Cargo.toml #1786).
• Redaction policy for secrets in JSON diagnostics.
• AI agent output capture recommendation: per-command redirection to .tmp/<cmd>.stdout / .tmp/<cmd>.stderr.

Scope — in-scope binaries

• src/main.rs — tracker server (no-stdout-result class)
• src/bin/http_health_check.rs — stdout-result-data class
• src/bin/e2e_tests_runner.rs, src/bin/qbittorrent_e2e_runner.rs — TBD
• src/bin/profiling.rs — likely developer-only; may be out of normative scope
• console/tracker-client/ — all subcommands

Relationship to existing contracts

The tracker-client local ADR (console/tracker-client/docs/adrs/20260512080000_define_tracker_cli_io_contract_and_error_handling.md) will be superseded by this global ADR once accepted.

Full spec

docs/issues/open/1798-global-cli-output-contract-adr.md

References

• Index ADR-T-010: https://github.com/torrust/torrust-index/blob/develop/adr/010-global-command-line-output-contract.md
• Deployer UX research: console-output-logging-strategy, console-stdout-stderr-handling, user-output-vs-logging-separation
• Related: chore: migrate lint configuration to [workspace.lints] in Cargo.toml #1786 (workspace lints migration)