This report analyzes console output patterns across the gh-aw codebase (pkg/ and cmd/), evaluating consistency, Lipgloss usage, and Huh form implementations.

Summary

Overall, the codebase has a mature, consistent console output system. The pkg/console and pkg/styles packages provide a robust, Lipgloss-backed formatting layer that is widely and correctly adopted. A small set of files diverge from the pattern and are called out below.

✅ What's Working Well

Console Formatting Adoption

The pkg/console package is well-designed and heavily used. Top formatting functions by usage:

Stdout vs Stderr Routing

The codebase correctly routes output following Unix conventions:

• Structured data (JSON, tables, hashes, Mermaid graphs) → stdout ✅
• Diagnostic messages (info, warnings, errors) → stderr via console.* ✅
• No fmt.Fprintf(os.Stdout, ...) for diagnostics found ✅

Lipgloss Integration

pkg/styles/theme.go provides a comprehensive, production-quality Lipgloss setup:

• Adaptive color system using charm.land/lipgloss/v2 with compat.AdaptiveColor for automatic light/dark terminal adaptation (Dracula theme for dark, high-contrast for light) ✅
• TTY detection via pkg/tty using golang.org/x/term, with applyStyle() in console.go that skips ANSI codes when not in a TTY ✅
• Pre-configured styles: Error, Warning, Success, Info, FilePath, Command, Progress, TableHeader, TableCell, ServerName, etc. ✅
• Border definitions: RoundedBorder, NormalBorder, ThickBorder centralized for consistency ✅
• Table & tree styles: TableHeader, TableCell, TreeEnumerator, TreeNode for structured output ✅
• Error boxes with ErrorBox (rounded border + padding) used in MCP inspection output ✅

Huh Interactive Forms

All 12 files using huh forms apply the custom theme and accessibility mode consistently:

huh.NewForm(...).WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode())

• pkg/styles/huh_theme.go: Custom HuhTheme() maps the entire Dracula-inspired palette to huh's field styles (focused/blurred borders, selectors, buttons, text input cursors) ✅
• pkg/console/accessibility.go: IsAccessibleMode() checks ACCESSIBLE, TERM=dumb, NO_COLOR env vars ✅
• All interactive files (add_interactive_*.go, run_interactive.go, engine_secrets.go, interactive.go) apply the theme ✅
• Proper huh.Group / field organization across all wizards ✅

⚠️ Issues Found

1. Raw fmt.Fprintf(os.Stderr) Warning/Error Messages in pkg/workflow/

These files have logger vars (logger.New(...)) but still use raw fmt.Fprintf for user-visible warning/error messages instead of console.FormatWarningMessage or the logger:

fmt.Fprintf(os.Stderr, "Warning: Failed to parse cache configuration: %v\n", err)
fmt.Fprintf(os.Stderr, "Warning: No cache key found in parsed configuration\n")

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

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

fmt.Fprintf(os.Stderr, "WARNING: Skipping security scan for unresolvable import '%s': %v\n", ...)
fmt.Fprintf(os.Stderr, "WARNING: Skipping security scan for unreadable import '%s' ...\n", ...)

fmt.Fprintf(os.Stderr, "Failed to parse Claude log as JSON array, ...")
fmt.Fprintf(os.Stderr, "Skipping invalid JSON line: %s\n", ...)
fmt.Fprintf(os.Stderr, "No valid JSON entries found in Claude log\n")
fmt.Fprintf(os.Stderr, "Extracted %d JSON entries from ...", ...)
fmt.Fprintf(os.Stderr, "Extracted from Claude result payload: ...")
fmt.Fprintf(os.Stderr, "Claude parser extracted %d tool sequences ...")

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

2. Mixed Console Usage in pkg/cli/mcp_list_tools.go

The file correctly uses console.FormatInfoMessage and console.FormatWarningMessage in most places, but falls back to raw fmt.Fprintf for two user-visible messages:

fmt.Fprintf(os.Stderr, "Available MCP servers: ")
fmt.Fprintf(os.Stderr, "%s\n", strings.Join(serverNames, ", "))

fmt.Fprintf(os.Stderr, "Found MCP server '%s' in %d workflow(s): %s\n", ...)
fmt.Fprintf(os.Stderr, "\nRun 'gh aw mcp list-tools ...' to list tools\n", ...)

The second block is a user-facing instruction that should use console.FormatInfoMessage and console.FormatCommandMessage.

3. Raw fmt.Fprintln(os.Stderr) in pkg/cli/copilot_setup.go and pkg/cli/mcp_config_file.go

These files output YAML code block instructions to stderr using many raw fmt.Fprintln calls. While the YAML content itself is intentionally unformatted, the surrounding instructional text (e.g., "To enable GitHub Copilot Agent integration...") skips console.FormatInfoMessage.

Consider wrapping the instructional header and footer in console.FormatInfoMessage, and using console.RenderInfoSection for the YAML code block content.

4. Debug Messages Not Using Logger in pkg/workflow/claude_logs.go

Six fmt.Fprintf(os.Stderr, ...) calls output parser diagnostic info unconditionally. Since claudeLogsLog is already defined, these should be claudeLogsLog.Printf(...) so they're hidden unless DEBUG=workflow:claude_logs is set.

💡 Recommendations

🏆 Exemplary Files

These files demonstrate the gold standard for console output:

• pkg/cli/audit_report_render.go — Consistent use of console.FormatSectionHeader, console.FormatErrorMessage, console.FormatWarningMessage throughout a complex multi-section renderer
• pkg/cli/mcp_inspect_mcp.go — Good mix of console formatting for diagnostics and structured table output to stdout
• pkg/cli/interactive.go — Huh forms with WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode()) applied consistently
• pkg/styles/theme.go — Well-documented adaptive color system with semantic variables and consistent naming
• pkg/styles/huh_theme.go — Complete Huh theme mapping all field states (focused/blurred, selected/unselected, error/success)

References:

• §23269964364

AI generated by Terminal Stylist · history

• expires on Mar 19, 2026, 10:28 PM UTC