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

[github-actions[bot]]

Overview

A comprehensive analysis of 972 Go source files in pkg/ reveals a well-architected console output system built on the Charmbracelet ecosystem. The codebase demonstrates strong consistency in Huh form usage and an excellent adaptive color foundation — with a few targeted areas for improvement.

Key metrics:

Metric	Value
Total Go source files analyzed	972
Files using console.* formatters	216
Console formatter call-sites	1,703
Direct fmt.Print to stderr/stdout (outside console/)	784
Huh form instances with WithTheme+WithAccessible	17/17 (100%)
Files using Lipgloss directly	6

---

Lipgloss Analysis

✅ Excellent patterns

Adaptive color system (pkg/styles/theme.go)
The codebase implements a custom adaptiveColor type that selects Light/Dark hex variants at startup via lipgloss.HasDarkBackground. Colors follow the Dracula dark palette with accessible light alternatives. All 11 semantic color constants (Error, Warning, Success, Info, Purple, Yellow, Comment, Foreground, Background, Border, TableAltRow) are well-documented.

TTY-gated styling (pkg/console/console.go)
All styled output passes through applyStyle()/applyStyleWithTTY() which returns plain text for non-TTY environments. This is extended via FormatSuccessMessageStderr, FormatInfoMessageStderr, etc., each having distinct stdout/stderr TTY checks.

Table rendering (RenderTable in console.go)
Uses lipgloss/table with StyleFunc for zebra striping, header and total-row styles, and a caller-overridable TTYFunc field for stderr tables. Consistent with the style system.

Rich component library

• Spinner: Bubble Tea WithoutRenderer() pattern with tea.WithInput(nil) to prevent input consumption before subsequent Huh forms
• Progress bar: Bubbles with scaled color blend (purple→cyan, adaptive)
• Banner: TTY-gated with Lipgloss purple styling

⚠️ Lipgloss improvements

Inline styles bypassing the style registry
RenderTitleBox, RenderErrorBox, and RenderInfoSection in console.go (lines 394–445) construct lipgloss.NewStyle() inline with ad-hoc properties instead of referencing pre-defined constants from pkg/styles:

// Current (inline, not reusable)
box := lipgloss.NewStyle().
    Bold(true).
    Foreground(styles.ColorInfo).
    Border(lipgloss.DoubleBorder(), true, false).
    Padding(0, 2).
    Width(width).
    Align(lipgloss.Center).
    Render(title)

// Better: define TitleBox, ErrorBox in pkg/styles and reference here

styles.ErrorBox already exists in pkg/styles but RenderErrorBox does not use it — it constructs its own inline style.

Raw ANSI escape sequences (pkg/console/terminal.go)
The file defines ansiClearLine = "\033[K" and ansiClearScreen = "\033[H\033[2J" as raw string constants used in the spinner. These are well-isolated (used only by spinner/terminal), but the Charmbracelet ecosystem provides ANSI utilities via github.com/charmbracelet/x/ansi or lipgloss ansi package if a migration is ever desired.

---

Huh Analysis

✅ Excellent patterns

100% consistent form configuration — All 17 huh.NewForm(...) call-sites across the codebase apply .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()). No rogue forms bypass the shared theme or accessibility mode.

Custom theme (pkg/styles/huh_theme.go)
A complete huh.ThemeFunc maps all semantic pkg/styles colors to Focused/Blurred/Group field states. Uses lipgloss.LightDark(isDark) correctly for theme-aware colors. Covers: borders, titles, descriptions, selectors, options, buttons, text input cursor/placeholder/prompt.

Non-TTY fallbacks
console.ConfirmAction falls back to showTextConfirm and console.ShowInteractiveList falls back to showTextList for piped environments.

Validation and security
PromptSecretInput uses EchoModePassword and validates for non-empty input.

⚠️ Huh improvements

Missing context propagation on some forms
Several forms use .Run() without a context, while others correctly use .RunWithContext(ctx). Forms with long operations (engine selection, git operations) should pass context for cancellation:

// Found in add_interactive_git.go
titleForm.Run()  // missing ctx

// Correct pattern (already used in add_interactive_orchestrator.go)
form.RunWithContext(c.Ctx)

Direct huh.NewForm vs. console wrappers
Some files create huh.NewForm directly for patterns already covered by console.ConfirmAction, console.ShowInteractiveList, or console.PromptSecretInput. The console wrappers handle non-TTY fallback logic that the direct forms skip:

// pkg/cli/add_interactive_workflow.go uses direct form (no non-TTY fallback)
form := huh.NewForm(...).WithTheme(...).WithAccessible(...)
form.RunWithContext(ctx)

// console.ConfirmAction already handles the non-TTY case
console.ConfirmAction(title, "Yes", "No")

---

Direct fmt.Print* Issues

Of the 784 fmt.Print* calls outside console/, the majority are acceptable — building strings into strings.Builder for YAML generation in pkg/workflow/. Terminal-facing issues are concentrated in pkg/cli/ interactive files.

Issue 1: Plain-text messages without console formatters (medium priority)

Files: add_interactive_auth.go, add_interactive_engine.go, add_interactive_git.go, add_interactive_orchestrator.go, add_interactive_workflow.go

// Current: no styling
fmt.Fprintln(os.Stderr, "Please merge the PR manually from the GitHub web interface.")
fmt.Fprintln(os.Stderr, "Once you have write access or an admin configures the repository, set the secret with:")
fmt.Fprintln(os.Stderr, "Operation cancelled.")

// Better: styled with appropriate level
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Please merge the PR manually from the GitHub web interface."))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Operation cancelled."))

Issue 2: Manual Unicode separator lines (medium priority)

Files: actionlint.go (line 119), add_interactive_orchestrator.go (lines 326, 328), trial_confirmation.go (line 221)

// Current: hardcoded separator, not TTY-aware
separator := strings.Repeat("━", 60)
fmt.Fprintf(os.Stderr, "\n%s\n", separator)

// Better: use console.RenderTitleBox which handles TTY/non-TTY
for _, line := range console.RenderTitleBox("Actionlint Summary", 60) {
    fmt.Fprintln(os.Stderr, line)
}

Issue 3: Inline bullet points bypassing FormatListItem (low priority)

Files: actionlint.go (line 146), add_interactive_orchestrator.go (line 247)

// Current: manual bullet, no TTY-aware styling
fmt.Fprintf(os.Stderr, "  \u2022 %s: %d\n", kind, count)
fmt.Fprintf(os.Stderr, "  \u2022 .github/workflows/%s\n", f)

// Better: use console formatter
fmt.Fprintln(os.Stderr, console.FormatListItemStderr(fmt.Sprintf("%s: %d", kind, count)))

Issue 4: Progress messages without console.FormatProgressMessage (low priority)

File: add_interactive_workflow.go (lines 133, 138, 141)

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

// Better: styled progress indicator
fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Updating local branch (this may take a few seconds)..."))

Issue 5: trial_confirmation.go sub-list items (low priority)

File: trial_confirmation.go (lines 182-183, 199-200)

Parent list items use console.FormatInfoMessage, but sub-items (a., b.) use raw fmt.Fprintf with no styling, creating visual inconsistency.

// Current (inconsistent): parent styled, children not
fmt.Fprintf(os.Stderr, console.FormatInfoMessage("  %d. For each of %d executions:\n"), stepNum, count)
fmt.Fprintf(os.Stderr, "     a. Execute %s\n", workflowName)  // unstyled
fmt.Fprintf(os.Stderr, "     b. Auto-merge any pull requests...\n")  // unstyled

---

Recommendations

Priority 1 (Quick wins):

1. Define named styles for RenderTitleBox/RenderErrorBox/RenderInfoSection in pkg/styles/theme.go and have console.go reference them — improves testability and doc coverage
2. Use console.RenderTitleBox() instead of strings.Repeat("━", N) in actionlint.go and add_interactive_orchestrator.go
3. Apply console.FormatWarningMessage to "Operation cancelled." in add_interactive_orchestrator.go

Priority 2 (Consistency):
4. Replace plain-text instruction fmt.Fprintln(os.Stderr, ...) calls in add_interactive_*.go with console.FormatInfoMessage equivalents
5. Replace manual bullet points (• %s) with console.FormatListItemStderr() in actionlint.go and add_interactive_orchestrator.go
6. Wrap progress messages in add_interactive_workflow.go with console.FormatProgressMessage()

Priority 3 (Architecture):
7. Add .RunWithContext(ctx) to forms in add_interactive_git.go that currently use .Run() — enables proper cancellation
8. Consider consolidating more direct huh.NewForm confirm/select usages into console.ConfirmAction / console.ShowInteractiveList to automatically gain their non-TTY fallback logic

References:

• §28364426521

Generated by 💄 Terminal Stylist · 92 AIC · ⌖ 11.5 AIC · ⊞ 5.7K · ◷

• expires on Jun 30, 2026, 2:17 AM UTC-08:00