weatherreporter/docs/internal/cli.md

CLI Internals

This document describes command output ownership in internal/cli.

Purpose

internal/cli owns command parsing, app request construction, help text, and presentation of command results. It converts app-layer results into stable CLI summaries and writes stdout/stderr through shared output helpers.

Command Categories

• Action commands: generate and run. These perform work, write artifacts, and return compact summaries.
• Inspection commands: inspect reports, inspect metadata, inspect modules, inspect data-package, inspect prior, and inspect sources. These read existing artifacts and return requested data.

Future commands must declare which category they belong to before adding output behavior.

Stdout And Stderr

Action commands write JSON summaries to stdout by default. run also writes compact status lines to stderr through writeBatchStatus. generate does not write routine stderr today. Pre-run errors return without partial JSON.

Inspection commands write requested JSON data to stdout with writeJSON. They do not use action output helpers and do not support quiet mode.

Returned errors are not hidden by output helpers. The caller remains responsible for displaying command errors.

Quiet Mode

--quiet is supported only by action commands. It suppresses successful stdout and routine stderr by passing outputOptions{Quiet: true} to writeActionResult. It does not suppress returned errors.

Quiet mode is intentionally not accepted by inspection commands because inspection stdout is the command result.

Summary Ownership

CLI-safe summary structs live in internal/cli/result.go.

• newGenerateSummary converts *app.ReportResult plus an optional error into the generate JSON contract.
• newBatchSummary converts *app.BatchResult into the run JSON contract and derives the top-level run status.

Summary types must not expose full app internals, module contents, data package contents, raw generated text, Scriptorium result bodies, or full distributor payloads.

Helper Path

New action commands should:

1. parse command-specific flags into CLI option structs;
2. call the app-layer use case;
3. convert app results into a CLI summary type;
4. write through writeActionResult;
5. use a status writer only for routine stderr status lines.

New inspection commands should call the app inspection use case and write the returned data through writeJSON.