epoch_forge/docs/presentation-design.md

164 lines
6.3 KiB
Markdown

# Presentation and export design
This is the remaining implementation contract for tracker issue
[#10](https://proxy.dandaedre.com/gitea/idle-org/epoch_forge/issues/10).
`show`, full entity display, and world diff already build strings before the
CLI writes them. The issue is not complete until every command follows one
coherent output boundary and useful reports can be saved without scraping ANSI
terminal output.
## Goals
- Domain/library operations return typed data and never print.
- Command handlers resolve input and choose presentation; renderers never
mutate repositories.
- Each invocation performs at most one stdout write and, when needed, one
stderr write after successful rendering.
- Essential meaning survives `NO_COLOR`, `--no-default-features`, redirection,
narrow terminals, and UTF-8 terminals without Nerd Fonts.
- The same typed report can target terminal text, plain text, or a stable
machine representation without parsing a decorated string.
- `--output PATH` writes atomically and refuses to overwrite unless explicitly
requested. It never changes repository state.
## Layering
```text
lib_efo domain operation
↓ typed result/report
bin_efo presentation model
↓ renderer selected by OutputOptions
String / serializable value
↓ one stdout write or atomic output-file replacement
```
Introduce a small `presentation` module in `bin_efo`; do not make `lib_efo`
depend on terminal crates.
```text
OutputOptions {
format: Human | Plain | Json,
output: Option<PathBuf>,
force: bool,
color: Auto | Always | Never
}
Document {
title: Option<String>,
blocks: Vec<Block>
}
Block = Paragraph | KeyValues | Table | Tree | Changes | Warning | Recovery
```
The document model carries semantics (added/removed/warning/success), not ANSI
codes or Nerd Font glyphs. Human rendering may choose colour and decorative
glyphs; plain rendering uses accessible ASCII/Unicode labels; JSON serializes
the original typed report rather than the human `Document` where possible.
JSON is included here because “printing or saving depending on need” requires
a non-lossy format. Its schema is versioned per report (`schema_version`,
`kind`) and tested. JSON output disables colour and decorative glyphs and emits
no success prose. JSONL remains a later extension for streaming lists.
## CLI contract
Global or consistently flattened options:
```text
--format human|plain|json
--output PATH
--force
--color auto|always|never
```
Defaults preserve today's human terminal experience. When stdout is not a TTY,
`human` automatically suppresses colour but keeps UTF-8 structure. `plain`
avoids decorative icons and ANSI regardless of terminal. Existing
`NO_COLOR` remains honored and wins over `auto`; `--color always` is the only
explicit override.
Writing rules:
- render fully before opening the output path;
- reject repository control paths and an input path used by the command;
- use sibling temporary file, flush, sync when repository-grade durability is
needed, then rename;
- without `--force`, an existing target is an actionable error;
- success/recovery messages go to stderr only when structured output occupies
stdout, otherwise remain part of the human document;
- errors never create or truncate the output file.
## Migration inventory
Priority is determined by risk and reuse, not file order:
1. Safety/destructive previews: `reset`, `prune-future`, recovery, locks.
2. Simulation previews: generation, travel, diffusion, influx, conflict.
3. State/history: status, stage/restore/commit/log/switch/revert, epoch.
4. Entity mutation confirmations and generated-name commands.
5. Legacy library printing (`Displayable::print_full`, `Prettiable` print
helpers, old epoch config helpers) replaced with returned strings or writers.
Tests and debug-only `println!` calls are outside the production inventory.
After migration, CI runs a source check that rejects production
`print!/println!/eprint!/eprintln!` outside the single output sink and process
entry error boundary.
## Information loading
Renderers receive a `ViewContext` assembled once per command:
```text
ViewContext {
repository_summary,
selected_layer,
entity_index,
optional_epoch_metadata,
terminal_capabilities
}
```
This avoids renderers reopening the repository or repeatedly scanning vectors.
It also satisfies the issue's “load many info” goal: entity tables can resolve
links/names, simulation reports can name sources and targets, and historical
views can attach epoch metadata without domain objects performing I/O.
## Coherence rules
- Titles use sentence case; stable IDs always retain an `@` prefix.
- Added/removed/modified markers remain `+`, `-`, `~`; `!` means important.
- Counts and empty states are always explicit.
- Preview documents start with `Preview` and finish with exactly what will or
will not change plus the recovery command.
- Successful mutation documents state the layer changed (`worktree`, `index`,
or committed epoch) and the next useful command.
- Warnings and errors never rely on colour or glyph shape.
- Tables have deterministic column order and rows have stable sort keys.
- Human wrapping is Unicode-width-aware; machine formats never wrap.
## Acceptance gates
- every production command returns/render-writes through one output sink;
- no library production function prints;
- golden tests cover human, portable/plain, and JSON for each report family;
- redirected output contains no ANSI escapes;
- `NO_COLOR` and portable builds retain all semantic labels;
- `--output` success, collision, permission failure, and atomicity are tested;
- JSON schemas round-trip and do not contain rendered terminal strings;
- large lists are bounded or paginated without partial writes;
- display tests use returned buffers, not global stdout capture;
- help documents formats, output files, overwrite behavior, and examples;
- both existing CLI behavior and new simulation previews migrate before #10 is
closed.
## Delivery slices
1. Add `OutputOptions`, the single sink, atomic file writer, and renderer tests.
2. Move safety and simulation previews to typed reports/documents.
3. Move state/history commands and expose plain/JSON formats.
4. Move entity and generation commands; retire production library printing.
5. Add the source-policy check, output-path failure tests, docs, and help
snapshots; close #10 only when the production inventory is empty.