[terminal-stylist] Terminal Stylist: console output consistency analysis (pkg/, non-test Go)

[github-actions[bot]]

Summary

Analyzed 1,696 non-test .go files under pkg/ (150 packages; _test.go files and testdata/ excluded). The central pkg/console package is in good shape: TTY-gated helpers, adaptive colors shared by Lipgloss and huh, a color-profile writer, and one themed, accessibility-aware wrapper that every interactive form goes through. The problems sit at the edges. A few styled outputs skip the color-profile writer, the progress bar checks the wrong stream, and status glyphs are doubled or inconsistent. Findings 1 to 5 change what users see in a terminal.

Key metrics

Metric	Value
Stderr writes (fmt.Fprint*(os.Stderr, ...))	2,581 (1,867 via console.*, 72%)
Stdout writes	123 (9 via console.*; sampled output is data and reports)
Raw fmt.Print* in production code	0 (the 3 matches are in a doc comment in pkg/styles/theme.go)
Files that build huh forms via console.New*Form	17; no raw huh.NewForm outside pkg/console
pkg/workflow direct os.Stderr writes	169 across 67 files (116 via console.*)
*Stderr-suffixed console calls vs unsuffixed Format*/Render* calls	180 vs 1,748
Call sites that embed a glyph under a helper that already adds one	12

Patterns to keep

• pkg/console/console.go: applyStderrStyle routes through colorwriter.Degrade, so NO_COLOR, COLORTERM, and TERM apply to helper output.
• pkg/console/prompt_form.go: NewForm applies styles.HuhTheme and WithAccessible(IsAccessibleMode()), and Run requires stdin and stderr to be TTYs. pkg/cli builds its fields with huh.New* and wraps them in these constructors, which is the right layering.
• pkg/console/spinner.go:143: the TTY gate checks stderr, which is where the spinner draws. Only one spinner can own the terminal at a time.
• pkg/logger/logger.go:129,142: debug lines go through lipgloss.Fprintf(stderrWriter(), ...).
• pkg/cli/engine_secrets.go:798-832: column widths use lipgloss.Width, which is display-width aware.

Findings

1. Styled output bypasses the color-profile writer (medium). console.RenderErrorBox returns pre-rendered ANSI when stderr is a TTY (pkg/console/console.go:525). Three callers print those lines with raw fmt.Fprintln(os.Stderr, line): pkg/cli/deps_security.go:96-98, pkg/cli/mcp_inspect_mcp.go:68-70, and pkg/cli/mcp_inspect_mcp.go:80-82. The progress bar has the same problem: pkg/cli/logs_run_download_concurrent.go:102 writes pb.Update(0) (bubbles ViewAs output) directly to os.Stderr, so NO_COLOR is ignored there too.
Fix: add a console helper that writes lines through stderrWriter(), or send these boxes through RenderComposedSections.

2. Progress bar checks stdout but draws on stderr (medium). pkg/console/progress.go:69 sets ttyCheck: isTTY, which is tty.IsStdoutTerminal(). The bar is written to stderr. Two results:

• stdout is a terminal and stderr is redirected: animated ANSI is written into the redirected file;
• stdout is piped and stderr is a terminal: the bar falls back to plain text in an interactive session.

Fix: default to tty.IsStderrTerminal(), as NewSpinner does.

3. NO_COLOR also turns on accessibility mode (medium; needs a maintainer decision). IsAccessibleMode() (pkg/console/accessibility.go:15-19) returns true when NO_COLOR is set. That value flows into WithAccessible on every huh form (prompt_form.go:34-36) and disables spinners (spinner.go:144-145). A user who sets NO_COLOR for color reasons gets plain-text prompts and no spinner. The NO_COLOR convention only asks for color to be removed.
Fix: split into ColorDisabled() (NO_COLOR, TERM=dumb) and IsAccessibleMode() (ACCESSIBLE, TERM=dumb). This changes behavior, so it should be confirmed first.

4. Full-screen Bubble Tea TUIs have no accessibility fallback (medium). pkg/cli/work_command_tui.go:308 checks only that stdin and stdout are terminals. pkg/cli/org_rollout_tui.go:271 starts tea.NewProgram with no accessibility check. Spinners and forms honor ACCESSIBLE and TERM=dumb; these TUIs do not. The work TUI already tells automation users to use state --json, and the same guidance could apply when accessible mode is set.

5. Status glyphs are doubled at 12 call sites (medium). The helpers already prepend a glyph: PrintSuccessMessage adds a check mark, PrintInfoMessage and FormatInfoMessage add i, and FormatWarningMessage adds a warning sign (console.go:209-242). Callers add their own on top:

• pkg/cli/mcp_inspect_mcp.go:90: PrintSuccessMessage with a ✅ prefix in the message shows ✓ ✅ Successfully connected...
• pkg/cli/mcp_inspect_mcp.go:621: PrintInfoMessage with a 💡 prefix shows i 💡 To allow blocked tools...
• pkg/workflow/npm_validation.go:102: FormatInfoMessage with a ✓ prefix shows an info marker followed by a success marker.

The full list is in the details block below.

6. Glyph vocabulary is inconsistent and partly double-width (low to medium).

• Success: ✓ (console, mcp_list.go:266) versus ✅ (audit_cross_run_render.go:147,354, mcp_tool_table.go:74).
• Warning: ⚠ versus ⚠️ (U+26A0 followed by U+FE0F; deps_report.go:124,152,177, deps_security.go:230).
• Error: ✗ versus ❌ (mcp_inspect_mcp.go:68,80) versus 🔴 (deps_security.go:96).

✅ and ❌ are double-width. In audit_cross_run_render.go:354-356, one column alternates between ✅ and ⚠, so text after the icon can shift by a cell depending on the terminal.
Fix: define one symbol set in pkg/console (a SymbolOK constant holding the check mark, for example) and use it everywhere.

7. Report renderers mix raw and helper output (low). pkg/cli/audit_report_render.go (83 raw calls), pkg/cli/mcp_inspect_mcp.go (64), and pkg/cli/experiments_analyze_statistics.go (46) write plain text to os.Stderr. Plain text is reasonable for grep-friendly reports, but the convention is undocumented, and single commands mix helper lines with raw lines.
Fix: document the rule, or add a small report writer that these renderers share.

8. The library layer writes to stderr directly (low). pkg/workflow has 169 direct os.Stderr writes. Diagnostics cannot be captured per compiler instance without swapping process-global state. Fix: inject an io.Writer for diagnostics on the compiler. The console.stderr hook is package-global and exists only for tests.

9. Console API surface (low). pkg/console exports 288 symbols. Unsuffixed helpers write to stderr, *Stdout variants write to stdout, and destination_aliases.go adds 9 *Stderr aliases that forward to the unsuffixed names. Some helpers have only one variant (FormatTableHeaderStderr, FormatErrorTextStderr). Fix: pick one naming scheme and mark the aliases // Deprecated:.

10. A doc example teaches the bypass pattern (low). pkg/styles/theme.go:40-47 shows fmt.Println(styles.Error.Render(...)), which skips TTY detection and degradation. Use console.FormatErrorMessage or console.PrintErrorMessage in the example.

Verify, not confirmed as a bug: IsCancelled is checked in only 3 files that run forms (add_interactive_workflow.go, engine_secrets.go, run_interactive.go). Confirm that Esc or Ctrl-C in other prompts ends as a clean cancellation rather than an error line.

Suggested order

1. Findings 1 and 2: small, local stream and degradation fixes.
2. Findings 5 and 6: one symbol set, mechanical changes.
3. Finding 3: needs a decision on NO_COLOR semantics.
4. Finding 4: accessibility guard for the TUIs.
5. Findings 7 to 10: cleanup.

Scope and method

Static analysis: grep counts, file reads, and Serena find_referencing_symbols on RenderErrorBox and IsAccessibleMode. The code was not built or run, so the terminal behavior described above comes from reading the code, not from observing output.

All 12 doubled-glyph call sites

Location	Helper	Rendered result
pkg/workflow/pip_validation.go:110	FormatInfoMessage	info marker, then check mark, then message
pkg/workflow/pip_validation.go:257	FormatInfoMessage	info marker, then check mark, then message
pkg/workflow/agent_validation.go:449	FormatInfoMessageStderr	info marker, then check mark, then message
pkg/workflow/npm_validation.go:102	FormatInfoMessage	info marker, then check mark, then message
pkg/cli/mcp_validation.go:171	FormatWarningMessage	warning sign, then cross mark and secret name
pkg/cli/compile_stats.go:204	FormatInfoMessageStderr	info marker, then light bulb emoji
pkg/cli/generate_action_metadata_command.go:92	FormatInfoMessage	info marker, then package emoji
pkg/cli/actions_build_command.go:205	FormatInfoMessage	info marker, then package emoji
pkg/cli/mcp_inspect_mcp.go:90	PrintSuccessMessage	check mark, then emoji check mark
pkg/cli/mcp_inspect_mcp.go:621	PrintInfoMessage	info marker, then light bulb emoji
pkg/cli/mcp_inspect_mcp.go:655	PrintInfoMessage	info marker, then light bulb emoji
pkg/cli/mcp_inspect_mcp.go:673	PrintSuccessMessage	check mark, then emoji check mark

pkg/cli/compile_stats.go:327 (FormatErrorTextStderr with a cross mark) is excluded: that helper adds no glyph, so the result is not doubled.

References: §42587486070

Generated by 💄 Terminal Stylist · pi · routed: haiku55 xhigh · ~17 AIC · ⌖ ~2 AIC · ⊞ 4.7K · ◷

• expires on Nov 10, 2026, 12:50 AM UTC-08:00