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

[github-actions[bot]]

This report analyzes console output patterns across the gh-aw codebase (711 Go source files) for consistency, Lipgloss styling, and Huh form usage. The analysis was triggered by workflow run §24665385101.

---

Summary

The codebase demonstrates strong console output discipline overall, with a well-designed pkg/console/ package providing TTY-aware Lipgloss styling and a custom Huh theme. The primary areas of concern are a few missing format functions in the non-wasm build and a handful of direct styles.* calls that bypass TTY detection.

Metric	Value
Total Go source files	711
CLI files using console.*	139
CLI files with stdout fmt.Print*	13
Lipgloss usage (files)	4 core (styles, console)
Huh usage (files)	10

---

✅ Strengths

Lipgloss — Excellent Adaptive Color System

pkg/styles/theme.go implements a fully adaptive color palette via charm.land/lipgloss/v2/compat.AdaptiveColor:

• Dracula-inspired dark theme paired with properly saturated light-mode variants
• All semantic colors (Error, Warning, Success, Info, Purple/Command, Yellow/Progress) defined with both Light and Dark hex values
• Border styles centralized (RoundedBorder, NormalBorder, ThickBorder)
• Pre-configured style variables: Error, Warning, Success, Info, Command, Progress, Prompt, Verbose, TableHeader, TableCell, TableTotal, etc.

TTY-Aware Rendering

pkg/console/console.go wraps all styling in an applyStyle() helper that queries tty.IsStdoutTerminal() before applying Lipgloss styles — ensuring ANSI codes are never emitted to non-terminal outputs.

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

Separate TTY checks also exist for stderr (tty.IsStderrTerminal()), used in RenderTitleBox, RenderErrorBox, RenderInfoSection, and RenderComposedSections.

Comprehensive Format Function Inventory

The console package provides a full set of semantic format helpers:

Function	Icon	Purpose
FormatSuccessMessage	✓	Confirmations
FormatInfoMessage	i	Informational
FormatWarningMessage	⚠	Warnings
FormatErrorMessage	✗	User-facing errors
FormatErrorChain	✗	Wrapped error chains
FormatCommandMessage	⚡	Command execution
FormatProgressMessage	🔨	Progress updates
FormatPromptMessage	❓	User prompts
FormatVerboseMessage	🔍	Debug/verbose output
FormatListItem	•	List items
FormatSectionHeader	—	Section headers

Rust-inspired error rendering with source context, line numbers, column pointers, and hints:

workflow.md:12:5: error: unknown field 'enginee'
    12 | enginee: copilot
                  ^^^^^^^^
hint: did you mean 'engine'?

Huh — Well-Themed Interactive Forms

pkg/styles/huh_theme.go implements huh.ThemeFunc (a huh v2 function type) that maps the Dracula palette to all huh form elements (focused/blurred states, selectors, buttons, text input, navigation indicators).

Consistent form creation pattern used across all huh callers:

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

• ✅ WithAccessible(IsAccessibleMode()) — proper accessibility mode support
• ✅ TTY guard in PromptSecretInput and ShowInteractiveList before running interactive forms
• ✅ Non-TTY text fallback in ShowInteractiveList

Output Routing Convention

Correct Unix conventions are observed throughout:

• Diagnostic output (messages, warnings, errors) → os.Stderr with console formatting
• Structured data (JSON, hashes, mermaid graphs) → os.Stdout via fmt.Println
• Markdown output (audit render functions) → os.Stdout — correct and intentional

---

⚠️ Issues Found

1. Missing Format Functions in Non-Wasm Build

The wasm stub (pkg/console/console_wasm.go) exposes three functions that have no counterpart in the main pkg/console/console.go:

Function	Wasm Stub	Non-Wasm
FormatLocationMessage(message)	"📁 " + message	❌ Missing
FormatCountMessage(message)	"📊 " + message	❌ Missing
FormatListHeader(header)	header (passthrough)	❌ Missing

Corresponding styles do exist in pkg/styles/theme.go (Location and Count), indicating these were intentionally designed but the non-wasm implementations were never added.

Risk: Any future caller using console.FormatLocationMessage() or console.FormatCountMessage() in a !js && !wasm context will fail to compile.

Recommendation: Add the three missing implementations to console.go:

func FormatLocationMessage(message string) string {
    return applyStyle(styles.Location, "📁 ") + message
}

func FormatCountMessage(message string) string {
    return applyStyle(styles.Count, "📊 ") + message
}

func FormatListHeader(header string) string {
    return applyStyle(styles.ListHeader, header)
}

2. Direct styles.* Calls Bypassing TTY Detection

pkg/cli/compile_stats.go:143-144 uses styles.Error.Render() directly instead of going through the console package:

// Current (bypasses TTY check):
workflowName = styles.Error.Render("✗ ") + styles.Error.Render(stats.Workflow)
fileSize = styles.Error.Render(console.FormatFileSize(stats.FileSize))

// Preferred (TTY-aware):
workflowName = console.FormatErrorMessage(stats.Workflow)

Direct styles.* calls emit ANSI escape codes unconditionally, potentially corrupting non-terminal output. This is the only instance found in the CLI package.

3. Markdown Render Functions: Raw fmt.Printf Volume

pkg/cli/audit_cross_run_render.go (72 calls) and pkg/cli/audit_diff_render.go (58 calls) contain dense raw fmt.Printf usage for markdown table construction. While this is intentional (these are structured markdown output functions), the pattern is verbose and error-prone.

The codebase already has RenderTable() (Lipgloss tables for TTY) but no equivalent markdown table builder helper. A utility like:

// FormatMarkdownTable(headers []string, rows [][]string) string

...could consolidate this pattern and reduce the surface area for formatting bugs.

---

📋 Recommendations

Priority	Area	Recommendation
High	API gap	Add FormatLocationMessage, FormatCountMessage, FormatListHeader to console.go with styles.Location, styles.Count, styles.ListHeader
Medium	TTY safety	Replace styles.Error.Render() in compile_stats.go with console.FormatErrorMessage()
Low	DX / maintenance	Add a FormatMarkdownTable(headers, rows) helper to reduce 130+ raw fmt.Printf table-formatting lines in audit render files
Low	Huh UX	Consider WithOutput(os.Stderr) in form creation to be explicit about output target (huh defaults vary by version)

---

Files Analyzed

Files with strong console formatting usage (sample)

• pkg/cli/audit_report_render.go — 31 console.* calls, proper stderr routing
• pkg/cli/logs_metrics.go — 49 console.* calls
• pkg/cli/trial_repository.go — 48 console.* calls
• pkg/cli/pr_command.go — 47 console.* calls
• pkg/cli/run_workflow_execution.go — 42 console.* calls
• pkg/cli/mcp_inspect_mcp.go — 36 console.* calls
• pkg/console/console.go — Core formatting with Lipgloss + TTY detection
• pkg/styles/theme.go — Adaptive color palette (53 Lipgloss references)
• pkg/styles/huh_theme.go — Custom Huh form theme

Files using stdout for structured data (correct pattern)

• pkg/cli/hash_command.go — fmt.Println(hash) ✅
• pkg/cli/tool_graph.go — fmt.Println(mermaidGraph) ✅
• pkg/cli/compile_pipeline.go — fmt.Println(jsonStr) ✅
• pkg/cli/status_command.go — fmt.Println(string(jsonBytes)) / fmt.Print(console.RenderStruct(...)) ✅
• pkg/cli/audit_cross_run_render.go — markdown to stdout ✅
• pkg/cli/audit_diff_render.go — markdown to stdout ✅

---

References: §24665385101

Generated by Terminal Stylist · ● 1.4M · ◷

• expires on Apr 21, 2026, 12:09 PM UTC