tuify: Instructions file for Codex

Agent Development Guide

A file for guiding coding agents.

Commands

go build                         # build the tuify binary
go test ./...                    # run all tests
go test -run TestName ./internal/spotify   # run a single test in one package
gofmt -l .                       # CI fails hard if this lists anything
golangci-lint run ./...          # matches CI lint job; pinned to v2.14.0
go vet ./...

Linux build/test needs libasound2-dev (oto audio backend). Go 1.27+.

Architecture

main.go handles --version/--help (anything else exits 2) and calls bootstrap.Run, mapping its ErrInterrupted to exit status 130. Everything lives under internal/. Each internal package has a doc.go — read it before touching the package; the package-level comment is the source of truth for intent and invariants.

Startup sequence (internal/bootstrap)

Run owns a root context.Context that is cancelled on return. That context is threaded into auth (token refresh), spotify (polls), librespot (reconnect/transfer), and the UI model so every background goroutine unwinds at shutdown rather than running to its per-op timeout. Order matters:

1. Load/setup config → theme.Apply(cfg.Theme) → ui.RebuildStyles() before any rendering (see Hard rule on Lipgloss style construction).
2. authenticate returns an *authSession: the *spotify.Client plus channels for revoked-token + token-save errors that are wired into the UI via ModelOptions, and a cleanup func.
3. startLibrespot is optional; when active it provides additional ModelOptions (WithAudioSource for the pipe → FFT path, WithLibrespotInactive for the device-dropped banner) and wires Process.OnReconnect to the transfer-back handler.
4. zone.NewGlobal() then tea.NewProgram(..., WithAltScreen(), WithMouseCellMotion()).

UI shell + screens + submodels (internal/ui)

• Shell (app*.go) owns the Model, view stack, event loop, and every side effect (Spotify calls, clipboard, device transfer).
• Screens (home/playlist/track/podcast/episode/search) own local state and render themselves. They communicate with the shell via intent messages (app_intents.go).
• Submodels (nowPlayingModel, visualizerModel, deviceSelectorModel) are long-lived state on Model that transcends the view stack.
• The shell dispatches via small capability interfaces in common.go (listProvider, scrollable, clickable, enterable, searchAware, syncableView, backable, …). Adding a new screen means implementing the capabilities it cares about and listing them in the compile-time checks at the end of common.go (the shell finds capabilities by type assertion, so a missing or misnamed method fails silently otherwise). Capability methods are lowercase except those mirroring bubbletea/bubbles (Init, Update, View, SetSize).
• Every frame that shows a list is wrapped in bubblezone.Scan; list rows are marked by list id and row index via zoneListDelegate (in styles.go) so clicks resolve back to specific rows even when a playlist repeats a track. Overlays and the visualizer skip the scan, and handleMouse ignores the pointer while they are up.