eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Refresh CLI collection and app internals

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-31 01:21:23 +00:00
parent 1130d807dc
commit c6f8570474
3 changed files with 166 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
docs/internal/cli.md
View File

@@ -1,67 +1,65 @@
# CLI Internals
This document describes command output ownership in `internal/cli`.
`internal/cli` turns process arguments into application requests and translates
application results into terminal output. The user-facing command, flag, and
output contract belongs in the [CLI reference](../cli.md).
## Purpose
## Responsibilities
`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.
`Runner.Run` dispatches the top-level action or inspection request. For actions,
the package parses command-specific and common flags, loads configuration with
CLI overrides, obtains the current time, and constructs either an
`app.GenerateRequest` or an `app.BatchRequest`. It delegates generation and
batch execution to `internal/app`.
## Command Categories
For inspection, it loads configuration, builds the appropriate app inspection
request, and writes the returned value. Inspection is read-only; the inspected
artifact types and user invocation remain owned by the [CLI reference](../cli.md)
and [operations guide](../operations.md).
- 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.
## Result Translation
Future commands must declare which category they belong to before adding output
behavior.
Action results become CLI-safe JSON summaries in `result.go`. Generate summaries
carry report identity, status, relevant artifact paths, and notification
summary data. Batch summaries carry aggregate counts, per-report outcomes, and
the optional batch notification result. The translation deliberately excludes
full module snapshots, prompt packages, raw generated text, Scriptorium output,
and complete Distributor payloads.
## Stdout And Stderr
When an action returns both a result and an error, the CLI writes the failed
summary before returning that error. Parse, configuration-load, and other
failures that produce no application result return without a summary.
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.
`writeActionResult` writes action status information to stderr first, then JSON
to stdout. Batch execution supplies the status writer; single-report generation
does not emit routine stderr output. Quiet action requests suppress both normal
streams but still return errors. Inspection writes its JSON value to stdout and
does not accept quiet mode because stdout is the inspection result.
Inspection commands write requested JSON data to stdout with `writeJSON`. They
do not use action output helpers and do not support quiet mode.
## Boundaries
Returned errors are not hidden by output helpers. The caller remains
responsible for displaying command errors.
The package owns argument parsing, request adaptation, help text, and terminal
presentation. It does not implement report selection, collection, state
persistence, external transport, subprocess execution, or notification policy.
Those concerns remain in [application orchestration](app-orchestration.md) and
their focused owners.
## Quiet Mode
## Failure Behavior
`--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.
- Invalid command names, flags, dates, and configuration fail before an app
request is executed.
- Application errors retain their application context; output helpers do not
hide or replace them.
- JSON-encoding errors are returned directly.
- A failed batch summary causes the CLI to return an aggregate batch error even
when the detailed batch call has already returned its result.
Quiet mode is intentionally not accepted by inspection commands because
inspection stdout is the command result.
## Tests And Invariants
## Summary Ownership
Focused tests are in `internal/cli/root_test.go`, `internal/cli/output_test.go`,
and `internal/cli/result_test.go`.
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`.
- CLI summaries are stable, bounded views of app results.
- Routine batch status lines precede the batch JSON summary.
- A quiet action produces no successful or failure summary output.
- Inspection never invokes action-output helpers.