106 lines
4.0 KiB
Markdown
106 lines
4.0 KiB
Markdown
# 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 repository
|
|
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.
|
|
|
|
Unsupported repository versions receive an actionable error. 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
|
|
|
|
```text
|
|
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, 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, then start the browser from a repository or name its
|
|
path explicitly:
|
|
|
|
```bash
|
|
cargo install --locked --path bin_efo
|
|
cargo install --locked --path tui_efo
|
|
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.
|