[terminal-stylist] Terminal Stylist Audit — Console Output Analysis

[github-actions[bot]]

Overview

This audit analyzed all non-test Go source files in pkg/ and cmd/ for console output consistency, Lipgloss usage patterns, and Huh interactive form implementations.

Summary:

• 1,755 console.* calls (well-established formatter usage)
• ~150 raw fmt.Println/fmt.Printf to stdout (mostly structured output — correct)
• ~35 raw fmt.Fprintf(os.Stderr, ...) / fmt.Fprintln(os.Stderr, ...) without console.Format* wrappers (improvement opportunity)
• Lipgloss v2 + adaptive colors: ✅ properly isolated in pkg/styles and pkg/console
• Huh v2 interactive forms: ✅ well-integrated with custom theme and accessibility mode

---

✅ What's Working Well

Lipgloss — Adaptive Colors & TTY Detection

pkg/styles/theme.go correctly uses lipgloss.Color with explicit light/dark hex pairs and lipgloss.LightDark in pkg/styles/huh_theme.go. The applyStyle() helper in pkg/console/console.go gates all rendering behind isTTY() so pipes/redirects receive plain text.

// pkg/console/console.go — correct pattern
func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text
}

Lipgloss Table — RenderTable()

pkg/console/console.go exposes a RenderTable(TableConfig) helper that wraps lipgloss/table with styled headers, alt-row highlighting, total rows, and TTY-aware borders. This is a good central abstraction.

Huh Forms — Theme + Accessibility

All interactive prompts (confirm.go, input.go, list.go, interactive add_* commands) apply styles.HuhTheme and console.IsAccessibleMode(), satisfying Huh's best-practice recommendations. Accessible mode is triggered via ACCESSIBLE, TERM=dumb, or NO_COLOR environment variables — a thorough implementation.

FormatErrorChain()

The new FormatErrorChain(err) function correctly unwraps nested errors and renders each level with consistent indentation, matching Rust-style error output.

---

⚠️ Issues & Improvement Opportunities

1. Raw Warning/Error Messages in pkg/workflow/

Several files emit diagnostic messages to stderr as bare strings without console.Format*:

File	Pattern	Instances
pkg/workflow/cache.go	fmt.Fprintf(os.Stderr, "Warning: ...")	2
pkg/workflow/push_to_pull_request_branch.go	fmt.Fprintf(os.Stderr, "Warning: ...")	1
pkg/workflow/mcp_renderer.go	fmt.Fprintf(os.Stderr, "Error ...")	1
pkg/workflow/compiler_orchestrator_engine.go	fmt.Fprintf(os.Stderr, "WARNING: ...")	2

Recommended fix:

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

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

2. Debug Messages to stderr in pkg/workflow/claude_logs.go

Lines 155–326 emit detailed diagnostic/trace information (JSON parsing progress, token counts, entry counts) directly to os.Stderr instead of using the debug logger. These messages are too verbose for normal stderr and belong in logger.New("workflow:claude_logs").

// ❌ Before
fmt.Fprintf(os.Stderr, "Extracted %d JSON entries from mixed format Claude log\n", len(logEntries))

// ✅ After  
claudeLog.Printf("Extracted %d JSON entries from mixed format Claude log", len(logEntries))

3. Manual SHA Info to stderr in pkg/workflow/action_sha_checker.go

Lines 186–187 output raw SHA values without formatting:

fmt.Fprintf(os.Stderr, "    Current: %s\n", check.Action.SHA)
fmt.Fprintf(os.Stderr, "    Latest:  %s\n", check.LatestSHA)

These should use console.FormatInfoMessage or the debug logger depending on their intent.

4. audit_cross_run_render.go and audit_diff_render.go — Manual Markdown Tables

These two files together account for 130 raw fmt.Printf/fmt.Println calls that produce plain markdown-formatted tables to stdout. While stdout is correct for structured output, the tables are entirely hand-crafted strings:

fmt.Printf("| Metric | Value |\n")
fmt.Printf("|--------|-------|\n")
fmt.Printf("| Runs analyzed | %d |\n", report.RunsAnalyzed)

Since these render as markdown (e.g., piped to a file or displayed in a terminal that renders markdown), this is acceptable but fragile. If TTY rendering is ever desired, console.RenderTable() is already available and could be used with a --plain fallback.

5. Unused FormatCountMessage / FormatLocationMessage / FormatListItem

Several console helpers defined in console.go and console_wasm.go (FormatCountMessage, FormatLocationMessage, FormatListItem) appear to have zero call-sites in production code. These either need adoption or can be removed to reduce dead surface area.

6. pkg/cli/compile_file_operations.go — Unformatted Error

fmt.Fprintln(os.Stderr, err.Error())  // line 113

Should be console.FormatErrorMessage(err.Error()).

---

Huh Usage Assessment

✅ Strengths

• Custom theme (pkg/styles/huh_theme.go): Full huh.ThemeFunc using the Dracula palette, covering focused/blurred states, selectors, buttons, text cursors, and file pickers. This is a model integration.
• Accessibility: WithAccessible(IsAccessibleMode()) applied consistently across all forms.
• Validation: PromptSecretInput includes non-empty validation; add_interactive_* files handle errors from form.Run() correctly.
• Field variety: Input, Confirm, Select, and MultiSelect are all used appropriately.

⚠️ Minor Observations

• pkg/cli/interactive.go and pkg/cli/run_interactive.go define custom huh forms directly rather than going through the console package helpers. This is fine for multi-field forms, but single-field prompts should use console.ConfirmAction() / console.PromptSecretInput() for consistency.
• No huh.Note fields are used anywhere. Where instructions or context need to be shown inside a form group (e.g., onboarding steps), huh.NewNote() would improve the UX.

---

Lipgloss Layout Assessment

✅ Strengths

• RenderTitleBox, RenderErrorBox, RenderInfoSection, and RenderComposedSections in console.go use lipgloss.JoinVertical and border composition correctly.
• All border/padding styles use the shared styles.RoundedBorder / styles.NormalBorder / styles.ThickBorder constants, ensuring visual consistency.

⚠️ Minor Observations

• pkg/cli/audit_report_render.go and sibling files use fmt.Fprintf(os.Stderr, ...) for tabular content that would benefit from console.RenderTable(). The audit rendering pipeline is the largest site of unformatted output.
• pkg/cli/copilot_setup.go emits multi-line YAML snippets as raw fmt.Fprintln(os.Stderr, ...) strings (lines 264–290). Wrapping this in console.RenderInfoSection() would give it a visual left-border emphasis consistent with how info sections are rendered elsewhere.

---

Recommendations — Priority Order

Priority	File(s)	Change
🔴 High	pkg/workflow/cache.go, mcp_renderer.go, push_to_pull_request_branch.go, compiler_orchestrator_engine.go	Replace fmt.Fprintf(os.Stderr, "Warning/Error: ...") with console.FormatWarningMessage / console.FormatErrorMessage
🔴 High	pkg/cli/compile_file_operations.go:113	Use console.FormatErrorMessage(err.Error())
🟡 Medium	pkg/workflow/claude_logs.go	Move debug-level trace messages to logger.New("workflow:claude_logs")
🟡 Medium	pkg/workflow/action_sha_checker.go:186-187	Use console.FormatInfoMessage or debug logger
🟡 Medium	pkg/cli/copilot_setup.go	Wrap YAML snippet block in console.RenderInfoSection()
🟢 Low	pkg/console/console.go	Adopt or remove FormatCountMessage, FormatLocationMessage, FormatListItem
🟢 Low	pkg/cli/interactive.go	Consider huh.NewNote() fields for onboarding context

---

References: §24834031763

Generated by Terminal Stylist · ● 854.2K · ◷

• expires on Apr 24, 2026, 12:07 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #28253.