[terminal-stylist] Terminal Stylist Analysis: Console Output Patterns in gh-aw

[github-actions[bot]]

Overview

This analysis covers all Go source files in pkg/ (excluding tests) for console output patterns, Lipgloss styling, and Huh form usage. The codebase shows a mature, well-structured approach to terminal output with a dedicated pkg/console package that centralizes formatting. The overall quality is high, with several specific improvement opportunities identified.

---

Summary Statistics

Pattern	Count
fmt.Fprintln/Fprintf (total)	2,971
fmt.Fprintln(os.Stderr, ...) calls	2,216
console.Format* usages	1,482
lipgloss.* usages	102
huh.* usages	122
Huh forms in pkg/cli/	16
Huh forms with WithTheme + WithAccessible	16 (100%)

---

✅ What's Working Well

Lipgloss — Robust Styling Infrastructure

• Adaptive colors: pkg/styles/theme.go defines every semantic color with both light/dark variants via compat.AdaptiveColor, automatically adapting to terminal background. Example: ColorError = compat.AdaptiveColor{Light: "#D73737", Dark: "#FF5555"}.
• TTY detection: applyStyle() in pkg/console/console.go guards all styling behind isTTY(), preventing ANSI escape codes from leaking into pipes/redirects.
• Centralized styles: Pre-built styles.Error, styles.Success, styles.Warning, styles.Info, styles.FilePath etc. encourage consistent usage.
• WASM compatibility: All non-terminal platforms have stub implementations in *_wasm.go files — clean build-tag separation.
• Table rendering: console.RenderTable uses lipgloss/table for structured data, abstracted behind a TableConfig struct.
• Struct-tag rendering: console.RenderStruct provides reflection-based rendering with console:"header:" and console:"title:" tags — a standout feature.

Huh — Consistent Interactive Forms

• 100% theme/accessibility coverage: All 16 huh.NewForm calls in pkg/cli/ correctly chain .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()).
• Accessibility detection: IsAccessibleMode() checks ACCESSIBLE, NO_COLOR, and TERM=dumb env vars — comprehensive.
• TTY guard before forms: pkg/console/input.go, list.go, and confirm.go all check tty.IsStderrTerminal() before launching interactive prompts and fall back gracefully.
• Validation present: PromptSecretInput validates non-empty input with a proper error message.
• Custom theme: styles.HuhTheme provides branded styling, keeping forms visually consistent with the rest of the CLI.

---

⚠️ Improvement Opportunities

1. TTY Stream Inconsistency in pkg/console/console.go

The module-level isTTY() helper checks stdout, but all format functions (FormatSuccessMessage, FormatInfoMessage, etc.) are used with os.Stderr. Lines 344–398 call tty.IsStderrTerminal() directly, creating a split:

// Line 22 — checks stdout
func isTTY() bool {
    return tty.IsStdoutTerminal()
}

// Lines 344, 362, 379, 398 — checks stderr directly
if tty.IsStderrTerminal() { ... }

Recommendation: Rename isTTY() to isStdoutTTY() and introduce isStderrTTY(), or reconsider whether applyStyle (used on stderr-bound output) should check tty.IsStderrTerminal() instead.

2. Unformatted Messages in User-Facing Code

Several pkg/cli/ files write plain strings directly to stderr instead of using console formatters. These messages lose color, icon prefixes, and consistent styling:

Files with unformatted stderr messages (click to expand)

pkg/cli/preconditions.go (lines 26–142) — All precondition guidance messages:

// ❌ Current
fmt.Fprintln(os.Stderr, "Please run the following command to authenticate:")
fmt.Fprintln(os.Stderr, "Agentic workflows require GitHub-owned actions to run.")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Please run the following command to authenticate:"))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Agentic workflows require GitHub-owned actions to run."))

pkg/cli/add_interactive_orchestrator.go (lines 233–331) — Post-wizard summary:

// ❌ Current — raw Unicode box-drawing character as separator
fmt.Fprintln(os.Stderr, "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
fmt.Fprintln(os.Stderr, "Operation cancelled.")

// ✅ Recommended — use console.FormatSectionHeader or styles.TableHeader
fmt.Fprintln(os.Stderr, console.FormatSectionHeader("Next steps"))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Operation cancelled."))

pkg/cli/add_interactive_git.go (lines 59–189) — merge/secret instructions:

// ❌ Current
fmt.Fprintln(os.Stderr, "Please merge the PR manually from the GitHub web interface.")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Please merge the PR manually from the GitHub web interface."))

pkg/cli/add_interactive_workflow.go (lines 63–139) — status messages during wizard:

// ❌ Current
fmt.Fprintln(os.Stderr, "Updating local branch (this may take a few seconds)...")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Updating local branch (this may take a few seconds)..."))

pkg/cli/fix_command.go (lines 248–249) — hint after fix:

// ❌ Current
fmt.Fprintln(os.Stderr, "  gh aw fix --write")

// ✅ Recommended — use FormatCommandMessage
fmt.Fprintln(os.Stderr, "  "+console.FormatCommandMessage("gh aw fix --write"))

3. Direct Lipgloss Usage in pkg/cli/compile_schedule_calendar.go

intensityStyle() creates lipgloss.NewStyle() values inline using styles.Color* constants, which is fine. However the table rows are manually built with a strings.Builder, and separators/headers are written with fmt.Fprintln(os.Stderr, styles.TableHeader.Render(header)). This bypasses the console.RenderTable abstraction.

Recommendation: For complex calendar-style output that doesn't map to simple tables, the current approach is acceptable. Consider extracting a console.FormatCalendar helper to keep CLI command files free of direct Lipgloss calls.

4. Markdown Report to Stdout in audit_cross_run_render.go

Lines 29–50 write raw Markdown headings and pipe-separated tables directly to stdout:

fmt.Fprintln(os.Stdout, "# Audit Report — Cross-Run Analysis")
fmt.Fprintf(os.Stdout, "| Metric | Value |\n")

This is intentional for machine-readable output, but the hardcoded # h1 heading violates the style guide (which reserves h1 for titles). If this output is meant for human reading in a terminal, consider using console.RenderStruct with struct tags for the table sections, or at minimum downgrade headers to ###.

---

📋 Prioritized Recommendations

Priority	File	Action
🔴 High	pkg/console/console.go	Fix TTY stream split: isTTY() checks stdout while format functions output to stderr
🟠 Medium	pkg/cli/preconditions.go	Replace plain fmt.Fprintln(os.Stderr, ...) strings with console.FormatInfoMessage / FormatWarningMessage
🟠 Medium	pkg/cli/add_interactive_orchestrator.go	Replace raw Unicode separator and plain messages with console.FormatSectionHeader / FormatWarningMessage
🟡 Low	pkg/cli/add_interactive_git.go	Wrap instruction messages with FormatInfoMessage
�� Low	pkg/cli/add_interactive_workflow.go	Wrap progress messages with FormatProgressMessage
🟡 Low	pkg/cli/fix_command.go	Wrap command hints with FormatCommandMessage
🔵 Info	pkg/cli/audit_cross_run_render.go	Consider whether stdout Markdown output should use lower heading levels

---

💡 Charmbracelet Ecosystem Best Practices — Compliance Summary

Practice	Status	Notes
Adaptive colors (light/dark)	✅ Excellent	All colors in pkg/styles have both variants
TTY detection before styling	✅ Good	applyStyle() guards all Lipgloss calls
Consistent semantic styles	✅ Good	console.Format*Message functions used throughout
Huh forms with theme	✅ Excellent	100% of forms use WithTheme(styles.HuhTheme)
Huh forms with accessibility	✅ Excellent	100% of forms use WithAccessible(IsAccessibleMode())
Non-TTY fallback for prompts	✅ Good	All interactive components check TTY before running
NO_COLOR / ACCESSIBLE env support	✅ Good	IsAccessibleMode() covers ACCESSIBLE, NO_COLOR, TERM=dumb
Plain text fallback (non-TTY)	✅ Good	ShowInteractiveList falls back to numbered text list
Avoiding raw ANSI escape codes	✅ Good	Compiler strips ANSI; styles use Lipgloss only
TTY stream consistency (stdout vs stderr)	⚠️ Needs fix	isTTY() checks stdout; stderr-bound styles check stderr directly
Consistent use of console formatters	⚠️ Partial	Several pkg/cli/ files bypass formatters for user-facing strings

---

References:

• Workflow run: §26709043138

Generated by 💄 Terminal Stylist · sonnet46 1.9M · ◷

• expires on Jun 1, 2026, 9:40 AM UTC