epoch_forge/docs/tui-design.md

4.2 KiB

TUI first-pass design

The terminal user interface is a separate efo-tui binary over lib_efo. It does not replace the efo CLI, invent another persistence path, or make the library depend on terminal rendering. The CLI remains the complete, scriptable interface and the reference recovery surface.

First checkpoint

The first checkpoint is deliberately read-only. It must make a format-2 repository easy to understand before interactive mutations are introduced:

  • open the repository rooted at the current directory;
  • show HEAD, staged state, worktree state, and entity totals without relying on colour or icons;
  • browse every entity collection and inspect an entity's stable UUID, description, and serialized details;
  • explain all active keys in an in-application help overlay;
  • reload state from disk without restarting; and
  • leave the terminal usable after normal exit, an application error, or a panic.

Format-1 repositories receive an actionable migration message and remain usable through efo. Repository discovery above the current directory and mutating actions are explicitly outside this checkpoint.

Interaction contract

The application has three focus areas: collection list, entity list, and details. The focused area is named in text and visually emphasized.

Key Action
Tab, Shift-Tab Move focus forward or backward
arrows, h/j/k/l Navigate focus and selected rows
? Toggle contextual help
r Reload repository state
q, Esc Close help first, then quit

Every essential state is expressed in words. Colour may reinforce meaning but is never the only signal. Borders and ordinary Unicode are the baseline; Nerd Font glyphs are optional decoration, never controls or status vocabulary. Layouts must degrade to a useful compact message in small terminals, and text must be clipped safely rather than wrapped into neighbouring panels.

Architecture

efo-tui input/render loop
          │
          ▼
pure application state and navigation
          │
          ▼
lib_efo::workspace::Workspace

The binary owns terminal setup, key mapping, view state, and rendering. Pure state transitions and rendering through Ratatui's test backend are unit tested. lib_efo continues to own repository validation and all future mutations.

A terminal guard must enter raw mode and the alternate screen only after setup succeeds, and undo both in Drop. A panic hook restores the terminal before delegating to the previous hook. No command changes the process working directory.

Later interactive mutations

Write operations require a second design checkpoint. The first candidates are stage/unstage, restore, and commit because Phase 4 already makes them atomic and reversible. Before exposure, each action needs:

  • an explicit preview of the affected layer and entities;
  • confirmation for discarding or history-changing operations;
  • success text naming the recovery command;
  • lock and interrupted-transaction guidance; and
  • integration tests proving the TUI invokes the same library operation as the CLI.

Entity editing, migration, recovery, and future pruning remain CLI-only until their interactive failure and recovery flows are equally clear.

Acceptance gate

The checkpoint is complete when efo-tui --help is self-documenting, startup and repository failures are actionable, navigation and rendering have tests, the terminal lifecycle is guarded, and the full workspace passes formatting, tests, strict Clippy, and release builds with default and portable features.

Running the first checkpoint

Install both interfaces, migrate the target repository to format 2 if needed, then start the browser from that repository or name its path explicitly:

cargo install --locked --path bin_efo
cargo install --locked --path tui_efo
efo migrate --to 2 --apply
efo-tui
# or: efo-tui --repository /path/to/world

The header reports HEAD, staged and unstaged state, and any active writer lock. The browser reloads only when r is pressed; it never writes or silently refreshes underneath a selection. Use efo status, efo lock status, or efo recover when its diagnostic recommends that CLI recovery path.