Complete configurable output directory implementation
This commit is contained in:
191
docs/roadmap/output-directory.md
Normal file
191
docs/roadmap/output-directory.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user