[terminal-stylist] Terminal Stylist: Console Output Analysis

[github-actions[bot]]

Scope: pkg/ directory, 1,005 non-test Go source files
Libraries analysed: charm.land/lipgloss/v2, charm.land/huh/v2, charm.land/bubbles/v2, charm.land/lipgloss/v2/tree, charm.land/lipgloss/v2/table

---

Summary

The codebase has a mature, well-structured terminal output system. Central style definitions live in pkg/styles/, formatting helpers in pkg/console/, and interactive forms are consistently themed via styles.HuhTheme. The vast majority of user-facing output passes through the console package correctly. A small set of callsites bypass it, and a few minor patterns could be tightened.

---

Key Metrics

Metric	Count
Total non-test Go files	1,005
Files using charm.* libraries	24
Files using console.* helpers	167
Huh forms (.WithTheme + .WithAccessible)	20
Raw fmt.Fprintf(os.Stderr, ...) without console wrapper	~35 callsites in 8 files
Direct styles.X.Render() without TTY guard	3 callsites (all guarded)
Raw ANSI escape sequences	3 constants in pkg/console/terminal.go

---

Lipgloss Usage Analysis

✅ Strengths

• Adaptive color system (pkg/styles/theme.go): The adaptiveColor type satisfies color.Color and automatically selects light/dark hex variants based on a startup terminal probe (lipgloss.HasDarkBackground). Windows is safely excluded from the probe to avoid ConPTY crashes.
• Centralized palette: 11 semantic color variables (ColorError, ColorWarning, ColorSuccess, ColorInfo, ColorPurple, ColorYellow, ColorComment, ColorForeground, ColorBackground, ColorBorder, ColorTableAltRow) — Dracula-inspired dark, accessible light equivalents.
• Pre-composed styles: styles.Error, styles.Warning, styles.Success, styles.Info, styles.FilePath, styles.Command, styles.Progress, styles.Prompt, styles.Verbose, styles.Header, styles.TableHeader, styles.TableCell, styles.TableTotal, styles.TableBorder, styles.ListHeader, styles.ListItem, styles.ServerName, styles.ServerType, styles.ErrorBox, styles.TreeEnumerator, styles.TreeNode, styles.ScheduleCalendar*.
• TTY detection before styling: pkg/console/console.go provides applyStyle and applyStyleWithTTY wrappers. All RenderTable, RenderTitleBox, RenderErrorBox, RenderInfoSection, and RenderComposedSections functions check tty.IsStderrTerminal() or use the injectable TTYFunc field in TableConfig.
• lipgloss/table for data tables: RenderTable uses charm.land/lipgloss/v2/table with zebra-stripe StyleFunc, rounded borders, and header/total row differentiation.
• lipgloss/tree for hierarchical data: pkg/cli/status_command.go uses charm.land/lipgloss/v2/tree with styles.TreeEnumerator and styles.TreeNode, matching the design system.
• lipgloss.Fprintf in logger: pkg/logger/logger.go uses lipgloss.Fprintf (color-profile-aware writer) rather than fmt.Fprintf, ensuring ANSI is stripped when the output is not a terminal.

⚠️ Minor Opportunities

1. compile_schedule_calendar.go (lines 252, 264): Calls styles.TableHeader.Render(header) and styles.TableHeader.Render(label) without going through applyStyle. Both are inside an if isTerminal block, so the TTY check is correct — but for consistency with the rest of the codebase the pattern should use console.applyStyle or just applyStyleWithTTY. Since applyStyle is unexported, consider adding an internal variant or moving these to use RenderTable.

2. compile_stats.go (lines 302–303): Uses styles.Error.Render("✗ ") directly inside a tty.IsStderrTerminal() guard. Functionally correct but inconsistent with console.FormatErrorMessage; could reuse applyStyleWithTTY.

3. org_runner.go (lines 87–103), update_container_pins.go (lines 160–344): Plain fmt.Fprintf(os.Stderr, " - ...") messages without color or console formatting. These are informational list items — ideal candidates for console.FormatListItemStderr or console.FormatInfoMessageStderr.

4. mcp_list_tools.go (lines 77–136): Uses raw fmt.Fprintf(os.Stderr, ...) for informational messages about MCP server discovery. Suitable for console.FormatInfoMessageStderr.

Huh Forms Usage Analysis

✅ Strengths

• 20 form instantiations in pkg/cli/ (add-wizard, run-interactive, engine-secrets, interactive.go) and pkg/console/ (confirm, input, list). All use .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()).
• Custom theme (pkg/styles/huh_theme.go): HuhTheme is a huh.ThemeFunc using lipgloss.LightDark(isDark) for per-render color selection (correct for forms, distinct from the package-level adaptiveColor probe). Maps all semantic palette colors to focused/blurred/group styles.
• Accessibility mode (pkg/console/accessibility.go): Detects ACCESSIBLE, TERM=dumb, and NO_COLOR env vars and passes IsAccessibleMode() to all forms.
• Field variety: huh.NewInput, huh.NewConfirm, huh.NewSelect, huh.NewMultiSelect, huh.NewText are all in use. huh.NewInput with EchoMode(huh.EchoModePassword) is used for secret input.
• TTY guard before form: pkg/console/confirm.go and pkg/console/input.go check tty.IsStderrTerminal() before showing a form and fall back to plain text input — good UX.
• Non-TTY text fallback: showTextConfirm in confirm.go provides a readable non-interactive alternative.

⚠️ Minor Opportunities

1. add_interactive_auth.go, add_interactive_git.go: Huh forms are constructed directly in CLI files rather than going through the pkg/console abstraction layer. This duplicates the .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()) chain — consider thin wrappers in pkg/console (e.g., console.PromptSelect, console.PromptInput) that bake in theme + accessibility automatically, reducing boilerplate.

2. Validation messages: Validation closures in engine_secrets.go and run_interactive.go return plain errors.New("...") strings. For consistency, these could use fmt.Errorf with the same terse, lowercase style used in compilation errors.

3. No Note fields: huh.NewNote is available for displaying contextual help inside forms but is not currently used. Where wizard steps display explanatory text via fmt.Fprintln(os.Stderr, ...) before showing a form, a Note field would keep context co-located with the form.

Raw fmt.Print* Callsites That Bypass Console Formatting

These are callsites in pkg/cli/ writing directly to os.Stderr / os.Stdout without a console.* wrapper:

File	Lines	Pattern	Suggested Replacement
trial_confirmation.go	182–183, 199–200	fmt.Fprintf(os.Stderr, " a. Execute...") sub-step bullets	console.FormatListItemStderr
trial_confirmation.go	220–222	fmt.Fprintln(os.Stderr, "") blank lines	Keep — structural spacing is fine
org_runner.go	87–103	fmt.Fprintf(os.Stderr, " - ...") bullet points	console.FormatListItemStderr
mcp_list_tools.go	77–136	Raw info strings to stderr	console.FormatInfoMessageStderr
experiments_command.go	765–807	Mixed raw stderr and JSON stdout	JSON to stdout is correct; stderr messages → console.FormatInfoMessageStderr
health_command.go	279–327	fmt.Fprintln(os.Stderr, "") spacing	Structural spacing — acceptable
update_container_pins.go	160–344	Mixed blank lines + " image: reason"	Blank lines acceptable; item lines → console.FormatListItemStderr
logs_format_compact.go	100–221	Structured [tag] value machine-parseable format	Intentional machine format — do not change

Note: logs_format_compact.go deliberately emits machine-parseable [tag] value tokens to stdout/writer — this is correct and should not use console styling.

---

Recommendations

High value, low effort:

1. Wrap org_runner.go and mcp_list_tools.go informational bullets with console.FormatInfoMessageStderr / console.FormatListItemStderr. These are user-facing status lines that would benefit from the i / • prefix and color.

2. Sub-step bullets in trial_confirmation.go (lines 182–183, 199–200): The surrounding steps use console.FormatInfoMessage; the two unformatted " a./b." sub-items are visually inconsistent. Consider console.FormatListItemStderr with a custom indent or a dedicated FormatSubItem helper.

Architectural consideration:

3. Centralise huh form construction behind thin pkg/console wrappers (PromptInput, PromptSelect, PromptMultiSelect, PromptText). This would eliminate the 16 copy-pasted .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()) chains in pkg/cli/ and enforce consistent form behavior automatically.

Already excellent — no action needed:

• Adaptive color system with Windows-safe probe ✅
• TTY detection before all styling ✅
• Huh accessibility mode wired everywhere ✅
• lipgloss/table with TTY-aware StyleFunc ✅
• lipgloss/tree using design-system styles ✅
• lipgloss.Fprintf in logger for color-safe output ✅
• Raw ANSI escape sequences isolated to pkg/console/terminal.go constants ✅

References:

• [§28736316355]

Generated by 💄 Terminal Stylist · 81.4 AIC · ⌖ 11.1 AIC · ⊞ 5.7K · ◷

• expires on Jul 6, 2026, 1:39 AM UTC-08:00

[pelikhan]

/plan

[github-actions[bot]]

🚀 Agentic Commands has started processing this discussion comment

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-06T09:39:34.305Z.

Closed by Workflow