[terminal-stylist] Terminal styling audit: stream-aware formatting and console consistency

[github-actions[bot]]

Overview

The Go console layer has a strong modern foundation: centralized semantic styles, adaptive light/dark colors, TTY-aware rendering, a shared accessible Huh wrapper, Lipgloss tables/trees, and Unicode-aware width calculation. The main consistency defect is not missing styling; it is that CLI code frequently formats text with stdout-aware helpers and then writes it to stderr.

Scope: all 1,467 non-test .go files were scanned, including 1,450 under pkg/. Files ending in _test.go and all non-Go files were excluded.

Key metrics and issues

Area	Finding
fmt.Print* / fmt.Fprint* usage	3,677 calls across 370 files
pkg/cli print calls	2,732
Files importing pkg/console	277
Lipgloss v2 importers	10 files
Huh v2 importers	17 files
Manual ANSI locations	3 files, all in appropriate low-level terminal/ANSI utilities
Huh form construction outside the shared wrapper	0
stdout-oriented formatter written to stderr	1,408 same-line occurrences in pkg/cli
Explicit stderr-oriented formatter written to stderr	113 same-line occurrences
Shared console.Print*Message calls	58

Highest-priority issue: calls such as

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

use FormatInfoMessage, which checks stdout TTY state, while the rendered value is sent to stderr. When stdout and stderr are routed differently, color can be omitted from an interactive stderr or emitted based on the wrong stream. Prefer:

console.PrintInfoMessage(message)

or, when a custom writer is required:

fmt.Fprintln(writer, console.FormatInfoMessageStderr(message))

The most affected files include pkg/cli/logs_metrics.go (57), pkg/cli/trial_repository.go (46), pkg/cli/pr_command.go (43), pkg/cli/run_workflow_execution.go (39), pkg/cli/logs_orchestrator_download.go (38), and pkg/cli/dispatch.go (37).

What is working well

• pkg/console/console.go centralizes semantic message styles, checks the correct TTY in its stderr-specific APIs, honors terminal color capabilities, and uses lipgloss/table.
• pkg/styles/theme.go provides a single adaptive light/dark palette and shared border/style definitions.
• pkg/styles/huh_theme.go uses lipgloss.LightDark and gives focused, blurred, navigation, input, validation, and button states a coherent theme.
• pkg/console/prompt_form.go is an effective accessibility boundary: every Huh form is routed through it, accessible mode is enabled centrally, stdin/stderr TTYs are required, context-aware runs are supported, and cancellation can be distinguished from failure.
• pkg/cli/engine_secrets.go, pkg/cli/compile_schedule_calendar.go, and pkg/console/render.go use lipgloss.Width/style widths rather than byte counts for Unicode-safe alignment.
• pkg/cli/mcp_inspect.go and pkg/cli/status_command.go use Lipgloss tree rendering rather than hand-building hierarchy graphics.
• Raw ANSI is confined to pkg/console/terminal.go, pkg/console/prompt_form.go, and pkg/stringutil/ansi.go. Cursor/screen control is TTY-gated where emitted and is a reasonable exception because Lipgloss is a styling/layout library, not a terminal-control API.

Detailed improvement opportunities

1. Standardize stream-aware message emission

Migrate stderr output to console.PrintInfoMessage, PrintWarningMessage, PrintSuccessMessage, PrintErrorMessage, PrintCommandMessage, and PrintSectionHeader. Where output must target an injected writer, use the corresponding *Stderr formatter.

A small static check should reject fmt.Fprint*(os.Stderr, console.Format*Message(...)) whenever a stderr-specific formatter exists. This prevents the current mismatch from returning.

2. Avoid duplicated semantic markers

The console formatters already add i, ✓, ⚠, ✗, or ▸. Several call sites add another icon or severity label inside the message, producing visually noisy combinations. Examples occur in:

• pkg/cli/actions_build_command.go ("✅ Validating...", "✨ All actions valid", "⚠ Warning: ...")
• pkg/cli/generate_action_metadata_command.go ("✗ Failed..." passed to the error formatter)
• pkg/cli/deps_outdated.go, pkg/cli/deps_report.go, and pkg/cli/deps_security.go ("✅ ..." passed to the success formatter)
• pkg/cli/project_command.go and pkg/cli/upgrade_command.go ("✓ ..." passed to the success formatter)

Pass plain message text to semantic formatters and let the console package own the marker.

3. Replace manual tables and fixed-width separators

Several human-facing reports use %‐Ns padding and fixed 60/62/66-column separators. These do not account for wide Unicode glyphs and do not adapt to narrow terminals. Candidates include:

• pkg/cli/audit_cross_run_render.go
• pkg/cli/audit_cross_run_clusters_render.go
• pkg/cli/outcomes_command.go
• pkg/cli/experiments_analyze_statistics.go
• pkg/cli/remove_command.go
• pkg/cli/actionlint.go
• pkg/cli/audit_diff_render.go

Use the existing console.RenderTable for tabular data and Lipgloss width/layout primitives for report sections. Keep plain, ANSI-free fallback output for pipes and redirected streams.

4. Consolidate interactive explanatory output

The Huh implementation itself is sound, but several interactive flows alternate themed forms with raw fmt.Fprintln(os.Stderr, ...) paragraphs and hand-built separators. pkg/cli/add_interactive_auth.go, pkg/cli/add_interactive_git.go, pkg/cli/add_interactive_orchestrator.go, and pkg/cli/add_interactive_workflow.go would benefit from shared note/instruction renderers (RenderInfoSection, section headers, command formatting, and list helpers).

Continue using field-level validation for structured values and secrets. For dynamically generated workflow inputs in pkg/cli/run_interactive.go, ensure workflow constraints are surfaced through Huh validation rather than only after submission. Preserve RunWithContext and console.IsCancelled handling.

5. Separate human UI from machine output

Not every raw fmt call should be styled. Shell completion, TSV/JSON, generated source, subprocess passthrough, and builder output should remain deterministic and ANSI-free. Standardization should target user-facing stderr paths, not blanket-replace all 3,677 print calls.

Recommended next actions

1. P0: Migrate stdout-aware formatters used on stderr, starting with the six highest-volume files listed above; add a focused static check.
2. P1: Remove embedded status icons/labels from messages passed to semantic formatters.
3. P1: Convert the audit, outcomes, and experiment report tables to console.RenderTable or Unicode-aware Lipgloss layout.
4. P2: Add shared note/instruction/list helpers for interactive flows and retain the existing centralized Huh accessibility/TTY boundary.
5. P2: Document which commands are human-facing versus machine-readable so future styling does not introduce ANSI into pipelines.

References:

• §37752853124

Generated by 💄 Terminal Stylist · pi · gpt56 · 80.6 AIC · ⌖ 23.1 AIC · ⊞ 7.3K · ◷

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

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-10-09T09:00:52.911Z.

Closed by Workflow