Terminal Stylist Audit: Console Output Patterns in gh-aw

[github-actions[bot]]

Executive Summary

This audit analyzed 545 Go source files across pkg/ and cmd/ directories for console output consistency, Lipgloss styling patterns, and Huh form implementations. The codebase has a strong foundation with a dedicated pkg/console package, but there are notable gaps in adoption.

Metric	Count
Source files scanned	545
Files using console.* formatting	145
Files with fmt.Fprintln/fmt.Fprintf (total)	181
Raw stderr writes in pkg/cli/ (unformatted)	508
Files directly importing huh outside pkg/console	8

---

✅ What's Working Well

1. Strong Console Package Architecture

pkg/console/ is a well-designed central hub for all terminal output:

• TTY-aware styling: The applyStyle() function checks isTTY() before applying Lipgloss styles — ANSI codes never leak into pipes or redirects.
• Adaptive colors: pkg/styles/theme.go uses lipgloss.AdaptiveColor with distinct Light/Dark variants for every semantic color (Error, Warning, Success, Info, etc.), inspired by the Dracula theme for dark mode.
• Rich component library: Spinner (Bubble Tea), ProgressBar (bubbles/progress with scaled gradient), interactive List (bubbles/list), Select/MultiSelect (huh), Input/PasswordInput (huh), Confirm dialog (huh), Form (huh), RenderTable (lipgloss/table), RenderTree (lipgloss/tree), Banner (lipgloss).
• Accessibility support: IsAccessibleMode() properly gates animations behind ACCESSIBLE, TERM=dumb, and NO_COLOR environment variables, and all Huh forms use .WithAccessible(console.IsAccessibleMode()).
• Structured output routing: JSON, hashes, and graph data correctly go to stdout via fmt.Println; all diagnostic output goes to stderr.
• Consistent message types: FormatSuccessMessage, FormatErrorMessage, FormatWarningMessage, FormatInfoMessage, FormatCommandMessage, FormatProgressMessage, FormatPromptMessage, FormatCountMessage, FormatVerboseMessage, FormatLocationMessage, FormatListHeader, FormatListItem.
• RenderStruct: Reflection-based struct rendering with console: struct tags — very powerful for uniform output of data objects.

2. Table and Tree Rendering

RenderTable and RenderTree use lipgloss/table and lipgloss/tree with proper fallback to plain text when not in a TTY. The table uses alternating row colors, styled headers, and totals rows.

3. Progress Bar with Gradient

NewProgressBar uses progress.WithScaledGradient("#BD93F9", "#8BE9FD") — the gradient scales with the filled portion, providing polished visual feedback without affecting non-TTY output.

---

⚠️ Issues Found

Issue 1: Direct huh Usage in CLI Layer (8 files)

These files import github.com/charmbracelet/huh directly instead of going through pkg/console abstractions:

File	Direct huh. Calls	Notes
pkg/cli/interactive.go	53	Large multi-step workflow builder
pkg/cli/engine_secrets.go	12	PAT/API key collection
pkg/cli/run_interactive.go	11	Run configuration forms
pkg/cli/add_interactive_engine.go	5	Engine setup
pkg/cli/git.go	3	Git commit confirmation
pkg/cli/add_interactive_workflow.go	3	Workflow setup
pkg/cli/add_interactive_orchestrator.go	3	Orchestrator setup
pkg/cli/add_interactive_auth.go	3	Auth setup

Impact: Theming changes to forms must be applied in multiple places; accessibility mode is applied consistently (all call console.IsAccessibleMode()), but this is a coincidence of convention, not enforced abstraction.

Recommendation: The pkg/console package already provides console.PromptInput, console.PromptSecretInput, console.PromptSelect, console.PromptMultiSelect, console.ConfirmAction, and console.RunForm. The multi-step workflow builder in interactive.go is too complex for these simple helpers and likely needs its own dedicated console component (e.g., console.RunMultiStepForm).

Issue 2: 508 Raw fmt.Fprintln/Fprintf(os.Stderr) Calls

The top 15 files with raw (unformatted) stderr writes:

File	Raw Stderr Writes
pkg/cli/audit_report_render.go	98
pkg/cli/mcp_inspect_mcp.go	41
pkg/cli/preconditions.go	35
pkg/cli/engine_secrets.go	31
pkg/cli/shell_completion.go	21
pkg/cli/deps_report.go	20
pkg/cli/copilot_setup.go	19
pkg/cli/add_interactive_workflow.go	19
pkg/cli/add_interactive_orchestrator.go	15
pkg/cli/fix_command.go	14
pkg/cli/enable.go	12
pkg/cli/run_interactive.go	11
pkg/cli/init.go	11
pkg/cli/run_push.go	10
pkg/cli/compile_helpers.go	10

These fall into two categories:

A. Blank lines — fmt.Fprintln(os.Stderr, "") used for visual spacing. Acceptable but could be centralized.

B. Unformatted instructional text — Plain strings without any console formatting:

// pkg/cli/preconditions.go
fmt.Fprintln(os.Stderr, "Please run the following command to authenticate:")
fmt.Fprintln(os.Stderr, "  gh auth login")

// pkg/cli/engine_secrets.go
fmt.Fprintln(os.Stderr, "GitHub Copilot requires a fine-grained Personal Access Token...")

These should use console.FormatInfoMessage(), console.RenderInfoSection(), or console.RenderComposedSections() for visual emphasis.

Issue 3: Inline Emoji + Markdown in mcp_inspect_mcp.go

This file uses raw fmt.Fprintf with inline markdown-style formatting and emojis:

fmt.Fprintf(os.Stderr, "📋 **Name:** %s\n", foundTool.Name)
fmt.Fprintf(os.Stderr, "📝 **Description:** %s\n", foundTool.Description)
fmt.Fprintf(os.Stderr, "✅ **Status:** Allowed\n")
fmt.Fprintf(os.Stderr, "🚫 **Status:** Not allowed...\n")

The **bold** markdown syntax renders as literal asterisks in a terminal. This should use Lipgloss bold styling via console.* formatting functions or the RenderInfoSection/table system.

Issue 4: Bullet Lists Duplicated Instead of Using FormatListItem

Several files implement their own bullet-point lists with raw fmt.Fprintf:

// pkg/cli/fix_command.go
fmt.Fprintf(os.Stderr, "    • %s\n", codemodName)

// pkg/cli/update_actions.go
fmt.Fprintf(os.Stderr, "  %s\n", action)

// pkg/cli/enable.go
fmt.Fprintf(os.Stderr, "  %s\n", wf)

console.FormatListItem() already exists for this purpose, and console.FormatListHeader() for headers.

Issue 5: Missing RenderInfoSection Usage in Instructional Blocks

preconditions.go, engine_secrets.go, and mcp_config_file.go output multi-line instructional blocks as raw text. The console package already provides RenderInfoSection (left border emphasis) and RenderComposedSections for visually grouped content — these are unused in the instructional output contexts where they would be most valuable.

---

📋 Recommendations by Priority

High Priority

1. Migrate preconditions.go instructional output (35 raw writes) to use console.RenderInfoSection / console.RenderComposedSections. This is a high-impact, visible user-facing file.

2. Fix mcp_inspect_mcp.go markdown-in-terminal anti-pattern (41 raw writes) — replace **Bold:** literals with Lipgloss-styled output or console.FormatSectionHeader + console.FormatListItem.

3. Replace inline bullet lists with console.FormatListItem() across fix_command.go, update_actions.go, and enable.go.

Medium Priority

4. Centralize multi-step form logic from pkg/cli/interactive.go into a console.RunMultiStepForm or console.WorkflowBuilder component so theming is enforced at the package boundary.

5. Migrate engine_secrets.go instructional blocks to use console.RenderInfoSection for PAT setup instructions — these are multi-line user-visible content that would benefit from visual framing.

Low Priority / Style

6. Replace fmt.Fprintln(os.Stderr, "") blank-line spacers with a helper like console.PrintBlankLine() for semantically clear intent.

7. Audit audit_report_render.go — it mixes console formatting calls and raw writes. While the 98 raw writes are mostly blank lines and spacing, the pattern should be consistent.

---

💎 Standout Patterns Worth Highlighting

• RenderTitleBox with lipgloss.DoubleBorder() and auto-fallback to ━━━ separators is a great TTY-aware pattern.
• RenderErrorBox with lipgloss.RoundedBorder() and red border foreground is clean and consistent.
• buildLipglossTree using lipgloss/tree with EnumeratorStyle + ItemStyle is modern and idiomatic.
• Progress bar gradient (#BD93F9 → #8BE9FD) with WithScaledGradient is a nice UX touch that also works as plain text in non-TTY.
• RenderStruct with struct tag-based rendering (console:"header:...", console:"omitempty") is a powerful abstraction used in audit reporting.

---

Files Exemplifying Best Practices

• pkg/cli/audit.go — 43 console formatting calls, minimal raw writes
• pkg/cli/trial_command.go — 75 console calls, JSON to stdout correctly
• pkg/cli/logs_orchestrator.go — 49 console calls, well-structured output
• pkg/cli/upgrade_command.go — 25 console calls, consistent formatting

---

Analyzed by Terminal Stylist Agent on 2026-02-19. Repository: github/gh-aw.

AI generated by Terminal Stylist

• expires on Feb 26, 2026, 10:28 PM UTC