# 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`.