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

[github-actions[bot]]

Overview

A static scan covered all 1,438 Go files under pkg/ that do not end in _test.go. This includes 1,288 production files and 150 linter fixtures under testdata; fixture matches were scanned but excluded from actionable metrics.

The terminal layer has a strong foundation: centralized semantic styles, adaptive light/dark colors, TTY-aware rendering helpers, Lipgloss tables, and a shared Huh theme/accessibility wrapper. The main consistency defect is that much of pkg/cli writes to stderr using stdout-aware formatters.

Key metrics and issues

Area	Finding
fmt.Print* / fmt.Fprint*	3,540 call sites in 353 production files; many generate strings/YAML or deliberately emit machine-readable stdout, so raw count is not itself a defect
console.*	2,238 references across 278 production files
Lipgloss	10 production files import Lipgloss; 35 CLI calls use the centralized console.RenderTable path
Huh	17 production files import Huh; 40 field/group/form constructors
Raw ANSI	3 production files, limited to cursor/screen control or ANSI processing
Stream mismatch	1,408 direct stderr writes in 171 files use stdout-aware semantic formatters
Correct stderr formatter adoption	113 direct uses across 23 CLI files

1. High priority — make styling stream-aware by construction

Examples such as pkg/cli/run_workflow_execution.go:84, pkg/cli/update_workflows.go:77, and pkg/cli/logs_metrics.go:68 write console.FormatInfoMessage(...) to os.Stderr. FormatInfoMessage, FormatWarningMessage, FormatSuccessMessage, FormatProgressMessage, and FormatCommandMessage inspect stdout TTY state, while their result is sent to stderr.

Consequences:

• stdout redirected + stderr interactive: useful stderr styling is unexpectedly disabled.
• stdout interactive + stderr redirected: ANSI can be emitted into redirected stderr.
• behavior differs from newer compile paths that correctly use *Stderr helpers.

The scan found at least:

• 657 stderr writes using FormatInfoMessage
• 499 using FormatWarningMessage
• 222 using FormatSuccessMessage
• 13 using FormatProgressMessage
• 17 using FormatCommandMessage

Recommendation: prefer console.Print*Message for direct stderr output. Where composition is required, use the matching Format*MessageStderr helper. Longer term, consider APIs that require an output stream/profile rather than maintaining easily confused stdout/stderr function pairs. Add a static check preventing stdout-aware formatter results from being written to stderr.

2. Medium priority — provide a plain, responsive table mode

pkg/console/console.go:318 always applies styles.RoundedBorder, even when the destination is not a TTY; only colors and row styles are disabled. This avoids ANSI leakage, but piped output still receives Unicode box drawing and padding. The renderer also has no terminal-width budget, while 35 CLI call sites depend on it.

Recommendation: select a borderless/ASCII table for non-TTY or accessible output, and accept a width budget derived from the destination terminal. Truncate/wrap lower-priority columns or expose compact output for narrow terminals. Keep current rounded borders and zebra striping for interactive TTYs.

3. Medium priority — detect the input terminal for Huh forms

pkg/console/input.go:21, pkg/console/confirm.go:24, pkg/console/list.go:29, and pkg/console/prompt_form.go:35 decide interactivity from tty.IsStderrTerminal(). The comment in input.go says it checks stdin, but pkg/tty/tty.go exposes only stdout/stderr checks. A process can have terminal stderr and piped/closed stdin; Huh then attempts an interactive form without a terminal input. Conversely, the “non-TTY” list/confirm fallbacks still read stdin and can block pipelines.

Recommendation: add tty.IsStdinTerminal(). Require terminal stdin for Huh forms, and make non-interactive behavior explicit: supplied flag/default, clear error, or prompt only when input is intentionally available. Continue rendering the TUI to stderr.

4. Low priority — prevent duplicated semantic prefixes

The semantic formatters already add ✓ or ⚠, but several messages embed another prefix. Examples include pkg/cli/run_interactive.go:101, pkg/cli/project_command.go:166, and pkg/cli/upgrade_command.go:280; pkg/cli/upgrade_command.go:330 embeds Warning: inside FormatWarningMessage.

Recommendation: pass plain message content to semantic formatters and let the formatter own the icon/label. Add focused tests or a lint check for leading semantic glyphs/labels.

Patterns that are already strong

• pkg/styles/theme.go centralizes semantic colors and provides light/dark variants.
• pkg/styles/huh_theme.go maps the same palette into Huh with lipgloss.LightDark, including focused, blurred, selection, button, input, and error states.
• pkg/console/console.go gates color on TTY state, honors terminal color profiles/NO_COLOR, and centralizes Lipgloss table rendering.
• pkg/console/prompt_form.go applies one Huh theme and accessibility mode to forms and cleans up completed prompts only on an interactive stderr.
• pkg/console/input.go masks secrets and validates empty values.
• pkg/console/terminal.go guards raw cursor/screen ANSI behind stderr TTY detection. The other raw-ANSI locations are prompt cursor management and ANSI string processing, so replacing them with Lipgloss would not improve correctness.
• pkg/console/console.go produces IDE-parseable file:line:column: error: diagnostics with context and hints.
• Newer compile-oriented files consistently use stderr-aware helpers; these are good migration examples.

Files using stderr-aware semantic formatters correctly

• pkg/cli/add_interactive_secrets.go
• pkg/cli/compile_args.go
• pkg/cli/compile_compiler_setup.go
• pkg/cli/compile_external_tools.go
• pkg/cli/compile_file_operations.go
• pkg/cli/compile_guard_policy_report.go
• pkg/cli/compile_infrastructure.go
• pkg/cli/compile_orchestrator.go
• pkg/cli/compile_pipeline.go
• pkg/cli/compile_post_processing.go
• pkg/cli/compile_repository_manifest.go
• pkg/cli/compile_schedule_calendar.go
• pkg/cli/compile_stats.go
• pkg/cli/compile_update_check.go
• pkg/cli/compile_watch.go
• pkg/cli/compile_workflow_processor.go
• pkg/cli/copilot_setup.go
• pkg/cli/devcontainer.go
• pkg/cli/mcp_config_file.go
• pkg/cli/mcp_list_tools.go
• pkg/cli/org_runner.go
• pkg/cli/trial_confirmation.go
• pkg/cli/vscode_config.go

Files with direct stderr/stdout-aware formatter mismatches

• pkg/cli/access_log.go
• pkg/cli/actionlint.go
• pkg/cli/actions_build_command.go
• pkg/cli/add_command_orchestrator.go
• pkg/cli/add_command_resources.go
• pkg/cli/add_init.go
• pkg/cli/add_interactive_auth.go
• pkg/cli/add_interactive_engine.go
• pkg/cli/add_interactive_git.go
• pkg/cli/add_interactive_orchestrator.go
• pkg/cli/add_interactive_schedule.go
• pkg/cli/add_interactive_workflow.go
• pkg/cli/add_package_ownership.go
• pkg/cli/add_skill_rewrite.go
• pkg/cli/add_workflow_compilation.go
• pkg/cli/add_workflow_content.go
• pkg/cli/add_workflow_pr.go
• pkg/cli/add_workflow_resolution.go
• pkg/cli/audit_analysis_fanout.go
• pkg/cli/audit_command.go
• pkg/cli/audit_cross_run_clusters_render.go
• pkg/cli/audit_cross_run_render.go
• pkg/cli/audit_diff_command.go
• pkg/cli/audit_diff_render.go
• pkg/cli/audit_group.go
• pkg/cli/audit_job.go
• pkg/cli/audit_render_output.go
• pkg/cli/audit_run_pipeline.go
• pkg/cli/audit_summary_build.go
• pkg/cli/audit_threat_detection_session.go
• pkg/cli/bootstrap_config.go
• pkg/cli/bootstrap_profile_actions_repo.go
• pkg/cli/bootstrap_profile_git.go
• pkg/cli/bootstrap_profile_github_app.go
• pkg/cli/bootstrap_profile_helpers.go
• pkg/cli/bootstrap_profile_runner.go
• pkg/cli/checks_command.go
• pkg/cli/codemod_bash_single_quoted_args.go
• pkg/cli/commands.go
• pkg/cli/compile_external_tools.go
• pkg/cli/compile_orchestrator.go
• pkg/cli/copilot_agent.go
• pkg/cli/copilot_agents.go
• pkg/cli/copilot_events_jsonl.go
• pkg/cli/deploy_org.go
• pkg/cli/deps_outdated.go
• pkg/cli/deps_report.go
• pkg/cli/deps_security.go
• pkg/cli/dispatch.go
• pkg/cli/domains_command.go
• pkg/cli/drain3_train.go
• pkg/cli/enable.go
• pkg/cli/env_command.go
• pkg/cli/experiments_analyze_statistics.go
• pkg/cli/experiments_command.go
• pkg/cli/experiments_render.go
• pkg/cli/fetch.go
• pkg/cli/file_tracker.go
• pkg/cli/firewall_log.go
• pkg/cli/fix_command.go
• pkg/cli/forecast.go
• pkg/cli/forecast_compute.go
• pkg/cli/forecast_render.go
• pkg/cli/forecast_resolution.go
• pkg/cli/format_command.go
• pkg/cli/gateway_logs_parsing.go
• pkg/cli/gateway_logs_rpc.go
• pkg/cli/generate_action_metadata_command.go
• pkg/cli/grant.go
• pkg/cli/grype.go
• pkg/cli/health_command.go
• pkg/cli/imports.go
• pkg/cli/includes.go
• pkg/cli/init.go
• pkg/cli/interactive.go
• pkg/cli/list_workflows_command.go
• pkg/cli/log_aggregation.go
• pkg/cli/logs_cache.go
• pkg/cli/logs_cached_json.go
• pkg/cli/logs_download.go
• pkg/cli/logs_download_artifacts.go
• pkg/cli/logs_download_flatten.go
• pkg/cli/logs_github_api.go
• pkg/cli/logs_github_rate_limit_usage.go
• pkg/cli/logs_metrics.go
• pkg/cli/logs_multi.go
• pkg/cli/logs_orchestrator_download.go
• pkg/cli/logs_orchestrator_filters.go
• pkg/cli/logs_orchestrator_render.go
• pkg/cli/logs_orchestrator_stdin.go
• pkg/cli/logs_parsing_core.go
• pkg/cli/logs_parsing_engines.go
• pkg/cli/logs_parsing_firewall.go
• pkg/cli/logs_parsing_javascript.go
• pkg/cli/logs_rate_limit.go
• pkg/cli/logs_report.go
• pkg/cli/logs_run_processor.go
• pkg/cli/logs_storage_limit.go
• pkg/cli/logs_utils.go
• pkg/cli/logs_work_queue.go
• pkg/cli/mcp_add.go
• pkg/cli/mcp_inspect.go
• pkg/cli/mcp_inspect_inspector.go
• pkg/cli/mcp_inspect_list.go
• pkg/cli/mcp_inspect_mcp.go
• pkg/cli/mcp_inspect_mcp_scripts_files.go
• pkg/cli/mcp_inspect_mcp_scripts_server.go
• pkg/cli/mcp_list.go
• pkg/cli/mcp_list_tools.go
• pkg/cli/mcp_registry_list.go
• pkg/cli/mcp_secrets.go
• pkg/cli/mcp_server_http.go
• pkg/cli/mcp_validation.go
• pkg/cli/mcp_workflow_scanner.go
• pkg/cli/org_issue_pr_helpers.go
• pkg/cli/org_runner.go
• pkg/cli/outcomes_command.go
• pkg/cli/outcomes_history.go
• pkg/cli/packages.go
• pkg/cli/poutine.go
• pkg/cli/pr_automerge.go
• pkg/cli/pr_command.go
• pkg/cli/pr_helpers.go
• pkg/cli/preconditions.go
• pkg/cli/project_command.go
• pkg/cli/redacted_domains.go
• pkg/cli/remove_command.go
• pkg/cli/resources.go
• pkg/cli/run_interactive.go
• pkg/cli/run_push.go
• pkg/cli/run_workflow_execution.go
• pkg/cli/run_workflow_tracking.go
• pkg/cli/run_workflow_validation.go
• pkg/cli/runner_guard.go
• pkg/cli/secret_set_command.go
• pkg/cli/sessions_download.go
• pkg/cli/setup_repository.go
• pkg/cli/shell_completion.go
• pkg/cli/shellcheck.go
• pkg/cli/signal_aware_poll.go
• pkg/cli/status_command.go
• pkg/cli/syft.go
• pkg/cli/token_usage_find.go
• pkg/cli/tokens_bootstrap.go
• pkg/cli/tool_graph.go
• pkg/cli/trial_helpers.go
• pkg/cli/trial_repository.go
• pkg/cli/trial_runner.go
• pkg/cli/trial_support.go
• pkg/cli/update_actions_content_refs.go
• pkg/cli/update_actions_lockfile.go
• pkg/cli/update_actions_release.go
• pkg/cli/update_actions_workflow_files.go
• pkg/cli/update_check.go
• pkg/cli/update_command.go
• pkg/cli/update_container_pins.go
• pkg/cli/update_display.go
• pkg/cli/update_extension_check.go
• pkg/cli/update_manifest.go
• pkg/cli/update_merge.go
• pkg/cli/update_org.go
• pkg/cli/update_org_search.go
• pkg/cli/update_redirects.go
• pkg/cli/update_workflows.go
• pkg/cli/upgrade_command.go
• pkg/cli/upgrade_org.go
• pkg/cli/view_command.go
• pkg/cli/workflow_run_metadata.go
• pkg/cli/workflows.go
• pkg/cli/yamllint.go
• pkg/cli/zizmor.go

Huh implementation assessment

The codebase uses Input, Text, Select, MultiSelect, and Confirm; no compelling current use case requires adding Note or FilePicker. Most forms correctly go through console.NewForm / NewInputForm / NewSelectForm / NewConfirmForm, which gives consistent theming and WithAccessible(...) behavior. Validation is present on required and secret-bearing inputs.

Suggested refinements:

1. Base form eligibility on stdin TTY status, not only stderr.
2. Preserve plain non-interactive alternatives for automation, but do not silently read from a closed/piped stdin.
3. Keep validation errors short and actionable; centralize common required-value validation to avoid wording drift.
4. Test keyboard cancellation and accessible mode across multi-field forms, especially the Text and MultiSelect paths in pkg/cli/interactive.go.

Next actions

1. Migrate the 171 mismatch files incrementally, starting with pkg/cli/logs_metrics.go, pkg/cli/trial_repository.go, pkg/cli/pr_command.go, and pkg/cli/run_workflow_execution.go.
2. Add a linter or repository check for fmt.Fprint*(stderr, console.Format*Message(...)) when a stderr variant exists.
3. Add stdin TTY detection and define non-interactive prompt behavior.
4. Add non-TTY/accessibility and narrow-terminal table snapshots.
5. Remove duplicated semantic glyphs and labels.

References:

• §37596688043

Generated by 💄 Terminal Stylist · pi · gpt56 · 88.7 AIC · ⌖ 24.9 AIC · ⊞ 7.2K · ◷

• expires on Oct 8, 2026, 12:59 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #66843.