127 lines
6.2 KiB
Markdown
127 lines
6.2 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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](recovery.md) 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:
|
||
|
||
```bash
|
||
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.
|