164 lines
6.3 KiB
Markdown
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.
|
|
|