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.