Terminal Stylist: Console Output Analysis Report — gh-aw

[github-actions[bot]]

This report summarizes a full audit of console output patterns across the gh-aw Go codebase, evaluating consistency, Lipgloss v2 usage, and Huh interactive form implementations.

---

Summary

Metric	Value
Go source files analyzed	614
Files using console.Format* / console.Render*	116 of 117 in pkg/cli/
Huh interactive forms	16 across 9 files
Huh forms with WithTheme + WithAccessible	16/16 (100%) ✅
Files with raw unformatted stderr output	~20 in pkg/cli/, ~10 in pkg/workflow/

Overall health: Good architecture with localized inconsistencies. The pkg/console and pkg/styles packages are well-designed. Most output goes through proper formatters. Gaps are concentrated in a small number of files.

---

Lipgloss v2 — Architecture & Best Practices

✅ Excellent architecture: Lipgloss usage is centralized in pkg/styles/theme.go and pkg/console/console.go. Direct Lipgloss imports are absent from pkg/cli and pkg/workflow — all styling flows through the abstraction layer.

✅ Adaptive colors: The pkg/styles package defines a complete Dracula-inspired adaptive palette using charm.land/lipgloss/v2/compat.AdaptiveColor for both light and dark terminal themes. Every semantic color (Error, Warning, Success, Info, Purple, Yellow, Comment, etc.) has both light and dark variants.

✅ TTY detection: The applyStyle() function in pkg/console/console.go gates all Lipgloss rendering through isTTY() backed by pkg/tty. Styles are never applied in pipes or redirected output.

✅ WASM stubs: Every console function has a corresponding *_wasm.go stub with emoji-based fallbacks, ensuring output remains readable in WebAssembly environments.

✅ Rich border system: pkg/styles centralizes three border styles (RoundedBorder, NormalBorder, ThickBorder). The RenderErrorBox, RenderInfoSection, and RenderTitleBox functions in pkg/console make consistent use of these.

✅ Table rendering: Tables use charm.land/lipgloss/v2/table via RenderTable(). Zebra striping uses ColorTableAltRow adaptive color.

⚠️ Dual Lipgloss versions: The project uses two Lipgloss versions — charm.land/lipgloss/v2 (primary) and github.com/charmbracelet/lipgloss v1 (required by huh v0.8.0). The huh theme in pkg/styles/huh_theme.go necessarily uses the v1 import to match huh's type system. This is unavoidable until huh upgrades its Lipgloss dependency. It is well-documented with a comment.

Lipgloss: Files and patterns reviewed

File	Lipgloss Usage	Assessment
pkg/styles/theme.go	Defines all adaptive colors + pre-configured styles	✅ Canonical, correct
pkg/styles/huh_theme.go	Maps palette to huh using v1 lipgloss	✅ Correctly isolated, documented
pkg/console/console.go	Renders formatted messages via applyStyle()	✅ Proper TTY-aware application
pkg/console/render.go	RenderStruct, RenderTable, tree rendering	✅ Rich struct-tag-driven rendering
pkg/console/banner.go	ASCII banner with gradient/padding	✅ Correct use of lipgloss layout
pkg/console/progress.go	Animated spinner fallback for non-TTY	✅ Accessibility-aware

---

Huh Interactive Forms — Assessment

✅ 100% consistent theme application: All 16 huh.NewForm() calls chain .WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode()). No exceptions found.

✅ Accessibility mode: Properly detected via ACCESSIBLE env var through console.IsAccessibleMode(), which is propagated to all forms, spinners, and interactive components.

✅ Rich field variety: The codebase uses huh.NewInput, huh.NewSelect, huh.NewMultiSelect, huh.NewConfirm, huh.NewText — covering the full interactive spectrum.

✅ Validation: The wizard form in interactive.go uses .Validate(ValidateWorkflowIntent) on text input fields. The run_interactive.go parameter form uses inline validation functions with descriptive error messages.

✅ Multi-group forms: The add-workflow wizard (interactive.go:171) uses a 4-group form (Basic Configuration, Capabilities, Network & Security, Instructions) with group titles and descriptions — excellent UX design.

Huh: All form locations

File	Field Types	Groups	WithAccessible
run_interactive.go	Select, Input, Confirm	1 each	✅
interactive.go	Select×3, MultiSelect×2, Text, Confirm	4	✅
add_interactive_auth.go	Input (password)	1	✅
add_interactive_engine.go	Select	1	✅
add_interactive_git.go	Select, Input	1 each	✅
add_interactive_orchestrator.go	Confirm	1	✅
add_interactive_schedule.go	Select	1	✅
add_interactive_workflow.go	Input	1	✅
engine_secrets.go	Input×3 (API keys)	3 forms	✅

---

Inconsistencies Found — Raw Output Without Console Formatting

The main gap in the codebase is the use of raw fmt.Fprintf(os.Stderr, ...) and fmt.Fprintln(os.Stderr, ...) for user-visible diagnostic messages, bypassing the console.Format* functions. These messages miss the color coding, icons, and TTY-aware rendering that formatted messages provide.

High Priority

pkg/cli/copilot_setup.go — ~12 raw stderr writes for setup instruction output:

// Current (raw, unformatted):
fmt.Fprintf(os.Stderr, "No version upgrade needed for %s\n", setupStepsPath)
fmt.Fprintf(os.Stderr, "Updated %s with new version %s\n", setupStepsPath, version)
fmt.Fprintln(os.Stderr, "To enable GitHub Copilot Agent integration, please add...")

// Recommended:
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("No version upgrade needed for %s", setupStepsPath)))
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("Updated %s with new version %s", setupStepsPath, version)))

pkg/cli/mcp_list_tools.go — 4 raw informational messages:

// Current (raw):
fmt.Fprintf(os.Stderr, "Available MCP servers: ")
fmt.Fprintf(os.Stderr, "Found MCP server '%s' in %d workflow(s): %s\n", ...)
fmt.Fprintf(os.Stderr, "\nRun 'gh aw mcp list-tools %s <workflow-name>'...\n", ...)

// Recommended:
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Available MCP servers: %s", strings.Join(serverNames, ", "))))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Found MCP server '%s' in %d workflow(s): %s", ...)))
fmt.Fprintln(os.Stderr, console.FormatCommandMessage(fmt.Sprintf("gh aw mcp list-tools %s <workflow-name>", mcpServerName)))

pkg/cli/add_interactive_secrets.go — Raw count message:

// Current:
fmt.Fprintf(os.Stderr, "Found %d existing secret(s) (repository + organization)\n", len(c.existingSecrets))

// Recommended:
fmt.Fprintln(os.Stderr, console.FormatCountMessage(fmt.Sprintf("Found %d existing secret(s) (repository + organization)", len(c.existingSecrets))))

Medium Priority

pkg/cli/audit_report_render.go — Bullet list items use raw fmt.Fprintf instead of console.FormatListItem:

// Current (raw bullet points in 3 sections):
fmt.Fprintf(os.Stderr, "  • %s (%s)", file.Path, formattedSize)
fmt.Fprintf(os.Stderr, "  • %s\n", tool.Tool)
fmt.Fprintf(os.Stderr, "  • %s: %s\n", failure.ServerName, failure.Status)

// Recommended (consistent with update_display.go and update_actions.go):
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s (%s)", file.Path, formattedSize)))
fmt.Fprintln(os.Stderr, console.FormatListItem(tool.Tool))
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s: %s", failure.ServerName, failure.Status)))

pkg/workflow/compiler_orchestrator_engine.go — Uses "WARNING:" prefix in raw format:

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

// Recommended:
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Skipping security scan for unresolvable import '%s': %v", ...)))

pkg/workflow/cache.go — Raw warning strings:

// 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)))

Low Priority (Debug Output — Consider Using logger Package)

pkg/workflow/claude_logs.go — Debug-level internal state messages sent to stderr via raw fmt.Fprintf. These would be better served by the pkg/logger debug logger since they are internal diagnostics, not user-facing messages:

// Current:
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", len(logEntries))

// Recommended (use debug logger):
var claudeLogsLog = logger.New("workflow:claude_logs")
claudeLogsLog.Printf("Failed to parse as JSON array, trying JSONL: %v", err)
claudeLogsLog.Printf("Extracted %d JSON entries from mixed format", len(logEntries))

Complete list of files with raw stderr output

pkg/cli/ (affected files):

• copilot_setup.go — Setup instructions and status messages
• mcp_list_tools.go — MCP server discovery messages
• audit_report_render.go — Bullet list items in multiple sections
• add_interactive_secrets.go — Secret count message
• health_command.go — Blank line separators (acceptable)
• audit_report_render.go — Comparison details with raw indentation

pkg/workflow/ (affected files):

• compiler_orchestrator_engine.go — "WARNING:" security scan skip messages
• cache.go — Cache configuration warning messages
• claude_logs.go — Debug-level log parsing messages (5+ instances)
• action_sha_checker.go — SHA comparison output
• mcp_renderer.go — Error generating custom MCP config
• push_to_pull_request_branch.go — Invalid if-no-changes value warning
• compiler.go — Uses formatCompilerMessage() local helper (acceptable pattern)

---

Recommendations

1. Adopt console.FormatListItem for Bullet Lists

FormatListItem exists but is only used in 2 files (update_display.go, update_actions.go). The audit_report_render.go file has 3 separate sections that manually format bullet points. Migrate to FormatListItem for consistency:

// Pattern to standardize:
fmt.Fprintln(os.Stderr, console.FormatListItem(item))

2. Migrate Debug Messages to pkg/logger

Messages in pkg/workflow/claude_logs.go are internal diagnostics (JSON parsing progress, entry counts) that should use the debug logger rather than unconditional stderr output. This would make them opt-in with DEBUG=workflow:claude_logs.

3. Consider a console.PrintInfo / console.PrintSuccess Shorthand

The pattern fmt.Fprintln(os.Stderr, console.FormatInfoMessage("...")) is verbose. Many files could benefit from convenience functions:

// Could add to pkg/console:
func PrintInfo(message string)    { fmt.Fprintln(os.Stderr, FormatInfoMessage(message)) }
func PrintSuccess(message string) { fmt.Fprintln(os.Stderr, FormatSuccessMessage(message)) }
func PrintWarning(message string) { fmt.Fprintln(os.Stderr, FormatWarningMessage(message)) }
func PrintError(message string)   { fmt.Fprintln(os.Stderr, FormatErrorMessage(message)) }

4. Standardize Multi-line Setup Output in copilot_setup.go

The YAML snippet output in copilot_setup.go is printed line by line. Consider using a console.RenderInfoSection or a code-block-style box to visually group the snippet output for users.

---

What's Working Well ✅

• Adaptive color system: Dracula-inspired palette with full light/dark variants is best-in-class
• TTY-aware rendering: applyStyle() correctly gates all Lipgloss output through TTY detection
• Huh accessibility: 100% of interactive forms pass WithAccessible(console.IsAccessibleMode())
• Huh theming: All forms use the custom HuhTheme() that matches the CLI's Dracula palette
• RenderStruct: Struct-tag-based rendering (console:"header,...") provides rich data display without manual formatting
• WASM compatibility: Every console function has emoji-based WASM stub implementations
• Rust-like error rendering: FormatError(CompilerError) renders errors with source context lines (file:line:col: type: message format)
• Spinner/progress: TTY-aware animated spinner with accessibility fallback
• pkg/logger: Debug logging system with namespaced patterns and zero overhead when disabled

---

References:

• §23539713352

AI generated by Terminal Stylist · history

• expires on Mar 26, 2026, 12:03 PM UTC

[github-actions[bot]]

💥 WHOOSH!

ZAP! The smoke test agent was HERE! 🦸

POW! Claude engine blazing through all systems — GitHub MCP, Serena, Tavily, Playwright, Make build... ALL SYSTEMS NOMINAL!

KAPOW! Run §23541048104 complete — no villains detected in the codebase today!

...to be continued 🎉

Note

🔒 Integrity filter blocked 1 item

The following item were blocked because they don't meet the GitHub integrity level.

• fix: post add_comment status update even when code push fails #22887 pull_request_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

💥 [THE END] — Illustrated by Smoke Claude · ◷

[github-actions[bot]]

🤖 Beep boop! The smoke test agent was here! I've completed my inspection and everything looks great. Carry on, humans! 🚀

📰 BREAKING: Report filed by Smoke Copilot · ◷

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #23107.