[terminal-stylist] Terminal Stylist Report: Console Output Analysis

[github-actions[bot]]

Overview

This report covers a full scan of the 868 non-test Go source files in pkg/ for console output patterns, Lipgloss styling, and Huh form implementations. The codebase has a mature, well-structured approach to terminal output built on the Charmbracelet ecosystem.

---

✅ What's Working Well

Console Formatting Package (pkg/console)

The project has a dedicated pkg/console package with a comprehensive set of formatters:

Function	Purpose
FormatSuccessMessage	✅ green success
FormatInfoMessage	i info (cyan)
FormatWarningMessage	⚠️ warning (orange)
FormatErrorMessage	✗ error (red)
FormatCommandMessage	⚡ command display
FormatProgressMessage	🔨 progress
FormatPromptMessage	❓ prompts
FormatCountMessage	📊 counts
FormatVerboseMessage	🔍 debug/verbose
FormatError	Rust-style error with source position
FormatErrorWithSuggestions	Error with actionable hints
RenderTable	Lipgloss-backed table rendering
RenderStruct	Struct-to-table rendering
RenderTitleBox, RenderErrorBox, RenderInfoSection	Boxed layout sections

Usage is high: 1,533 console.Format* calls across the pkg/cli package, vs. 2,047 total stderr calls — ~75% adoption rate.

Lipgloss Integration (pkg/styles)

The pkg/styles package is excellently architected:

• Adaptive colors via compat.AdaptiveColor — all semantic colors (Error, Warning, Success, Info, etc.) have separate Light/Dark hex values automatically selected based on terminal background.
• Dracula-inspired dark theme and high-contrast light theme with accessibility in mind.
• lipgloss v2 with colorprofile.Detect — detects terminal capabilities and profile at init time.
• TTY detection via pkg/tty before applying styles in console.applyStyle().
• Calendar view in pkg/cli/compile_schedule_calendar.go uses lipgloss.NewStyle().Foreground(styles.Color*) correctly with TTY guards.
• streamStyleRenderer interface in pkg/cli/gateway_logs_timeline_render.go allows TTY-conditional styling without importing lipgloss in helper files.

Huh Forms (charm.land/huh/v2)

All interactive forms follow a consistent, correct pattern:

form := huh.NewForm(...).
    WithTheme(styles.HuhTheme).
    WithAccessible(console.IsAccessibleMode())

All 20+ form instantiations across add_interactive_workflow.go, add_interactive_schedule.go, add_interactive_git.go, run_interactive.go, add_interactive_orchestrator.go, add_interactive_auth.go, engine_secrets.go, interactive.go, add_interactive_engine.go, and pkg/console/{list,confirm,input}.go.

✅ All apply styles.HuhTheme and console.IsAccessibleMode() — the theme maps the Dracula palette to huh field styles (primary, success, error, warning, comment, fg, bg, border) using lipgloss.LightDark().

---

⚠️ Areas for Improvement

1. Unformatted Stderr Messages (~25% of CLI stderr output)

~514 fmt.Fprintln/Fprintf(os.Stderr, ...) calls do not use console.Format* wrappers. Common patterns:

pkg/cli/fix_command.go — codemod detail listing uses raw formatting:

// ❌ Raw format strings
fmt.Fprintf(os.Stderr, "    ID: %s\n", codemod.ID)
fmt.Fprintf(os.Stderr, "    Introduced in: %s\n", codemod.IntroducedIn)
fmt.Fprintf(os.Stderr, "    %s\n", codemod.Description)
fmt.Fprintln(os.Stderr, "  gh aw fix --write")
fmt.Fprintf(os.Stderr, "    • %s\n", codemodName)

These should use FormatCommandMessage, FormatInfoMessage, or FormatListItem.

pkg/cli/add_interactive_workflow.go — workflow status monitoring uses raw debug prints:

// ❌ Debug-like raw output
fmt.Fprintf(os.Stderr, "Checking workflow status (attempt %d/5) for: %s\n", ...)
fmt.Fprintf(os.Stderr, "Status check error: %v\n", err)
fmt.Fprintf(os.Stderr, "Running: gh %s\n", ...)
fmt.Fprintf(os.Stderr, "gh workflow list output: %s\n", ...)

These should use logger.New("cli:add_interactive_workflow") so they only appear with DEBUG=cli:*.

pkg/cli/update_display.go — update failure display:

// ❌ No wrapping
fmt.Fprintf(os.Stderr, "  %s: %s\n", failure.Name, failure.Error)

Should use FormatErrorMessage or FormatListItem.

2. Direct Lipgloss in CLI (Minor)

pkg/cli/compile_schedule_calendar.go creates lipgloss.NewStyle() instances directly:

// ⚠️ Direct lipgloss usage in CLI (not in pkg/styles)
return lipgloss.NewStyle().Foreground(styles.ColorComment)
return lipgloss.NewStyle().Foreground(styles.ColorInfo)

Functionally correct (TTY-guarded). Minor improvement: define these as pre-built styles.* style variables to centralize all style definitions in pkg/styles.

3. Huh Field Validation (Opportunistic)

Most huh.NewInput() and huh.NewSelect() fields lack .Validate() callbacks. Adding validation to critical fields (repo names, schedule expressions, PR titles) would surface errors inline before form submission:

// ✅ Example improvement
huh.NewInput().
    Title("PR Title").
    Validate(func(s string) error {
        if strings.TrimSpace(s) == "" {
            return errors.New("title cannot be empty")
        }
        return nil
    })

---

📋 Summary

Category	Status	Notes
Console formatting adoption	✅ Good (75%)	~1,533/2,047 stderr calls use console formatters
Lipgloss adaptive colors	✅ Excellent	compat.AdaptiveColor with light/dark variants
TTY detection	✅ Excellent	applyStyle() guards, streamStyleRenderer pattern
Huh theme & accessibility	✅ Excellent	All 20+ forms use styles.HuhTheme + IsAccessibleMode()
Debug/verbose output	⚠️ Mixed	~25 raw prints should use logger or FormatVerboseMessage
Structured data routing	✅ Correct	RenderStruct, JSON outputs go to stdout
Huh field validation	⚠️ Limited	Most form fields lack inline .Validate() callbacks
Lipgloss centralization	⚠️ Minor	A few inline lipgloss.NewStyle() calls could move to pkg/styles

References: §26680271060

Generated by 💄 Terminal Stylist · sonnet46 1.7M · ◷

• expires on May 31, 2026, 9:28 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-31T09:28:34.042Z.

Closed by Workflow