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 PATHwrites 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:
- Safety/destructive previews:
reset,prune-future, recovery, locks. - Simulation previews: generation, travel, diffusion, influx, conflict.
- State/history: status, stage/restore/commit/log/switch/revert, epoch.
- Entity mutation confirmations and generated-name commands.
- Legacy library printing (
Displayable::print_full,Prettiableprint 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
Previewand 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_COLORand portable builds retain all semantic labels;--outputsuccess, 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
- Add
OutputOptions, the single sink, atomic file writer, and renderer tests. - Move safety and simulation previews to typed reports/documents.
- Move state/history commands and expose plain/JSON formats.
- Move entity and generation commands; retire production library printing.
- Add the source-policy check, output-path failure tests, docs, and help snapshots; close #10 only when the production inventory is empty.