68 lines
2.4 KiB
Markdown
68 lines
2.4 KiB
Markdown
# 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`.
|