Files
pipelines/internal/tui/AGENTS.md
T

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 — the Model, the key map (keys), and Update/View dispatch. 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.