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

[github-actions[bot]]

Summary

This report analyzes console output patterns across 871 Go source files in the pkg/ directory, focusing on consistency, Lipgloss styling, and Huh form usage.

Metric	Count
Total non-test Go source files	871
Files using pkg/console formatters	198
Files using Lipgloss directly	8
Files using Huh forms	13
CLI files with raw fmt.Fprintln(os.Stderr, "...")	55
Total raw string-to-stderr calls in pkg/cli/	398

Overall health: The project has a solid foundation — a well-designed pkg/console formatting package, an adaptive Lipgloss theme (pkg/styles), and a consistent Huh theme (styles.HuhTheme). The main gap is 398 raw fmt.Fprintln(os.Stderr, "...") calls in 55 CLI files that bypass the console formatting layer.

---

✅ What's Working Well

Lipgloss Integration

• pkg/styles/theme.go is a well-structured, fully adaptive color system using compat.AdaptiveColor with both Light and Dark hex variants (Dracula-inspired for dark mode)
• TTY detection is correctly delegated to pkg/tty — applyStyle() in console.go is gated on tty.IsStdoutTerminal()
• Rich border styles (RoundedBorder, NormalBorder, ThickBorder) are centralized
• Pre-configured styles cover all semantic categories: Error, Warning, Success, Info, FilePath, Progress, Command, ListHeader, TableHeader, etc.
• Color profile detection uses colorprofile.Detect(os.Stderr, os.Environ()) — correct for terminal capability detection

Console Formatting Package

• pkg/console provides a comprehensive set of format helpers: FormatSuccessMessage, FormatInfoMessage, FormatWarningMessage, FormatErrorMessage, FormatCommandMessage, FormatProgressMessage, FormatPromptMessage, FormatVerboseMessage
• Rust-like error rendering with source context (FormatError with renderContext)
• Composed section rendering (RenderComposedSections, RenderTitleBox, RenderErrorBox, RenderInfoSection) for consistent layout
• Error chain formatting (FormatErrorChain) for wrapped errors

Huh Form Integration

• All 16 huh.NewForm(...) call sites use .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()) — 100% consistent
• styles.HuhTheme is a proper huh.ThemeFunc mapping the full palette to focused/blurred states
• Accessibility mode support (console.IsAccessibleMode()) is consistently applied
• console.ConfirmAction, console.PromptSecretInput, and console.list are well-encapsulated wrappers
• Forms use appropriate field types: huh.NewConfirm, huh.NewSelect, huh.NewInput (with EchoModePassword for secrets), huh.NewMultiSelect
• TTY check in PromptSecretInput before showing interactive forms is correct

---

⚠️ Areas for Improvement

1. Raw fmt.Fprintln(os.Stderr, "...") Calls Bypassing Console Formatting

The most widespread issue: 398 raw string messages written directly to stderr in 55 CLI files, bypassing all styling and TTY detection.

Top 15 files by raw stderr message count

File	Raw calls
pkg/cli/mcp_inspect_mcp.go	57
pkg/cli/audit_report_render.go	32
pkg/cli/fix_command.go	24
pkg/cli/compile_stats.go	18
pkg/cli/audit_cross_run_render.go	18
pkg/cli/add_interactive_workflow.go	16
pkg/cli/copilot_setup.go	15
pkg/cli/actionlint.go	15
pkg/cli/preconditions.go	14
pkg/cli/experiments_analyze_statistics.go	14
pkg/cli/engine_secrets.go	14
pkg/cli/enable.go	12
pkg/cli/deps_report.go	12
pkg/cli/outcomes_command.go	9
pkg/cli/experiments_command.go	8

Example pattern to fix (pkg/cli/preconditions.go):

// ❌ Current
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.")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Please run the following command to authenticate:"))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("You can still add workflows, but they won't run until Actions is enabled."))

Example from pkg/cli/add_interactive_workflow.go:

// ❌ Current - no styling
fmt.Fprintln(os.Stderr, "No workflows found matching pattern yet")
fmt.Fprintln(os.Stderr, "Updating local branch (this may take a few seconds)...")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("No workflows found matching pattern yet"))
fmt.Fprintln(os.Stderr, console.FormatProgressMessage("Updating local branch (this may take a few seconds)..."))

2. Manual Separator Lines Instead of Console Borders

pkg/cli/add_interactive_orchestrator.go (and others) use hardcoded Unicode separators:

// ❌ Current
fmt.Fprintln(os.Stderr, "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")

// ✅ Recommended — use console.RenderTitleBox or a Lipgloss rule
fmt.Fprintln(os.Stderr, console.FormatSectionHeader("Workflow Added"))

3. Files Using Raw fmt.Fprintln(os.Stderr) Without console Import

Six files write to stderr without importing the console package at all:

• pkg/cli/add_interactive_secrets.go
• pkg/cli/copilot_setup.go
• pkg/cli/devcontainer.go
• pkg/cli/mcp_config_file.go
• pkg/cli/observability_insights.go
• pkg/cli/vscode_config.go

These need both the import and updated message calls.

4. isTTY() in console.go Checks stdout Instead of stderr

The applyStyle() helper gates styling on tty.IsStdoutTerminal(), but all diagnostic output goes to stderr. Messages styled with applyStyle() may lose their styling when stdout is redirected but stderr remains a terminal (the common CI case).

// pkg/console/console.go — current
func isTTY() bool {
    return tty.IsStdoutTerminal()  // ⚠️ Should be IsStderrTerminal() for stderr output
}

Note: RenderComposedSections, RenderTitleBox and related functions already correctly use tty.IsStderrTerminal() — the inconsistency is only in applyStyle().

5. audit_report_render.go — Mixed Raw/Styled Output Pattern

This file (32 raw calls) uses fmt.Fprintln(os.Stderr, line) to print pre-built styled strings (e.g., compLine, metricsLine). While the content is styled, the pattern is fragile — consider refactoring to route all rendering through console.RenderComposedSections.

---

Recommendations (Priority Order)

1. 🔴 Fix isTTY() in console.go — change IsStdoutTerminal() to IsStderrTerminal(). This is a small change with significant correctness impact for CI environments.

2. 🟠 Migrate top 5 raw-stderr files — mcp_inspect_mcp.go (57), audit_report_render.go (32), fix_command.go (24), compile_stats.go (18), audit_cross_run_render.go (18) account for 149 of the 398 raw calls (~37%). Converting these would dramatically improve consistency.

3. 🟡 Add console import to the 6 files that write raw strings to stderr without it.

4. 🟢 Replace hardcoded separators (━━━...) with console.FormatSectionHeader() or console.RenderTitleBox().

5. 🟢 Lipgloss table usage — pkg/cli/compile_schedule_calendar.go and pkg/cli/gateway_logs_timeline_render.go use Lipgloss tables directly. These are well-implemented; ensure they're using styles.TableBorder, styles.TableHeader, and styles.ColorTableAltRow for zebra striping consistency.

---

References: §26749137896

Generated by 💄 Terminal Stylist · sonnet46 1.7M · ◷

• expires on Jun 2, 2026, 10:29 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #36431.