[terminal-stylist] Terminal styling analysis: Go console output, Lipgloss, and Huh

[github-actions[bot]]

Overview

The Go console layer is in good shape: output routing is documented, diagnostic output is generally sent to stderr, structured output is sent to stdout, and styling is centralized behind pkg/console and pkg/styles. Lipgloss and Huh usage is deliberately terminal-aware and accessibility-aware.

The largest opportunity is not a library migration; it is finishing the migration of interactive prose and verbose diagnostics to the existing console helpers so visually equivalent messages share prefixes, destination-aware color handling, and severity semantics.

Key metrics

Measure	Result
Go files scanned (excluding _test.go)	1,546
Files under pkg/	1,526
Production fmt.Print*/fmt.Fprint* calls	3,526 across 357 files
Production console.* calls	2,182 across 276 files
Lipgloss calls	94 across 11 files
Huh calls	68 across 17 files
Raw ANSI string locations	6 across 2 files

pkg/cli is the primary output surface: 2,656 fmt output calls and 2,028 console calls. A large portion of raw fmt output is intentional structured content—Markdown reports, JSON/text payloads, tables assembled in buffers, blank lines, and subprocess passthrough—not an automatic styling defect.

Priority findings

1. Standardize unformatted interactive prose (medium). Several interactive flows mix formatted warnings/success messages with adjacent raw stderr prose. Representative locations:

   • pkg/cli/add_interactive_auth.go:28
   • pkg/cli/add_interactive_git.go:97, :185, :234-236
   • pkg/cli/add_interactive_workflow.go:121-149, :160
   • pkg/cli/add_interactive_orchestrator.go:398, :430-447, :467-476

   Use console.FormatInfoMessage, FormatWarningMessage, FormatCommandMessage, and FormatSectionHeader according to meaning, or the corresponding Print* helpers. Keep raw fmt for spacing and intentionally structured blocks. This will make fallback instructions, status polling, and final summaries consistent without styling machine-readable output.

2. Use the logging package for verbose diagnostics (medium). pkg/cli/add_interactive_workflow.go:121-142 writes status polling diagnostics directly with fmt.Fprintf. These messages fit the existing namespace logger better than user-facing output. Moving them to addInteractiveLog preserves normal terminal cleanliness and follows the repository’s debug-output convention.

3. Make input validation inline where correction is expected (low). pkg/cli/add_interactive_git.go checks an empty edited PR title only after the Huh form exits. Add a Huh Validate function so the form retains focus and explains the correction in context. Existing strong examples include pkg/cli/bootstrap_profile_helpers.go, pkg/cli/run_interactive.go, and secret inputs in pkg/cli/engine_secrets.go.

4. Prefer the existing Print* facade for simple diagnostics (low). The common pattern fmt.Fprintln(os.Stderr, console.Format...(...)) is valid and protected by pkg/linters/consolestderr, but direct console.PrintInfoMessage, PrintWarningMessage, PrintErrorMessage, and PrintSuccessMessage reduce destination/style mismatches. Keep formatter-plus-writer composition for multiline layouts and buffers.

5. Centralize the work-queue frame only if the TUI expands (low). pkg/cli/work_command_tui_view.go correctly uses Lipgloss width/height, reverse focus, bounded rendering, and Bubble Tea’s alternate screen. Its local ASCII border is accessible and color-independent. If more TUIs are added, move the frame and focus styles into pkg/styles to prevent visual drift; no immediate conversion is necessary.

Patterns implemented well

• pkg/console/doc.go clearly defines Format* versus Render* and stderr/stdout routing.
• pkg/console/console.go gates styles on the correct stream’s TTY status and degrades output through the terminal color profile.
• pkg/styles/theme.go centralizes adaptive light/dark colors, semantic message styles, borders, tables, and calendars.
• pkg/styles/huh_theme.go uses lipgloss.LightDark and applies a consistent Huh theme for focused, blurred, selected, error, and button states.
• pkg/console/prompt_form.go applies the shared theme, enables Huh accessible mode, requires TTYs, and distinguishes cancellation from failures.
• pkg/console/confirm.go provides a plain-text fallback when stderr cannot render a form.
• pkg/console/spinner.go disables animation outside a TTY and in accessible mode.
• pkg/cli/compile_schedule_calendar.go checks both terminal capability and accessibility before styling and degrades colors for the terminal profile.
• pkg/cli/engine_secrets.go uses lipgloss.Width for Unicode-aware alignment and masks sensitive Huh inputs.
• pkg/cli/status_command.go keeps JSON on stdout and diagnostics on stderr.
• pkg/linters/consolestderr enforces destination-aware formatter variants for direct standard-stream writes.

Lipgloss assessment

Lipgloss is concentrated rather than scattered: 94 calls in 11 production files. Most styling lives in pkg/console and pkg/styles; direct CLI usage is limited to width-aware alignment, tree rendering, the schedule calendar, status output, and the work-queue TUI.

No problematic hard-coded ANSI colors were found. The only raw ANSI sequences are cursor/screen controls in pkg/console/terminal.go and pkg/console/prompt_form.go; Lipgloss does not replace those controls, and they are guarded by TTY/accessibility behavior.

The work-queue TUI intentionally relies on reverse video and ASCII borders rather than color alone, which is a good accessibility property. Table rendering already uses lipgloss/table, adaptive alternating rows, bounded width, and plain output when not attached to a terminal.

Huh assessment

Huh usage covers input, text, select, multiselect, and confirm fields. All forms are funneled through console.NewForm/New*Form, which provides the shared theme and accessible mode. Password fields use EchoModePassword, and important inputs have validators.

Keyboard navigation is delegated to Huh/Bubble Tea rather than reimplemented. Form rendering requires stdin and stderr TTYs, while confirmation has a text fallback. The main usability improvement is to move remaining post-submit checks—such as the empty PR-title check—into field validation so users can correct values without leaving the form.

Method and scope

The scan parsed every .go file in the repository except files ending in _test.go, with pkg/ treated as the primary analysis area. Import-aware AST classification separated fmt, repository console, Lipgloss, Huh, and raw ANSI usage; testdata was excluded from production metrics.

Serena project activation and semantic pattern searches succeeded. Serena’s symbol-overview language-server startup subsequently failed with an environment-detection error, so symbol-level review was completed with Go AST parsing and targeted source reads rather than Serena diagnostics.

Recommended next actions

1. Convert the four interactive-flow clusters above to semantic console helpers, preserving raw output for layout only.
2. Move workflow-status polling diagnostics to addInteractiveLog.
3. Add inline Huh validation for editable PR titles and other correction-required fields.
4. Add or extend lint coverage only if the team wants to prohibit raw user-facing prose on stderr; avoid flagging structured renderers and subprocess passthrough.

References:

• §38126150525

Generated by 💄 Terminal Stylist · pi · gpt56 · 128.4 AIC · ⌖ 23.3 AIC · ⊞ 7.3K · ◷

• expires on Oct 12, 2026, 12:56 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-10-12T08:56:17.275Z.

Closed by Workflow