[terminal-stylist] Console Output Analysis: Terminal Styling Patterns & Recommendations

[github-actions[bot]]

Overview

This analysis scanned 759 non-test Go source files across pkg/ for console output patterns, covering fmt.Print* usage, the internal console package, Lipgloss styling, and Huh interactive forms. The codebase demonstrates a mature, well-structured terminal output system with strong adoption of established patterns. A few targeted improvement opportunities are noted.

---

Summary Statistics

Category	Count
Total non-test Go source files	759
console.Format* calls	1,618
huh.NewForm interactive forms	19
lipgloss.NewStyle calls	42
Raw fmt.Println to stdout	~164
Raw fmt.Fprintln(os.Stderr) (diagnostic)	~1,846

---

✅ What's Working Well

Console Package Adoption

The pkg/console package is heavily and consistently used across the CLI layer, with all major message types applied correctly:

• 1,618 console.Format* calls — strong adoption of the formatting helpers
• Most common: FormatInfoMessage (627), FormatWarningMessage (508), FormatSuccessMessage (208), FormatErrorMessage (55)
• console.RenderTable (42 calls) and console.RenderStruct (13) provide consistent tabular output
• console.NewSpinner (14) used for progress indication
• console.FormatErrorWithSuggestions (17) for actionable error messages
• console.IsAccessibleMode() propagated to all huh.NewForm calls (see below)

TTY Detection

The applyStyle() function in pkg/console/console.go correctly gates Lipgloss rendering on TTY detection (tty.IsStdoutTerminal()/tty.IsStderrTerminal()), preventing ANSI escape codes from polluting piped/redirected output.

Lipgloss Styling — pkg/styles Package

The pkg/styles package implements a best-practice adaptive color system:

• Every color uses compat.AdaptiveColor{Light: ..., Dark: ...} — automatically adjusts for terminal background
• Dracula-inspired dark palette with high-contrast light alternatives
• Colors are semantic: ColorError, ColorWarning, ColorSuccess, ColorInfo, ColorPurple, ColorYellow, ColorComment, ColorForeground, ColorBackground, ColorBorder, ColorTableAltRow
• Custom HuhTheme in pkg/styles/huh_theme.go for consistent Huh form styling

Huh Interactive Forms — Full Coverage

All 19 huh.NewForm instances across the codebase follow best practices:

• ✅ .WithTheme(styles.HuhTheme) — consistent styling applied everywhere
• ✅ .WithAccessible(console.IsAccessibleMode()) — accessibility mode respected in all forms
• ✅ .Validate(...) used for critical input fields (workflow names, secrets, auth tokens)
• Forms structured in groups, using appropriate field types (Input, Select, MultiSelect, Confirm, Text)
• EchoModePassword used for secret inputs (engine_secrets.go)

Structured Output Routing

Commands correctly route output by type:

• Diagnostic output → fmt.Fprintln(os.Stderr, console.Format*(...)) ✅
• Structured data (JSON, hashes, graphs, Mermaid) → fmt.Println(...) to stdout ✅

Examples of correct stdout usage: hash_command.go, tool_graph.go, compile_pipeline.go, status_command.go, deps_report.go.

---

⚠️ Improvement Opportunities

1. Bare `fmt.Fprintf(os.Stderr)` Without Console Formatting — `pkg/workflow`

Several files in pkg/workflow/ emit diagnostic messages directly without console formatting. These lose color styling and inconsistently format warning/info messages:

pkg/workflow/cache.go (lines 338, 347):

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

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Failed to parse cache configuration: %v", err)))

pkg/workflow/compiler_orchestrator_engine.go (lines 171, 177):

// ❌ Current
fmt.Fprintf(os.Stderr, "WARNING: Skipping security scan for unresolvable import '%s': %v\n", importedFile, resolveErr)

// ✅ Recommended — or use logger.New("workflow:compiler_orchestrator_engine") for debug-only messages
fmt.Fprintln(os.Stderr, console.FormatWarningMessage(fmt.Sprintf("Skipping security scan for unresolvable import '%s': %v", importedFile, resolveErr)))

pkg/workflow/push_to_pull_request_branch.go (line 112): Similar pattern.

2. Debug Diagnostics Should Use Logger — `pkg/workflow/claude_logs.go`

claude_logs.go contains multiple fmt.Fprintf(os.Stderr, ...) calls that appear to be debug/diagnostic information rather than user-facing output. These should use logger.New(...) instead:

// ❌ Current — always printed to stderr
fmt.Fprintf(os.Stderr, "Claude parser extracted %d tool sequences with %d total tool calls\n", ...)
fmt.Fprintf(os.Stderr, "Extracted %d JSON entries from mixed format Claude log\n", len(logEntries))
fmt.Fprintf(os.Stderr, "Skipping invalid JSON line: %s\n", trimmedLine)

// ✅ Recommended — only shown when DEBUG=workflow:claude_logs
var log = logger.New("workflow:claude_logs")
log.Printf("Claude parser extracted %d tool sequences with %d total tool calls", ...)

This applies to ~6 calls in claude_logs.go.

3. `audit_cross_run_render.go` and `audit_diff_render.go` — Raw Markdown Headers to Stdout

These files output raw markdown headings (# Audit Report, ## Executive Summary, etc.) via fmt.Println. While this is intentional for report generation (structured output to stdout), the mixing of styled terminal output and markdown is inconsistent with the rest of the audit rendering stack.

Consider whether these reports should go through a console.RenderMarkdown abstraction or use Lipgloss headers for live terminal rendering vs. plain markdown for redirected output.

4. `compile_file_operations.go` — One Unformatted Line (line 174)

// ❌ Line 174 — bare message without console formatting
fmt.Fprintln(os.Stderr, "Watching for file changes")

// ✅ Recommended
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Watching for file changes"))

All other output in this file correctly uses console.Format* helpers.

5. `action_sha_checker.go` and `side_repo_maintenance.go` — Informational Messages Without Console Formatting

// ❌ Current — action_sha_checker.go lines 187-188
fmt.Fprintf(os.Stderr, "    Current: %s\n", check.Action.SHA)
fmt.Fprintf(os.Stderr, "    Latest:  %s\n", check.LatestSHA)

// ❌ Current — side_repo_maintenance.go lines 113, 137
fmt.Fprintf(os.Stderr, "  Generated side-repo maintenance workflow: %s\n", filename)
fmt.Fprintf(os.Stderr, "  Removed stale side-repo maintenance workflow: %s\n", name)

// ✅ Recommended — use console.FormatInfoMessage or logger for debug info
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Generated side-repo maintenance workflow: %s", filename)))

6. Hardcoded ANSI Codes in Logger — `pkg/logger/logger.go`

The logger uses raw \033[38;5;...m ANSI escape sequences for namespace colorization. While functional, this bypasses the adaptive color system in pkg/styles. However, given logger colors are debug-only and the current implementation is intentional (zero overhead), this is low priority.

---

Recommendations

Priority	File(s)	Action
🟡 Medium	pkg/workflow/cache.go, push_to_pull_request_branch.go, compiler_orchestrator_engine.go	Replace bare fmt.Fprintf(os.Stderr, "Warning:...") with console.FormatWarningMessage
🟡 Medium	pkg/workflow/claude_logs.go	Convert 6 debug fmt.Fprintf calls to logger.New("workflow:claude_logs")
🟢 Low	pkg/cli/compile_file_operations.go line 174	Wrap "Watching for file changes" in console.FormatInfoMessage
�� Low	pkg/workflow/action_sha_checker.go, side_repo_maintenance.go	Use console.FormatInfoMessage for informational output
🔵 Consider	audit_cross_run_render.go, audit_diff_render.go	Evaluate Lipgloss-styled headers for TTY vs markdown for piped output

---

Architecture Strengths

1. Centralized styling: pkg/styles + pkg/console provide a single source of truth for all terminal aesthetics
2. Adaptive colors throughout: Light/dark terminal detection via compat.AdaptiveColor
3. Consistent Huh patterns: Every interactive form uses the same theme, accessible mode, and validation approach
4. TTY-gated rendering: applyStyle() ensures clean output in CI and piped contexts
5. Semantic ANSI stripping: pkg/stringutil/ansi.go prevents ANSI codes from leaking into YAML/structured output
6. Console package WASM support: WASM fallbacks (*_wasm.go) maintain feature parity without styling

References:

• §25311247254

Generated by Terminal Stylist · ● 1.2M · ◷

• expires on May 5, 2026, 9:29 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-05-05T09:29:18.138Z.

Closed by Workflow