docs: approve first tui checkpoint

This commit is contained in:
Dandaedre 2026-09-21 01:17:39 +02:00
parent d841899545
commit ee40a29987
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 128 additions and 8 deletions

View File

@ -19,6 +19,10 @@ portable release gates.
default and portable test, Clippy, and release gates on 2026-09-21. Format 2 is
explicitly migratable, transactional, staged, immutable, and recoverable.
**Milestone 5 — first TUI checkpoint: in progress.** Its read-only scope,
terminal lifecycle, keyboard contract, and accessibility gate are approved in
[`docs/tui-design.md`](docs/tui-design.md).
## Phase 0 — audit and guardrails
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
@ -125,11 +129,28 @@ explicitly migratable, transactional, staged, immutable, and recoverable.
- [ ] Provide import/export and migration tooling before changing defaults.
- [ ] Test repositories containing user-defined fields and entity kinds.
## TUI checkpoint 1 — safe repository browser
- [x] Approve the separate-binary architecture and read-only first-pass scope.
- [x] Define keyboard navigation, compact-layout, accessibility, and terminal
restoration requirements.
- [ ] Add the `efo-tui` workspace binary without coupling `lib_efo` to a
terminal framework.
- [ ] Render format-2 HEAD/index/worktree status and all entity collections.
- [ ] Provide collection, entity, and detail navigation with contextual help.
- [ ] Report legacy, corrupt, locked, and interrupted repositories with the
next useful CLI command.
- [ ] Unit test state transitions and deterministic rendering with a test
backend.
- [ ] Document installation, startup, keys, scope, and CLI fallback paths.
- [ ] Pass default and portable formatting, test, strict Clippy, and release
gates without running release-only badge tooling.
## Stretch goals — proposal only
These require user approval and are not part of the current implementation:
- [ ] Interactive TUI layered over the exact same library operations (no GUI).
- [ ] Previewed, confirmed TUI mutations over the exact same library operations.
- [ ] Branching timelines with named branches and merge/conflict workflows.
- [ ] Shell completions and man pages generated from the Clap command model.
- [ ] JSON/JSONL output modes and stable query/filter expressions for scripts.

View File

@ -9,6 +9,8 @@ behavior clearly.
- [Architecture](architecture.md): crate responsibilities, data flow, and quality gates.
- [Staging design](staging-design.md): approved Phase 4 state, command, transaction,
and migration contract.
- [TUI design](tui-design.md): approved first-pass scope, interaction, safety,
and accessibility contract.
- [Roadmap](roadmap.md): current work and stretch proposals.
Start with the project [README](../README.md). Contributors should also read

View File

@ -1,18 +1,20 @@
# Architecture and development
```text
CLI parsing and rendering (`bin_efo`)
│
▼
CLI (`bin_efo`) TUI (`tui_efo`)
│ │
└─────┬──────┘
▼
domain and persistence (`lib_efo`)
│
▼
`.epoch` and `epoch/*`
```
`bin_efo` defines the Clap command tree and presentation. `lib_efo` owns
entities, statistics, identifiers, epochs, naming, and JSON persistence. New
behavior should be a testable library operation with a thin CLI handler.
`bin_efo` defines the Clap command tree and presentation. `tui_efo` owns only
its input loop, view state, and terminal presentation. `lib_efo` owns entities,
statistics, identifiers, epochs, naming, and JSON persistence. New behavior
should be a testable library operation with thin CLI and TUI adapters.
The design direction is to make repository paths explicit; replace truncating
writes with temporary-file plus rename; add locking; remove unsafe cache
@ -24,6 +26,8 @@ Phase 4's approved persistence boundary is specified in the
the index, and the editable worktree, and defines the atomic transaction and
migration rules that implementation must preserve. Versioned manifest and
snapshot types now isolate that future format from the active legacy reader.
The approved [first-pass TUI contract](tui-design.md) adds a separate read-only
format-2 browser without creating another persistence path.
Library tests currently cover parsing, statistics, display snapshots, and parts
of entity/epoch behavior. CLI integration coverage is the main gap. Routine CI

View File

@ -29,11 +29,16 @@ commits, revert, and recoverable pruning are implemented. Format 2 remains
opt-in. Organisation-agnostic custom fields and types follow, with
unknown-field retention designed before that format change.
The first [TUI checkpoint](tui-design.md) is now approved: a separate,
read-only `efo-tui` binary will browse format-2 status and entities through the
same library API. Interactive mutations remain a later, separately reviewed
checkpoint.
## Proposed stretch goals
1. Shell completions and generated man pages.
2. Stable JSON/JSONL output and query/filter expressions.
3. A keyboard-driven TUI over the same domain API (no GUI).
3. Extend the first read-only TUI with previewed, recoverable write workflows.
4. Named timeline branches with merge/conflict handling.
5. Setting templates for empires, companies, guilds, and nations.
6. Validation/simulation hooks before committing an epoch.

88
docs/tui-design.md Normal file
View File

@ -0,0 +1,88 @@
# 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
```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, 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.