[terminal-stylist] Terminal Stylist Report: Console Output Analysis (2026-05-29)

[github-actions[bot]]

Executive Summary

The gh-aw codebase demonstrates a mature, well-structured console output system built on Lipgloss v2 and Huh v2 from the Charmbracelet ecosystem. The foundational architecture is excellent — adaptive colors, TTY detection, a Dracula-inspired theme, and a custom Huh form theme are all properly implemented. A small number of gaps and inconsistencies were found, detailed below.

---

Inventory at a Glance

Layer	Location	Scale
pkg/console	Formatting + rendering functions	~1,832 call sites
pkg/styles	Lipgloss adaptive color palette	101 usages across 6 files
pkg/styles/huh_theme.go	Custom Huh v2 theme	122 huh. usages in 14 files
pkg/tty	TTY detection (IsStdoutTerminal, IsStderrTerminal)	Used in console.go
pkg/logger	Debug logger with Lipgloss namespace coloring	Per namespace

---

✅ What's Working Well

1. Adaptive Color System (pkg/styles/theme.go)

All colors use compat.AdaptiveColor with explicit light/dark hex values, following the Dracula palette for dark terminals and muted/saturated versions for light terminals. All semantic semantic roles are covered: ColorError, ColorWarning, ColorSuccess, ColorInfo, ColorPurple, ColorYellow, ColorComment, ColorForeground, ColorBackground, ColorBorder, ColorTableAltRow.

// Example — properly adaptive
ColorError = compat.AdaptiveColor{
    Light: lipgloss.Color("#D73737"),
    Dark:  lipgloss.Color("#FF5555"),
}

2. TTY-Gated Styling (pkg/console/console.go)

The applyStyle() helper correctly guards all Lipgloss rendering behind isTTY() detection, preventing ANSI escape codes from leaking into pipes and non-terminal environments.

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text
}

3. Rich Console Formatting API

The pkg/console package exposes 14+ typed formatting functions (FormatSuccessMessage, FormatInfoMessage, FormatWarningMessage, FormatErrorMessage, FormatCommandMessage, FormatProgressMessage, FormatPromptMessage, FormatVerboseMessage, FormatListItem, FormatSectionHeader, FormatErrorChain, FormatErrorWithSuggestions). These are consistently used across ~1,832 call sites.

4. Custom Huh Theme (pkg/styles/huh_theme.go)

A fully-realized huh.ThemeFunc maps the styles palette to every interactive form element — focused/blurred states, select selectors, button styles, text input cursors, and group headers. It uses the modern lipgloss.LightDark(isDark) helper for correct light/dark adaptation.

5. Output Routing Convention

The codebase largely follows the Unix convention correctly:

• Diagnostic output (messages, warnings, progress) → os.Stderr
• Structured output (JSON, hashes, rendered tables) → os.Stdout or fmt.Print

Only 3 fmt.Print* calls go to stdout from pkg/cli (two RenderStruct calls, one view_command.go raw output), all of which are intentional structured output.

6. Debug Logger with Lipgloss Namespace Coloring (pkg/logger)

The logger uses a rotating colorPalette of Lipgloss styles derived from pkg/styles to consistently color each debug namespace. The DEBUG_COLORS=0 escape hatch is respected for non-color environments.

---

⚠️ Issues Found

Issue 1: WASM stub exports functions not present in the native console package

pkg/console/console_wasm.go declares these functions, but pkg/console/console.go does not:

Function	WASM stub	Native
FormatLocationMessage	✅	❌ missing
FormatCountMessage	✅	❌ missing
FormatListHeader	✅	❌ missing
RenderTree	✅	❌ missing

pkg/console/doc.go even documents RenderTree as part of the public API. These are referenced in the wasm stub, which means any code compiled for the browser can call them, but native callers cannot — a public API gap.

Recommendation: Add native implementations of FormatLocationMessage, FormatCountMessage, FormatListHeader, and RenderTree to pkg/console/console.go using the existing applyStyle() pattern and pkg/styles colors. The wasm stub already shows the expected no-style fallback behavior.

Issue 2: Raw fmt.Fprintf for failure detail lines in update_display.go

pkg/cli/update_display.go line 27 outputs failure details without console formatting:

// ❌ No console formatting — plain text, no styling cues
fmt.Fprintf(os.Stderr, "  %s: %s\n", failure.Name, failure.Error)

The surrounding lines correctly use console.FormatErrorMessage and console.FormatListItem. The failure detail line should use console.FormatListItem or a dedicated error-detail style for visual consistency.

Recommendation:

// ✅ Consistent with surrounding output
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s: %s", failure.Name, failure.Error)))

Issue 3: Command suggestion strings in fix_command.go are unstyled

pkg/cli/fix_command.go lines 244–249 output actionable command strings as plain text:

// ❌ Hardcoded command string — no CommandMessage styling
fmt.Fprintln(os.Stderr, "  gh aw fix --write")
...
fmt.Fprintf(os.Stderr, "  gh aw fix %s --write\n", strings.TrimSuffix(wf.File, ".md"))

The console.FormatCommandMessage function (which applies styles.Command — bold purple) exists precisely for this use case.

Recommendation:

// ✅ Uses the Command style (bold purple)
fmt.Fprintln(os.Stderr, console.FormatCommandMessage("gh aw fix --write"))
fmt.Fprintln(os.Stderr, console.FormatCommandMessage(fmt.Sprintf("gh aw fix %s --write", name)))

Issue 4: Inline bullet characters in fix_command.go instead of FormatListItem

pkg/cli/fix_command.go lines 329 and 334 manually construct bullet points:

// ❌ Manual bullet character
fmt.Fprintf(os.Stderr, "    • %s\n", codemodName)

console.FormatListItem already encapsulates the bullet style with proper styles.ListItem Lipgloss rendering.

Recommendation:

// ✅ Use the shared list item formatter
fmt.Fprintln(os.Stderr, console.FormatListItem(codemodName))

Issue 5: intensityStyle in compile_schedule_calendar.go creates anonymous styles instead of named styles

pkg/cli/compile_schedule_calendar.go constructs anonymous lipgloss.NewStyle() values inline in a switch statement:

func intensityStyle(count int, isTerminal bool) lipgloss.Style {
    switch {
    case count == 0:
        return lipgloss.NewStyle()
    case count <= 2:
        return lipgloss.NewStyle().Foreground(styles.ColorComment)
    // ...
    }
}

This is a minor issue — the function correctly uses styles.Color* constants, but the anonymous styles are ephemeral allocations. This could be expressed as named style variables (e.g., in pkg/styles/theme.go) for reuse if calendar rendering becomes more prominent.

Recommendation (low priority): Extract as named styles in pkg/styles/theme.go if the calendar feature grows:

// In pkg/styles/theme.go
var CalendarEmpty  = lipgloss.NewStyle()
var CalendarLow    = lipgloss.NewStyle().Foreground(ColorComment)
var CalendarMedium = lipgloss.NewStyle().Foreground(ColorInfo)
// ...

---

Lipgloss Patterns Assessment

Pattern	Status	Notes
Adaptive colors (compat.AdaptiveColor)	✅ Excellent	All palette entries have light/dark variants
TTY detection guard	✅ Correct	applyStyle() in console.go wraps all styling
Named semantic styles	✅ Good	25+ pre-configured styles in pkg/styles/theme.go
Border definitions	✅ Good	Rounded, Normal, Thick variants defined centrally
Table rendering	✅ Good	lipgloss/table used via console.RenderTable
Tree rendering	⚠️ Gap	RenderTree declared in wasm stub but not in native
Color reuse	✅ Good	All colors from pkg/styles — no hardcoded ANSI
ANSI leak prevention	✅ Correct	stringutil.StripANSI() in compiler + TTY gating

Huh Patterns Assessment

Pattern	Status	Notes
Custom theme (HuhTheme)	✅ Excellent	Full ThemeFunc mapping palette to all field states
Field types used	✅ Good	Input, Select, MultiSelect, Confirm, Note seen in codebase
Validation	✅ Good	Validators present in form fields
Light/dark adaptation	✅ Correct	Uses lipgloss.LightDark(isDark) in theme
Accessible mode	🔍 Not verified	No explicit huh.WithAccessible() calls found
Form grouping	✅ Good	Groups used in multi-step wizard (add_wizard_command.go)

---

Summary of Recommendations (Priority Order)

#	File	Issue	Priority
1	pkg/console/console.go	Add FormatLocationMessage, FormatCountMessage, FormatListHeader, RenderTree to match wasm API	High
2	pkg/cli/update_display.go:27	Use console.FormatListItem for failure detail lines	Medium
3	pkg/cli/fix_command.go:244–249,329,334	Use FormatCommandMessage for command strings, FormatListItem for bullets	Medium
4	pkg/cli/compile_schedule_calendar.go	Extract intensity styles to pkg/styles/theme.go	Low
5	Interactive forms	Audit for huh.WithAccessible() usage for screen-reader support	Low

---

References:

• §26630630011

Generated by 💄 Terminal Stylist · sonnet46 1.2M · ◷

• expires on May 30, 2026, 9:59 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #35898.