[terminal-stylist] Terminal output consistency audit for Go sources

[github-actions[bot]]

Overview

The Go console-output audit is complete. I scanned all 1,789 non-test Go files, with 1,769 under pkg/ as the primary analysis area. Of those, 1,587 are production pkg/ files and 182 are linter fixtures under testdata. Serena semantic analysis and gopls diagnostics were used for the core console, style, Huh, and TUI implementations; no language-server diagnostics were reported for the sampled core files.

Overall, the terminal architecture is strong: user-facing status output is centralized through pkg/console, Lipgloss styling is adaptive and TTY-aware, Huh forms share one theme/accessibility wrapper, and raw ANSI is confined to terminal-control operations. The main opportunity is finishing migration of a small set of raw warning/error and verbose diagnostic writes that bypass the console conventions.

Key metrics and findings

• 2,198 console.* calls across 284 production pkg/ files. The dominant APIs are FormatInfoMessage (683), FormatWarningMessage (572), FormatSuccessMessage (234), and FormatVerboseMessage (80).
• No production direct fmt.Print, fmt.Printf, or fmt.Println calls were found in pkg/. The three textual matches are documentation examples in pkg/styles/theme.go.
• Lipgloss is concentrated in 9 production files, primarily pkg/console, pkg/styles, the logger, schedule rendering, secret layout, and the work-queue TUI.
• Huh is used in 18 production files. All forms are constructed through console.NewForm or its single-field wrappers, so the shared theme and accessible mode are consistently applied.
• Raw ANSI appears in only 3 production files: pkg/console/terminal.go, pkg/console/prompt_form.go, and pkg/stringutil/ansi.go. These uses are cursor/screen control or ANSI parsing rather than hand-coded color styling.
• 2,661 direct fmt.F* writes to os.Stdout/os.Stderr remain across 276 files. Most are intentional structured reports, machine-readable output, spacing, or already wrap console.Format*; a smaller subset contains raw status diagnostics that should be standardized.

Highest-value improvements

1. Standardize the remaining raw warning/error writes. These currently bypass semantic icons, adaptive color, NO_COLOR degradation, and consistent capitalization:

   • pkg/workflow/mcp_renderer.go:114 — raw Error generating custom MCP configuration...
   • pkg/workflow/compiler_orchestrator_engine.go:302-308 — uppercase raw WARNING: lines
   • pkg/workflow/push_to_pull_request_branch.go:127 — raw Warning: line
   • pkg/workflow/cache_steps.go:23 — raw verbose warning
   • pkg/cli/mcp_inspect_mcp.go:577,591 — raw schema display errors

   Prefer console.PrintWarningMessage, console.PrintErrorMessage, or destination-explicit Format*Stderr helpers. For compiler diagnostics with file context, prefer the existing formatCompilerMessage path.

2. Route Claude parser diagnostics through the established verbose/debug layer. pkg/workflow/claude_logs.go:144-321 emits several unstyled verbose lines directly to stderr, while the same file already has claudeLogsLog. Use the namespace logger for developer diagnostics or console.FormatVerboseMessageStderr for deliberate user-visible verbose output. In particular, avoid printing an entire invalid JSON line (:231) without truncation/redaction because log records can contain large or sensitive payloads.

3. Reduce destination ambiguity in new code. The codebase has explicit stdout/stderr aliases, but many call sites still combine fmt.Fprintln(os.Stderr, console.FormatInfoMessage(...)). Prefer the Print* helpers where no composition is needed, and use the *Stderr formatter names when composing multi-line reports. This makes stream intent reviewable and avoids accidentally selecting stdout TTY state for stderr output.

4. Consider gating the startup background probe on terminal availability. pkg/styles/theme.go skips Lipgloss background probing on Windows but otherwise probes during package initialization. Output rendering itself is correctly TTY-gated; adding an stdin/stderr terminal check before lipgloss.HasDarkBackground would make non-interactive startup behavior more explicit and avoid unnecessary terminal queries in CI and redirected execution.

Patterns implemented well

• pkg/console/console.go checks destination-specific TTY state and degrades rendered ANSI through the color-profile writer, honoring NO_COLOR, COLORTERM, and TERM.
• pkg/styles/theme.go provides a centralized semantic palette with light/dark variants for error, warning, success, info, borders, tables, and specialized UI elements.
• pkg/styles/huh_theme.go uses lipgloss.LightDark and maps focus, selection, validation errors, buttons, placeholders, and group styling consistently.
• pkg/console/prompt_form.go centralizes Huh theming, accessible mode, TTY requirements, cancellation handling, and form cleanup.
• pkg/cli/interactive.go organizes the larger authoring flow into titled Huh groups, uses appropriate Select/MultiSelect/Text fields, and validates the workflow intent.
• pkg/cli/run_interactive.go adds validation for required dynamic workflow inputs.
• pkg/cli/engine_secrets.go uses masked Huh inputs with validation for tokens and API keys.
• pkg/cli/work_command_tui_view.go uses Lipgloss width/height calculations, responsive single/two-pane layouts, alternate-screen rendering, viewport limits, and ASCII borders that remain legible on basic terminals. Dynamic values are escaped through workQueueText.
• Raw ANSI in pkg/console/terminal.go and pkg/console/prompt_form.go is justified because Lipgloss does not provide cursor save/restore or screen-clearing primitives, and execution is TTY-gated.

Library-specific recommendations

Lipgloss

• Keep semantic color and border definitions in pkg/styles; avoid adding one-off hardcoded colors in CLI packages.
• Continue using lipgloss.Width rather than byte/rune counts for alignment. Existing usage in tables, secret layouts, and schedule rendering is correct.
• For new tables and multi-column reports, prefer the existing console.RenderTable width-budget path over manual padding.
• Preserve the current rule that styling is applied only for the destination TTY and degraded by environment capabilities.
• The work-queue TUI intentionally uses reverse video rather than palette colors; this is a good high-compatibility choice. If semantic colors are added later, select them from pkg/styles and retain a no-color focus indicator.

Huh

• Continue requiring all forms to pass through console.NewForm; no direct huh.NewForm construction was found outside that wrapper.
• Keep validation close to required/secret fields. Consider reusable validators for required trimmed text and minimum-length secrets to reduce minor differences among prompts.
• The centralized WithAccessible handling is a strong baseline. Consider documenting whether NO_COLOR is intended to imply full Huh accessible mode, since color preference and screen-reader mode are related but not identical user choices.
• Text fallbacks in pkg/console/confirm.go and pkg/console/list.go are valuable. A shared fallback prompt abstraction could improve testability and make list input injectable like confirmation input already is.

Error and status messages

• Keep returned Go errors lowercase and context-wrapped with %w; apply user-facing capitalization/icons only at the terminal boundary.
• Avoid manually embedding Warning:, WARNING:, or Error: when a semantic formatter is available.
• Reserve raw stdout for command data and machine-readable formats; progress, warnings, prompts, and diagnostics should remain on stderr.
• Use debug logger namespaces for parser internals rather than verbose raw writes when the information is primarily diagnostic.

Recommended next actions

1. Replace the identified raw warning/error call sites with console or compiler-diagnostic helpers.
2. Refactor Claude log verbose output to the logger/verbose formatter and truncate or redact invalid payload excerpts.
3. Add a lightweight lint/check that rejects new raw user-facing Warning:, WARNING:, and Error: writes to stderr outside approved renderer/debug paths.
4. Document the intended distinction between no-color mode and Huh screen-reader/accessibility mode.
5. Optionally add a TTY gate around the terminal background probe.

References:

• §40295621358

Generated by 💄 Terminal Stylist · pi · gpt56 · ~94 AIC · ⌖ ~23 AIC · ⊞ 8.3K · ◷

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

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #72365.