6.2 KiB
TUI browser and release contract
efo-tui is a separate, read-only terminal interface over lib_efo. It browses
all six entity collections in HEAD, index (staged), and worktree (editable)
state. The CLI remains the complete interface for changes, history, comparison,
and recovery. No repository format changes are introduced by the browser.
Running
cargo install --locked --path tui_efo
efo-tui --repository /path/to/world
# From a repository root:
efo-tui
# Monochrome (NO_COLOR also works):
efo-tui --no-color
The path must identify a repository root; parent-directory discovery is not
performed. Both stdin and stdout must be interactive terminals. --help and
--version also work when redirected. For scripts use efo status and
efo show.
Browsing
The header reports HEAD, staged and unstaged changes, writer-lock state, the
viewed layer, and its world summary. Start in the worktree. Press 1, 2, or
3 to browse HEAD, index, or worktree. Collection counts reflect the viewed
layer. Entities sort by lowercase name, then stable UUID, and show a shortened
UUID beside their name. Details default to a formatted view with the full UUID,
description, properties, metadata, and statistics. Bold headings, aligned
labels, and indented nested fields make events and other entities readable.
Press v to switch between formatted details and the complete, indented raw
JSON. The panel title identifies the mode. Switching resets detail scrolling to
the top, preserves the selected entity and layer, and keeps the chosen mode
while navigating or reloading during the session. Both modes wrap and scroll.
Switch to an earlier layer to inspect an entity removed from the worktree.
Use efo diff or efo diff --staged for a complete change comparison.
Search applies to the current collection in every layer. It matches name and
description using Unicode lowercase matching, or any substring of the UUID
(with or without @). This is literal substring matching, not a query language
or accent-insensitive search. Press /, edit the query, and press Enter to
keep it. An empty query clears the filter; Escape restores the previous query.
While editing, ordinary character keys enter text instead of invoking commands.
| Key | Action |
|---|---|
Tab, Shift-Tab, h/l, left/right |
Cycle focus: collections, entities, details |
up/down, j/k |
Select a row or scroll details/help |
Home, End |
First/last row or start/end of details/help |
PageUp, PageDown |
Move by approximately one visible page |
/ |
Edit the search filter; Backspace removes a character |
Enter, Esc during search |
Keep filter / restore previous filter |
1, 2, 3 |
View HEAD / index / worktree |
v |
Toggle formatted / raw JSON details |
r |
Reload from disk, preserving selection by UUID when present |
?, ! |
Open help and the last reload diagnostic |
?, !, q, Esc in help |
Close help |
q, Esc outside help/search |
Quit |
Ctrl-C |
Quit from any view, including help and search |
At widths of 100 columns and above, the browser shows three panels. Narrower terminals show the focused panel at full width; Tab cycles between them. The minimum usable size is 32×10. Smaller sizes show resize advice. Details wrap within their panel and scrolling stops at the last page, including after a resize. Help and diagnostics scroll independently.
Focus, selection, and repository state use text and reverse video as well as
optional colour. No Nerd Font is required. --no-color or the presence of
NO_COLOR disables application colours while retaining these selection cues.
Snapshot and failure behavior
The browser reads a snapshot on startup and refreshes only on r; external
changes never silently move the selection. Successful reload and layer changes
keep the selected UUID when it remains in the filtered collection, otherwise
clamp to an available row. A failed reload keeps the last loaded snapshot and
sets a visible stale-data message. Press ! and scroll to read the full error,
including its path and recovery advice; fix the problem and retry with r.
Unsupported versions, corrupt data, and unfinished transactions fail startup
before raw mode is enabled. A writer lock is displayed, never broken. Use
efo lock status, efo status, or efo recover when appropriate. See
recovery for the CLI safety workflows.
Architecture and verification
The binary owns argument parsing, terminal setup, key mapping, view state, and
Ratatui rendering. lib_efo::workspace::Workspace owns repository loading and
validation. No command changes the process working directory or writes world
state. Ratatui's rendered-line measurement bounds wrapped scrolling; its
unstable-rendered-line-info feature is enabled against the locked version.
A terminal guard restores raw mode, cursor visibility, and the alternate screen on normal exit and application errors. The panic hook restores an active terminal before printing the panic, and does not emit terminal controls before terminal setup. Ctrl-C takes the same guarded exit path. Forced process kills cannot run cleanup.
Tests cover search, navigation, layer/reload identity, corrupt reload recovery, scrolling, responsive layouts, monochrome rendering, and noninteractive startup. The release gate includes workspace formatting, tests, strict Clippy, default and portable builds, plus a pseudo-terminal navigation/restoration smoke test. On Unix, run it with:
cargo build -p efo-tui --locked
python3 tui_efo/tests/terminal_smoke.py
The smoke check uses a temporary copy of the curated example, verifies that its
files remain byte-identical, and checks terminal restoration on q and Ctrl-C.
Future interactive writes
The current release scope is a read-only browser. Stage/unstage, restore, commit, entity editing, recovery, and future pruning remain CLI operations. Before adding an interactive write, provide:
- a preview naming the affected layer and entities;
- confirmation for discarding or history-changing actions;
- success text naming the recovery command;
- lock and interrupted-transaction guidance; and
- integration tests proving use of the same library operations as the CLI.
These are additional workflows, not implied capabilities of the browser.