192 lines
8.2 KiB
Markdown
192 lines
8.2 KiB
Markdown
# Configurable Output Directory Roadmap
|
|
|
|
Status: Implemented; retained temporarily for post-implementation review.
|
|
|
|
## Purpose
|
|
|
|
Weatherreporter currently writes generated reports beneath the present working
|
|
directory unless an operator supplies `--out` for a single report or
|
|
`--out-dir` for a batch. Scheduled and packaged deployments should be able to
|
|
select their ordinary report directory in configuration without repeating a
|
|
CLI flag on every invocation.
|
|
|
|
This feature adds one optional nested configuration value:
|
|
|
|
```yaml
|
|
output:
|
|
directory: /var/lib/weatherreporter/reports
|
|
```
|
|
|
|
The nested `output` namespace leaves room for future output-related settings,
|
|
but this roadmap approves only `output.directory`.
|
|
|
|
## User Intent
|
|
|
|
The configured directory is an operator-owned publication destination. It is
|
|
not an application workspace, history store, cache, or source of input for a
|
|
later run. The feature must preserve Weatherreporter's stateless execution
|
|
model and atomic report publication.
|
|
|
|
Operators should be able to establish a stable default once in `config.yml`
|
|
while retaining explicit per-invocation control through the existing CLI
|
|
flags.
|
|
|
|
## Target Configuration Contract
|
|
|
|
`output.directory` is an optional string with an empty default.
|
|
|
|
- An omitted or empty value preserves the current behavior: default report
|
|
names are published beneath the process's present working directory.
|
|
- A nonempty absolute path selects that directory directly.
|
|
- A nonempty relative path is resolved against the process's present working
|
|
directory, matching the existing relative-path behavior of `--out` and
|
|
`--out-dir`. It is not resolved relative to the configuration file.
|
|
- A whitespace-only value is invalid rather than being treated as an implicit
|
|
current-directory selection.
|
|
- A nonexistent directory is allowed and may be created as part of normal
|
|
atomic output publication.
|
|
- An existing path that is not a directory, an inaccessible destination, or
|
|
any other unsafe output target fails through the existing output preflight
|
|
and publication contracts.
|
|
|
|
The configuration remains strict: unknown fields beneath `output` are rejected
|
|
in the same way as unknown fields elsewhere in the configuration.
|
|
|
|
## Destination Precedence
|
|
|
|
Effective output selection follows this precedence, from highest to lowest:
|
|
|
|
1. An explicit `--out` path for `generate`, or an explicit `--out-dir` path for
|
|
`run`.
|
|
2. `output.directory` from the effective configuration.
|
|
3. The process's present working directory.
|
|
|
|
For single-report generation:
|
|
|
|
- `generate <report>` without `--out` publishes the report's existing default
|
|
filename beneath `output.directory` when configured.
|
|
- `generate <report> --out PATH` treats `PATH` as the complete destination and
|
|
ignores `output.directory`.
|
|
- A relative `--out` value remains relative to the present working directory;
|
|
it is not placed beneath `output.directory`.
|
|
|
|
For batch generation:
|
|
|
|
- `run <batch>` without `--out-dir` publishes every selected report beneath
|
|
`output.directory` when configured.
|
|
- `run <batch> --out-dir PATH` ignores `output.directory` for that invocation.
|
|
|
|
Default report filenames, batch membership, summaries, and notification
|
|
behavior do not change.
|
|
|
|
## Architectural End State
|
|
|
|
The configuration package owns the `output.directory` field, its empty
|
|
default, YAML decoding, normalization, and configuration-level validation.
|
|
The CLI continues to own flag parsing and the present working directory used
|
|
for relative CLI values. Application orchestration owns the final precedence
|
|
decision, output preflight, default filename placement, atomic publication, and
|
|
the resolved output paths returned in action results.
|
|
|
|
Single-report and batch paths must use one coherent destination-resolution
|
|
policy rather than maintaining independent interpretations of the configured
|
|
directory. Output destinations must still be fully resolved and validated
|
|
before weather collection or Promptkit execution where the existing workflow
|
|
provides that guarantee.
|
|
|
|
The generated Markdown remains the only ordinary durable artifact. No
|
|
directory scan, prior report lookup, manifest, metadata file, or managed
|
|
cleanup behavior is introduced.
|
|
|
|
## Scope
|
|
|
|
The completed feature includes:
|
|
|
|
- an `OutputConfig` configuration boundary containing `directory`;
|
|
- an empty default that preserves current installations;
|
|
- strict YAML loading and validation for the nested configuration;
|
|
- configured-directory fallback for both `generate` and `run`;
|
|
- explicit CLI-over-configuration precedence;
|
|
- consistent absolute and relative path handling;
|
|
- preservation of output preflight, atomic replacement, cancellation, and
|
|
notification ordering guarantees;
|
|
- updates to the maintained example configuration;
|
|
- updates to the canonical configuration, CLI, operations, architecture, and
|
|
app-orchestration documentation where their owned contracts change; and
|
|
- focused configuration, CLI, and application tests protecting the public
|
|
behavior and important failure paths.
|
|
|
|
## Compatibility
|
|
|
|
This is an additive configuration feature. Existing configuration files remain
|
|
valid, and installations that do not set `output.directory` retain the current
|
|
working-directory behavior.
|
|
|
|
Existing `--out` and `--out-dir` syntax and relative-path semantics remain
|
|
unchanged. The feature does not alter report contents, default filenames,
|
|
Promptkit execution, Distributor payloads, or exit behavior.
|
|
|
|
## Testing Expectations
|
|
|
|
Tests should provide durable coverage for:
|
|
|
|
- the empty default and YAML loading of absolute and relative directories;
|
|
- rejection of whitespace-only and unknown output configuration values;
|
|
- current-working-directory fallback when the field is omitted;
|
|
- configured-directory use by representative single-report and batch actions;
|
|
- `--out` and `--out-dir` precedence over the configured directory;
|
|
- preservation of existing relative CLI path semantics;
|
|
- rejection of an existing non-directory destination before expensive work;
|
|
- successful publication beneath a directory that does not yet exist; and
|
|
- preservation of atomic destination replacement and action-result paths.
|
|
|
|
Tests must remain deterministic, offline, and independent of machine-specific
|
|
directories. Filesystem cases should use temporary directories and exercise
|
|
behavior through the narrowest stable configuration, CLI, or application
|
|
boundary that owns the contract.
|
|
|
|
## Documentation End State
|
|
|
|
Once implemented, the exact field definition, default, and path semantics
|
|
belong in the [configuration reference](../config.md). CLI flag syntax and
|
|
precedence summaries belong in the [CLI reference](../cli.md). Normal output
|
|
handling belongs in the [operations guide](../operations.md), while ownership
|
|
and workflow mechanics belong in the [architecture policy](../policy/architecture.md)
|
|
and [app-orchestration internals](../internal/app-orchestration.md),
|
|
respectively.
|
|
|
|
The maintained configuration under `examples/` should illustrate the field
|
|
without turning another document into a duplicate configuration reference.
|
|
Current-state documentation must not describe this feature as available until
|
|
the implementation lands.
|
|
|
|
## Non-Goals
|
|
|
|
This roadmap does not introduce:
|
|
|
|
- per-report or per-batch configured output directories;
|
|
- filename or directory templates;
|
|
- a new `--out-dir` flag for single-report generation;
|
|
- environment-variable expansion or home-directory expansion in paths;
|
|
- paths resolved relative to the configuration file;
|
|
- output retention, rotation, cleanup, indexing, or history;
|
|
- configuration-time directory creation;
|
|
- multiple output destinations or output format selection; or
|
|
- changes to debug artifact placement or Distributor notification routing.
|
|
|
|
Any future output settings require their own accepted scope and should be
|
|
added beneath `output` only when a concrete requirement exists.
|
|
|
|
## Completion Criteria
|
|
|
|
The feature is complete when operators can set `output.directory` and obtain
|
|
the same destination behavior for ordinary single-report and batch generation,
|
|
explicit CLI destinations reliably take precedence, omitted configuration is
|
|
fully backward compatible, output safety invariants remain intact, and all
|
|
affected canonical documentation and maintained examples describe the
|
|
implemented contract.
|
|
|
|
## Open Questions
|
|
|
|
None. The target behavior and policy choices are defined above.
|