190 lines
10 KiB
Markdown
190 lines
10 KiB
Markdown
# TUI browser, editor, and release contract
|
||
|
||
`efo-tui` is a separate terminal interface over `lib_efo`. It browses
|
||
all six entity collections in HEAD, index (staged), and worktree (editable)
|
||
state and creates/edits entities in the worktree with explicit save previews.
|
||
The CLI remains the complete interface for staging, commits, history,
|
||
relationships, 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 |
|
||
| `a`, `e` | Add to the current collection / edit the selected entity (worktree only) |
|
||
| `u` | Preview undo of the last TUI save in this session |
|
||
| `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 the browser/help/search; cancel a form or undo confirmation |
|
||
|
||
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 and entity-draft parsing. No command changes the process working
|
||
directory. `Workspace::apply_entity_change` holds the writer lock across a fresh
|
||
read, comparison of manifest/index/worktree with the editor snapshot, validation,
|
||
and the existing journalled write operation. It writes only the worktree and
|
||
updates the browser snapshot only after success. 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. It verifies
|
||
read-only browsing, creation, multiline paste, save previews, editing, draft
|
||
cancellation, exact entity undo, unchanged HEAD/index, and terminal restoration
|
||
on `q` and Ctrl-C.
|
||
|
||
## Creating and editing entities
|
||
|
||
Select the collection (characters, towns, events, calamities, organisations, or
|
||
blockers), press `3` for the worktree, and press `a` to add. To edit, select an
|
||
entity and press `e`. HEAD and index browsing stays read-only: switch to the
|
||
worktree explicitly before opening a form.
|
||
|
||
The form has seven fields: name, multiline description, exact position, duration,
|
||
effect mode, bounds, and absolute statistics. Wide terminals show a field list;
|
||
narrow terminals show the active field. Newly created entities have zero stats,
|
||
a new stable UUID, and type-specific duration/effect/bounds defaults (events
|
||
start with one turn and `todo` effects). UUID, type, and existing relationships
|
||
are preserved while editing; use the CLI for relationship changes.
|
||
|
||
| Form key | Action |
|
||
| --- | --- |
|
||
| `Tab` / `Shift-Tab`, up/down | Next / previous field |
|
||
| left/right, `Home` / `End` | Move the text cursor |
|
||
| Backspace / Delete | Remove the previous / next character |
|
||
| `Ctrl-U` | Clear the active field |
|
||
| Enter | New line in description; next field elsewhere |
|
||
| Paste | Insert text; multiline descriptions supported |
|
||
| `Ctrl-S` | Validate and preview the exact worktree change |
|
||
| `y` in preview | Save the previewed change |
|
||
| `n` / `Esc` in preview | Return to the draft |
|
||
| `Esc` / `Ctrl-C` in form | Cancel; changed drafts require `y` to discard |
|
||
|
||
Names must be non-empty and unique (case-insensitively) within their collection.
|
||
Position uses exact integer `x,y` coordinates, including negative coordinates.
|
||
Duration accepts `permanent`, `done`, or a non-negative number of turns. Effect
|
||
accepts `recurring`, `when-present`, `todo`, or `done`. Bounds use `min:max`, with
|
||
the minimum no greater than the maximum. Statistics use the full field names
|
||
shown in the form and whitespace-separated `field:value` pairs. These are
|
||
absolute integer values, including aggregates; omitted fields stay unchanged,
|
||
and no randomisation or automatic aggregate recalculation occurs.
|
||
|
||
Preview shows the affected entity/type, worktree layer, and before/after values.
|
||
Scroll with arrows, PageUp/PageDown, or Home/End. Saving clears the browser search
|
||
so the saved entity remains visible. It does not stage or commit. Use
|
||
`efo diff`, `efo stage`, and `efo commit` for the rest of the workflow.
|
||
|
||
A save failure retains the draft and gives a scrollable error. Locks are never
|
||
broken automatically; use `efo lock status`. Interrupted transactions require
|
||
`efo recover`; then inspect the worktree before retrying, since recovery can
|
||
complete an already-written save. If another process changed manifest, index,
|
||
or worktree while the form was open, the save is refused. Cancel the draft,
|
||
reload with `r`, and reopen the entity to edit the current state.
|
||
|
||
## Undo and recovery scope
|
||
|
||
After a successful save, `u` previews undo and `y` confirms it. Undo restores the
|
||
exact previous entity, including any edits that were already unstaged when the
|
||
form opened, or removes an entity just created by the TUI. Other entities,
|
||
HEAD, and index are unchanged. Any intervening repository change refuses undo;
|
||
reloading does not bypass this check. Use `efo status` / `efo diff` to review
|
||
such changes.
|
||
|
||
Undo is **one step, in this TUI session only**. A later successful save replaces
|
||
the prior undo record; exiting loses it. For a durable recovery point, stage
|
||
and commit valuable work before continuing to edit. The CLI's
|
||
`efo restore --worktree --kind KIND @UUID` restores that entity from the index,
|
||
which discards all its unstaged edits and is not equivalent to TUI undo.
|
||
See [recovery](recovery.md).
|
||
|
||
Stage/unstage, commit, relationship editing, general deletion, transaction
|
||
recovery, and future pruning remain CLI operations. Additional interactive
|
||
writes require explicit previews, recovery guidance, and tests through the
|
||
library transaction operations.
|