[terminal-stylist] Terminal Stylist audit: stream-aware console output and Charmbracelet usage

[github-actions[bot]]

Overview

The terminal UI foundation is strong: pkg/styles centralizes an adaptive Lipgloss palette, pkg/console provides semantic formatters and Huh wrappers, tables use lipgloss/table, and animated components generally gate themselves on TTY/accessibility checks.

The main consistency defect is stream-aware styling. A large amount of text written to stderr is formatted by helpers that inspect stdout. This can suppress styling in an interactive terminal or emit ANSI into redirected stderr, depending on which stream is a TTY.

Scope: all 1,513 non-test Go files were statically scanned, with detailed review focused on the 1,493 files under pkg/. Test files and non-Go files were excluded.

Key metrics and issues

Area	Result
Non-test Go files scanned	1,513
Non-test Go files under pkg/	1,493
pkg/ files with fmt.Print* / fmt.Fprint* calls	364
pkg/ files using console.* calls	278
pkg/ files importing/using Lipgloss	9
pkg/ files importing/using Huh	17
Potential stderr/formatter stream mismatches	1,588 calls in 217 files
Raw ANSI locations	2 console files, for cursor/screen control

1. High: formatters inspect the wrong stream

There are 1,588 direct writes where an stdout-oriented formatter is passed to os.Stderr:

Formatter	Calls	Files
FormatInfoMessage	682	142
FormatWarningMessage	554	165
FormatSuccessMessage	228	89
FormatVerboseMessage	77	30
FormatCommandMessage	17	8
FormatProgressMessage	13	8
FormatSectionHeader	11	4
Other formatters	6	6

Example:

fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Checking status of workflow files"))

FormatInfoMessage calls the stdout TTY detector. If stdout is piped but stderr is interactive, the status loses styling. If stdout is interactive but stderr is redirected, styled bytes can be written into the redirected stream.

Prefer the already available writer-aware path:

console.PrintInfoMessage("Checking status of workflow files")

or, where composition is necessary:

fmt.Fprintln(os.Stderr, console.FormatInfoMessageStderr(message))

This pattern appears broadly in pkg/cli/, including status_command.go, mcp_inspect.go, run_workflow_execution.go, update_workflows.go, and audit/log rendering files.

2. High: two styled trees bypass TTY/color-profile handling

• pkg/cli/mcp_inspect.go:193-228
• pkg/cli/status_command.go:436-460

Both construct lipgloss/tree output with styles.TreeEnumerator and styles.TreeNode, call String(), then write directly to stderr. Unlike console.RenderTable, these paths do not select styles based on the destination TTY and do not pass through colorwriter.Stderr().

Add a console-level tree renderer that accepts the destination stream/TTY policy, or conditionally attach tree styles only when tty.IsStderrTerminal() and write through the color-profile-aware stderr writer.

3. Medium: banner styling checks stdout but writes stderr

pkg/console/banner.go calls FormatBanner(), which uses the stdout-oriented applyStyle, and then writes the result to stderrWriter(). This is the same split-stream defect in a centralized component. Add FormatBannerStderr, or have PrintBanner render through applyStderrStyle directly.

4. Medium: raw user-facing diagnostics remain inconsistent

There are legitimate raw writes for tables, structured reports, subprocess output, JSON, and shell completion. However, several human-facing failures and warnings bypass semantic console formatting, for example:

• pkg/cli/add_interactive_workflow.go:129,246 — raw Status check error / gh workflow list failed
• pkg/cli/mcp_inspect_mcp.go:574,588 — raw schema display errors
• pkg/workflow/cache_steps.go:23 — raw Warning: diagnostic
• pkg/workflow/compiler_orchestrator_engine.go:289,295 — raw uppercase warnings
• pkg/workflow/mcp_renderer.go:111 — raw generation error

Route CLI diagnostics through console.PrintErrorMessage / PrintWarningMessage. For compiler diagnostics, retain the IDE-parseable file:line:column: type: message contract and centralize rendering rather than adding decorative prefixes indiscriminately.

What is working well

Representative files and patterns using the console stack correctly

• pkg/console/console.go — semantic styles, stdout/stderr variants, TTY gating, color-profile degradation, and lipgloss/table integration.
• pkg/styles/theme.go — centralized semantic palette with light/dark adaptive colors and reusable borders/styles.
• pkg/styles/huh_theme.go — one palette shared with Huh via lipgloss.LightDark.
• pkg/console/prompt_form.go — common Huh theme, accessibility mode, dual stdin/stderr TTY checks, and controlled cleanup.
• pkg/console/spinner.go — stderr TTY detection, accessibility-aware animation suppression, and single-spinner coordination.
• pkg/console/progress.go — visual TTY rendering with a plain-text non-TTY fallback.
• pkg/console/terminal.go — raw ANSI is limited to cursor/screen operations that Lipgloss does not model and is guarded by stderr TTY checks.
• pkg/tty/tty.go and pkg/colorwriter/colorprofile_writer.go — clear centralized terminal detection and NO_COLOR/terminal-profile handling.
• pkg/cli/experiments_render.go — correctly supplies TTYFunc: tty.IsStderrTerminal to tables destined for stderr.
• pkg/cli/engine_secrets.go, logs_format_compact.go, logs_report.go, logs_work_queue_render.go, and mcp_inspect_mcp.go have begun adopting the direct console.Print* helpers (72 calls across these five files).
• pkg/cli/work_command_tui_view.go — responsive width/height handling, small-terminal fallback, alternate-screen usage, and keyboard help.

Lipgloss assessment

• Adaptive colors: Good centralized light/dark palette. Avoid new hardcoded color literals outside pkg/styles.
• TTY behavior: Good inside most pkg/console helpers; inconsistent when callers render Lipgloss objects directly or select an stdout formatter for stderr.
• Tables/layout: console.RenderTable is the correct standard. It already handles borders, zebra rows, totals, and destination-specific TTY checks. Prefer it over new hand-aligned tables where output is intended for humans.
• Borders: Central rounded/normal/thick definitions are consistent. The work-queue TUI's ASCII border is appropriate for its deliberately plain full-screen view.
• Responsiveness: The work-queue TUI responds well to terminal dimensions. The progress bar's fixed width of 40 is acceptable but could be clamped to terminal width for narrow terminals.
• Raw ANSI: No broad anti-pattern was found. The sequences in terminal.go and prompt_form.go are cursor-control operations, are documented, and are appropriately TTY-gated.

Huh assessment

All reviewed CLI Huh forms route through console.NewForm, NewInputForm, NewSelectForm, or NewConfirmForm, so they inherit the shared theme and accessible mode. Password input uses EchoModePassword, and the shared form runner rejects non-interactive stdin/stderr combinations.

Opportunities:

1. pkg/console/list.go uses package-level fmt.Scanf in its text fallback, unlike showTextConfirm, which accepts an io.Reader. Accept a reader consistently for testability and predictable input ownership.
2. Separate no color from accessible interaction mode. Currently NO_COLOR enables Huh accessible mode and disables spinners. NO_COLOR necessarily means no color, but does not always mean the user wants a different interaction model. Keep ACCESSIBLE and TERM=dumb as explicit accessibility signals; handle color suppression independently.
3. Continue adding field-level validators where values have real constraints. Do not add validation merely for selects/confirms whose option sets already constrain input.
4. No compelling case was found for converting ordinary non-interactive commands into Huh forms. Preserve scriptability and use Huh only in explicit wizard/interactive flows.

Recommended next actions

1. P0 — Make destination stream explicit. Standardize direct messages on console.Print*; add missing stderr variants or a destination-aware formatter/printer abstraction for composed output.
2. P0 — Add a static check. Flag fmt.Fprint*(os.Stderr, console.FormatX(...)) when FormatX is stdout-oriented, and the inverse for stdout.
3. P1 — Fix direct Lipgloss renderers. Make MCP/status trees and the banner destination-aware and color-profile-aware.
4. P1 — Normalize raw human-facing errors. Start with interactive CLI and compiler warning paths; leave JSON, shell completion, subprocess passthrough, and parseable compiler records plain where required.
5. P2 — Refine Huh fallbacks/accessibility. Inject readers into text fallbacks and decouple NO_COLOR from screen-reader-oriented interaction changes.
6. P2 — Add stream-matrix tests. Cover stdout/stderr independently for (TTY, pipe), (pipe, TTY), NO_COLOR, and TERM=dumb.

Method and limitations

The inventory used a lexical scan of every non-test .go file, followed by targeted source review of pkg/console, pkg/styles, pkg/tty, pkg/colorwriter, direct Lipgloss users, direct Huh users, and representative CLI/compiler output sites. Counts describe source call sites, not runtime execution frequency.

Serena project activation succeeded, but its Go language server could not initialize because the Serena service reported that Go was unavailable in its environment. Semantic symbol/reference queries were therefore unavailable; analysis continued with repository-local source scanning and targeted reads.

References: §37907719497

Generated by 💄 Terminal Stylist · pi · gpt56 · 85 AIC · ⌖ 26.7 AIC · ⊞ 7.3K · ◷

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