[terminal-stylist] Terminal Stylist: console output consistency review (pkg/)

[github-actions[bot]]

Overview

Scanned all 1,988 non-test .go files under pkg/, focusing on console, Lipgloss, and Huh usage. This was analysis only; no code was changed.

The design holds up. Stream routing is consistent, colors adapt to light and dark backgrounds, and interactive prompts check for a TTY. Four gaps matter most:

1. 581 stderr writes are plain text with no styling helper.
2. 7 call sites print a double glyph, such as i ✓ Agent file exists.
3. Two full-screen TUIs ignore accessible mode, which spinners and forms honor.
4. Two names exist for the same stderr function, FormatInfoMessage and FormatInfoMessageStderr, and call sites use both.

Key metrics

Metric	Value
Non-test Go files under pkg/	1,988
Direct stderr writes (excluding pkg/console and linter fixtures)	2,562
...calling a console helper	1,861
...via formatCompilerMessage (styled)	38
...blank-line spacers	82
...plain text, no styling helper	581
Direct stdout writes (same scope)	123 (9 via console, 23 blank, 91 plain, mostly JSON or Markdown)
Stream or formatter mismatches	0
Double-glyph call sites	7
Files importing lipgloss/v2, huh/v2, bubbletea/v2	9, 17, 5
RenderTable / RenderTableStdout call sites	27 / 6
Hand-aligned %-Ns table lines	9 (4 files)

Findings by library and pattern

Library or area	Status	Key finding
Lipgloss	Good	Adaptive palettes, width-aware padding. Remaining: hand-aligned tables and hand-drawn separators.
Huh	Good	Forms check TTY, use the shared theme, and honor accessible mode. NO_COLOR also triggers accessible prompts.
Bubble Tea	Gap	Two full-screen TUIs do not check accessible mode.
Console formatting	Gap	7 double glyphs, 581 plain stderr writes, duplicate alias names.

Console formatting

Double glyphs. FormatInfoMessage already prefixes i , so a message starting with ✓ renders i ✓ .... Switch these to the success helper and drop the glyph:

• pkg/workflow/agent_validation.go:109 and :449: use FormatSuccessMessageStderr
• pkg/workflow/pip_validation.go:110 and :268: use FormatSuccessMessage
• pkg/workflow/npm_validation.go:102: use FormatSuccessMessage
• pkg/workflow/repository_features_validation.go:285 and :289: use FormatSuccessMessage

Plain-text stderr writes (581). Examples:

• pkg/workflow/cache_steps.go:24 and pkg/workflow/push_to_pull_request_branch.go:128 hand-write a Warning: prefix. Use FormatWarningMessageStderr.
• pkg/cli/preconditions.go:93 and :145 hand-write a Note: prefix. Use FormatInfoMessageStderr.
• pkg/cli/deps_report.go:177 hard-codes a warning emoji with extra spaces. Use FormatWarningMessageStderr.
• pkg/workflow/side_repo_maintenance.go:218 and :237 prepend a stray space. Use a console helper.
• pkg/workflow/claude_logs.go:144 to :155 are verbose-gated raw fmt.Fprintf calls. console.LogVerbose would keep them consistent.

Alias naming. pkg/console/destination_aliases.go defines nine *Stderr functions that only call the unsuffixed versions. Serena reference lookup shows bare FormatInfoMessage referenced from 692 non-test symbols in 153 files, and FormatInfoMessageStderr from 76 in 28. Both mean the same thing, so readers cannot tell which calls are stream-aware. Recommendation: use the bare names for stderr, since *Stdout is the explicit exception, and deprecate the aliases in a follow-up.

Positive. The *Stdout/*Stderr routing is documented in pkg/console/README.md and matches the code. My scan found zero mismatches.

Lipgloss and color

• Adaptive color is in place. pkg/styles/theme.go has light and dark palettes, detects background at startup on non-Windows, and HuhTheme uses lipgloss.LightDark.
• Hand-aligned tables (9 lines). %-Ns counts runes, not display cells, so wide glyphs misalign. experiments_analyze_statistics.go and audit_cross_run_render.go are the main cases. pkg/cli/engine_secrets.go:798 to :832 already uses lipgloss.Width, which is the model to follow. Also consider console.RenderTable.
• Hand-drawn separators (4). strings.Repeat with box-drawing characters at audit_diff_render.go:52, experiments_analyze_statistics.go:806 and :821, and actionlint.go:123. A small console helper would keep them consistent.
• Hard-coded glyphs in 37 non-console files. Many are generated CI echo strings, which is fine. CLI-facing ones should use helpers, such as pkg/cli/compile_stats.go:327.
• Raw ANSI. pkg/console/terminal.go documents its ANSI exception. pkg/console/prompt_form.go cursor controls have no such note.
• Misleading parameter name. renderTableWithTTY(..., degradeStdout bool) in pkg/console/console.go receives true from the stderr RenderTable path. The flag controls color degradation, so rename it, e.g. degradeColor. A custom TTYFunc also skips degradation. No production code sets it, so this is latent.
• NO_COLOR parsing. colorwriter.noColorEnabled in pkg/colorwriter/colorprofile_writer.go uses strconv.ParseBool. NO_COLOR=yes therefore enables accessible mode (see Huh) but is not treated as no-color by this explicit check. I did not verify whether colorprofile.Env covers it. Make it use presence semantics, as no-color.org describes.

Huh

• Good. console.NewForm applies the shared theme and accessible mode. PromptForm.Run rejects non-TTY stdin or stderr. ConfirmAction falls back to plain text when only stderr is not a TTY.
• Policy question. console.IsAccessibleMode() treats any non-empty NO_COLOR as accessible mode. pkg/cli/interactive_test.go pins this. The effect is that forms switch to accessible prompts and spinners stop, even though the user only asked for no color. The NO_COLOR policy decision is in the Lipgloss section.

Bubble Tea

• pkg/cli/work_command_tui.go:308 checks only stdin and stdout TTYs. It does not call console.IsAccessibleMode().
• pkg/cli/org_rollout_flags.go:82 checks TTY and CI for --interactive, then runOrgRolloutTUI (pkg/cli/org_rollout_tui.go:271) runs even when TERM=dumb or ACCESSIBLE is set. runOrgRolloutPlain already exists and could serve as the accessible fallback.
• Spinners (pkg/console/spinner.go:142 to :146) already honor accessible mode.
• Recommendation: route both TUIs to the plain path, or return an error with a hint, when IsAccessibleMode() is true.

Method and limitations

• Serena: project activated (go, typescript, and bash language servers active). Used get_symbols_overview on pkg/styles/theme.go and find_referencing_symbols for alias counts.
• Stream counts come from a balanced-parenthesis scan of fmt.Fprint*(os.Stderr or os.Stdout, ...) in non-test files. Excluded: pkg/console, pkg/linters fixtures, and testdata.
• The repo consolestderr analyzer (cmd/linters) could not be built. The sandbox cannot reach the Go module proxy and the repo has no vendor directory. I did not work around this, so the zero-mismatch result comes from my scan, not the analyzer.
• Not verified: lipgloss HasDarkBackground behavior when stdin or stderr is not a terminal (init-time probe in pkg/styles/theme.go), and colorprofile.Env handling of NO_COLOR. Module sources are not cached locally.

Next actions

1. Fix the 7 double-glyph call sites (small, low-risk change).
2. Route Warning:, Note:, and emoji-prefixed raw writes through console helpers, starting with pkg/workflow/cache_steps.go and pkg/cli/preconditions.go.
3. Add accessible-mode routing to work tui and org rollout --interactive.
4. Decide the NO_COLOR policy, then align noColorEnabled with it.
5. Pick one stderr name and deprecate the *Stderr aliases.

References: §43184716859

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

• expires on Nov 13, 2026, 12:51 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #77398.