# 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, force: bool, color: Auto | Always | Never } Document { title: Option, blocks: Vec } 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.