hzqtc/taproom

Purpose and Entry Point

taproom is a Go terminal UI for browsing and managing Homebrew formulae and casks. It consolidates package metadata, local installation state, dependency relationships, and selected operational commands into an interactive Bubble Tea application. Process startup is main.go, with application state and event handling centered in internal/model/model.go.

CLI and Application Bootstrap

main.go parses runtime flags such as cache invalidation, release fetching, hidden columns, initial filters/sort, help visibility, timer display, and theme selection. It initializes the loading/application flow and starts the Bubble Tea runtime. Key bindings and root model behavior are defined in internal/model/keys.go and internal/model/model.go; root rendering is in internal/model/view.go.

Homebrew Integration Boundary

internal/brew encapsulates all interaction with the local brew executable and Homebrew-derived data. internal/brew/command.go executes brew operations; internal/brew/api.go obtains package catalog/API data; internal/brew/installation.go derives installed, outdated, pinned, explicit/dependency-installed, and disk-use state. internal/brew/tap.go handles tap metadata. This package is the boundary between the TUI/domain layers and external Homebrew CLI/API behavior.

Package Domain and Enrichment

internal/data/package.go defines the package-level data representation used throughout the UI and derives relationships needed for display. The system combines formula/cask catalog data with local installation information, recursive missing dependencies, reverse dependents, popularity, and optional release metadata. Release enrichment is delegated to internal/gh/gh.go, which invokes the optional GitHub CLI and is enabled by --fetch-release.

Loading and Data Assembly

internal/loading/loading.go orchestrates startup data acquisition, likely issuing independent Homebrew/local-data loading tasks concurrently so slower optional columns can be suppressed via --hide-columns. It supplies loading progress to the UI before handing assembled package data to the main model. internal/ui/loadingscreen.go presents this staged initialization, including the optional load timer.

Interactive TUI Composition

The presentation layer is split into focused Bubble Tea/Bubbles components under internal/ui. internal/ui/packagetable.go renders and navigates the package overview; internal/ui/details.go renders the selected package’s metadata and dependency/dependent information. internal/ui/searchinput.go, internal/ui/filter.go, and internal/ui/filterview.go implement real-time query and filter state. internal/ui/column.go and internal/ui/stats.go support sortable/tabular package presentation and aggregate status display.

Primary Control Flow

Startup flows from main.go to loading orchestration, then into the Bubble Tea model with a complete package dataset. User keystrokes flow through internal/model/keys.go and model update logic, mutating selection, search, filters, sorting, and views. The model recomputes the visible package set and delegates rendering to UI components. Mutating actions—install, uninstall, upgrade, pin, unpin—cross back through internal/brew/command.go, after which application state must be refreshed or reconciled.

Runtime Dependencies

The binary runs locally in a terminal with Go-built Bubble Tea, Bubbles, and Lip Gloss UI libraries. Required external executables/services are Homebrew (brew) and du; GitHub CLI (gh) is optional for release lookup. Homebrew’s package/API data and GitHub release information are the material remote data sources.