Document CLI output contract
This commit is contained in:
119
docs/cli.md
119
docs/cli.md
@@ -20,15 +20,15 @@ Markdown report after final metadata is saved.
|
||||
|
||||
```text
|
||||
weatherreporter --help
|
||||
weatherreporter generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD]
|
||||
weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] --start TIME --end TIME
|
||||
weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
|
||||
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
|
||||
weatherreporter generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] [--quiet]
|
||||
weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet] --start TIME --end TIME
|
||||
weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
|
||||
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
|
||||
weatherreporter inspect reports [--config PATH] [--limit N]
|
||||
weatherreporter inspect metadata [--config PATH] RUN_ID
|
||||
weatherreporter inspect modules [--config PATH] RUN_ID
|
||||
@@ -37,10 +37,13 @@ weatherreporter inspect prior [--config PATH] RUN_ID
|
||||
weatherreporter inspect sources [--config PATH] RUN_ID
|
||||
```
|
||||
|
||||
Implemented `generate` commands write a JSON module snapshot, YAML data package,
|
||||
preflight artifact, managed Markdown report, and metadata under the configured
|
||||
workspace. `--out` writes an extra Markdown copy for the operator; distributor
|
||||
notification uses the managed report path, not the extra copy. `generate daily`,
|
||||
Implemented `generate` commands emit a compact JSON summary to stdout on
|
||||
success. The summary includes command identity, report identity, RunID, status,
|
||||
valid period, and managed artifact paths. They also write a JSON module
|
||||
snapshot, YAML data package, preflight artifact, managed Markdown report, and
|
||||
metadata under the configured workspace. `--out` writes an extra Markdown copy
|
||||
for the operator; distributor notification uses the managed report path, not
|
||||
the extra copy. `generate daily`,
|
||||
`generate today`, `generate tomorrow`, and `generate hourly` write managed
|
||||
generated-text artifacts, validate structured text from Scriptorium, and render
|
||||
the managed Markdown report from embedded templates. `generate daily` requires
|
||||
@@ -71,8 +74,91 @@ report fails, the batch notification is skipped for the whole batch.
|
||||
Hourly Report, 3-Day Outlook, and Weekend Outlook are explicit only; they are
|
||||
not included in `run morning` or `run evening`.
|
||||
|
||||
`inspect` commands read existing workspace artifacts and emit JSON to stdout.
|
||||
They do not collect weather data or invoke `scriptorium`.
|
||||
`inspect` commands read existing workspace artifacts and emit the requested
|
||||
JSON data to stdout. They do not collect weather data or invoke `scriptorium`.
|
||||
Inspection commands do not accept `--quiet`.
|
||||
|
||||
## Output
|
||||
|
||||
Action commands, meaning `generate` and `run`, emit JSON summaries to stdout by
|
||||
default. Pre-run errors, such as invalid flags, missing required arguments, or
|
||||
configuration load failures, return an error without emitting partial JSON.
|
||||
`--quiet` suppresses successful action-command stdout and routine stderr. It
|
||||
does not hide returned errors. Inspection commands are data-output commands;
|
||||
they always write the requested JSON to stdout and are not quietable.
|
||||
|
||||
Generate summaries have this shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "generate",
|
||||
"reportId": "today",
|
||||
"reportName": "Today Report",
|
||||
"promptId": "weather.today_generated_text",
|
||||
"runId": "20260529T120000.000000000Z_today",
|
||||
"status": "succeeded",
|
||||
"generatedAt": "2026-05-29T12:00:00Z",
|
||||
"validPeriod": {
|
||||
"start": "2026-05-29T00:00:00-05:00",
|
||||
"end": "2026-05-30T00:00:00-05:00"
|
||||
},
|
||||
"reportPath": "workspace/reports/today/2026-05-29/report.20260529T120000.000000000Z_today.md",
|
||||
"metadataPath": "workspace/snapshots/today/2026-05-29/metadata.20260529T120000.000000000Z_today.json",
|
||||
"dataPackagePath": "workspace/data-packages/today/2026-05-29/data_package.20260529T120000.000000000Z_today.yaml",
|
||||
"preflightPath": "workspace/preflight/today/2026-05-29/render.20260529T120000.000000000Z_today.json",
|
||||
"generatedTextRawPath": "workspace/snapshots/today/2026-05-29/generated_text_raw.20260529T120000.000000000Z_today.json",
|
||||
"generatedTextResultPath": "workspace/snapshots/today/2026-05-29/generated_text_result.20260529T120000.000000000Z_today.json",
|
||||
"generatedTextPath": "workspace/snapshots/today/2026-05-29/generated_text.20260529T120000.000000000Z_today.json",
|
||||
"renderContextPath": "workspace/snapshots/today/2026-05-29/render_context.20260529T120000.000000000Z_today.json"
|
||||
}
|
||||
```
|
||||
|
||||
Markdown-path reports omit the generated-text fields. If distributor
|
||||
notification is attempted, summaries include `notificationPath`; successful
|
||||
notification also includes a compact `notification` object. If notification
|
||||
fails after report artifacts exist, the summary has `"status": "failed"` and an
|
||||
`error` string while retaining inspectable artifact paths.
|
||||
|
||||
Run summaries have this shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "run",
|
||||
"batch": "morning",
|
||||
"status": "succeeded",
|
||||
"startedAt": "2026-05-29T12:00:00Z",
|
||||
"finishedAt": "2026-05-29T12:01:00Z",
|
||||
"total": 1,
|
||||
"succeeded": 1,
|
||||
"failed": 0,
|
||||
"reports": [
|
||||
{
|
||||
"reportId": "today",
|
||||
"reportName": "Today Report",
|
||||
"promptId": "weather.today_generated_text",
|
||||
"runId": "20260529T120000.000000000Z_today",
|
||||
"status": "succeeded",
|
||||
"generatedAt": "2026-05-29T12:00:00Z",
|
||||
"validPeriod": {
|
||||
"start": "2026-05-29T00:00:00-05:00",
|
||||
"end": "2026-05-30T00:00:00-05:00"
|
||||
},
|
||||
"reportPath": "workspace/reports/today/2026-05-29/report.20260529T120000.000000000Z_today.md",
|
||||
"metadataPath": "workspace/snapshots/today/2026-05-29/metadata.20260529T120000.000000000Z_today.json",
|
||||
"dataPackagePath": "workspace/data-packages/today/2026-05-29/data_package.20260529T120000.000000000Z_today.yaml",
|
||||
"preflightPath": "workspace/preflight/today/2026-05-29/render.20260529T120000.000000000Z_today.json"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`run` status is `failed` when any report failed or the top-level batch
|
||||
notification failed. Batch stderr uses compact status lines, for example:
|
||||
|
||||
```text
|
||||
report=today status=succeeded output="reports/today.md"
|
||||
batch=morning total=2 succeeded=2 failed=0
|
||||
```
|
||||
|
||||
## Flags
|
||||
|
||||
@@ -82,6 +168,7 @@ They do not collect weather data or invoke `scriptorium`.
|
||||
- `--tz NAME`: override configured Weather API timezone for `generate` and `run`.
|
||||
- `--out PATH`: write an extra Markdown report copy where supported by the `generate` command.
|
||||
- `--out-dir PATH`: write extra Markdown report copies for `run morning` and `run evening`.
|
||||
- `--quiet`: suppress successful stdout and routine stderr for `generate` and `run`.
|
||||
- `--date YYYY-MM-DD`: required date for `generate daily`; optional date for `generate today`, defaulting to the current local date in the configured timezone.
|
||||
- `--start TIME`: required start time for `generate storm`.
|
||||
- `--end TIME`: required end time for `generate storm`.
|
||||
@@ -105,6 +192,8 @@ weatherreporter generate weekend --out ./weekend.md
|
||||
weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00 --out ./storm.md
|
||||
weatherreporter run morning --out-dir ./reports
|
||||
weatherreporter run evening --out-dir ./reports
|
||||
weatherreporter generate today --quiet
|
||||
weatherreporter run morning --quiet
|
||||
```
|
||||
|
||||
## Inspection
|
||||
|
||||
67
docs/internal/cli.md
Normal file
67
docs/internal/cli.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# 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`.
|
||||
@@ -37,7 +37,9 @@ effective report timezone and is not included in `run morning` or
|
||||
When distributor notification is enabled, weatherreporter uploads the managed
|
||||
Markdown report after report rendering succeeds and final metadata is saved.
|
||||
`--out PATH` writes an extra Markdown copy for generated reports; it is not used
|
||||
as the distributor upload source.
|
||||
as the distributor upload source. Generate commands emit a compact JSON summary
|
||||
to stdout by default. Use `--quiet` to suppress successful stdout for cron jobs
|
||||
or other schedulers that only need nonzero exits and external logs.
|
||||
|
||||
Batch commands:
|
||||
|
||||
@@ -64,7 +66,8 @@ after every planned report succeeds. If any report fails, the batch upload is
|
||||
skipped for the whole batch. `--out-dir PATH` writes extra Markdown copies
|
||||
using report default filenames such as `today.md` and `tomorrow.md`; dynamic
|
||||
Daily copies use `daily-YYYY-MM-DD.md`. These copies are not used as
|
||||
distributor upload sources.
|
||||
distributor upload sources. Use `--quiet` to suppress successful batch summary
|
||||
and status output; failures still return nonzero.
|
||||
|
||||
## Filesystem Layout
|
||||
|
||||
|
||||
@@ -121,8 +121,12 @@ The CLI is owned by `internal/cli`.
|
||||
When adding or changing a command or flag:
|
||||
|
||||
- update help text and parser behavior together;
|
||||
- declare whether the command is an action command or an inspection/data-output
|
||||
command;
|
||||
- convert parsed values into app-layer request structs;
|
||||
- keep domain decisions in `internal/app` or domain packages;
|
||||
- use the centralized output helpers in `internal/cli/output.go`;
|
||||
- keep action-command summary conversion in `internal/cli/result.go`;
|
||||
- add parser or command tests in `internal/cli`;
|
||||
- update `docs/cli.md`;
|
||||
- update `docs/operations.md` or `docs/troubleshooting.md` when behavior affects
|
||||
|
||||
@@ -1,326 +0,0 @@
|
||||
# CLI Output Implementation Plan
|
||||
|
||||
## Purpose
|
||||
|
||||
This document is the staged implementation plan for
|
||||
[cli.md](cli.md). It is written for an LLM coding agent that will implement the
|
||||
CLI output harmonization in order.
|
||||
|
||||
The feature is complete when `generate`, `run`, and `inspect` have consistent
|
||||
stdout/stderr behavior, action commands support `--quiet`, CLI output logic is
|
||||
centralized in `internal/cli`, and maintained docs describe the implemented
|
||||
contract.
|
||||
|
||||
## Ground Rules
|
||||
|
||||
- Review `docs/policy/architecture.md`, `docs/policy/development.md`, and
|
||||
`docs/policy/documentation.md` before editing code.
|
||||
- Keep application orchestration and domain behavior in `internal/app`.
|
||||
- Keep CLI presentation, output summaries, stdout/stderr policy, and quiet-mode
|
||||
behavior in `internal/cli`.
|
||||
- Do not serialize full `app.ReportResult` values directly to CLI stdout.
|
||||
- Do not add `--quiet` to inspection commands in this pass.
|
||||
- Do not add global `--format`, NDJSON progress, human-readable success output,
|
||||
or machine-readable error envelopes.
|
||||
- Preserve current command semantics except where this plan explicitly changes
|
||||
output behavior.
|
||||
|
||||
## Decisions
|
||||
|
||||
- CLI-safe summary structs live in `internal/cli/result.go`, not
|
||||
`internal/app`.
|
||||
- Add `app.GenerateDetailed(ctx, GenerateRequest) (*ReportResult, error)`.
|
||||
- Keep `app.Generate(ctx, GenerateRequest) error` as a wrapper around
|
||||
`GenerateDetailed`.
|
||||
- Keep `app.RunBatchDetailed(ctx, BatchRequest) (*BatchResult, error)` as the
|
||||
app-layer batch source.
|
||||
- Add `command` and `status` fields in CLI summary structs, not in
|
||||
`app.BatchResult`.
|
||||
- `BatchSummary.status` is `failed` when any report failed or the top-level
|
||||
batch notification status is `failed`; otherwise it is `succeeded`.
|
||||
- `GenerateSummary.status` is `succeeded` for a successful generated report and
|
||||
`failed` only when a non-nil `ReportResult` is returned with an error after
|
||||
inspectable artifacts exist.
|
||||
- Default action-command output may include a failure JSON summary when the app
|
||||
layer returns a non-nil result with an error.
|
||||
- Quiet mode suppresses successful action-command stdout and routine stderr. It
|
||||
does not hide returned errors.
|
||||
|
||||
## Stage 1: Detailed Generate Result
|
||||
|
||||
Goal: make single-report generation return the same kind of structured result
|
||||
that batch generation already uses internally.
|
||||
|
||||
Implementation:
|
||||
|
||||
- Add `GenerateDetailed(ctx, GenerateRequest) (*ReportResult, error)` in
|
||||
`internal/app`.
|
||||
- Move the current body of `Generate` into `GenerateDetailed`.
|
||||
- Change `Generate` to call `GenerateDetailed` and return only the error.
|
||||
- Ensure `GenerateDetailed` preserves existing behavior for:
|
||||
- collecting weather before resolving/generating;
|
||||
- unknown or unimplemented reports;
|
||||
- explicit Daily date requirements;
|
||||
- optional output copy behavior;
|
||||
- distributor notification behavior.
|
||||
- When `GenerateReport` or generated-template finalization receives a non-empty
|
||||
`finalizeRenderedReportResult` plus an error after managed artifacts exist,
|
||||
return a non-nil `ReportResult` together with that error. This is especially
|
||||
important for notification failures where the report and notification artifact
|
||||
are inspectable.
|
||||
- Do not return partial results for flag/config/pre-run validation failures or
|
||||
failures before a useful run identity exists.
|
||||
|
||||
Tests:
|
||||
|
||||
- Add app tests for `GenerateDetailed` success.
|
||||
- Add an app test showing `Generate` still returns only the underlying error.
|
||||
- Add or adjust an app test for notification failure so `GenerateDetailed`
|
||||
returns a non-nil result with report, metadata, and notification artifact
|
||||
paths while also returning the notification error.
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
go test ./internal/app
|
||||
```
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- Existing app behavior is preserved for callers of `Generate`.
|
||||
- CLI callers can obtain a rich `ReportResult` from `GenerateDetailed`.
|
||||
|
||||
## Stage 2: CLI Summary Types
|
||||
|
||||
Goal: define small, stable CLI output contracts without exposing full app
|
||||
internals.
|
||||
|
||||
Implementation:
|
||||
|
||||
- Add `internal/cli/result.go`.
|
||||
- Define a `generateSummary` struct with these JSON fields:
|
||||
- `command`
|
||||
- `reportId`
|
||||
- `reportName`
|
||||
- `promptId`
|
||||
- `runId`
|
||||
- `status`
|
||||
- `generatedAt`
|
||||
- `validPeriod`
|
||||
- `reportPath,omitempty`
|
||||
- `outputPath,omitempty`
|
||||
- `metadataPath,omitempty`
|
||||
- `dataPackagePath,omitempty`
|
||||
- `preflightPath,omitempty`
|
||||
- `generatedTextRawPath,omitempty`
|
||||
- `generatedTextResultPath,omitempty`
|
||||
- `generatedTextPath,omitempty`
|
||||
- `renderContextPath,omitempty`
|
||||
- `notificationPath,omitempty`
|
||||
- `notification,omitempty`
|
||||
- `error,omitempty`
|
||||
- Define a `batchSummary` struct with these JSON fields:
|
||||
- `command`
|
||||
- `batch`
|
||||
- `status`
|
||||
- `startedAt`
|
||||
- `finishedAt`
|
||||
- `total`
|
||||
- `succeeded`
|
||||
- `failed`
|
||||
- `notification,omitempty`
|
||||
- `reports`
|
||||
- `error,omitempty`
|
||||
- Reuse existing app result substructures where they are already CLI-safe:
|
||||
`timeutil.Period`, `app.BatchNotificationResult`, and
|
||||
`app.BatchReportResult`.
|
||||
- Add conversion helpers:
|
||||
- `newGenerateSummary(result *app.ReportResult, err error) generateSummary`
|
||||
- `newBatchSummary(result *app.BatchResult) batchSummary`
|
||||
- Do not include module snapshot contents, data package contents, raw generated
|
||||
text bytes, render result bodies, or full distributor adapter payloads.
|
||||
- Keep error strings concise and avoid adding secrets.
|
||||
|
||||
Tests:
|
||||
|
||||
- Add focused unit tests for summary conversion.
|
||||
- Cover generated-text reports, markdown reports, disabled notification, and
|
||||
notification failure with a non-nil result.
|
||||
- Cover batch status derivation for success, report failure, skipped
|
||||
notification, and failed notification.
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
go test ./internal/cli
|
||||
```
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- CLI summary shapes are explicit and independent of full app result structs.
|
||||
|
||||
## Stage 3: Centralized Output Helpers
|
||||
|
||||
Goal: make the consistent output path the default path for current and future
|
||||
commands.
|
||||
|
||||
Implementation:
|
||||
|
||||
- Add `internal/cli/output.go`.
|
||||
- Move `writeJSON` from `root.go` into `output.go`.
|
||||
- Move `writeRunLogs` from `root.go` into `output.go` and rename it to
|
||||
`writeBatchStatus`.
|
||||
- Add an `outputOptions` struct with at least:
|
||||
- `Quiet bool`
|
||||
- Add a small action output helper such as:
|
||||
`writeActionResult(stdout, stderr io.Writer, value any, opts outputOptions, writeStatus func(io.Writer)) error`.
|
||||
- The helper must:
|
||||
- return without writing stdout or routine stderr when `opts.Quiet` is true;
|
||||
- write status before JSON for default action output when a status writer is
|
||||
provided;
|
||||
- use the shared JSON writer for stdout;
|
||||
- tolerate nil stderr when no status output is needed.
|
||||
- Keep inspect commands using `writeJSON` directly because inspection is data
|
||||
output, not quietable action output.
|
||||
- Ensure `root.go` no longer calls `json.NewEncoder` directly.
|
||||
|
||||
Tests:
|
||||
|
||||
- Add unit tests for quiet/default action output helper behavior.
|
||||
- Keep existing batch stderr tests, updated for renamed helpers if needed.
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
go test ./internal/cli
|
||||
```
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- JSON encoding and action status output are centralized outside command
|
||||
routing.
|
||||
|
||||
## Stage 4: Wire Generate And Run Output
|
||||
|
||||
Goal: make current action commands use the same output contract.
|
||||
|
||||
Implementation:
|
||||
|
||||
- Extend `commonOptions` or action-specific options with `Quiet bool`.
|
||||
- Parse `--quiet` for `generate` and `run`.
|
||||
- Do not parse or accept `--quiet` for `inspect`.
|
||||
- Update `Runner.Run`:
|
||||
- `generate` should call `app.GenerateDetailed`;
|
||||
- when a non-nil result is returned, convert it to `generateSummary`;
|
||||
- write the summary through the centralized action output helper;
|
||||
- if an error is also returned, write default JSON only when a non-nil result
|
||||
exists and quiet is false, then return the error;
|
||||
- if no result is returned, return the error without writing partial JSON.
|
||||
- Update `run` command handling:
|
||||
- convert `*app.BatchResult` to `batchSummary`;
|
||||
- write through the centralized action output helper;
|
||||
- preserve the current behavior that a batch result is emitted in default
|
||||
mode before returning `app.BatchError` for failed reports;
|
||||
- preserve notification-only batch failure behavior.
|
||||
- Keep `inspect` commands unchanged except for using the relocated `writeJSON`.
|
||||
|
||||
Tests:
|
||||
|
||||
- `generate today` emits valid JSON on success.
|
||||
- The generate JSON includes `command: "generate"`, `status: "succeeded"`,
|
||||
`reportId`, `runId`, `reportPath`, `metadataPath`, `dataPackagePath`, and
|
||||
`preflightPath`.
|
||||
- Generated-text reports include generated-text artifact paths.
|
||||
- Markdown reports omit generated-text artifact paths.
|
||||
- `generate --quiet` emits no stdout or routine stderr on success.
|
||||
- Generate pre-run errors emit no partial JSON.
|
||||
- Generate notification failure with an inspectable result emits a failure JSON
|
||||
summary in default mode and returns nonzero.
|
||||
- `run morning` and `run evening` still emit JSON summaries by default.
|
||||
- Run JSON includes `command: "run"` and a derived `status`.
|
||||
- `run --quiet` suppresses successful summary/status output.
|
||||
- Failed batch runs still return nonzero and still emit default JSON when quiet
|
||||
is false.
|
||||
- Inspect commands still emit requested JSON and reject `--quiet` as an
|
||||
unexpected flag.
|
||||
- Output tests confirm distributor token values are not printed.
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
go test ./internal/cli ./internal/app
|
||||
```
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- Current action commands have consistent default JSON behavior.
|
||||
- Quiet mode is available for action commands and not inspection commands.
|
||||
|
||||
## Stage 5: Documentation
|
||||
|
||||
Goal: document the implemented CLI output contract in maintained docs and make
|
||||
future changes follow the same structure.
|
||||
|
||||
Documentation changes:
|
||||
|
||||
- Update `docs/cli.md`:
|
||||
- document default JSON stdout for `generate`, `run`, and `inspect`;
|
||||
- document compact status stderr for batch commands;
|
||||
- document `--quiet` for `generate` and `run`;
|
||||
- include representative generate and run JSON snippets;
|
||||
- state that inspection commands are not quietable.
|
||||
- Update `docs/operations.md` if cron/operator behavior changes need an
|
||||
operations note.
|
||||
- Add `docs/internal/cli.md` documenting:
|
||||
- command categories;
|
||||
- stdout/stderr rules;
|
||||
- quiet-mode behavior;
|
||||
- summary conversion ownership;
|
||||
- the expected helper path for future commands.
|
||||
- Update `docs/policy/development.md` CLI-change guidance so future CLI
|
||||
commands are expected to use the centralized output helpers and declare an
|
||||
output category.
|
||||
|
||||
Tests:
|
||||
|
||||
- Update CLI help-output tests for `--quiet`.
|
||||
- Add or update docs-related tests only if this repository already validates the
|
||||
touched docs/examples in tests.
|
||||
|
||||
Validation:
|
||||
|
||||
```bash
|
||||
go test ./internal/cli ./internal/app
|
||||
go test ./...
|
||||
go run ./cmd/weatherreporter --help
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Completion criteria:
|
||||
|
||||
- Non-roadmap docs describe only implemented behavior.
|
||||
- The roadmap can be removed after implementation if no deferred CLI-output
|
||||
feature remains in it.
|
||||
|
||||
## Final Verification
|
||||
|
||||
Before considering the feature complete, run:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
go run ./cmd/weatherreporter --help
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Also manually verify these command behaviors against test fixtures or a local
|
||||
test config when practical:
|
||||
|
||||
```bash
|
||||
weatherreporter generate today --quiet
|
||||
weatherreporter run morning --quiet
|
||||
weatherreporter inspect reports --limit 1
|
||||
```
|
||||
|
||||
## Open Questions
|
||||
|
||||
None. The decisions above are sufficient for implementation.
|
||||
@@ -16,15 +16,15 @@ const helpText = `weatherreporter prepares weather reports from normalized forec
|
||||
|
||||
Usage:
|
||||
weatherreporter --help
|
||||
weatherreporter generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD]
|
||||
weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH]
|
||||
weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] --start TIME --end TIME
|
||||
weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
|
||||
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH]
|
||||
weatherreporter generate daily --date YYYY-MM-DD [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate today [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--date YYYY-MM-DD] [--quiet]
|
||||
weatherreporter generate tomorrow [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate hourly [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate three-day [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate weekend [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet]
|
||||
weatherreporter generate storm [--config PATH] [--units VALUE] [--tz NAME] [--out PATH] [--quiet] --start TIME --end TIME
|
||||
weatherreporter run morning [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
|
||||
weatherreporter run evening [--config PATH] [--units VALUE] [--tz NAME] [--out-dir PATH] [--quiet]
|
||||
weatherreporter inspect reports [--config PATH] [--limit N]
|
||||
weatherreporter inspect metadata [--config PATH] RUN_ID
|
||||
weatherreporter inspect modules [--config PATH] RUN_ID
|
||||
@@ -39,6 +39,7 @@ Options:
|
||||
--tz NAME Override weather API timezone.
|
||||
--out PATH Write an extra Markdown report copy where supported by the generate command.
|
||||
--out-dir PATH Write extra Markdown report copies for run commands.
|
||||
--quiet Suppress successful generate and run output.
|
||||
`
|
||||
|
||||
type Runner struct {
|
||||
|
||||
@@ -32,6 +32,12 @@ func TestRunHelpLongFlag(t *testing.T) {
|
||||
if !strings.Contains(output.stdout, "weatherreporter generate hourly") {
|
||||
t.Fatalf("help output missing hourly generate command:\n%s", output.stdout)
|
||||
}
|
||||
if !strings.Contains(output.stdout, "generate today") || !strings.Contains(output.stdout, "[--quiet]") {
|
||||
t.Fatalf("help output missing quiet generate usage:\n%s", output.stdout)
|
||||
}
|
||||
if !strings.Contains(output.stdout, "run morning") || !strings.Contains(output.stdout, "--quiet Suppress successful generate and run output.") {
|
||||
t.Fatalf("help output missing quiet run option:\n%s", output.stdout)
|
||||
}
|
||||
removedGenerateCommand := "generate " + strings.Join([]string{"near", "term"}, "-")
|
||||
if strings.Contains(output.stdout, removedGenerateCommand) {
|
||||
t.Fatalf("help output includes retired generate command:\n%s", output.stdout)
|
||||
|
||||
Reference in New Issue
Block a user