Terminal Stylist: Console Output Analysis for gh-aw

[github-actions[bot]]

This report analyzes console output patterns across 582 Go source files in pkg/, evaluating consistency, Lipgloss styling, and Huh form implementations.

Summary

Metric	Count
Go source files scanned	582
console.Format* calls	~1,400+
Direct fmt.Fprintf(os.Stderr, …) without console formatting	~35
Huh form instances	16
Forms with WithAccessible(…)	16 (100%)
Direct lipgloss calls outside pkg/console/pkg/styles	0

Overall Health: ✅ Excellent. The codebase has a well-designed, centralized console formatting layer. The Charmbracelet ecosystem is used consistently and correctly in the vast majority of files.

---

Lipgloss Patterns

✅ Strengths

• Fully centralized styling — zero direct lipgloss.* calls outside pkg/console/ and pkg/styles/. All color and layout primitives flow through one controlled layer.
• Adaptive color system — pkg/styles/theme.go uses lipgloss.AdaptiveColor for every semantic color (Error, Warning, Success, Info, Purple, Yellow, Comment, Foreground). Both light (high-contrast) and dark (Dracula-inspired) variants are defined with documentation per color.
• TTY-aware rendering — applyStyle() in pkg/console/console.go gates all style application behind tty.IsStdoutTerminal(), preventing ANSI codes from leaking into pipes/redirects.
• Rich layout primitives — RenderTitleBox uses lipgloss.DoubleBorder + centered alignment; RenderErrorBox uses rounded borders with error foreground; RenderInfoSection uses a left-border emphasis pattern. RenderComposedSections uses lipgloss.JoinVertical for correct vertical layout composition.
• Table rendering — RenderTable in pkg/console/console.go uses lipgloss/table with zebra-stripe rows, styled headers, total rows, and a StyleFunc that is gated behind TTY detection.
• Banner — pkg/console/banner.go uses an embedded ASCII logo with lipgloss bold + purple styling and proper TTY fall-through.

⚠️ Minor Observations

None — Lipgloss usage is fully correct and well-abstracted.

---

Huh Form Patterns

✅ Strengths

• 100% accessibility coverage — All 16 huh.NewForm(…) instances call .WithAccessible(console.IsAccessibleMode()).
• IsAccessibleMode() checks three env vars: ACCESSIBLE, TERM=dumb, NO_COLOR — covers screen readers, CI environments, and no-color preferences.
• Centralized form helpers — pkg/console/confirm.go and pkg/console/input.go wrap common form patterns (confirmation dialogs, secret inputs) so consuming code stays simple.
• TTY guard before interactive forms — pkg/console/input.go::PromptSecretInput checks tty.IsStderrTerminal() before running the form, returning a clear error if not in a terminal.
• Input variety — Forms use Select, MultiSelect, Confirm, Input, and EchoModePassword appropriately for their context.
• Field validation — PromptSecretInput validates non-empty value with a clear message.
• Search/filtering — Workflow selection in run_interactive.go enables Filtering(true) with Height(15), improving UX for large lists.

⚠️ Minor Observations

• Forms in run_interactive.go (lines 182, 345) and several add_interactive_*.go files don't check for TTY before calling form.Run(). If invoked non-interactively, huh will fail with a less-than-ideal error. Only pkg/console/input.go has the TTY guard. Consider adding a TTY pre-check helper shared across all interactive command entrypoints.
• No Huh Note field or FilePicker field is used anywhere; these could improve UX in the gh aw add wizard for selecting existing files or displaying rich onboarding text.

---

Raw fmt.Fprintf(os.Stderr, …) Without Console Formatting

The following files have user-facing messages written directly to stderr without console formatting, inconsistent with the rest of the codebase:

pkg/workflow/cache.go — 2 raw warnings

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

Recommended:

fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Failed to parse cache configuration: %v", err)))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("No cache key found in parsed configuration"))

pkg/workflow/compiler_orchestrator_engine.go — 2 raw warnings

// Line 154
fmt.Fprintf(os.Stderr, "WARNING: Skipping security scan for unresolvable import '%s': %v\n", importedFile, resolveErr)
// Line 160
fmt.Fprintf(os.Stderr, "WARNING: Skipping security scan for unreadable import '%s' (resolved path: %s): %v\n", importedFile, fullPath, readErr)

Recommended:

fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Skipping security scan for unresolvable import %q: %v", importedFile, resolveErr)))

pkg/workflow/mcp_renderer.go — 1 raw error

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

Recommended:

fmt.Fprintln(os.Stderr, console.FormatErrorMessage(fmt.Sprintf("Error generating custom MCP configuration for %s: %v", toolName, err)))

pkg/cli/copilot_setup.go — info messages without console formatting

Lines 222, 233, 242 emit plain-text status messages ("No version upgrade needed", "Updated %s with new version", "Skipping %s") without console.FormatInfoMessage. Lines 265–292 intentionally output YAML to stderr — this is acceptable structured output for copy-paste use.

Recommended for lines 222/233/242:

fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("No version upgrade needed for %s", setupStepsPath)))

pkg/cli/mcp_list_tools.go — info messages without console formatting

// Lines 76–78
fmt.Fprintf(os.Stderr, "Available MCP servers: ")
fmt.Fprintf(os.Stderr, "%s\n", strings.Join(serverNames, ", "))
// Lines 133–135
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: Use console.FormatInfoMessage for the status lines and console.FormatCommandMessage for the command suggestion.

pkg/workflow/claude_logs.go — debug diagnostics via stderr

Lines 155, 216, 226, 232, 284, 331 write parser diagnostic output directly to stderr ("Skipping invalid JSON line", "No valid JSON entries found", "Claude parser extracted %d tool sequences"). These read as internal diagnostics rather than user messages and should use the logger package:

// Replace
fmt.Fprintf(os.Stderr, "Skipping invalid JSON line: %s\n", trimmedLine)
// With
claudeLogsLog.Printf("Skipping invalid JSON line: %s", trimmedLine)

pkg/cli/audit_report_render.go — inline list items bypassing FormatListItem

Many list items are manually formatted (" • %s\n") rather than using console.FormatListItem. While the manual format renders identically in non-TTY mode, it misses the styled list item rendering in TTY mode.

// Current
fmt.Fprintf(os.Stderr, "  • %s\n", tool.Tool)
// Recommended
fmt.Fprintln(os.Stderr, console.FormatListItem(tool.Tool))

Affected sections: Missing Tools, MCP Server Failures, Redacted URL Domains, firewall domain lists (lines 89–392).

---

Recommendations (Priority Order)

1. Medium — Convert raw "WARNING:" / "Error" writes in pkg/workflow/ (cache.go, compiler_orchestrator_engine.go, mcp_renderer.go) to console.FormatWarningMessage / console.FormatErrorMessage. These are user-visible during compilation and deserve consistent styling.

2. Medium — Migrate diagnostic writes in pkg/workflow/claude_logs.go to the logger package. These are internal parser diagnostics that should only appear when DEBUG=workflow:claude_logs, not unconditionally on stderr.

3. Low — Update pkg/cli/audit_report_render.go inline list items to use console.FormatListItem for TTY-aware formatting consistency.

4. Low — Add a shared TTY pre-check helper for interactive Huh forms in pkg/cli/ entrypoints (currently only pkg/console/input.go guards this).

5. Low — Update pkg/cli/copilot_setup.go info status messages (lines 222/233/242) to console.FormatInfoMessage. The YAML output block (lines 265–292) is intentional structured output and should remain as-is.

6. Enhancement — Consider using Huh Note fields in the gh aw add wizard to display rich contextual help text instead of pre-form fmt.Fprintln banners.

---

References:

• §23168718428

AI generated by Terminal Stylist · history

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

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #21455.