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

Refresh cleanup-related documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-29 20:49:19 +00:00
parent a34aec1dd2
commit 8089f62806
4 changed files with 208 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/internal/app-orchestration.md
View File

@@ -4,38 +4,47 @@ This document describes the implemented workflow coordinator in `internal/app`.
## Purpose ## Purpose
`internal/app` coordinates top-level use cases: generating one report through `internal/app` coordinates the top-level use cases after CLI parsing and config
the shared report-generation path, running morning or evening batches, building loading are complete. It resolves report definitions, fetches weather data,
inspectable briefing artifacts, fetching weather bundles, and reading existing builds briefing and prompt-input artifacts, invokes Scriptorium through the
adapter boundary, persists managed state, runs batches, and reads existing
artifacts for inspection. artifacts for inspection.
## Inputs And Outputs ## Inputs And Outputs
Inputs: Inputs:
- app request structs containing config, report or batch selection, clock time, - `GenerateRequest` for one report command
optional report date, optional Storm Report bounds, output paths, renderer - `BatchRequest` for morning or evening batch commands
fakes, or state-store fakes - `FetchBundleRequest` for explicit bundle fetch and save workflows
- `BriefingRequest` and `ReportRequest` for package-level orchestration tests
and internal composition
- resolved report definitions from `internal/report` - resolved report definitions from `internal/report`
- forecast bundles from the Weather API adapter - forecast bundles from `internal/adapters/weatherapi`
- prior briefing snapshots from `internal/state` - prior snapshots loaded from `internal/state`
- optional renderer and state-store fakes for tests
Outputs: Outputs:
- report results for generated report definitions with briefing, data package, - generated report results with briefing, data package, preflight, report,
preflight, report, metadata, prior snapshot, Recent Changes, and Scriptorium metadata, prior snapshot, Recent Changes, and Scriptorium result details
results - batch summaries with per-report status, artifact paths, and error text
- batch summaries with per-report status and artifact paths - saved Weather API bundle JSON for fetch workflows
- inspection JSON values for reports, metadata, briefings, data packages, prior - inspection JSON values for reports, metadata, briefings, data packages, prior
snapshots, and source provenance snapshots, and source provenance
## Boundaries ## Boundaries
- The package coordinates workflow order. `internal/app` owns workflow order and request composition. It does not parse
- It does not parse CLI flags, load YAML files directly, implement HTTP calls, CLI flags, load YAML files directly, implement HTTP transport, derive forecast
derive forecast facts, define report periods, compare Markdown, or construct facts, define report periods, compare rendered Markdown, or construct
Scriptorium argv. Scriptorium argv.
Report selection and report identity policy come from `internal/report`.
Weather API transport stays in `internal/adapters/weatherapi`. Scriptorium
subprocess behavior stays in `internal/adapters/scriptorium`. Filesystem layout
and persisted metadata stay in `internal/state`.
## Config Fields Used ## Config Fields Used
- `weather_api.*` for Weather API client construction and briefing metadata - `weather_api.*` for Weather API client construction and briefing metadata
@@ -44,36 +53,57 @@ Outputs:
- `dayparts` for daily and outlook summarization - `dayparts` for daily and outlook summarization
- `recent_change.*` for structured Recent Changes thresholds - `recent_change.*` for structured Recent Changes thresholds
## External Adapters Used Output copy flags are command request fields. They are not configuration
defaults.
- `internal/adapters/weatherapi` for forecast bundle fetching ## Generation Workflow
- `internal/adapters/scriptorium` for render preflight and report generation
- `internal/state` filesystem store for persisted artifacts
## State Or Manifest Behavior Single-report generation follows this order:
Generation saves the briefing snapshot, data package, preflight result when 1. Resolve the command report to a `report.Resolved` value.
available, rendered report, and metadata. Metadata links all managed artifact 2. Create or use a filesystem store.
paths. Inspection workflows read existing state and do not fetch weather data or 3. Locate any prior compatible snapshot through `internal/state`.
invoke Scriptorium. 4. Fetch a Weather API bundle.
5. Build a report-specific briefing package.
6. Save the briefing snapshot.
7. Compute Recent Changes from structured prior and current briefings.
8. Build and save the Scriptorium `data_package`.
9. Run Scriptorium render preflight.
10. Save preflight JSON when a render result is available.
11. Save metadata for inspection.
12. Run Scriptorium report generation to the managed report path.
13. Copy the managed report to the requested `--out` path when provided.
14. Save metadata with the managed report path.
## Skip And Resume Behavior If render preflight returns both a result and an error, preflight JSON and
metadata are persisted before the error is returned. If Scriptorium report
generation returns an error after writing output, the managed report and
metadata remain inspectable.
There is no resume workflow. Batch generation continues remaining independent ## Batch Workflow
reports after one report fails, then reports aggregate success and failure
counts. `run morning` resolves Daily Today, 3-Day Outlook, and Weekend Outlook except
on Sunday. `run evening` resolves Daily Tomorrow. Batch output copy names come
from report definitions. Batch generation continues independent reports after a
failure, records each result, writes compact status lines to stderr, emits a
JSON summary to stdout, and returns an aggregate error when any report failed.
## Inspection Workflow
Inspection workflows load existing filesystem state only. They do not fetch
weather data or invoke Scriptorium. Run-specific inspect commands share the same
store and metadata lookup path, then load the requested artifact or derived
inspection view.
## Failure Behavior ## Failure Behavior
- Resolve errors stop the requested workflow before fetching weather data. - Resolve errors stop the requested workflow before fetching weather data.
- Weather API or briefing errors stop that report before Scriptorium is called. - Weather API and briefing errors stop that report before Scriptorium runs.
- Render preflight runs before Scriptorium report generation. - Prompt input validation fails before render preflight.
- If render preflight returns a result and an error, preflight JSON and metadata - Render and run errors preserve Scriptorium stderr and exit-code context.
are persisted before the error is returned. - Metadata and artifact path errors include filesystem context.
- If Scriptorium report generation returns an error after writing output, - Batch failures are recorded per report and surfaced through an aggregate
metadata and the managed report path remain inspectable. batch error.
- Batch failures are recorded per report and surfaced through aggregate batch
failure.
## Tests ## Tests

86
docs/internal/report-registry.md
View File

@@ -1,59 +1,81 @@
# Report Registry Internals # Report Registry Internals
This document describes report identity, valid-period resolution, batch This document describes report identity, valid-period resolution, batch
membership, and comparison declarations in `internal/report`. membership, output naming, artifact grouping, and comparison declarations in
`internal/report`.
## Purpose ## Purpose
`internal/report` centralizes report definitions so report IDs, prompt IDs, `internal/report` is the canonical source for report definitions. App, state,
artifact groups, batch output names, generated-report eligibility, comparison briefing, and CLI wiring consume resolved definitions instead of owning report
compatibility, comparison strategies, and valid periods are declared in one identity policy themselves.
package.
## Inputs And Outputs ## Definition Fields
Inputs: Each report definition declares:
- report ID or batch name - report ID and display name
- generation time - Scriptorium prompt ID
- timezone - valid-period resolver
- optional Daily date override - comparison strategy
- optional Storm Report start and end times - managed artifact group
- batch output copy filename
- generated-report eligibility
- prior-report compatibility list
- morning or evening batch membership
Outputs: ## Implemented Reports
- `report.Resolved` values with definition metadata and half-open valid periods | Report | ID | Prompt | Artifact group | Batch copy | Prior compatibility |
- `report.Metadata` values used by briefing and persisted metadata builders | --- | --- | --- | --- | --- | --- |
| Daily Today | `daily_today` | `weather.daily_report` | `daily` | `daily.md` | Daily Today, Daily Tomorrow |
| Daily Tomorrow | `daily_tomorrow` | `weather.daily_report` | `daily` | `tomorrow.md` | Daily Today, Daily Tomorrow |
| 3-Day Outlook | `three_day` | `weather.three_day_outlook` | `three-day` | `three-day.md` | 3-Day Outlook |
| Weekend Outlook | `weekend` | `weather.weekend_outlook` | `weekend` | `weekend.md` | Weekend Outlook |
| Storm Report | `storm` | `weather.storm_report` | `storm` | `storm.md` | Storm Report |
All implemented report definitions are eligible for generation.
## Valid Periods
- Daily Today covers the selected local civil day, or the current local civil
day when no date override is supplied.
- Daily Tomorrow covers the next local civil day from generation time.
- 3-Day Outlook covers the interval from generation time through local midnight
three days later.
- Weekend Outlook covers the upcoming weekend window and is not scheduled for
Sunday morning batch resolution.
- Storm Report covers an explicit event window supplied by the caller.
Storm event windows can be parsed from local `YYYY-MM-DDTHH:MM` timestamps in
the configured timezone or RFC3339 timestamps with explicit offsets. End time
must be after start time.
## Boundaries ## Boundaries
- This package defines report identity and time coverage only. `internal/report` defines report metadata and time coverage. It does not fetch
- It does not fetch weather data, build briefings, compare snapshots, write weather data, build briefings, compare briefing contents, write state, parse CLI
state, parse CLI flags, or invoke Scriptorium. flags, or invoke Scriptorium.
The CLI owns public command names. The app maps those command names to report
IDs, then uses the registry for report policy.
## Config Fields Used ## Config Fields Used
The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch The app supplies `weather_api.timezone` as a loaded `time.Location`. Batch
output path copying uses batch output names from report definitions. output path copying uses batch output names from report definitions.
## External Adapters Used ## State And App Usage
None. - State paths use `ArtifactGroup`.
- Batch output copies use `BatchOutputName`.
## State Or Manifest Behavior - Generation checks `Generated`.
- Prior lookup checks `CompatiblePriorIDs` and the comparison strategy.
None directly. Resolved metadata contributes RunID, report ID, prompt ID, - RunIDs include the resolved report ID.
generation time, timezone, and valid period to later briefing and state
metadata. Artifact groups declared by report definitions are used by state path
construction.
## Skip And Resume Behavior
No resume behavior. Morning batch resolution skips Weekend Outlook on Sunday.
## Failure Behavior ## Failure Behavior
- Unknown reports and batch names return actionable errors. - Unknown report IDs and batch names return actionable errors.
- Weekend Outlook resolution returns an error when resolved directly on Sunday. - Weekend Outlook resolution returns an error when resolved directly on Sunday.
- Storm Report resolution requires start and end, with end after start. - Storm Report resolution requires start and end, with end after start.

62
docs/internal/scriptorium-adapter.md
View File

@@ -6,8 +6,9 @@ This document describes the subprocess adapter in
## Purpose ## Purpose
The adapter runs `scriptorium render` for prompt preflight and `scriptorium run` The adapter runs `scriptorium render` for prompt preflight and `scriptorium run`
for Markdown report generation while isolating subprocess details from domain for Markdown report generation. It isolates subprocess execution, argv
packages. construction, timeout handling, output capture, and exit-code interpretation
from app and domain packages.
## Inputs And Outputs ## Inputs And Outputs
@@ -17,19 +18,25 @@ Inputs:
- prompt input data package path - prompt input data package path
- report output path for `run` - report output path for `run`
- configured binary, config path, profile, timeout, and extra arguments - configured binary, config path, profile, timeout, and extra arguments
- context for cancellation
Outputs: Outputs:
- argv used for execution - argv used for execution
- captured stdout and stderr with truncation flags - captured stdout and stderr
- truncation flags for captured output
- exit code - exit code
- report output path for `run` - report output path for `run`
## Boundaries ## Boundaries
- This adapter owns Scriptorium argv construction and subprocess execution. `internal/adapters/scriptorium` owns Scriptorium command construction and
- It does not choose report types, build prompt input, fetch weather data, subprocess execution. It does not choose report types, build prompt input,
decide workflow order, or persist workflow metadata. fetch weather data, decide workflow order, or persist workflow metadata.
The adapter exposes request and result structs for render and run operations.
State persistence uses a state-owned preflight artifact shape; app
orchestration converts render results before saving.
## Config Fields Used ## Config Fields Used
@@ -39,29 +46,43 @@ Outputs:
- `scriptorium.timeout` - `scriptorium.timeout`
- `scriptorium.extra_args` - `scriptorium.extra_args`
## External Adapters Used ## Commands
- external `scriptorium` CLI Render preflight argv starts with:
See [Scriptorium integration](../integrations/scriptorium.md) for the external ```text
CLI contract used by this project. scriptorium render --prompt <prompt_id> --input data_package=<path> --format json
```
## State Or Manifest Behavior Report generation argv starts with:
None directly. The adapter returns render and run results; app orchestration and ```text
state own managed preflight paths and metadata links. scriptorium run --prompt <prompt_id> --input data_package=<path> --out <path>
```
## Skip And Resume Behavior Configured `--config` and `--profile` flags are inserted after the subcommand
and before prompt-specific arguments. Extra arguments are appended after the
built-in arguments.
None. Context cancellation and configured timeout stop subprocess execution. ## Execution Behavior
The adapter runs commands without shell interpolation. The same private
execution path is used by render and run after command-specific request
validation and argv construction.
When `scriptorium.timeout` is greater than zero, each subprocess call uses a
context with that timeout. Stdout and stderr are captured separately, capped at
1 MiB each, and marked as truncated when the cap is reached.
## Failure Behavior ## Failure Behavior
- Missing prompt ID, data package path, or run output path returns an error. - Missing prompt ID or data package path returns an error before subprocess
- Subprocess start or context errors are wrapped with operation context. execution.
- Nonzero render and run exits return captured output plus an error containing - Missing run output path returns an error before subprocess execution.
exit code and stderr. - Subprocess start errors, context cancellation, and timeouts are wrapped with
- Captured stdout and stderr are size-limited and marked when truncated. operation context by the caller-facing method.
- Nonzero render and run exits return the captured result plus an error
containing the exit code and stderr.
## Tests ## Tests
@@ -75,4 +96,5 @@ Inspect:
- No shell interpolation is used. - No shell interpolation is used.
- The Scriptorium input name is `data_package`. - The Scriptorium input name is `data_package`.
- Render and run preserve command-specific result structs.
- Scriptorium-specific flags stay inside adapter and config boundaries. - Scriptorium-specific flags stay inside adapter and config boundaries.

70
docs/internal/state.md
View File

@@ -4,7 +4,7 @@ This document describes filesystem state in `internal/state`.
## Purpose ## Purpose
`internal/state` owns managed artifact paths, atomic JSON writes, persisted `internal/state` owns managed workspace paths, atomic JSON writes, persisted
metadata, prior snapshot lookup, and read-only artifact inspection helpers. metadata, prior snapshot lookup, and read-only artifact inspection helpers.
## Inputs And Outputs ## Inputs And Outputs
@@ -32,11 +32,13 @@ Outputs:
## Boundaries ## Boundaries
- This package owns managed workspace layout, path validation, filesystem `internal/state` owns local filesystem layout, path validation, durable writes,
writes, and metadata reads. metadata reads, prior lookup, and report listing. It does not fetch weather
- It does not fetch weather data, derive forecasts, build prompt input content, data, derive forecasts, build prompt input content, compare briefing contents,
compare briefing contents, invoke Scriptorium, import adapter result types, or invoke Scriptorium, import adapter result types, or parse CLI flags.
parse CLI flags.
Preflight persistence uses the state-owned `PreflightArtifact` shape. The app
converts adapter render results into that shape before saving.
## Config Fields Used ## Config Fields Used
@@ -49,31 +51,48 @@ Outputs:
Workspace subdirectories must be relative paths that stay under Workspace subdirectories must be relative paths that stay under
`workspace.root`. `workspace.root`.
## External Adapters Used ## Managed Layout
- local filesystem Paths are derived from the resolved report definition's artifact group, the
valid-period start date for JSON artifacts, and the RunID.
## State Or Manifest Behavior ```text
<workspace.root>/
snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.briefing.json
snapshots/<artifact_group>/<YYYY-MM-DD>/<run_id>.metadata.json
data-packages/<artifact_group>/<YYYY-MM-DD>/<run_id>.data_package.json
preflight/<artifact_group>/<YYYY-MM-DD>/<run_id>.render.json
reports/<artifact_group>/<run_id>.md
```
Managed paths are grouped by the report definition's artifact group and Metadata is stored beside briefing snapshots and links the briefing, data
valid-period start date for JSON artifacts. Reports are written under the same package, preflight, and report paths. Report listing walks metadata files under
artifact group. Metadata is stored beside briefing snapshots and links the snapshots directory.
briefing, data package, preflight, and report paths. Report listing walks
metadata files under the snapshots directory.
Prior snapshot lookup reads metadata through the shared lookup path and selects ## Prior Lookup
the latest earlier snapshot whose report ID is compatible according to the
current report definition. Daily Today and Daily Tomorrow are compatible with
each other for the same valid local date. 3-Day Outlook compares with prior
3-Day snapshots for the same valid local date. Weekend Outlook compares with
prior Weekend snapshots for the same weekend window. Storm Report currently has
no prior lookup because its comparison strategy is not searched by the
filesystem store.
## Skip And Resume Behavior Prior snapshot lookup reads stored metadata through the shared lookup path and
selects the latest earlier snapshot whose report ID is compatible with the
current report definition.
There is no resume workflow. Missing metadata directories return no inspection - Daily Today and Daily Tomorrow are compatible with each other for the same
records or no prior snapshot rather than creating state. valid local date.
- 3-Day Outlook compares with prior 3-Day snapshots for the same valid local
date.
- Weekend Outlook compares with prior Weekend snapshots for the same weekend
window.
- Storm Report currently has no prior lookup because explicit event-window
comparison is not searched by the filesystem store.
## Writes And Inspection
Durable JSON writes use shared atomic file helpers. Managed Markdown reports are
prepared by creating their parent directory; Scriptorium writes the report body
to the prepared path. Extra Markdown copies are handled by app orchestration.
Inspection helpers read existing metadata, briefing, and data package files.
Missing metadata directories return no inspection records or no prior snapshot
rather than creating state.
## Failure Behavior ## Failure Behavior
@@ -93,5 +112,6 @@ Inspect:
## Invariants ## Invariants
- Managed paths stay under the configured workspace root. - Managed paths stay under the configured workspace root.
- Artifact grouping comes from report definitions.
- Metadata links artifacts produced for a run. - Metadata links artifacts produced for a run.
- Prior lookup is based on structured metadata, not rendered report text. - Prior lookup is based on structured metadata, not rendered report text.