Terminal Stylist Analysis: Console Output Patterns in gh-aw

[github-actions[bot]]

This report analyzes console output patterns across all Go source files in the pkg/ and cmd/ directories of github/gh-aw, evaluated against Charmbracelet ecosystem best practices.

Summary

Metric	Count
Files analyzed	~200 Go source files (non-test)
console.* formatter usages	1,527
fmt.Fprintln/fprintf(os.Stderr, …) usages	2,095
Direct fmt.Println/Printf to stdout	~120
Files using Huh forms directly	11
Files using Huh via console wrappers	2

Overall, the codebase demonstrates strong discipline in terminal output formatting. The vast majority of diagnostic output correctly uses os.Stderr with console formatting helpers, and structured data is correctly routed to os.Stdout.

---

✅ What the Codebase Does Well

Lipgloss Integration

The pkg/console/console.go file is a well-designed Lipgloss v2 integration layer:

• TTY-gated styling: All styling is applied via a local applyStyle(style, text) helper that checks tty.IsStdoutTerminal() before applying styles. Raw text is returned for non-TTY environments (pipes, CI, scripts).
• Adaptive color system (pkg/styles/theme.go): All colors use compat.AdaptiveColor{Light: ..., Dark: ...} pairs, automatically adapting to the user's terminal background. The palette is Dracula-inspired for dark mode and high-contrast for light mode.
• lipgloss/table for structured data: RenderTable() in console.go uses the charm.land/lipgloss/v2/table package with a styleFunc that applies alternating row colors, distinct header/total row styles, and padding — all TTY-gated.
• Composable layout utilities: RenderTitleBox, RenderErrorBox, RenderInfoSection, and RenderComposedSections use lipgloss.JoinVertical and border styles with fallbacks for non-TTY output. Double-border title boxes and rounded-border error boxes provide rich visual hierarchy in terminals.
• Rust-like compiler errors: FormatError() renders CompilerError structs with IDE-parseable file:line:col: type: message format, source context highlighting, and ^ pointer underlines — styled with Lipgloss and gracefully degraded for non-TTY.
• Lipgloss is never used directly in pkg/cli/: All CLI commands access styling exclusively through the console and styles packages, achieving clean separation of concerns.

Huh Form Implementation

The Huh integration is consistently well-structured across all 11 files using it directly:

• Every huh.NewForm(...) call includes .WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode()) — no exceptions found. This ensures visual consistency and screen-reader support.
• Custom HuhTheme() in pkg/styles/huh_theme.go: Maps the shared Dracula palette to Huh's theming API using lipgloss.AdaptiveColor. Covers focused/blurred states, select/multi-select indicators, button styles, and text input cursors.
• pkg/console/confirm.go and pkg/console/input.go provide wrapper functions (ConfirmAction, PromptSecretInput) that abstract single-field forms behind clean APIs.
• TTY guard in PromptSecretInput: Correctly checks tty.IsStderrTerminal() before attempting interactive input, returning a clear error when not in a terminal.
• Accessibility mode: console.IsAccessibleMode() reads the ACCESSIBLE environment variable, passed consistently to all forms.

Output Routing

The codebase correctly separates:

• Diagnostic output → os.Stderr with console formatting (FormatSuccessMessage, FormatErrorMessage, etc.)
• Structured data (JSON, hashes, Mermaid graphs, markdown reports) → os.Stdout via fmt.Println/Printf

---

⚠️ Areas for Improvement

1. Markdown Report Renderers Using Raw fmt.Printf to Stdout

audit_cross_run_render.go (66 calls) and audit_diff_render.go (35 calls) render markdown tables entirely with raw fmt.Printf/fmt.Println. While routing to stdout is correct for pipeable markdown output, these files could benefit from a shared markdown table builder utility to reduce repetition and eliminate typo-prone format strings.

Example pattern (audit_cross_run_render.go)

// Current pattern (correct but verbose):
fmt.Printf("| Metric | Value |\n")
fmt.Printf("|--------|-------|\n")
fmt.Printf("| Runs analyzed | %d |\n", report.RunsAnalyzed)
fmt.Printf("| Total requests | %d |\n", report.Summary.TotalRequests)

// Could be abstracted into a shared markdown table builder

2. Two-Library Lipgloss Split (Architectural Note)

Huh v0.8.0 depends on github.com/charmbracelet/lipgloss (v1), while the rest of the codebase uses charm.land/lipgloss/v2. The huh_theme.go file already calls this out with a comment. This is a known constraint of the ecosystem and is handled cleanly by isolating the v1 import to pkg/styles/huh_theme.go. No action needed, but worth tracking for when Huh upgrades to Lipgloss v2.

3. mcp_list_tools.go and mcp_inspect_mcp.go: fmt.Print(table) to Stdout

These files render pre-formatted text tables using fmt.Print(table) to stdout. Since these are formatted as structured output (not diagnostic messages), routing to stdout is acceptable. However, the table variable (table string) is built manually rather than using console.RenderTable() or console.RenderStruct(). Migrating to the shared console table renderer would provide consistent styling and TTY detection.

4. Bubble Tea List in pkg/console/list.go

The list.go file implements a full Bubble Tea interactive list picker (charm.land/bubbles/v2/list). This is the only direct Bubble Tea model implementation outside of huh. It includes proper TTY detection (falls back to non-interactive text list when not in a terminal). This is a good pattern but could benefit from a note in the console package README about when to prefer Bubble Tea list vs. Huh Select.

---

📋 Specific Recommendations

Priority	File(s)	Issue	Recommendation
Low	audit_cross_run_render.go, audit_diff_render.go	100+ raw fmt.Printf markdown table calls	Extract a markdownTable(headers []string, rows [][]string) helper
Low	mcp_list_tools.go, mcp_inspect_mcp.go	Manual table strings via fmt.Print(table)	Consider migrating to console.RenderTable() with TTY fallback
Info	pkg/styles/huh_theme.go	Dual Lipgloss dependency	Track Huh v2 release for Lipgloss v2 compatibility
Info	pkg/console/list.go	Bubble Tea list vs Huh Select	Document in console README when each is preferred

---

🏆 Best-Practice Examples in the Codebase

Lipgloss adaptive color system (pkg/styles/theme.go):

var ColorError = compat.AdaptiveColor{
    Light: hexColorErrorLight, // "#D73737"
    Dark:  hexColorErrorDark,  // "#FF5555"
}

TTY-safe styling (pkg/console/console.go):

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text
}

Consistent Huh form pattern (pkg/cli/interactive.go):

form := huh.NewForm(groups...).
    WithTheme(styles.HuhTheme()).
    WithAccessible(console.IsAccessibleMode())

Correct output routing (pkg/cli/tool_graph.go):

fmt.Println(mermaidGraph)   // ✅ Structured data → stdout
fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Building graph..."))  // ✅ Diagnostic → stderr

---

References:

• §23796057432

AI generated by Terminal Stylist · history

• expires on Apr 1, 2026, 12:03 PM UTC

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #23875.