3.0 KiB
CLI Internals
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.
Responsibilities
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.
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 and operations guide.
Result Translation
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.
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.
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.
Boundaries
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 and their focused owners.
Failure Behavior
- 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.
Tests And Invariants
Focused tests are in internal/cli/root_test.go, internal/cli/output_test.go,
and internal/cli/result_test.go.
- 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.