diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index 2cd8dcf..cdbef33 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -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. diff --git a/docs/README.md b/docs/README.md index 720ea36..70918d2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/architecture.md b/docs/architecture.md index 2084510..871829c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 diff --git a/docs/roadmap.md b/docs/roadmap.md index 7d8948f..698ab85 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -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. diff --git a/docs/tui-design.md b/docs/tui-design.md new file mode 100644 index 0000000..175f3ab --- /dev/null +++ b/docs/tui-design.md @@ -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.