docs: approve first tui checkpoint
This commit is contained in:
parent
d841899545
commit
ee40a29987
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue