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

[github-actions[bot]]

This report covers a full scan of 687 Go source files in pkg/ and cmd/ for console output patterns, Lipgloss styling usage, and Huh form implementations.

---

Executive Summary

Metric	Value
Total Go source files scanned	687
Files using console.* formatters	Widespread – 1,756 calls
Files using lipgloss.* directly	4 (all in pkg/console/ and pkg/styles/)
Files using huh.* directly	14 (11 in pkg/cli/, 3 in pkg/console/)
Raw fmt.Print* to stdout (legitimate structured data)	~15 files
Raw fmt.Fprintf(os.Stderr, ...) bypassing console formatting	~8 files
Audit markdown render files (intentional raw output)	2 files, 130 calls

Overall assessment: ✅ Very good. The codebase has a well-designed, layered console output system. Most issues are isolated to a few specific files.

---

Architecture Overview

The console output stack is clean and well-organized:

pkg/styles/theme.go         ← Lipgloss styles + adaptive color palette (light/dark)
pkg/styles/huh_theme.go     ← Custom Huh form theme matching the color palette
pkg/tty/tty.go              ← TTY detection (stdout + stderr)
pkg/console/console.go      ← High-level formatters (FormatSuccessMessage, etc.)
pkg/console/render.go       ← Struct/table rendering via reflection
pkg/console/list.go         ← Interactive list via huh.Select
pkg/console/input.go        ← Secret input via huh.Input
pkg/console/confirm.go      ← Confirmation via huh.Confirm
pkg/cli/**_command.go       ← Commands using console.Format* + os.Stderr

Lipgloss is used exclusively through pkg/styles and pkg/console — no raw lipgloss.* calls appear in CLI command files. This is excellent encapsulation.

---

✅ Good Patterns

Adaptive Color System

pkg/styles/theme.go uses lipgloss/v2/compat.AdaptiveColor throughout. Every color constant has both light and dark hex variants that automatically adapt to the user's terminal theme. This is the correct modern approach.

TTY-aware Styling

applyStyle() in console.go correctly checks tty.IsStdoutTerminal() before applying Lipgloss styles. Layout functions (RenderTitleBox, RenderErrorBox, etc.) similarly check tty.IsStderrTerminal(). This prevents ANSI escape codes leaking into piped output.

Proper stdout/stderr routing

Structured data (JSON, hashes, Mermaid graphs, Markdown) → stdout for piping. Diagnostic messages (info, warnings, errors, progress) → stderr via console.Format* + fmt.Fprintln(os.Stderr, ...). This Unix convention is correctly followed throughout the CLI commands.

Custom Huh Theme

pkg/styles/huh_theme.go maps the full Dracula-inspired color palette to Huh form fields using the modern lipgloss.LightDark(isDark) helper. Interactive forms share the same visual identity as static console output.

Accessibility Support

All Huh form calls include .WithAccessible(IsAccessibleMode()), enabling screen reader support. Accessibility mode is detected consistently.

FormatErrorChain

pkg/console/console.go has a sophisticated FormatErrorChain() function that recursively unwraps %w-wrapped errors and displays them in an indented chain. This is a notable best practice for CLI usability.

---

⚠️ Issues Found

Issue 1: TTY detection inconsistency — stdout vs stderr (console.go)

File: pkg/console/console.go
Lines: 22–23

// isTTY checks if stdout is a terminal
func isTTY() bool {
    return tty.IsStdoutTerminal()  // ← checks stdout
}

isTTY() checks whether stdout is a terminal, but it is used to decide whether to apply Lipgloss styles to messages that are typically written to stderr (e.g., FormatSuccessMessage, FormatWarningMessage, FormatInfoMessage).

This creates a subtle mismatch: if a user pipes stdout (gh aw compile > out.txt), isTTY() returns false and styles are stripped, even though stderr is still a terminal and the messages would render fine in color.

The layout functions (RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderComposedSections) correctly use tty.IsStderrTerminal() — making the inconsistency clear.

Recommendation: Consider renaming isTTY() to isStdoutTTY() and adding an isStderrTTY() helper. Use the appropriate check based on the output destination.

Issue 2: Missing console functions in non-WASM build

File: pkg/console/console_wasm.go defines functions not present in pkg/console/console.go:

Function	WASM stub	Non-WASM implementation
FormatLocationMessage	✅	❌ Missing
FormatCountMessage	✅	❌ Missing
FormatListHeader	✅	❌ Missing

These functions exist only as bare stubs in the WASM file (no styling), but are absent from the main non-WASM console.go. Although no current CLI code calls them, they represent an API surface inconsistency. Any future code using them would silently fail to compile unless the WASM build tag is in effect.

Recommendation: Add implementations for FormatLocationMessage, FormatCountMessage, and FormatListHeader to pkg/console/console.go with proper Lipgloss styling (e.g., using styles.Info for location, styles.Purple for count).

Issue 3: Raw fmt.Fprintf(os.Stderr) bypassing console formatters in enable.go

File: pkg/cli/enable.go

Multiple diagnostic messages bypass the console formatting layer:

// Lines 46, 136, 141, 192, 198, 200, 260, 321, 330, 346, 348, 367
fmt.Fprintf(os.Stderr, "No specific workflows provided. %sing all workflows...\n", ...)
fmt.Fprintf(os.Stderr, "Workflow %s is already enabled\n", name)
fmt.Fprintf(os.Stderr, "Workflow %s is already disabled\n", name)
fmt.Fprintf(os.Stderr, "All specified workflows are already %sd\n", action)
fmt.Fprintf(os.Stderr, "The following workflows will be %sd:\n", action)
fmt.Fprintf(os.Stderr, "  %s (current state: %s)\n", t.Name, t.CurrentState)
fmt.Fprintf(os.Stderr, "%sd workflow: %s\n", ...)
fmt.Fprintf(os.Stderr, "Keeping enabled: %s\n", base)
fmt.Fprintf(os.Stderr, "Disabling %d workflow(s) in cloned repository:\n", ...)

These should use console.FormatInfoMessage, console.FormatSuccessMessage, or console.FormatWarningMessage for consistent styling.

Recommendation: Replace raw fmt.Fprintf(os.Stderr, ...) calls with appropriate console formatters.

Issue 4: Raw fmt.Fprintf(os.Stderr) in compile_file_operations.go

File: pkg/cli/compile_file_operations.go, line 301

fmt.Fprintf(os.Stderr, "  ✗ %s\n", filepath.Base(failure.Path))

This manually replicates the error icon (✗) instead of using console.FormatErrorMessage. The manually-inserted ✗ won't be colored in a TTY.

Recommendation: Replace with console.FormatErrorMessage(filepath.Base(failure.Path)).

Issue 5: Inconsistent formatting in deps_security.go

File: pkg/cli/deps_security.go, lines 117–127

fmt.Fprintf(os.Stderr, "    %s", adv.Summary)
if adv.CVE != "" {
    fmt.Fprintf(os.Stderr, " (%s)", adv.CVE)
}
fmt.Fprintf(os.Stderr, "\n")
// ...
fmt.Fprintf(os.Stderr, "    Fixed in: %s\n", strings.Join(adv.PatchedVers, ", "))
fmt.Fprintf(os.Stderr, "    %s\n", adv.URL)

Security advisory output is formatted with raw fmt.Fprintf calls without any styling. Given that this is security-sensitive information, it would benefit from consistent warning-level formatting.

Recommendation: Use console.FormatWarningMessage for advisory summaries and console.FormatListItem for CVE/URL details.

Informational: audit_cross_run_render.go and audit_diff_render.go (intentional raw output)

Files: pkg/cli/audit_cross_run_render.go (72 calls), pkg/cli/audit_diff_render.go (58 calls)

These files contain large numbers of fmt.Println/fmt.Printf calls to stdout. This is intentional and correct — these functions implement Markdown report renderers whose output is meant to be piped, redirected, or viewed in a Markdown viewer. Raw fmt.Print* is appropriate here.

Both files have corresponding renderXxxJSON and renderXxxPretty variants that correctly use console.Format* for pretty output to stderr. The three rendering modes (JSON, Markdown, Pretty) are properly separated.

No changes needed.

---

Lipgloss Usage Analysis

Direct Lipgloss calls are intentionally confined to pkg/styles/ and pkg/console/, which is excellent architecture. The rest of the codebase never imports Lipgloss directly — all styling goes through the abstraction layers.

Pattern	Status
Adaptive colors (LightDark/AdaptiveColor)	✅ Used correctly throughout pkg/styles/theme.go
TTY detection before styling	✅ applyStyle() wraps all style calls
Table rendering via lipgloss/table	✅ console.RenderTable() provides a config-based wrapper
Border styles	✅ styles.RoundedBorder used consistently
Layout composition (JoinVertical)	✅ Used in RenderComposedSections
Hardcoded ANSI escape codes	✅ Absent (only terminal.go uses raw ANSI for cursor control, which is appropriate)

Lipgloss v2 migration: The codebase uses charm.land/lipgloss/v2 (the new import path) and the modern lipgloss.LightDark(isDark) API. This is current with the v2 API.

---

Huh Form Analysis

Aspect	Status
Custom theme integration	✅ All forms use styles.HuhTheme
Accessibility mode	✅ All forms use .WithAccessible(IsAccessibleMode())
TTY guard before showing forms	✅ input.go and list.go check tty.IsStderrTerminal()
Non-TTY fallback	✅ list.go falls back to text list when no TTY
Field validation	✅ Input fields include Validate() callbacks
Echo masking for secrets	✅ PromptSecretInput uses EchoModePassword
Huh v2 API	✅ Uses charm.land/huh/v2 (modern import)

The Huh integration in pkg/console/ is a well-designed wrapper layer. CLI code in pkg/cli/add_interactive_*.go uses Huh forms directly (not through the wrapper), which is acceptable for complex multi-field forms.

---

Recommendations Summary

Priority	File	Action
Medium	pkg/console/console.go	Fix isTTY() — use tty.IsStderrTerminal() for formatter functions that output to stderr
Low	pkg/console/console.go	Add FormatLocationMessage, FormatCountMessage, FormatListHeader (currently only in WASM stub)
Low	pkg/cli/enable.go	Replace ~10 raw fmt.Fprintf(os.Stderr, ...) calls with console formatters
Low	pkg/cli/compile_file_operations.go:301	Use console.FormatErrorMessage instead of manually inserting ✗
Low	pkg/cli/deps_security.go:117–127	Use console formatters for security advisory display

---

References:

• §24453291464

Generated by Terminal Stylist · ● 1.4M · ◷

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