Terminal Stylist Audit: Console Output Patterns in gh-aw

[github-actions[bot]]

This report analyzes console output patterns across all Go source files in pkg/, covering Lipgloss v2 usage, Huh form implementations, and console formatting consistency.

Workflow Run: §23684561979

---

Summary

Metric	Value
CLI source files	220
Files using console.* formatting	123 (56%)
Files without console.* formatting	97 (44%)
Total fmt.Fprintln/Fprintf(os.Stderr) calls	~2,624
Of those using console.* helpers	~1,636
Raw stderr calls bypassing console helpers	~477
Huh forms using custom theme	✅ All (15 forms)
Huh forms using accessibility mode	✅ All (15 forms)
Huh forms using RunWithContext	✅ Most (13/15)

---

Lipgloss Usage Analysis

✅ Strengths

Architecture (pkg/styles/): The codebase has an excellent centralized style system:

• Full adaptive color palette using compat.AdaptiveColor{Light, Dark} for every semantic color — properly handles both light and dark terminal themes
• All pre-configured style variables (Error, Warning, Success, Info, Command, Progress, Prompt, Verbose, Count, FilePath, etc.) use adaptive colors
• Version split handled correctly: charm.land/lipgloss/v2 used for core CLI, github.com/charmbracelet/lipgloss (v1) used in pkg/styles/huh_theme.go to match huh's dependency requirements

TTY Detection: The applyStyle() helper in console.go correctly gates all Lipgloss rendering:

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

Table Rendering: RenderTable() in console.go uses charm.land/lipgloss/v2/table with proper zebra-striping via ColorTableAltRow, header styling, and border configuration.

Layout Features Used:

• lipgloss.JoinVertical() for composing multi-section displays
• lipgloss.DoubleBorder() for title boxes
• lipgloss.NormalBorder() for info section left-border emphasis
• lipgloss.RoundedBorder() for error boxes

Charmbracelet Ecosystem Integration:

• charm.land/bubbles/v2/spinner — TTY-aware, accessible-mode disabled
• charm.land/bubbles/v2/progress — Determinate/indeterminate with gradient blend
• charm.land/bubbles/v2/list — Full Bubble Tea interactive list with keyboard nav

⚠️ Improvement Opportunities

1. Manual formatting in audit_cross_run_render.go and audit_diff_render.go

These files produce markdown-formatted table output using raw fmt.Printf instead of the RenderTable() helper. While intentional for piped/redirected output (the output is markdown text, not styled terminal output), the inconsistency is notable:

// Current: audit_cross_run_render.go
fmt.Printf("| Metric | Value |\n")
fmt.Printf("|--------|-------|\n")
// ...

// Could use RenderTable() for TTY display and fallback gracefully

2. Missing symmetric functions in console.go

The WASM stub (console_wasm.go) defines three functions absent from console.go:

• FormatLocationMessage(message string) — for directory/file location messages
• FormatCountMessage(message string) — for count/numeric status
• FormatListHeader(header string) — for list section headers

While pkg/styles/theme.go defines Location, Count, and ListHeader styles, the corresponding Format*Message() helper functions are missing from the non-WASM build. This creates an API inconsistency between build targets and prevents these patterns from being used in non-WASM CLI code.

3. Raw stderr calls bypassing console formatting (~477 occurrences)

The following files have diagnostic messages sent to stderr without using the console formatting helpers — missing the styled prefix icons and color coding:

pkg/cli/compile_watch.go (5 occurrences):

// Current — plain text
fmt.Fprintln(os.Stderr, "Press Ctrl+C to stop watching.")
fmt.Fprintln(os.Stderr, "🔨 Initial compilation of all workflow files...")
fmt.Fprintln(os.Stderr, "Watching for file changes")

// Should be
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Press Ctrl+C to stop watching."))
fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Initial compilation of all workflow files..."))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Watching for file changes"))

pkg/cli/preconditions.go (~11 occurrences):

// Current — unformatted guidance text
fmt.Fprintln(os.Stderr, "Please run the following command to authenticate:")
fmt.Fprintln(os.Stderr, "You can still add workflows, but they won't run until Actions is enabled.")

// Should use FormatInfoMessage or FormatWarningMessage

pkg/cli/mcp_inspect_inspector.go (~7 occurrences — configuration detail lines):

// Current
fmt.Fprintf(os.Stderr, "  • %s (%s)\n", config.Name, config.Type)
fmt.Fprintf(os.Stderr, "  Container: %s\n", config.Container)
fmt.Fprintf(os.Stderr, "  URL: %s\n", config.URL)

// Could use FormatListItem() for bullet items
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s (%s)", config.Name, config.Type)))

pkg/workflow/compiler_orchestrator_engine.go (2 occurrences):

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

// Should be
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(...))

pkg/workflow/cache.go (2 occurrences):

// Current
fmt.Fprintf(os.Stderr, "Warning: Failed to parse cache configuration: %v\n", err)

// Should be
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(...))

pkg/cli/compile_stats.go (6 occurrences):

// Current — raw formatting
fmt.Fprintf(os.Stderr, "  Total workflows: %d\n", len(statsList))
fmt.Fprintf(os.Stderr, "  Total size:      %s\n", console.FormatFileSize(totalSize))

// Could use RenderTable() for structured stats display

pkg/workflow/claude_logs.go (~5 occurrences — debug-level messages):

// Current — debug info going to stderr
fmt.Fprintf(os.Stderr, "Skipping invalid JSON line: %s\n", trimmedLine)
fmt.Fprintf(os.Stderr, "Extracted %d entries...\n", ...)

// Should use pkg/logger for debug output (not stderr)
var log = logger.New("workflow:claude_logs")
log.Printf("Skipping invalid JSON line: %s", trimmedLine)

---

Huh Form Analysis

✅ Strengths

Consistent theming across all 15 forms: Every form applies the custom Dracula-inspired theme:

form.WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode())

Accessibility mode: All forms check console.IsAccessibleMode(), which correctly detects ACCESSIBLE, TERM=dumb, and NO_COLOR environment variables — excellent screen reader support.

Context propagation: 13/15 forms use RunWithContext(ctx) instead of Run() for proper cancellation support. The 2 exceptions (confirm.go, input.go) are utility helpers that don't have a context parameter, which is acceptable.

Theme implementation (pkg/styles/huh_theme.go): Well-structured mapping of the codebase palette to huh's field styles, covering:

• Focused/Blurred states
• Error indicators, descriptions, selectors, buttons
• TextInput cursor, placeholder, and prompt styles

Field types in use:

• NewInput — secret entry with EchoModePassword (masking), validation
• NewSelect — engine selection with descriptive labels
• NewMultiSelect — tool selection
• NewConfirm — PR merge confirmation
• NewText — multi-line intent/prompt input

⚠️ Improvement Opportunities

1. No Description fields on most Select forms

Most NewSelect forms omit the .Description() call, which provides helpful context below the title:

// Current
huh.NewSelect[string]().
    Title("Which coding agent would you like to use?").
    Options(engineOptions...).
    Value(&selectedEngine)

// Improved — with description
huh.NewSelect[string]().
    Title("Which coding agent would you like to use?").
    Description("Select the AI engine that will process your agentic workflows.").
    Options(engineOptions...).
    Value(&selectedEngine)

2. `huh.NewNote` not used for informational display

Several places output raw fmt.Fprintln(os.Stderr, ...) text before or after forms. These could use huh.NewNote() fields within the form group for more cohesive UI:

// Current — message before form
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Workflow specifies engine: "+workflowSpecifiedEngine))
form := huh.NewForm(...)

// Improved — Note as part of form
huh.NewForm(
    huh.NewGroup(
        huh.NewNote().
            Title("Engine Preference").
            Body("This workflow specifies: " + workflowSpecifiedEngine),
        huh.NewSelect[string]()...
    ),
)

3. Validation inconsistency

pkg/console/input.go implements field validation but many NewInput usages in pkg/cli/ do not validate input:

// console/input.go — has validation
huh.NewInput().
    Validate(func(s string) error {
        if len(s) == 0 {
            return errors.New("value cannot be empty")
        }
        return nil
    })

// Some cli forms — no validation on required inputs
huh.NewInput().
    Title("Workflow name").
    Value(&workflowName)
    // Missing: Validate() to prevent empty submission

---

Console Package Architecture Assessment

The pkg/console/ package is well-designed with clear separation of concerns:

File	Responsibility	Assessment
console.go	Format functions, table, box rendering	✅ Comprehensive
banner.go	ASCII logo rendering	✅ Proper applyStyle usage
spinner.go	Animated spinner (Bubble Tea)	✅ TTY-aware
progress.go	Progress bar (determinate/indeterminate)	✅ Gradient, TTY fallback
list.go	Interactive list (Bubble Tea)	✅ TTY fallback to text
confirm.go	Confirm dialog (Huh)	✅ Accessible
input.go	Password input (Huh)	✅ Masked, validated
accessibility.go	Mode detection	✅ Comprehensive env checks
verbose.go	Verbose logging helper	✅ Simple, correct
render.go	Struct→console via reflection	✅ Tag-driven rendering
format.go	File size / number formatting	✅ Pure utility

Minor gap: FormatLocationMessage, FormatCountMessage, and FormatListHeader are defined in the WASM stub but absent from console.go. While no code currently calls them from non-WASM builds, adding them would complete the API symmetry and enable new usage patterns (particularly FormatCountMessage for statistics output, which currently uses raw fmt.Fprintf).

---

Recommendations (Priority Order)

Priority	Area	Action
🔴 High	pkg/workflow/claude_logs.go	Replace fmt.Fprintf(os.Stderr, ...) with logger.Printf() — these are debug messages, not user messages
🔴 High	pkg/workflow/compiler_orchestrator_engine.go, cache.go	Replace "WARNING: ..." strings with console.FormatWarningMessage()
🟡 Medium	pkg/cli/compile_watch.go, preconditions.go	Adopt console format helpers for all informational messages
🟡 Medium	pkg/console/console.go	Add FormatLocationMessage, FormatCountMessage, FormatListHeader to match WASM stub API
🟡 Medium	pkg/cli/mcp_inspect_inspector.go	Use console.FormatListItem() for bullet point server listings
🟢 Low	Huh forms	Add .Description() to NewSelect fields for better UX
🟢 Low	Huh forms	Use huh.NewNote() for pre-form informational messages
🟢 Low	Huh forms	Add input validation to required fields in interactive CLI forms

---

Positive Patterns to Preserve

// ✅ Adaptive color — works in both light and dark terminals
var ColorError = compat.AdaptiveColor{
    Light: lipgloss.Color("#D73737"),
    Dark:  lipgloss.Color("#FF5555"),
}

// ✅ TTY-gated styling — no ANSI codes in pipes
func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() { return style.Render(text) }
    return text
}

// ✅ Universal huh form pattern — themed + accessible + context-aware
form.WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode())
if err := form.RunWithContext(ctx); err != nil { ... }

// ✅ Correct output routing — diagnostics→stderr, data→stdout
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Processing...")) // diagnostic
fmt.Println(string(jsonBytes))                                       // structured data

References:

• §23684561979

AI generated by Terminal Stylist · history

• expires on Mar 29, 2026, 11:56 AM UTC