[terminal-stylist] Terminal Stylist Audit: Console Output Patterns Analysis

[github-actions[bot]]

This audit covers all 729 non-test Go source files in pkg/, analyzing console output consistency, Lipgloss styling patterns, and Huh form usage.

---

Executive Summary

The codebase has a well-architected terminal output system (pkg/console + pkg/styles) that the majority of CLI commands use correctly. The Lipgloss and Huh integrations follow ecosystem best practices. A small number of files bypass the console formatters and write unformatted strings to os.Stderr — these represent the primary improvement opportunity.

Metric	Value
Total Go source files	729
Files correctly using console.Format*	135
Files with interactive Huh forms	9
Bare stderr prints without console formatting	~648 call sites
Bare err.Error() to stderr (anti-pattern)	9 files

---

✅ Strengths

Lipgloss — Well-Integrated

pkg/styles/theme.go and pkg/console/console.go form a strong foundation:

• Adaptive colors via compat.AdaptiveColor — every color has Light/Dark hex variants that auto-select based on terminal background. The dark palette is Dracula-inspired; light palette is high-contrast for readability.
• TTY gating — applyStyle() returns plain text when stdout is not a TTY, preventing ANSI escape codes in pipes/redirects.
• Centralized style definitions — all semantic styles (Error, Warning, Success, Info, FilePath, Command, Progress, etc.) are defined once in pkg/styles/theme.go.
• Table rendering — RenderTable() uses lipgloss/table with zebra striping, RoundedBorder, and TTY-conditional styling.
• Composed layouts — RenderComposedSections() uses lipgloss.JoinVertical in TTY mode, plain line output otherwise.
• Semantic border types — RoundedBorder, NormalBorder, and ThickBorder are centrally defined with documented use cases.

Huh Forms — Consistent UX

pkg/styles/huh_theme.go maps the same color palette to Huh field styles, giving interactive forms the same visual identity as static output. Notable patterns found across 9 form files:

• Custom HuhTheme applied universally — focused/blurred/error states all use the established palette
• The Bubble Tea SpinnerWrapper correctly sets tea.WithInput(nil) to avoid consuming stdin before subsequent Huh forms
• Accessibility respected via ACCESSIBLE environment variable (disables spinner animation)

Spinner — Production-Ready

pkg/console/spinner.go follows idiomatic Bubble Tea patterns:

• Thread-safe start/stop via sync.Mutex + sync.WaitGroup
• Safe no-op when stopped before start
• MiniDot style with styles.Info color
• StopWithMessage prints the final message to stderr even when spinner is disabled

---

⚠️ Improvement Opportunities

1. Bare fmt.Fprintln(os.Stderr, ...) Without Console Formatting

~648 call sites across the CLI write plain strings to os.Stderr without using console.Format* helpers. This produces uncolored, unstyled output inconsistent with the surrounding UI.

Key files with this pattern:

File	Issue
pkg/cli/enable.go	~12 bare progress/status lines
pkg/cli/engine_secrets.go	Multi-line instruction blocks to stderr
pkg/cli/deps_security.go	Advisory summaries without styling
pkg/cli/deps_outdated.go	Blank-line separators only
pkg/cli/copilot_setup.go	Multi-line instruction output
pkg/cli/add_interactive_git.go	PR merge instructions
pkg/cli/compile_file_operations.go	Watch-mode status line
pkg/cli/update_container_pins.go	Progress separators

Examples of bare stderr anti-patterns

// ❌ BAD — pkg/cli/compile_file_operations.go:213
fmt.Fprintln(os.Stderr, "Watching for file changes")

// ✅ SHOULD BE
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Watching for file changes"))

// ❌ BAD — pkg/cli/enable.go:198
fmt.Fprintf(os.Stderr, "The following workflows will be %sd:\n", action)

// ✅ SHOULD BE
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("The following workflows will be %sd:", action)))

// ❌ BAD — pkg/cli/engine_secrets.go:293
fmt.Fprintln(os.Stderr, "GitHub Copilot requires a fine-grained Personal Access Token (PAT) with 'Copilot requests' permissions.")

// ✅ SHOULD BE
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("GitHub Copilot requires a fine-grained PAT with 'Copilot requests' permissions."))

2. Raw err.Error() to os.Stderr Instead of FormatErrorMessage

9 files pass raw err.Error() strings to stderr without console.FormatErrorMessage() or console.FormatErrorChain():

// ❌ BAD — pkg/cli/compile_file_operations.go:113
fmt.Fprintln(os.Stderr, err.Error())

// ✅ SHOULD BE
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(err.Error()))
// OR for wrapped error chains:
fmt.Fprintln(os.Stderr, console.FormatErrorChain(err))

3. audit_cross_run_render.go — Markdown Tables to Stdout

pkg/cli/audit_cross_run_render.go writes raw Markdown table syntax to stdout via fmt.Printf. This is intentional structured output (designed to be piped/redirected), but lacks a comment explaining the design intent. Adding a comment would prevent future reviewers from treating these as styling regressions.

// RenderCrossRunReport outputs a Markdown-formatted report to stdout
// for piping/redirection. Raw fmt.Printf is intentional — no ANSI styling.
func RenderCrossRunReport(report *CrossRunReport) {
    fmt.Println("# Audit Report — Cross-Run Analysis")
    ...
}

---

Recommendations

Priority 1 — High impact, low effort:

• Apply console.FormatInfoMessage / console.FormatProgressMessage to plain informational fmt.Fprintln(os.Stderr, ...) calls in enable.go, compile_file_operations.go, and add_interactive_git.go
• Replace fmt.Fprintln(os.Stderr, err.Error()) with console.FormatErrorMessage(err.Error()) in the 9 affected files

Priority 2 — Medium impact:

• Standardize the instruction blocks in engine_secrets.go and copilot_setup.go using console.RenderInfoSection() for the multi-line instructional content — this would add the left-border emphasis style that's already available

Priority 3 — Documentation:

• Add a comment to audit_cross_run_render.go (and similar render files) noting that fmt.Printf is intentional for structured stdout output

No action needed on:

• JSON output files (domains_command.go, status_command.go, trial_helpers.go, hash_command.go) — fmt.Println(jsonBytes) to stdout is correct per the codebase style guide
• Lipgloss adaptive color usage — already follows best practices
• Huh theme integration — already uses the shared palette
• Spinner implementation — idiomatic Bubble Tea, fully accessible

---

References:

• §25107925380

Generated by Terminal Stylist · ● 869.1K · ◷

• expires on Apr 30, 2026, 12:15 PM UTC