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

[github-actions[bot]]

Overview

Scope: 1,926 non-test Go files under pkg/ (_test.go and testdata/ excluded). This analysis is read-only: no code was changed and no repository tests were run. Console output is mostly centralised: 1,883 of 2,702 terminal-directed fmt calls (70%) go through pkg/console. The main gap is 819 raw calls (705 to stderr), concentrated in pkg/cli.

Key metrics

Metric	Value
Terminal-directed fmt calls (Print*, or Fprint* to os.Stdout or os.Stderr)	2,702
Routed through pkg/console	1,883 (70%)
Raw (no console.* in the call)	819 (705 stderr, 114 stdout)
Raw calls by package	pkg/cli 760, pkg/workflow 54, pkg/console 4, pkg/actionpins 1
Files with raw terminal calls	117
Stream mismatches in direct writes	0
Hard-coded hex colours outside pkg/styles	0

Lipgloss and Huh usage

• Lipgloss v2 (charm.land/lipgloss/v2): 12 non-test files import it. Colours come from a shared adaptive light and dark palette in pkg/styles/theme.go. Direct lipgloss.NewStyle() calls outside pkg/console and pkg/styles number 9: 6 in the TUI view (pkg/cli/work_command_tui_view.go), layout-only padding in pkg/cli/engine_secrets.go and pkg/cli/compile_schedule_calendar.go, and the logger palette in pkg/logger/logger.go. These look reasonable.
• Huh v2 (charm.land/huh/v2): 60 huh.New* calls (fields and options) in pkg/cli, all wrapped by console.NewConfirmForm, NewInputForm, NewSelectForm or NewForm. The only huh.NewForm call (pkg/console/prompt_form.go) applies styles.HuhTheme and WithAccessible(IsAccessibleMode()). PromptForm.Run and RunWithContext check that stdin and stderr are terminals first. This is a strong pattern.

Findings

1. Raw stderr text bypasses formatters (highest impact)

Instructional lines are unstyled, and commands are not visually separated from prose.

Bad:

fmt.Fprintln(os.Stderr, "Please run the following command:")

Good:

fmt.Fprintln(os.Stderr, console.FormatInfoMessageStderr("Run the following command:"))
fmt.Fprintln(os.Stderr, console.FormatCommandMessageStderr(command))

Hot spots: pkg/cli/preconditions.go, pkg/cli/engine_secrets.go, pkg/cli/add_interactive_auth.go, pkg/cli/add_interactive_engine.go and pkg/cli/experiments_analyze_statistics.go. Eight raw calls align labels by hand (%-Ns), and four build separators with strings.Repeat. Where the output is human-facing, console.RenderStruct or console.FormatSectionHeader would replace them.

2. Inconsistent warning glyph and hard-coded prefixes

• Formatters use ✓, ✗, ⚠ and i, each followed by one space.
• The emoji form ⚠️ (with the VS16 selector and two spaces) appears 17 times. The plain ⚠ glyph appears 12 times. Terminals render the two with different widths (example: pkg/cli/deps_report.go).
• Hard-coded prefixes bypass the formatter: Warning: in pkg/workflow/cache_steps.go and pkg/workflow/push_to_pull_request_branch.go, and Note: in pkg/cli/preconditions.go.
• Emoji status markers appear in raw stderr output, for example ✅ **Status:** in pkg/cli/mcp_inspect_mcp.go.

3. Markdown syntax written to stderr

Thirteen raw stderr lines in pkg/cli/mcp_inspect_mcp.go (for example 📝 **Description:**) contain Markdown bold markers. In a terminal the asterisks show literally. If the output is meant for Markdown consumers, send it to stdout. Otherwise, use styled labels.

4. Formatters wrap printf format strings (fragile)

23 call sites in pkg/cli/trial_confirmation.go and pkg/cli/run_push.go pass a formatter output as the format argument:

fmt.Fprintf(os.Stderr, console.FormatInfoMessageStderr("  %d. Execute %s"), stepNum, workflowName)

This works today because the formatter only adds a prefix and ANSI styling. However, the format argument is not a constant, so go vet cannot check it, and any formatter that transforms its input would break the verbs. Format first, then style: console.FormatInfoMessageStderr(fmt.Sprintf(...)).

5. Banner styled for the wrong stream

pkg/console/banner.go: FormatBanner() uses applyStyle, which checks the stdout TTY state, but PrintBanner() writes to stderr. If stdout is piped and stderr is a terminal, the banner loses its colour. Leaked escape codes are unlikely, because colorwriter.Stderr() strips ANSI when stderr is not a terminal. This comes from code reading and was not run. Fix: add FormatBannerStderr backed by applyStderrStyle.

6. NO_COLOR also enables accessible prompts

IsAccessibleMode() returns true when NO_COLOR is set, and console.NewForm passes that value to WithAccessible. Users who disable colour therefore also get the Huh accessible (line-based) prompt mode. This may be intended, but it couples two separate preferences. Review it.

What works well

• Formatter pairs by destination: default formatters check the stderr TTY state, and *Stdout variants check the stdout TTY state. Direct writes show no mismatches.
• pkg/linters/consolestderr enforces destination-aware formatting for direct standard-stream writes, and it is registered.
• 1,751 fmt.Fprintln(os.Stderr, console.*) calls use the console package correctly.
• TTY gating before prompts, NO_COLOR and TERM=dumb handling, and no hard-coded hex colours outside pkg/styles.
• Raw stdout output (114 calls, mostly Markdown and JSON reports in pkg/cli) looks deliberate and is not flagged.

Top files by raw terminal calls

Raw calls	File
89	pkg/cli/audit_diff_render.go (partly stdout Markdown report)
80	pkg/cli/audit_report_render.go (partly stdout Markdown report)
64	pkg/cli/mcp_inspect_mcp.go
47	pkg/cli/experiments_analyze_statistics.go
27	pkg/cli/preconditions.go
26	pkg/cli/audit_cross_run_render.go
24	pkg/cli/engine_secrets.go
21	pkg/cli/deps_report.go
21	pkg/cli/shell_completion.go
20	pkg/cli/add_interactive_orchestrator.go
20	pkg/cli/copilot_setup.go

Recommendations (priority order)

1. Route raw stderr status and instructional text in pkg/cli through console helpers, starting with preconditions.go, engine_secrets.go and the add_interactive_*.go files.
2. Standardise the warning glyph on ⚠ (replace the 17 ⚠️ sites), and replace hard-coded Warning: and Note: prefixes with formatters.
3. Move the Markdown bold markers out of stderr in mcp_inspect_mcp.go, or send that output to stdout.
4. Format printf arguments before applying the console formatter at the 23 wrapped call sites.
5. Add FormatBannerStderr so the banner matches its destination.
6. Decide whether NO_COLOR should imply accessible prompts, and document the decision.
7. Consider a consolestderr-style analyzer that flags raw fmt.Fprint*(os.Stderr, "literal") calls in pkg/cli, with (nolint/redacted) for intentional cases. This would stop the raw backlog from growing.

Scope and limitations

• _test.go files and testdata/ directories are excluded. Counts come from a Go AST scan plus grep. Serena was used for project activation and reference lookups.
• Lipgloss and Huh are imported from charm.land/..., not github.com/charmbracelet/....
• Raw-call counts include deliberate report output, so they overstate the number of defects.

References: §42784303186

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

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

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #76814.