[terminal-stylist] Terminal output consistency audit for Go CLI code

[github-actions[bot]]

Overview

A static AST scan covered all 1,818 non-test Go files, including 1,798 files under pkg/. The review focused on direct fmt.Print* output, pkg/console, Lipgloss, Huh, error presentation, TTY behavior, and accessibility. Serena semantic analysis was active; diagnostics for the central console, prompt-form, and Huh-theme files were clean.

The overall foundation is strong: terminal styling is centralized, adaptive light/dark colors are defined once, ANSI color output is gated by TTY and color-profile handling, and Huh forms consistently inherit theme and accessibility settings. The main opportunities are in several large renderers that mix structured console helpers with raw fmt.Fprintf output.

Key metrics

Area	Result
Non-test Go files scanned	1,818
Non-test Go files under pkg/	1,798
console.* call expressions under pkg/	2,196
Lipgloss call expressions under pkg/	89 across 12 importing files
Huh call expressions under pkg/	68 across 17 importing files
Direct fmt.Fprint* calls to stdout/stderr under pkg/	2,714
Direct terminal calls containing a console.* formatter	1,880 (69%)

The remaining raw calls are not automatically defects. Many intentionally emit JSON, generated snippets, tables, reports, or subprocess output. They identify where future consistency work has the highest leverage.

What is working well

• Centralized terminal policy: pkg/console/console.go checks stdout/stderr independently and degrades Lipgloss output through the color-profile writer, honoring NO_COLOR, COLORTERM, and TERM.
• Adaptive palette: pkg/styles/theme.go supplies semantic light/dark colors and reusable styles for errors, warnings, success, tables, borders, commands, and calendar intensity.
• Accessible Huh integration: pkg/console/prompt_form.go applies styles.HuhTheme, enables Huh accessible mode, requires stdin and stderr TTYs, and avoids cursor-clearing behavior in accessible mode.
• Well-structured forms: pkg/cli/interactive.go groups related fields into configuration, capabilities, security, and instructions pages. Required free-text fields use validation.
• TTY-safe specialized rendering: pkg/cli/compile_schedule_calendar.go suppresses styled cells outside terminals and in accessible mode.
• Raw ANSI is narrowly scoped: cursor and screen-control sequences are confined to pkg/console/prompt_form.go and pkg/console/terminal.go, where Lipgloss has no equivalent, and are protected by TTY checks.
• Reusable rendering primitives: console.RenderTable, console.RenderStruct, section headers, message formatters, spinners, confirms, and list selection already cover most CLI needs.

Priority findings

1. Do not embed terminal styling in returned errors.

   • pkg/cli/env_command.go:215 constructs an error with errors.New(console.FormatErrorMessage(err.Error())).
   • This mixes presentation with error semantics, can preserve ANSI in an error value, and risks duplicate formatting when the command boundary renders the error.
   • Recommendation: return or wrap the plain error and apply FormatErrorMessage only at the final output boundary.

2. Standardize the dependency report renderer.

   • pkg/cli/deps_report.go:104-180 mixes formatted headings with manual box-drawing separators, raw labels, and hard-coded status emoji.
   • Recommendation: use FormatSectionHeader, RenderStruct, and RenderTable; route recommendations through warning/error/success helpers. This will improve redirected output, alignment, and visual consistency.

3. Avoid Markdown syntax in terminal-only output.

   • pkg/cli/mcp_inspect_mcp.go:519-591 prints literal **Name:** labels and fenced code blocks to stderr. Standard terminals do not render Markdown, so users see the asterisks and backticks.
   • Recommendation: render metadata with RenderStruct or a two-column table and print schemas with an indented plain-text block. Reserve Markdown for file/report output modes.

4. Avoid duplicate semantic icons.

   • console.FormatSuccessMessage already adds ✓, while several MCP inspection calls pass messages beginning with ✅. RenderErrorBox/error formatters similarly receive messages beginning with ❌.
   • Recommendation: let the console helper own the semantic prefix. Message strings should contain content only.

5. Consolidate mixed print APIs in large renderers.

   • High-volume raw terminal output appears in pkg/cli/audit_diff_render.go, pkg/cli/audit_report_render.go, pkg/cli/mcp_inspect_mcp.go, pkg/cli/experiments_analyze_statistics.go, and pkg/cli/audit_cross_run_render.go.
   • These renderers often combine console.Print*, fmt.Fprintln, manual spacing, and manual column construction.
   • Recommendation: build a complete section with strings.Builder, RenderTable, or RenderStruct, then write it once through a destination-aware console API. This reduces partial lines and makes stdout/stderr policy easier to review.

Lipgloss assessment

Detailed Lipgloss findings

• The repository already follows the most important best practice: semantic styles live in pkg/styles instead of being recreated throughout commands.
• Light/dark adaptation is handled centrally, and Huh uses lipgloss.LightDark per render.
• Color application is generally TTY-aware. Layout-only calls such as .Width() are safe in redirected output because they do not add color escapes.
• console.RenderTable should remain the preferred table path instead of introducing direct lipgloss/table usage in command packages.
• The manual dependency-report separators and MCP detail layout are the clearest candidates for borders, padding, and column alignment through existing console abstractions.
• The work-queue TUI appropriately uses direct Lipgloss composition because it is a full-screen Bubble Tea view rather than ordinary command output.

Huh assessment

Detailed Huh findings

• All reviewed forms are routed through console.NewForm or its input/select/confirm wrappers, providing one accessibility and theme policy.
• Multi-group forms are organized logically, and required workflow inputs and intent fields use validation.
• Cancellation has a dedicated console.IsCancelled helper.
• The TTY precondition produces a clear error rather than attempting interactive rendering in pipes.
• Continue adding field-local validation for newly introduced free-form identifiers, repository references, paths, or secrets. Select and confirm fields generally do not need extra validation because their values come from constrained options.
• If future forms grow substantially, prefer shorter groups/pages and concise descriptions to keep screen-reader narration manageable.

Suggested implementation order

1. Remove styled error construction in pkg/cli/env_command.go.
2. Refactor pkg/cli/mcp_inspect_mcp.go to terminal-native labels and schema blocks, and remove duplicate icons.
3. Convert pkg/cli/deps_report.go to existing section/table/struct renderers.
4. Add a small lint rule or review check preventing errors.New(console.Format...) and duplicate semantic icon prefixes.
5. Incrementally migrate the large audit renderers when they are next modified; no wholesale rewrite is required.

References:

• §41027997960

Generated by 💄 Terminal Stylist · pi · gpt56 · ~86 AIC · ⌖ ~17 AIC · ⊞ 8.3K · ◷

• expires on Oct 31, 2026, 12:49 AM UTC-08:00