[terminal-stylist] Terminal output consistency and accessibility audit (Go)

[github-actions[bot]]

Overview

The Go console layer is mature and generally follows Charmbracelet best practices: styling is centralized, TTY-aware, color-profile degradation is supported, Huh forms share one adaptive theme, and raw ANSI is confined to terminal-control utilities. The main opportunities are API consistency, keeping styling out of error values, removing duplicated visual markers, and adding an accessible path for the Work Queue TUI.

Scan metrics

• Scanned 1,791 .go files, excluding _test.go; 1,771 were under pkg/.
• Production-oriented pkg/ view (excluding linter testdata fixtures): 1,589 files.
• 293 production files use the console package, 14 use Lipgloss, and 18 use Huh.
• Found 3,459 fmt.Print*/fmt.Fprint*-style calls in production pkg/; 2,665 directly target standard streams.
• 1,862 standard-stream calls wrap a console.Format* result, while the higher-level console.Print* helpers are used only 78 times.
• Raw escape literals occur in only 4 production files and are appropriately limited to cursor control or ANSI parsing/stripping.
• Serena diagnostics were clean for the central console, interactive form, and Work Queue TUI files examined.

Priority findings

1. Do not embed terminal styling in returned errors. pkg/cli/env_command.go:214 returns errors.New(console.FormatErrorMessage(err.Error())). This can place prefixes and ANSI styling inside an error value before the final output boundary is known. Return the original/plain wrapped error and style it once at the command’s top-level renderer.
2. Consolidate human-facing stderr writes behind the console API. The current dominant pattern is fmt.Fprintln(os.Stderr, console.Format...()), despite pkg/console/print.go already exposing PrintInfoMessage, PrintWarningMessage, and related helpers. A writer-aware console renderer would reduce repeated stream selection, newline handling, and accidental stdout/stderr style mismatches while preserving raw writers for JSON, Markdown, completion, and other machine output.
3. Remove duplicate semantic icons. Console formatters already add ✓, i, ⚠, or ✗, but at least 19 formatted messages add another emoji. Examples include console.PrintSuccessMessage("✅ Successfully connected...") and emoji-prefixed section/info messages in pkg/cli/mcp_inspect_mcp.go. This produces output such as ✓ ✅ ... and adds noise in accessible/plain modes.
4. Add an accessible mode for the Work Queue TUI. Huh forms correctly use console.IsAccessibleMode() and .WithAccessible(...), but workTUICommand only checks stdin/stdout TTYs. Its view depends on alternate-screen rendering, borders, reverse-video focus, compact symbols, and a dense persistent footer. Respect ACCESSIBLE, TERM=dumb, and NO_COLOR; provide a linear non-alt-screen presentation or route users to equivalent list/inspect/action commands.

What is already working well

• pkg/console/console.go strips styling when output is not a TTY and degrades rendered color through the detected terminal profile.
• pkg/styles/theme.go provides a shared light/dark palette and reusable semantic styles instead of scattering hardcoded colors.
• pkg/console/console.go uses lipgloss/table, bounded widths, alternate rows, totals, and shared borders rather than manual terminal tables.
• pkg/styles/huh_theme.go maps the shared palette through lipgloss.LightDark, including focused, blurred, validation, selection, and input states.
• pkg/console/prompt_form.go applies the theme and accessible mode centrally; Huh inputs use validation and secret inputs use password echo mode.
• Non-TTY workflow creation has an explicit plain-text fallback instead of forcing a full-screen form into redirected output.
• The few raw ANSI sequences in pkg/console/terminal.go and pkg/console/prompt_form.go are for operations Lipgloss does not model; parsing/stripping is centralized in pkg/stringutil/ansi.go.

Representative consistency opportunities

• pkg/cli/mcp_inspect_mcp.go: mixes console.Print* with extra emoji markers and substantial raw formatted output. Standardize section labels and let semantic console styles own status markers.
• pkg/cli/interactive.go: TTY mode uses well-structured Huh groups and validation; non-TTY prompts duplicate option definitions and formatting. Extract shared option models so labels, defaults, and validation cannot drift between modes.
• pkg/cli/work_command_tui_view.go: uses local border/reverse styles rather than shared pkg/styles tokens. Reuse shared border/focus styles and ensure focus is conveyed by text as well as reverse video.
• Large report renderers such as audit_diff_render.go intentionally emit raw Markdown to stdout and styled terminal tables to stderr. Keep this separation explicit; these machine/report paths should not be mechanically migrated to styled console helpers.

Recommended next actions

1. Fix the styled-error return in pkg/cli/env_command.go and add a lint/check preventing console.Format* inside errors.New or fmt.Errorf.
2. Introduce writer-aware helpers (for example, a console.Printer bound to stderr/stdout) and migrate human-facing diagnostics incrementally; exclude serialized JSON, Markdown, shell completion, and generated content.
3. Remove embedded status emoji from calls to semantic Format*/Print* helpers and document whether section headers may use decorative icons.
4. Add an accessible Work Queue presentation and a focused test matrix covering TTY/non-TTY, NO_COLOR, TERM=dumb, ACCESSIBLE, narrow terminals, and redirected stdout/stderr.
5. Extract shared option definitions for Huh and non-TTY interactive workflow creation.

References:

• §40476570565

Generated by 💄 Terminal Stylist · pi · gpt56 · ~128 AIC · ⌖ ~22 AIC · ⊞ 8.3K · ◷

• expires on Oct 28, 2026, 1:01 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #72620.