[terminal-stylist] Terminal Stylist: Console Output Analysis — gh-aw pkg/

[github-actions[bot]]

Terminal Stylist Analysis — Console Output Patterns

Overview

947 Go source files analyzed in pkg/ (excluding test files). The codebase has an excellent, mature foundation for terminal output with pkg/console and pkg/styles. Most output is handled consistently, with a few isolated files bypassing the established patterns.

Metric	Value
Total Go source files	947
Files using pkg/console package	~204
Files using lipgloss directly	10
Files using huh directly	14
Bare fmt.Print() to stdout (outside console pkg)	3 (all justified)
Raw fmt.Fprintf(os.Stderr) without formatters	~25 call sites
Hardcoded colors	0
Missing TTY detection	0
ANSI escape literals centralized	✅ (terminal.go)

---

Strengths

✅ Adaptive Color System — Excellent

pkg/styles/theme.go defines a fully adaptive color palette using compat.AdaptiveColor (light/dark variants) with hex constants named by role. Dark mode is Dracula-inspired; light mode uses high-contrast saturated variants. Every style variable (Error, Warning, Success, Info, Command, Progress, etc.) uses these adaptive colors — zero hardcoded colors in any component file.

ColorError = compat.AdaptiveColor{
    Light: lipgloss.Color("#D73737"),
    Dark:  lipgloss.Color("#FF5555"),
}

An init() in styles/theme.go runs lipgloss.HasDarkBackground() against stderr with a Windows-safe guard, so color detection works correctly across platforms.

✅ TTY Detection — Consistent

pkg/console/console.go wraps every lipgloss render call in applyStyle():

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

RenderTitleBox, RenderErrorBox, and RenderComposedSections all branch on tty.IsStderrTerminal(), with clean text fallbacks. No raw ANSI-styled output is ever emitted in non-TTY environments.

✅ Accessibility Support — Comprehensive

IsAccessibleMode() checks three environment signals: ACCESSIBLE, TERM=dumb, and NO_COLOR. This is applied to every huh form via .WithAccessible(IsAccessibleMode()). Spinners also check ACCESSIBLE to disable animations for screen readers.

✅ Lipgloss Table Rendering — Proper Usage

console.RenderTable() uses lipgloss/table with per-cell styleFunc that respects TTY status, applies zebra-striping, distinct header/total row styles, and rounded borders. pkg/cli/gateway_logs_timeline_render.go demonstrates correct integration using console.TableConfig.

✅ Huh Form Integration — Well-Structured

pkg/styles/huh_theme.go defines a HuhTheme that maps the full styles palette to every huh field type (focused/blurred, selectors, buttons, text inputs). All 14 files using huh directly apply this theme. Non-TTY fallbacks exist in console/confirm.go and console/list.go (numbered text lists). Validation with Validate() is used in console/input.go.

✅ Spinner — Idiomatic Bubble Tea

Uses tea.NewProgram with WithoutRenderer() for manual print control, WithInput(nil) to prevent stdin consumption before subsequent huh forms, and mutex-guarded running state. ANSI sequences (\r, \033[K) are constants in terminal.go — not scattered throughout code.

✅ Error Rendering — Rust-Like

console.FormatError() produces IDE-parseable file:line:col: type: message format with optional source-code context highlighting (pointer ^^^ under the error token). FormatErrorChain() unwraps Go error chains into readable indented form. formatCompilerMessage() and formatCompilerError() in pkg/workflow/ correctly delegate to console.FormatError().

---

Issues Found

⚠️ `pkg/cli/compile_stats.go` — ~15 Raw Formatting Calls

This file formats compiler summaries with hardcoded emoji and manual structure, bypassing the console package entirely:

// Current — raw formatting, no console wrappers
fmt.Fprintf(os.Stderr, "  ✗ %s\n", filepath.Base(failure.Path))
fmt.Fprintln(os.Stderr, "  💡 Recovery plan:")
fmt.Fprintf(os.Stderr, "  %s %s:\n", prioritized.Severity.Icon(), heading)
fmt.Fprintf(os.Stderr, "    %d. %s\n", i+1, prioritized.Message)
fmt.Fprintf(os.Stderr, "       → %s\n", prioritized.Suggestion)
fmt.Fprintf(os.Stderr, "  i Suppressed %d cascading error(s)...\n", ...)

Recommendation: Use console.FormatErrorMessage(), console.FormatInfoMessage(), console.FormatListItem(), and console.FormatSectionHeader() to gain adaptive colors, TTY detection, and consistent icon styling.

⚠️ `pkg/workflow/claude_logs.go` — Debug Logs to Stderr Without Logger

~6 fmt.Fprintf(os.Stderr, ...) calls emit parse-progress messages unconditionally, regardless of debug mode:

fmt.Fprintf(os.Stderr, "Failed to parse Claude log as JSON array, trying JSONL format: %v\n", err)
fmt.Fprintf(os.Stderr, "Extracted %d JSON entries from mixed format Claude log\n", ...)

Recommendation: Replace with logger.New("workflow:claude_logs") and use log.Printf(...). Debug messages should be gated behind the DEBUG env var, not always emitted.

⚠️ Raw `WARNING:` Prefixes in `pkg/workflow/`

Several files use raw string prefixes instead of console formatters:

// compiler_orchestrator_engine.go
fmt.Fprintf(os.Stderr, "WARNING: Skipping security scan for unresolvable import '%s'...", ...)

// cache.go
fmt.Fprintf(os.Stderr, "Warning: Failed to parse cache configuration: %v\n", err)

// push_to_pull_request_branch.go
fmt.Fprintf(os.Stderr, "Warning: invalid if-no-changes value '%s', ...\n", ...)

// mcp_renderer.go
fmt.Fprintf(os.Stderr, "Error generating custom MCP configuration for %s: %v\n", ...)

Recommendation: Replace with console.FormatWarningMessage() / console.FormatErrorMessage() for consistent icon and color styling.

⚠️ `pkg/cli/experiments_command.go` — Section Headers Without Styling

// Current
fmt.Fprintln(os.Stderr, "\nExperiments:")
fmt.Fprintln(os.Stderr, "\nRecent runs:")

// Recommended
fmt.Fprintln(os.Stderr, console.FormatSectionHeader("Experiments"))
fmt.Fprintln(os.Stderr, console.FormatSectionHeader("Recent runs"))

⚠️ `pkg/workflow/side_repo_maintenance.go` — Unformatted Info Messages

fmt.Fprintf(os.Stderr, "  Generated side-repo maintenance workflow: %s\n", filename)
fmt.Fprintf(os.Stderr, "  Removed stale side-repo maintenance workflow: %s\n", name)

Recommendation: Use console.FormatSuccessMessage() / console.FormatInfoMessage().

⚠️ `pkg/workflow/lock_validation.go` — Missing Console Formatting

fmt.Fprintf(os.Stderr, "    Current: %s\n", check.Action.SHA)
fmt.Fprintf(os.Stderr, "    Latest:  %s\n", check.LatestSHA)

These raw commit SHA lines lack any visual structure. Consider console.FormatListItem() or RenderTable().

💡 Minor: `pkg/cli/view_command.go` — Info to Stdout

// Line 178 — writes info message to stdout instead of stderr
fmt.Fprintln(os.Stdout, console.FormatInfoMessage(runURL))

Status/info messages are conventionally stderr. This may affect pipe consumers who expect clean stdout data.

---

Recommendations

High Priority

1. compile_stats.go: Migrate ~15 raw format calls to console.Format*() functions. This is user-facing output shown on every compile error — consistency matters most here.
2. claude_logs.go: Replace fmt.Fprintf(os.Stderr, ...) debug output with a logger.New() instance gated on DEBUG env var.

Medium Priority

3. pkg/workflow/ raw warnings: Replace WARNING: / Warning: / Error prefixed raw strings in cache.go, mcp_renderer.go, compiler_orchestrator_engine.go, push_to_pull_request_branch.go with console.FormatWarningMessage() / console.FormatErrorMessage().

Low Priority

4. experiments_command.go: Use console.FormatSectionHeader() for section labels.
5. side_repo_maintenance.go: Use console.FormatSuccessMessage() for generated/removed file messages.
6. view_command.go line 178: Move FormatInfoMessage(runURL) from stdout to stderr.

---

Patterns Working Well — Keep As-Is

• All huh forms correctly apply HuhTheme and IsAccessibleMode() ✅
• All spinners detect TTY and respect ACCESSIBLE env var ✅
• All table rendering uses console.RenderTable() with lipgloss/table ✅
• All lipgloss colors use compat.AdaptiveColor — no hardcoded hex anywhere in components ✅
• ANSI escape codes are constants in terminal.go — not repeated as string literals ✅
• formatCompilerMessage() / formatCompilerError() in pkg/workflow/ delegate to console.FormatError() ✅
• pkg/console/confirm.go and pkg/console/list.go provide clean TTY/non-TTY dual-mode behavior ✅

References: §28089995167

Generated by 💄 Terminal Stylist · 78.7 AIC · ⌖ 13.9 AIC · ⊞ 5.7K · ◷

• expires on Jun 25, 2026, 1:56 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #41410.