Skip to main content

menus

The interactive menu is a persistent TUI shell (internal/tui/app): a stack of screens with a breadcrumb header, contextual footer, and a command palette. This page maps the current flows and their tests.

KeyAction
↑↓ / j kmove cursor
enter / → / lselect / drill in
esc / ← / backspace / hback (quits at root)
/fuzzy-filter the current menu
ctrl+pcommand palette (fuzzy search over every action)
?help overlay
g / Gfirst / last item
q / ctrl+cquit

All flows render natively inside the shell. (Historical note: items once the shell resumes) — they are candidates for native-screen migration.

graph TD
Home[Home] --> Status["📊 Status (native scrollable view)"]
Home --> Doctor["🩺 Doctor (native diagnostics, --fix/--bench via CLI)"]
Home --> Terminal["👻 Terminal Setup (Ghostty/WezTerm: install, Dock pin, themed config)"]
Home --> Shell[🐚 Bluefin Shell]
Home --> Install[📦 Install Apps]
Home --> Wallpapers["🖼 Wallpapers (install collections + set wallpaper on macOS/GNOME/Windows)"]
Home --> Fonts["🔤 Fonts (native multiselect)"]
Home --> Starship["🚀 Starship Theme (native select)"]
Home --> Sunset["🌇 Sunset Switching (plus build, WSL/Windows only)"]
Home --> Exit[👋 Exit]

Shell --> Toggle["🔄 Toggle current shell (auto-detected)"]
Shell --> Components["🔧 Configure Components (native multiselect)"]
Shell --> MOTD["📰 MOTD Settings (native menu)"]
Shell --> Shells["🐚 Other Shells (native multiselect)"]
Shell --> Advanced["🎨 Advanced (native: dark mode, flavor)"]

Install --> AI["🤖 AI Tools"]
Install --> CLI["💻 CLI Essentials"]
Install --> CNCF["🌐 CNCF Tools"]
Install --> XIDE["🧪 Experimental IDE"]
Install --> IDE["📝 IDE Tools"]
Install --> K8s["🎡 Kubernetes Tools"]
Install --> Gnome["🐧 Full GNOME Desktop (Linux+GNOME only)"]

AI --> Pkg["Per-category package multiselect (native):\ninstalled pre-checked, diff → confirm → runner"]
Install --> MyBrew["🏠 My Brewfile: install all, manage, add via\ncross-manager search, remove, dump"]

The ctrl+p palette lists every leaf destination above (Status, each install category, Wallpapers, Fonts, Starship, Sunset). A single search reaches every destination in the tree. Each command or menu module registers its own palette action; cmd/menu.go only composes the navigation tree.

How this is tested​

Three layers, run by CI and just recipes:

  1. Model tests (internal/tui/app/app_test.go): Use synchronous tests for navigation state, cursor movement, the filter, palette, help, and the composed frame.
  2. Menu wiring tests (cmd/menu_test.go): Check every menu item and bundle category. Each entry must resolve to an action and never lead nowhere.
  3. End-to-end smoke (scripts/tui-smoke.sh, just tui-smoke): Drives the real binary in a tmux pane. It captures the screen and checks the menu, drill-down, filter, palette, help, and quit.

For more about the TUI tests, see the test guide.

Native screens & extras​

  • Every flow renders inside the shell. Selection UIs use app.FormScreen, and read-only views use app.TextScreen. Tasks that print (brew installs, MOTD, doctor) use app.RunnerScreen. The runner captures stdout in a scrollable log with a spinner and elapsed time. The only terminal handover is the WSL→Windows sunset delegation (app.RunExternal), which launches another interactive program.
  • bluefin-cli doctor — environment diagnostics with fix hints.
  • bluefin-cli theme <flavor> — pin a Catppuccin flavor (latte, frappe, macchiato, mocha) or auto to follow the terminal background.
  • bluefin-cli update — script installs use the release checksums. The menu checks for updates in the background and shows a toast.
  • 🦕 Dino Run — hidden runner mini-game on the half-block pixel canvas: ctrl+p → "Dino Run", or the hidden bluefin-cli dino command. Space jumps kelp, stay down under fish; high score persists.
  • 👻 Terminal Setup — install Ghostty on macOS/Linux via brew or WezTerm on Windows via winget. Pin Ghostty to the macOS Dock and write a Catppuccin light/dark config with your Nerd Font.
  • 🏠 My Brewfile — one package file for every OS. Dump installed packages, search across managers, remove entries, or install everything. Also run bluefin-cli brewfile. For the syntax, refer to the Brewfile guide.
  • 📦 Profiles — profile export/import/diff/push/pull replay a whole setup (shells, tools, flavor) across machines, synced via a private gist. See the profile workflow guide.