feat!: Global command-line output contract (ADR-T-010)

[peer-cat]

Summary

Lands ADR-T-010 end to end: every shipped, documented, or operator-facing first-party Torrust Index command-line entrypoint now follows one JSON-only stream contract.

Stdout is reserved for machine-readable result data. Stderr carries machine-readable diagnostics and control records as JSON/NDJSON. Commands that emit stdout result data refuse direct terminal stdout, so automation cannot accidentally mix data streams with human-facing diagnostics.

⚠ Breaking for operators and scripts. Any automation that scraped previous plain-text output from helper binaries, root maintenance commands, parse_torrent, server logs, or container startup must switch to exit codes plus JSON/NDJSON parsing.

Why

ADR-T-009 introduced strict stream rules for container helper binaries, but the underlying problem was repository-wide: every CLI entrypoint had its own stdout/stderr behavior.

That made shell integration brittle:

• helper JSON could be corrupted by plain diagnostics;
• clap help/errors and Rust panic output could still leak raw text;
• server and maintenance logs were not consistently machine-readable;
• parse_torrent and maintenance tools mixed operator text with command results;
• container startup used plain text and DEBUG=1 shell tracing instead of structured records;
• command-reachable libraries could still print or exit outside the command boundary.

This PR promotes the helper contract into a global CLI contract and migrates the existing command surface to match it.

Highlights

• ADR-T-010 becomes canonical. adr/010-global-command-line-output-contract.md now records the completed repository-wide contract, command classifications, shared schema, implementation summary, redaction policy, and guards.
• Shared CLI infrastructure. torrust-index-cli-common now owns JSON clap help/version/usage handling, stderr control-plane records, baseline exit classes, JSON panic diagnostics, JSON tracing setup, TTY refusal, stdout JSON emission, command runners, locked stderr writes, and redaction helpers.
• Helper binaries migrated. torrust-index-auth-keypair, torrust-index-config-probe, and torrust-index-health-check now share the same JSON control plane. Successful stdout payloads are single JSON objects with a top-level schema field; help, version, argv errors, TTY refusal, panic diagnostics, and tracing go to stderr as JSON.
• Server logging boundary migrated. torrust-index now emits JSON tracing records on stderr. The configured logging threshold remains the default filter, while non-empty RUST_LOG takes precedence. Binary entrypoints return explicit ExitCode values instead of relying on Rust default termination.
• Torrent helper commands migrated. parse_torrent is now a stdout-result command emitting schema, torrent, original_v1_info_hash, and input_byte_length. create_test_torrent is a no-stdout side-effect command with JSON stderr diagnostics.
• Maintenance commands migrated. import_tracker_statistics, seeder, and upgrade now keep stdout empty and emit help, usage errors, status, diagnostics, tracing, and panic records as JSON/NDJSON on stderr.
• Upgrade path hardened. The v1-to-v2 upgrader now propagates typed errors for setup, migrations, transfer validation, torrent decoding, missing fields, and timestamp conversion instead of relying on plain output, color formatting, unwraps, or panic-driven failures.
• Command-reachable libraries cleaned up. Shutdown notices use structured tracing, mail template failures are returned to callers, terminal color formatting is removed from command paths, and parsing helpers leave reporting to their command callers.
• Container entry script migrated. Startup validation failures, status notices, expected utility failures, jq failures, unexpected shell exits, and DEBUG=1 phase records now emit JSON/NDJSON on stderr. Helper stdout stays internal to command substitutions.
• Regression guards added. Workspace Clippy now denies accidental raw print_stdout, print_stderr, and direct exit usage outside approved boundaries, and tests/cli_contract.rs keeps in-scope binaries returning ExitCode.

Breaking Changes

Surface	Before	After
CLI stream contract	Per-command stdout/stderr behavior	ADR-T-010 JSON-only contract across first-party entrypoints
Server logs	Human-formatted tracing output	JSON records on stderr
Helper stdout schemas	Some payloads lacked explicit schema versioning	Successful helper payloads include top-level schema
Helper help/errors/panics	Plain clap or Rust panic text could reach stderr	JSON control-plane records on stderr
parse_torrent	Legacy plain-text CLI behavior	Single JSON stdout result; refuses direct terminal stdout
create_test_torrent	Plain status/diagnostic output	Empty stdout; JSON/NDJSON stderr
import_tracker_statistics, seeder, upgrade	Plain status/errors and panic/unwrap paths	Empty stdout; JSON/NDJSON stderr; explicit exit codes
Container entry script	Plain startup text and DEBUG=1 / set -x tracing	JSON/NDJSON stderr records and explicit debug phase records
Command libraries	Some direct printing/exiting/color formatting	Structured diagnostics returned or logged through the command boundary

Operator Migration

Stdout-producing commands should be piped or redirected before inspection:

torrust-index-auth-keypair | jq .
torrust-index-config-probe | jq .
torrust-index-health-check http://127.0.0.1:3001/health_check | jq .
cargo run --quiet --bin parse_torrent -- "$fixture" | jq .'

Credits

Thank-you for @da2ce7 for writing the ADR 10, and starting the work.

[codecov]

Codecov Report

❌ Patch coverage is 53.53626% with 519 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.53%. Comparing base (70ba64c) to head (5a6dab0).

Files with missing lines	Patch %	Lines
packages/index-cli-common/src/lib.rs	51.85%	177 Missing and 5 partials ⚠️
src/console/commands/seeder/api.rs	0.00%	48 Missing ⚠️
..._0_0_to_v2_0_0/transferrers/torrent_transferrer.rs	62.76%	31 Missing and 4 partials ⚠️
src/console/commands/seeder/app.rs	0.00%	30 Missing ⚠️
...rc/console/cronjobs/tracker_statistics_importer.rs	18.75%	25 Missing and 1 partial ⚠️
src/bin/create_test_torrent.rs	76.71%	13 Missing and 4 partials ⚠️
src/main.rs	0.00%	17 Missing ⚠️
src/bin/parse_torrent.rs	80.28%	13 Missing and 1 partial ⚠️
...auth-keypair/src/bin/torrust-index-auth-keypair.rs	68.29%	13 Missing ⚠️
...0_0_to_v2_0_0/transferrers/category_transferrer.rs	69.04%	13 Missing ⚠️
... and 18 more

Additional details and impacted files

@@            Coverage Diff            @@
##           develop     #869    +/-   ##
=========================================
  Coverage    68.53%   68.53%            
=========================================
  Files          161      161            
  Lines        12394    13111   +717     
  Branches     12394    13111   +717     
=========================================
+ Hits          8494     8986   +492     
- Misses        3647     3850   +203     
- Partials       253      275    +22     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Lands ADR-T-010, replacing per-command stdout/stderr behavior with a global JSON-only CLI output contract across every first-party Torrust Index entrypoint. Helpers, server, maintenance commands, and the container entry script now emit machine-readable JSON/NDJSON on stderr while reserving stdout for typed result payloads. The upgrade path is refactored from panic/unwrap flows to typed UpgradeError propagation, and a regression test enforces ExitCode mains for in-scope binaries.

Changes:

• Migrate all in-scope binaries (helpers, server, parse_torrent, create_test_torrent, import_tracker_statistics, seeder, upgrade) to JSON stdout/NDJSON stderr with explicit ExitCode returns.
• Replace println!/eprintln!/unwrap/color-formatted output in command-reachable libraries (upgrade transferrers, shutdown signals, parse helpers) with structured tracing and typed errors.
• Add CLI contract regression test plus operator-facing docs (upgrades/from_v1_0_0_to_v2_0_0/README.md, module docs) describing the new contract.

Reviewed changes

Copilot reviewed 73 out of 74 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
upgrades/from_v1_0_0_to_v2_0_0/README.md	Update operator instructions for new -- argv separator and NDJSON stderr capture.
tests/upgrades/from_v1_0_0_to_v2_0_0/upgrader.rs	Adapt test to new Result-returning upgrade() signature.
tests/upgrades/.../torrent_transferrer_tester.rs	Handle now-fallible convert_timestamp_to_datetime via .expect.
tests/upgrades/.../sqlite_v1_0_0.rs	Allow clippy::print_stdout for test scaffolding.
tests/e2e/.../torrent/{steps,contract}.rs, tests/common/contexts/torrent/fixtures.rs	Allow clippy::print_stdout/print_stderr in e2e/test fixtures under new workspace lints.
tests/cli_contract.rs	New regression test asserting in-scope binaries return ExitCode and not Result.
src/web/api/server/signals.rs	Replace println! shutdown notice with structured info!; extract grace timeout constant.
src/utils/parse_torrent.rs	Drop println!/eprintln! from decode_torrent/encode_torrent; leave reporting to callers.
src/upgrades/from_v1_0_0_to_v2_0_0/upgrader.rs	Refactor run/upgrade to accept parsed Arguments and return Result<(), UpgradeError>; switch status output to tracing::info!.
src/upgrades/.../user_transferrer.rs	Replace unwrap/assert!/println! with typed UpgradeError mapping and structured tracing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[peer-cat]

ACK 5a6dab0

[da2ce7]

ACK 5a6dab0