2.2 KiB
2.2 KiB
The TUI — working map
Read this before touching internal/tui/. The generic side — how a Go CLI/TUI project is built,
tested and reviewed — belongs to the pipeline that started you.
Build and test
go build ./...
go test ./internal/tui # fast (~2-4 s); the whole tree is ~1 min
go vet ./...
No device, no capture, no network: a TUI change is verified by unit tests plus a rendered frame.
How the TUI is put together
model.go— theModel, the key map (keys), andUpdate/Viewdispatch. Key bindings are declared in one place; a new binding goes there, not inline.dashboard.go,pipeline.go,runs.go,run_detail.go— the screens. A run's detail is built from sections, and a section can open as its own pane in the sliding stack.context_footer.go— the footer for the current mode. A modal's footer replaces the page's; never inherit shortcuts that the modal does not honour.theme.go/style.go— colours and text styles. Status colour comes from one vocabulary so a state looks the same in every screen.linetext.go,graph.go— line building and the stage graph rendering.- Human decision stages are answered in the TUI:
↑/↓ choose · Tab feedback · Enter decide · Esc cancel.
Reviewing a TUI change without a terminal
The pinned frames in internal/harness/tmp/ui-review/render/ (empty-catalog-*, filter-no-match-*,
narrow-long-model-*, plain-nocolor-*, wide-focused-*, in dark and light) are the reference
renders. Compare against them when a change alters layout, spacing, colour or the footer, and add a
frame when you introduce a new state worth pinning. A change that alters a pinned frame and does not
say why is a review finding.
Conventions and traps
- No polling: state arrives from the server; do not add a ticker to look busy.
- The footer and the pane stack are shared surfaces — a change there affects every screen, so say what you checked.
- Terminal width matters: verify at a narrow width as well as a wide one, and never assume colour
support (
plain-nocolor-*exists for a reason). - Do not restart the deployed server, the lanes or ntfy to test a TUI change: run the binary against a scratch server or use the fixtures.