71 lines
3.3 KiB
Markdown
71 lines
3.3 KiB
Markdown
# 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](../cli.md).
|
|
|
|
## 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`.
|
|
|
|
`Runner` also owns a project-owned prompt-executor factory seam. Its production
|
|
factory maps `promptkit` configuration to the Promptkit adapter, while tests can
|
|
inject a factory without importing dependency types. Each `generate` request
|
|
constructs one executor after configuration loads and passes it to the 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](../cli.md)
|
|
and [operations guide](../operations.md).
|
|
|
|
## 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](app-orchestration.md) 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.
|