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

[github-actions[bot]]

Analysis of 913 non-test .go files in pkg/ for console output patterns, Lipgloss styling, and Huh form implementations.

Summary

Metric	Value
Files in pkg/	913
Files importing pkg/console	199 (22%)
Files importing pkg/styles directly	23
Files using huh directly	13
Files using lipgloss directly	6
Hardcoded hex colors outside pkg/styles/	0 ✅

Status: ✅ Strong overall consistency — 6 targeted improvements identified.

---

Architecture

Clear 3-layer terminal UI stack:

1. pkg/styles/ — Centralized Lipgloss color palette + Huh theming
2. pkg/console/ — High-level UI components (Format*, Render*, forms, spinner, progress)
3. pkg/cli/ + pkg/workflow/ — Consumers (199 files)

---

✅ Strengths

• Adaptive colors: compat.AdaptiveColor with Dracula-inspired light/dark hex values; Windows-safe init()
• Huh theming: Every form consistently uses .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode())
• TTY gating: applyStyle() conditionally applies Lipgloss — no ANSI leaking into pipes
• Non-TTY fallbacks: confirm.go, list.go provide text-based fallbacks for non-TTY environments
• Output routing: diagnostic → stderr, structured data → stdout (documented in doc.go)
• Naming convention: Format* = pure string, Render* = structured output (documented)

---

⚠️ Improvement Opportunities

Issue 1: Direct huh callers in `pkg/cli/` skip the TTY pre-check (8 of 9 callers)

Console wrappers (confirm.go, list.go, input.go) all call tty.IsStderrTerminal() before running forms and provide text fallbacks. Direct callers in pkg/cli/ skip this:

• interactive.go, add_interactive_auth.go, add_interactive_workflow.go, add_interactive_orchestrator.go
• add_interactive_engine.go, add_interactive_schedule.go, add_interactive_git.go, engine_secrets.go

Only run_interactive.go has the TTY check. Recommendation: Add TTY pre-check at command entry point or document the assumption.

Issue 2: Bare `fmt.Fprintf(os.Stderr, ...)` in several `pkg/cli/` files

File	Lines	Issue
trial_confirmation.go	182–222	Manual bullet lists without styling
token_usage.go	444–533	Debug messages bypassing console
outcomes_history.go	165–313	Stats report without formatters
vscode_config.go	82	Single unstyled notice
compile_stats.go	162–191	Failure report without console

Recommendation: Replace with console.FormatInfoMessage(), console.FormatWarningMessage(), etc.

Issue 3: `ShowWelcomeBanner()` emits unstyled welcome text

pkg/console/terminal.go lines 43–46 use bare fmt.Fprintln(os.Stderr, ...) for the welcome header and description while PrintBanner() nearby correctly uses applyStyle(). Recommendation: Apply styles.Header to the title and a style via applyStyle() to the description.

Issue 4: `RunForm([]FormField)` has only a wasm stub

console_types.go defines FormField; form_wasm.go stubs RunForm() with an error. No native implementation exists. The 16+ direct huh.NewForm(...) usages in pkg/cli/ build forms inline. Recommendation: Implement the native version or remove FormField and the stub.

Issue 5: `intensityStyle()` allocates new `lipgloss.Style` per call

pkg/cli/compile_schedule_calendar.go calls lipgloss.NewStyle() inside intensityStyle() for every cell in a 168-cell grid. Recommendation: Pre-define the 5 intensity styles as package-level vars (consistent with pkg/styles/theme.go).

Issue 6: `styles/theme.go` doc examples use stdout

Lines 39–46 show fmt.Println(styles.Error.Render(...)) in doc comments. Per doc.go convention, diagnostic output goes to stderr. Recommendation: Change examples to fmt.Fprintln(os.Stderr, ...).

---

Lipgloss Summary

File	Assessment
pkg/styles/theme.go	✅ Excellent — adaptive colors, Windows-safe init
pkg/styles/huh_theme.go	✅ Excellent — full Huh theme from Dracula palette
pkg/console/console.go	✅ Excellent — applyStyle() TTY guard, lipgloss/table
pkg/logger/logger.go	✅ Good — per-namespace adaptive coloring
pkg/cli/compile_schedule_calendar.go	⚠️ Minor — inline style creation (Issue 5)

Huh Summary

File(s)	Assessment
pkg/console/confirm.go, input.go, list.go	✅ Excellent — TTY fallback + theme + accessible
pkg/cli/run_interactive.go	✅ Good — TTY check + theme + accessible
pkg/cli/add_interactive_*.go, interactive.go, engine_secrets.go	⚠️ Missing TTY pre-check (Issue 1)

---

Recommendations (Priority)

1. Add TTY pre-checks to direct huh callers (Issue 1)
2. Replace bare fmt.Fprintf(os.Stderr, ...) with console formatters (Issue 2)
3. Style ShowWelcomeBanner() text with Lipgloss (Issue 3)
4. Implement or remove RunForm() (Issue 4)
5. Pre-define intensityStyle variants (Issue 5)
6. Fix styles/theme.go doc examples to use stderr (Issue 6)

References: §27463157795

Generated by 💄 Terminal Stylist · 502.2 AIC · ⌖ 14.1 AIC · ⊞ 21.7K · ◷

• expires on Jun 14, 2026, 1:50 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-06-14T09:50:02.486Z.

Closed by Workflow