[terminal-stylist] Terminal Stylist: Console Output Analysis — pkg/ Charmbracelet Best Practices Review

[github-actions[bot]]

Overview

This report analyzes console output patterns across all 959 non-test Go source files in pkg/ to evaluate consistency, Lipgloss styling, Huh form usage, and opportunities for improvement.

---

Key Metrics

Metric	Count
Total pkg/ Go source files	959
Packages analyzed	29
Files importing pkg/console	205
Files with raw fmt.Fprintln/Fprintf to stderr (outside pkg/console)	201
Files using huh forms	13
huh files missing WithTheme or WithAccessible	0 ✅
Files with raw ANSI escape codes	1 (isolated, intentional)

---

Strengths ✅

1. Well-designed abstraction layer — pkg/console, pkg/styles, and pkg/tty form a cohesive system with clear separation of concerns.
2. True adaptive color system — pkg/styles implements a custom adaptiveColor type that probes the terminal background at startup and selects Dracula-inspired dark or muted-saturated light variants automatically. Windows is safely excluded from the probe.
3. TTY-guarded styling — applyStyle() in console.go always checks isTTY() before applying Lipgloss styles, preventing raw ANSI codes from appearing in pipes/redirects.
4. lipgloss/table fully adopted — RenderTable() uses the charm.land/lipgloss/v2/table package with header, zebra-row, and total-row styles, plus RoundedBorder for a polished appearance.
5. lipgloss.JoinVertical for layout — RenderComposedSections() composes UI sections with proper layout rather than concatenating strings.
6. Huh integration is consistent and complete — All 13 files using huh (9 in pkg/cli, 3 in pkg/console, 1 in pkg/styles) apply both WithTheme(styles.HuhTheme) and WithAccessible(console.IsAccessibleMode()), providing brand-consistent interactive forms with accessibility support.
7. Custom HuhTheme — pkg/styles/huh_theme.go maps the shared color palette to all Huh field states (focused, blurred, selected, error, button, cursor), using lipgloss.LightDark() correctly for the v2 API.
8. Non-TTY fallbacks — ConfirmAction() and ShowInteractiveList() both detect non-TTY and fall back to text-based interaction.
9. ANSI escape codes isolated — Only terminal.go uses raw \033[ sequences, strictly for cursor control (clear screen, clear line), and these are wrapped in tty.IsStderrTerminal() guards.

---

Issues and Recommendations

⚠️ 1. Mixed styling in compile_stats.go — styled summaries, unstyled sub-items

compile_stats.go uses console.FormatErrorMessage() for top-level summaries but drops back to raw fmt.Fprintf for indented sub-items, creating visual inconsistency:

// Styled (good)
fmt.Fprintln(os.Stderr, console.FormatErrorMessage(summary))
fmt.Fprintln(os.Stderr, console.FormatErrorMessage("Failed workflows:"))

// Unstyled sub-items (inconsistent)
fmt.Fprintf(os.Stderr, "  ✗ %s\n", filepath.Base(failure.Path))
fmt.Fprintf(os.Stderr, "    %d. %s\n", i+1, prioritized.Message)
fmt.Fprintf(os.Stderr, "       → %s\n", prioritized.Suggestion)
fmt.Fprintf(os.Stderr, "  i Suppressed %d cascading error(s)...\n", ...)
fmt.Fprintf(os.Stderr, "  Run 'gh aw compile --show-all'...\n", ...)

Recommendation: Use console.FormatListItem(), console.FormatInfoMessage(), and styles.Error.Render() for the sub-items to match the top-level styling. The ✗, 💡, and i symbols should use styled prefixes like other message types.

⚠️ 2. Six files write to stderr without importing pkg/console

These files emit user-facing messages to stderr with no styling, bypassing the console abstraction entirely:

File	Raw stderr calls	Example
cli/add_interactive_secrets.go	1	"Found %d existing secret(s)..."
cli/copilot_setup.go	4+	"No version upgrade needed...", "Updated %s with new version..."
cli/devcontainer.go	2	"Updated existing devcontainer...", "Created new devcontainer..."
cli/mcp_config_file.go	1	"MCP server '%s' already configured..."
cli/observability_insights.go	4+	" %s %s [%s]\n" for insight items
cli/vscode_config.go	1	"Settings file already exists at %s"

Recommendation: Add pkg/console import and use the appropriate format function:

• Success/completion messages → console.FormatSuccessMessage()
• Info/status messages → console.FormatInfoMessage()
• observability_insights.go insight rendering → consider console.RenderTable() or console.FormatSectionHeader() + console.FormatListItem()

i️ 3. logs_format_compact.go — intentional machine-readable stdout (no action needed)

logs_format_compact.go uses fmt.Fprintf(os.Stdout, ...) with key=value structured format ([summary], [runs], [errors], etc.). This is intentional machine-readable output for scripting and piping — it should not be styled. No changes recommended here.

i️ 4. Huh — no MultiSelect or Note fields observed

The current Huh usage covers Input, Confirm, and Select field types. Two opportunities for enhanced UX:

• huh.NewMultiSelect: The add_interactive_workflow.go flow that collects tool selections would benefit from a MultiSelect field instead of multiple Select fields or CLI flags. The HuhTheme already covers MultiSelectSelector, SelectedPrefix, and UnselectedPrefix styles.
• huh.NewNote: Long instructional text currently printed with fmt.Fprintln before forms could be moved into a Note field so the help text stays in-form and scrolls with it.

i️ 5. experiments_command.go manual table formatting

experiments_command.go builds manual text tables with fmt.Fprintf(os.Stderr, " %-20s %d (%d%%)\n", ...). With console.RenderTable() available this could be upgraded to a proper styled table with borders, zebra rows, and adaptive colors — especially useful for the experiments breakdown output.

---

Lipgloss Usage — Detailed Assessment

Full Lipgloss Analysis

What's done well:

• adaptiveColor struct implements color.Color and is used for every semantic color — no hardcoded hex strings appear at the style callsites
• Border constants (RoundedBorder, NormalBorder, ThickBorder) centralized in pkg/styles and reused across console.go
• applyStyle(style, text) is a clean TTY-detection wrapper that avoids conditional blocks at every callsite
• RenderTitleBox() and RenderErrorBox() correctly fall back to plain-text separators in non-TTY mode
• lipgloss.JoinVertical(lipgloss.Left, sections...) used in RenderComposedSections() — correct composition pattern
• Calendar heatmap styles (ScheduleCalendarEmpty/Low/Medium/High/Critical) follow the semantic color progression correctly

Minor gaps:

• ShowWelcomeBanner() in terminal.go uses styles.Header.Render(header) but doesn't wrap in applyStyle() — instead uses a manual TTY check. While functionally equivalent, it diverges from the applyStyle() pattern used everywhere else.
• BannerStyle in banner.go is exported as a var but its applyStyle() call is in FormatBanner(). Callers using BannerStyle directly could bypass TTY detection. Consider keeping BannerStyle unexported.

---

Huh Usage — Detailed Assessment

Full Huh Analysis

Files and patterns:

File	Huh Fields Used	WithTheme	WithAccessible	TTY Check
console/confirm.go	Confirm	✅	✅	✅
console/input.go	Input (password)	✅	✅	✅
console/list.go	Select	✅	✅	✅
cli/interactive.go	Select, Input, Confirm	✅	✅	✅
cli/run_interactive.go	Select, Input, Confirm	✅	✅	✅
cli/add_interactive_*.go (×5)	Various	✅	✅	(via console helpers)
cli/engine_secrets.go	Input	✅	✅	✅

Accessibility support:

• console.IsAccessibleMode() reads the ACCESSIBLE env variable and propagates it to Huh's accessible text mode
• Huh accessible mode replaces visual select lists with numbered text prompts, suitable for screen readers

Validation:

• console/input.go uses .Validate() with empty-string check — good pattern
• console/confirm.go non-TTY fallback parses y/yes/1/n/no/2 — robust text fallback

Gaps:

• No .Validate() callbacks observed in the add_interactive_*.go forms beyond what huh provides natively
• No huh.NewNote usage for in-form rich documentation
• No huh.NewMultiSelect despite multiple multi-value collection points

---

Next Actions

Priority	Action	Files
🔴 High	Replace raw fmt.Fprintf sub-items in compile_stats.go with console.FormatListItem() / styled helpers	cli/compile_stats.go
🟡 Medium	Add pkg/console import and use format helpers in the 6 files that bypass it	add_interactive_secrets.go, copilot_setup.go, devcontainer.go, mcp_config_file.go, observability_insights.go, vscode_config.go
🟡 Medium	Upgrade experiments_command.go manual table to console.RenderTable()	cli/experiments_command.go
🟢 Low	Consider huh.NewMultiSelect for tool/option selection in interactive add wizard	cli/interactive.go, cli/add_interactive_workflow.go
🟢 Low	Consider huh.NewNote for pre-form instructional text	cli/add_interactive_*.go
🟢 Low	Make BannerStyle unexported to prevent direct style use that bypasses TTY detection	console/banner.go

---

References:

• [§28230500820]

Generated by 💄 Terminal Stylist · 110.5 AIC · ⌖ 15.3 AIC · ⊞ 5.7K · ◷

• expires on Jun 27, 2026, 1:58 AM UTC-08:00

[pelikhan]

/plan

[github-actions[bot]]

🚀 Agentic Commands has started processing this discussion comment