[terminal-stylist] Terminal output consistency audit: sink-aware styling and accessibility

[github-actions[bot]]

Overview

A static scan covered all 1,516 tracked non-test Go files (*_test.go excluded), with 1,496 files under pkg/ as the primary review area. The codebase already has a strong terminal foundation: centralized semantic styles, adaptive light/dark colors, TTY-aware rendering, color-profile degradation, a reusable Lipgloss table renderer, and accessibility-aware Huh wrappers.

The main consistency defect is output-sink mismatch. Most user-facing status messages are written to stderr but formatted by helpers that detect stdout. This can suppress color when stdout is redirected while stderr is interactive, or emit ANSI into redirected stderr when stdout remains a TTY.

Metric	Result
Non-test Go files scanned	1,516
Non-test Go files in pkg/	1,496
fmt.Print*/fmt.Fprint* references in pkg/	3,552 across 368 files
console.* references in pkg/	2,222
Files using Lipgloss directly	9
Files using Huh directly	18
Calls through console.New*Form	23 across 12 CLI files
Direct stderr table renders	22
Table configs explicitly selecting stderr TTY detection	2

Counts are lexical references, not a claim that every fmt call is terminal UI: many correctly build Markdown, JSON, YAML, or buffered reports.

Key issues and recommendations

1. High — make formatting destination-aware by construction. Examples such as pkg/cli/audit_diff_render.go, pkg/cli/logs_metrics.go, pkg/cli/dispatch.go, pkg/cli/run_workflow_execution.go, and many add/update commands write console.FormatInfoMessage, FormatWarningMessage, FormatSuccessMessage, or FormatErrorMessage to os.Stderr. Those non-Stderr helpers inspect stdout.

   • Prefer console.PrintInfoMessage, PrintWarningMessage, etc., or the existing *Stderr formatters.
   • Better: expose a small console.Printer bound to an io.Writer and its TTY detector so callers cannot accidentally pair a formatter with the wrong stream.
   • Fix pkg/console/print.go itself: PrintErrorMessage currently delegates to FormatErrorMessage, for which no FormatErrorMessageStderr counterpart exists.

2. High — bind tables to their destination. console.RenderTable defaults to stdout detection. There are 22 direct renders to stderr, while only the two configs in pkg/cli/experiments_render.go set TTYFunc: tty.IsStderrTerminal. Representative affected files are pkg/cli/audit_diff_render.go (12 calls), compile_stats.go, deps_outdated.go, domains_command.go, mcp_list.go, mcp_registry_list.go, and outcomes_history.go.

   • Add RenderTableTo(io.Writer, TableConfig) or require a destination/profile in TableConfig.
   • Avoid optional TTYFunc at call sites; infer the correct profile from a printer/render target.
   • This also centralizes width handling and leaves room for responsive column truncation on narrow terminals.

3. Medium — finish migration from raw status output. Raw fmt.Fprint* is appropriate for machine-readable stdout and report builders, but status/error lines should consistently use semantic console methods. Concentrated candidates include pkg/cli/audit_report_render.go, mcp_inspect_mcp.go, experiments_analyze_statistics.go, preconditions.go, audit_cross_run_render.go, engine_secrets.go, deps_report.go, and add_interactive_workflow.go.

   • Preserve plain fmt for JSON, Markdown, shell completion, and pass-through subprocess output.
   • Standardize error grammar: avoid duplicated prefixes such as ⚠ Warning: ...; the formatter already communicates severity.
   • Keep returned Go errors plain and style only at the final presentation boundary. Several paths wrap console.FormatErrorMessage(...) in errors.New(...), which risks ANSI leaking into logs or later wrapping.

4. Medium — add an accessible fallback for the full-screen work queue. pkg/cli/work_command_tui_view.go has good responsive sizing, clipping, ASCII borders, explicit keyboard help, and an alternate screen, but it does not consult console.IsAccessibleMode() and has no visible non-alt-screen/screen-reader mode.

   • Provide a linear text/list mode when ACCESSIBLE, NO_COLOR, or TERM=dumb is active.
   • Reuse centralized semantic styles rather than isolated Reverse(true)/ad hoc frames when adding status emphasis.

5. Low — tighten interactive preflight and cancellation handling. The shared Huh wrapper correctly requires both stdin and stderr TTYs, applies the project theme, and enables accessible mode. Some callers (for example pkg/cli/interactive.go and pkg/cli/run_interactive.go) preflight only stderr before choosing interactive versus fallback mode. If stdin is piped but stderr is a TTY, the fallback is skipped and the form returns an availability error.

   • Check both streams before selecting the Huh path.
   • Use console.IsCancelled consistently so cancellation is not reported as a generic failure.
   • Retain field validation already present for workflow names, intent, required inputs, and credentials.

What is already working well

• pkg/styles/theme.go centralizes semantic styles and adaptive light/dark palette values.
• pkg/styles/huh_theme.go maps that same palette into Huh with lipgloss.LightDark, avoiding a second color system.
• pkg/console/console.go degrades colors according to terminal capabilities and NO_COLOR, and uses lipgloss/table rather than hand-built display tables.
• pkg/console/prompt_form.go centralizes Huh theming, accessibility, TTY requirements, and cleanup.
• pkg/console/spinner.go disables animation outside a TTY and in accessible mode, and prevents concurrent spinner corruption.
• pkg/cli/compile_schedule_calendar.go is a strong sink-aware example: stderr detection, accessible plain-text fallback, centralized styles, and profile degradation are all explicit.
• Raw terminal-control escapes are localized to pkg/console/prompt_form.go and pkg/console/terminal.go; they are used for cursor/screen operations rather than hard-coded colors and are guarded by terminal checks.

Pattern examples

Preferred stderr pattern

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

Or, once writer-bound output is adopted:

console.Stderr().Warning(message)

Current mismatch

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

FormatWarningMessage uses stdout TTY detection even though the rendered value is sent to stderr.

Preferred interactive construction

form := console.NewSelectForm(
    huh.NewSelect[string]().
        Title("Select a workflow").
        Options(options...).
        Value(&selected),
)

This preserves the shared theme and accessible-mode policy; direct huh.NewForm construction should remain inside pkg/console.

Representative file categorization

Good centralized implementations / exemplars

• pkg/console/console.go
• pkg/console/prompt_form.go
• pkg/console/spinner.go
• pkg/console/accessibility.go
• pkg/styles/theme.go
• pkg/styles/huh_theme.go
• pkg/cli/compile_schedule_calendar.go
• stderr-aware compile paths such as pkg/cli/compile_file_operations.go, compile_pipeline.go, and compile_post_processing.go

Highest-value migration targets

• pkg/cli/audit_diff_render.go
• pkg/cli/logs_metrics.go
• pkg/cli/dispatch.go
• pkg/cli/run_workflow_execution.go
• pkg/cli/trial_repository.go
• pkg/cli/pr_command.go
• pkg/cli/update_workflows.go
• pkg/cli/mcp_list.go
• pkg/cli/outcomes_history.go
• pkg/console/print.go
• pkg/cli/work_command_tui_view.go

Next actions

1. Introduce writer-bound console rendering and migrate stderr tables/status calls first.
2. Add tests covering the two mixed-stream cases: stdout redirected/stderr TTY and stdout TTY/stderr redirected.
3. Add a lint rule preventing non-Stderr formatters from being passed to os.Stderr, and preventing styled console strings from being embedded in returned errors.
4. Add an accessible linear mode for the work-queue TUI.
5. Migrate remaining raw user-facing status lines incrementally; leave structured and machine-readable output unchanged.

The requested Serena project activation succeeded, but semantic lookup could not start because the Serena service reported that its Go language server runtime was unavailable. The report therefore uses a complete tracked-Go lexical scan plus targeted source review rather than Serena diagnostics.

References:

• §38039138277

Generated by 💄 Terminal Stylist · pi · gpt56 · 85.2 AIC · ⌖ 20.5 AIC · ⊞ 7.3K · ◷

• expires on Oct 11, 2026, 12:53 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #67686.