epoch_forge/docs/presentation-design.md

6.3 KiB

Presentation and export design

This is the remaining implementation contract for tracker issue #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

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.

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:

--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:

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.