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

[github-actions[bot]]

This report summarizes the console output patterns found across the codebase (/pkg/ and /cmd/), analyzed through the lens of Charmbracelet ecosystem best practices.

---

Overview

The codebase demonstrates strong, consistent adoption of modern terminal UI patterns. The pkg/console and pkg/styles packages serve as a well-designed central styling system, and usage is widespread. A few API gaps between the WASM and non-WASM builds represent the only noteworthy findings.

---

Console Output Summary

Metric	Count
Total console.Format* / console.Render* calls (non-test)	1,500+
Files using console formatting	100+
Direct fmt.Println/Printf to stdout (non-test, non-script)	~25
Huh form instances	104
Huh forms with correct .WithTheme + .WithAccessible	100%

---

✅ What's Working Well

Lipgloss

Adaptive color system — fully compliant

pkg/styles/theme.go defines the entire color palette using compat.AdaptiveColor{Light: ..., Dark: ...}, covering all semantic use cases:

• Status: ColorError, ColorWarning, ColorSuccess, ColorInfo
• Structural: ColorForeground, ColorBackground, ColorBorder
• UI: ColorPurple (commands/paths), ColorYellow (progress), ColorComment (muted text)
• Table: ColorTableAltRow for zebra striping

The Dracula-inspired dark-mode palette and high-contrast light-mode palette meet accessibility contrast requirements.

TTY detection — properly implemented

pkg/console/console.go wraps all styling with:

func applyStyle(style lipgloss.Style, text string) string {
    if isTTY() {
        return style.Render(text)
    }
    return text
}

isTTY() delegates to tty.IsStdoutTerminal(). TTY detection is also applied separately for stderr via tty.IsStderrTerminal() in RenderTitleBox, RenderErrorBox, RenderInfoSection, and RenderComposedSections. No raw ANSI escape codes are present anywhere in the codebase.

Layout features — good use of lipgloss primitives

• lipgloss/table package used in RenderTable() with zebra striping and header/total row differentiation
• lipgloss.JoinVertical() used in RenderComposedSections() for composing multi-section layouts
• lipgloss.DoubleBorder() for title boxes, lipgloss.RoundedBorder() for standard boxes, lipgloss.NormalBorder() for left-side info emphasis
• lipgloss.HiddenBorder() applied to blurred huh form fields — subtle and correct

Output routing — follows Unix conventions

All diagnostic output (info, warnings, errors, progress) goes to stderr via fmt.Fprintln(os.Stderr, ...) with console formatting. Structured output (JSON, hashes, Mermaid graphs, markdown reports) goes to stdout via fmt.Println(...). This allows piping and redirection to work cleanly.

Huh Forms

Consistent theming — 100% compliance

Every huh.NewForm(...) call across all 13 files that use huh applies:

).WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode())

styles.HuhTheme is a huh.ThemeFunc in pkg/styles/huh_theme.go that maps the Dracula-inspired palette to all huh element states: focused/blurred titles, selectors, options, buttons, text input cursor/placeholder/prompt, and error indicators.

Reusable wrappers — good abstraction

pkg/console provides three high-level wrappers:

• ConfirmAction(title, affirmative, negative) — confirm dialogs
• PromptSecretInput(title, description) — password-masked input with TTY guard
• ShowInteractiveList(title, items) — select list with non-TTY text fallback

These wrappers centralize the theme application and accessibility mode check, reducing duplication.

Validation — consistently present

All password/token input forms include inline validation:

Validate(func(s string) error {
    if len(s) < 10 {
        return errors.New("token appears to be too short")
    }
    return stringutil.ValidateCopilotPAT(s)
})

---

⚠️ Issues Found

1. WASM / Non-WASM API Parity Gap

The following functions are defined in console_wasm.go but missing from console.go (the non-WASM build):

Function	WASM	Non-WASM
FormatLocationMessage(msg)	✅ 📁 + msg	❌ missing
FormatCountMessage(msg)	✅ 📊 + msg	❌ missing
FormatListHeader(header)	✅ plain passthrough	❌ missing
RenderTree(root TreeNode)	✅ implemented	❌ missing

Conversely, FormatErrorChain is in console.go but missing from console_wasm.go.

None of these WASM-only functions are currently called from non-WASM code, so there is no active breakage. However, the gap means:

• Adding a call to FormatLocationMessage or FormatCountMessage in CLI code would fail to compile
• The RenderTree function referenced in doc.go is not available in the native build

Recommendation: Add stub implementations of FormatLocationMessage, FormatCountMessage, FormatListHeader, and RenderTree to console.go, and add FormatErrorChain to console_wasm.go.

2. FormatErrorWithSuggestions Location

FormatErrorWithSuggestions (13 call sites) lives in pkg/console/render.go rather than console.go. While this is not a bug, it may cause developers to miss this formatter when looking at console.go.

Recommendation: Add a comment at the top of console.go pointing to the additional formatters in render.go.

3. Markdown Render Files Use Raw fmt (Intentional)

audit_cross_run_render.go and audit_diff_render.go output markdown table syntax via fmt.Printf("| col | col |\n", ...) to stdout. This is the correct pattern for piped/structured markdown output and follows Unix conventions. However, these files have no TTY check — they always emit raw markdown even in a terminal.

Recommendation: Consider adding a "pretty" output path for TTY mode using console.RenderTable(), similar to how renderAuditDiffPretty wraps the same data with console-formatted stderr output.

---

Recommendations Summary

Priority	Finding	Action
Medium	WASM/non-WASM API gap (FormatLocationMessage, FormatCountMessage, FormatListHeader, RenderTree)	Add missing stubs to console.go; add FormatErrorChain to console_wasm.go
Low	FormatErrorWithSuggestions in render.go not obvious	Add cross-reference comment in console.go
Low	Markdown render functions always emit raw markdown in TTY	Consider TTY-aware pretty path using console.RenderTable()

---

References:

• §24342271882

Generated by Terminal Stylist · ● 1.8M · ◷

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

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #26207.