[terminal-stylist] Terminal Stylist Audit — Console Output Analysis

[github-actions[bot]]

This report analyzes console output patterns in the github/gh-aw codebase for consistency, formatting correctness, and alignment with Charmbracelet ecosystem best practices.

---

Overview

The codebase has a well-established console output architecture built on two layers:

1. pkg/styles — Lipgloss-based style definitions with adaptive colors (light/dark terminal support)
2. pkg/console — Higher-level formatting helpers (FormatInfoMessage, FormatWarningMessage, etc.) that wrap styles

Overall compliance is high. The vast majority of output (~1,600+ calls) correctly uses the console package. However, there are specific areas needing attention.

---

Summary Statistics

Category	Count
console.FormatInfoMessage calls	608
console.FormatWarningMessage calls	466
console.FormatSuccessMessage calls	202
console.FormatErrorMessage calls	53
Raw fmt.Println / fmt.Printf to stdout	~159
Raw fmt.Fprintln/Fprintf to stderr without console formatting	~30

---

✅ What's Working Well

Lipgloss Usage (pkg/styles)

• Adaptive colors via compat.AdaptiveColor with both Light/Dark variants — correctly handles dark and light terminal themes
• Semantic color palette: Error (red), Warning (orange), Success (green), Info (cyan), Purple, Yellow, Comment, Foreground, Background, Border
• Multiple border styles: RoundedBorder, NormalBorder, ThickBorder available for layout flexibility
• Pre-built component styles: ErrorBox with rounded borders and padding — good pattern for critical errors
• Uses charm.land/lipgloss/v2 (v2 API with adaptive color built-in) ✅

Console Package

• Comprehensive message types: Info, Warning, Success, Error, Command, Progress, Verbose, Location, Section headers
• console.RenderTable, console.TableConfig used consistently (~83 usages total)
• console.RenderStruct for structured data rendering
• console.ConfirmAction for interactive confirmations
• console.NewSpinner / console.SpinnerWrapper for progress feedback

Structured Output to stdout (Correct Pattern)

The following files correctly send structured/piped data to stdout:

• hash_command.go → hash string
• tool_graph.go → Mermaid graph
• status_command.go, list_workflows_command.go, deps_report.go → JSON
• audit_cross_run_render.go, audit_diff_render.go → Markdown reports (piped output)

---

⚠️ Areas Needing Improvement

1. Raw stderr output without console formatting

These files write to os.Stderr directly without using console.Format* helpers:

pkg/cli/enable.go (~12 raw stderr calls)

// Current (no formatting)
fmt.Fprintf(os.Stderr, "No specific workflows provided. %sing all workflows...\n", ...)
fmt.Fprintf(os.Stderr, "Workflow %s is already enabled\n", name)
fmt.Fprintf(os.Stderr, "All specified workflows are already %sd\n", action)
fmt.Fprintf(os.Stderr, "The following workflows will be %sd:\n", action)

// Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("No specific workflows provided. Enabling all workflows..."))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Workflow %s is already enabled", name)))

pkg/cli/deps_security.go (~4 raw stderr calls)

Security advisory output is printed as plain text. This is a high-visibility area that would benefit from styled output:

// Current
fmt.Fprintln(os.Stderr, line)
fmt.Fprintf(os.Stderr, "    %s", adv.Summary)

// Recommended — use console.FormatWarningMessage or console.FormatErrorMessage
// depending on severity

pkg/cli/audit.go (~3 raw stderr calls)

Log file paths written without formatting:

fmt.Fprintf(os.Stderr, "  - %s (full job log)\n", jobLogPath)

// Recommended
fmt.Fprintln(os.Stderr, console.FormatLocationMessage(fmt.Sprintf("- %s (full job log)", jobLogPath)))

pkg/workflow/cache.go (~2 raw stderr calls)

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

// Recommended
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Failed to parse cache configuration: %v", err)))

pkg/workflow/push_to_pull_request_branch.go (~1 raw stderr call)

// Current
fmt.Fprintf(os.Stderr, "Warning: invalid if-no-changes value '%s', using default 'warn'\n", ...)

// Recommended
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Invalid if-no-changes value '%s', using default 'warn'", ...)))

---

2. No Huh Forms Library

The codebase does not use charmbracelet/huh for interactive prompts. Instead, interactive flows are implemented manually (e.g., add_interactive_*.go files).

Recommendation: Evaluate charmbracelet/huh for future interactive wizards (add_wizard_command.go). It would provide:

• Structured form groups with validation
• Built-in accessibility mode
• Consistent keyboard navigation
• Native Lipgloss theming integration

This is not urgent — the current implementation works — but it's worth considering for gh aw add wizard UX improvements.

---

3. Minor: audit_cross_run_render.go uses Markdown headers to stdout

audit_cross_run_render.go outputs # Audit Report and ## Executive Summary as raw Markdown headers to stdout. This is intentional for report piping, but worth noting that it bypasses the styled rendering system entirely. This is acceptable for piped/redirected report output.

---

Recommendations (Prioritized)

Priority	Action	Files
🔴 High	Replace raw fmt.Fprintf(os.Stderr, ...) with console.Format* calls	enable.go, deps_security.go
🟡 Medium	Replace raw stderr in workflow package	cache.go, push_to_pull_request_branch.go
🟢 Low	Add file path context for audit log paths	audit.go
🔵 Future	Evaluate charmbracelet/huh for add wizard UX	add_wizard_command.go

---

Conclusion

The codebase demonstrates strong adherence to terminal styling best practices:

• Lipgloss v2 with adaptive colors is correctly implemented in pkg/styles
• The pkg/console package provides rich, consistent formatting helpers
• The vast majority of output follows the correct routing (diagnostic → stderr with formatting, structured data → stdout)

The main gap is ~30 raw stderr writes in enable.go and deps_security.go that bypass the formatting system. Addressing those two files would bring compliance to near 100%.

References:

• §24955994804

Generated by Terminal Stylist · ● 491.4K · ◷

• expires on Apr 27, 2026, 11:59 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #28712.