Terminal Stylist Report: Console Output Analysis

[github-actions[bot]]

This report analyzes console output patterns across all non-test Go source files in pkg/ and cmd/, covering Lipgloss styling, Huh form implementations, and consistency with the console formatting package.

---

Summary

Category	Finding
Total non-test .go files analyzed	~260 files
Files using console.* formatting	~60+ files (heavy usage in pkg/cli/)
Raw fmt.Fprintln(os.Stderr, ...) without console formatter	280+ calls across ~55 files
Raw bullet points (• ) vs console.FormatListItem()	~15 occurrences
Huh forms using WithTheme + WithAccessible	✅ All 16 form instances consistent
Lipgloss adaptive colors	✅ Properly configured in pkg/styles/
TTY-aware rendering	✅ applyStyle() guards all Lipgloss output
Stdout vs stderr routing	✅ JSON/hash/graph → stdout; diagnostics → stderr

---

✅ What's Working Well

Lipgloss (charm.land/lipgloss/v2)

• Adaptive colors are properly implemented across the entire color palette in pkg/styles/theme.go. All semantic colors (Error, Warning, Success, Info, Purple, etc.) use compat.AdaptiveColor with distinct Light/Dark hex values inspired by the Dracula theme.
• TTY-aware rendering: The applyStyle() helper in pkg/console/console.go wraps all Lipgloss rendering and short-circuits to plain text when not in a TTY — essential for piping and CI environments.
• Library encapsulation: Direct Lipgloss usage is confined to pkg/console/ and pkg/styles/, keeping styling concerns cleanly separated from business logic.
• Table rendering via lipgloss/table is used in console.RenderTable() and RenderStruct().
• Bubble Tea interactive list selection (console/list.go) with proper fallback for non-TTY.

Huh (github.com/charmbracelet/huh)

All 16 form instantiations are consistent and correct:

huh.NewForm(...).WithTheme(styles.HuhTheme()).WithAccessible(console.IsAccessibleMode())

• styles.HuhTheme() maps the full project palette (primary, success, error, warning, comment, fg, bg, border) to Huh field states.
• console.IsAccessibleMode() detects ACCESSIBLE, TERM=dumb, and NO_COLOR environment variables — covering screen readers and dumb terminals.
• The huh theme file correctly uses github.com/charmbracelet/lipgloss (v1) rather than charm.land/lipgloss/v2 to match Huh's own dependency — the inconsistency is intentional and justified by a comment.
• Field types are appropriately chosen: Confirm, Select, Input, MultiSelect are all in use.

Console Package

• Rich formatter vocabulary: FormatSuccessMessage, FormatInfoMessage, FormatWarningMessage, FormatErrorMessage, FormatCommandMessage, FormatProgressMessage, FormatVerboseMessage, FormatLocationMessage, FormatCountMessage, FormatPromptMessage, FormatSectionHeader, FormatListItem.
• WASM build variants exist for all formatters (console_wasm.go), using emoji-only output.
• console.RenderStruct() provides struct-tag-driven table/section rendering — a powerful pattern used in status_command.go and logs_report.go.

---

⚠️ Areas for Improvement

1. Bulk Raw fmt.Fprintf(os.Stderr, ...) — Missing Console Formatters

The following files have the highest counts of bare stderr writes that bypass the console formatting package. These often carry informational or instructional messages that would benefit from FormatInfoMessage, FormatWarningMessage, or FormatListItem styling.

Top offenders (non-formatter stderr writes)

File	Raw Calls	Notes
pkg/cli/audit_report_render.go	90	List items, spacing — uses FormatSectionHeader correctly but raw bullet points for detail lines
pkg/cli/mcp_inspect_mcp.go	41	Mix of FormatSectionHeader and bare fmt.Fprintf for details
pkg/cli/engine_secrets.go	32	PAT/API key instructions with no visual hierarchy
pkg/cli/preconditions.go	27	Auth/Actions guidance text — blank lines and instruction text unformatted
pkg/cli/add_interactive_workflow.go	22	Verbose status messages during interactive add flow
pkg/cli/shell_completion.go	21	Shell completion setup instructions
pkg/cli/deps_report.go	20	Dependency report output mixing raw text and structured output
pkg/cli/copilot_setup.go	19	Printed YAML snippets and instruction text — raw text is acceptable for YAML but diagnostic messages could use formatters
pkg/cli/add_interactive_git.go	17	Git setup guidance
pkg/cli/fix_command.go	14	Fix command status output

Example — preconditions.go (instruction text without visual hierarchy):

// ❌ Current
fmt.Fprintln(os.Stderr, "")
fmt.Fprintln(os.Stderr, "Please run the following command to authenticate:")
fmt.Fprintln(os.Stderr, "")
fmt.Fprintln(os.Stderr, console.FormatCommandMessage("  gh auth login"))

// ✅ Better
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Please run the following command to authenticate:"))
fmt.Fprintln(os.Stderr, console.FormatCommandMessage("  gh auth login"))

2. Raw Bullet Points vs console.FormatListItem()

Several files manually format list items with " • %s\n" instead of using the existing console.FormatListItem() helper, which applies proper Lipgloss styling:

Raw bullet point locations

• pkg/cli/audit_report_render.go:76,90,111 — file paths, tool names, server names
• pkg/cli/run_interactive.go:254 — workflow input parameter listing
• pkg/cli/actionlint.go:121 — linting category counts
• pkg/cli/add_interactive_orchestrator.go:211 — workflow file listing
• pkg/cli/mcp_inspect_inspector.go:76 — MCP server listing
• pkg/cli/mcp_inspect_list.go:62 — workflow name listing
• pkg/cli/engine_secrets.go:299-303 — token configuration instructions

// ❌ Current
fmt.Fprintf(os.Stderr, "  • %s\n", tool.Tool)

// ✅ Better
fmt.Fprintln(os.Stderr, console.FormatListItem(tool.Tool))

3. mcp_list_tools.go — Unformatted Info/Status Messages

// ❌ Current (lines 76-78, 133-135)
fmt.Fprintf(os.Stderr, "Available MCP servers: ")
fmt.Fprintf(os.Stderr, "%s\n", strings.Join(serverNames, ", "))
fmt.Fprintf(os.Stderr, "Found MCP server '%s' in %d workflow(s): %s\n", ...)

// ✅ Better
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Available MCP servers: " + strings.Join(serverNames, ", ")))
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("Found MCP server '%s' in %d workflow(s)", ...)))

4. copilot_setup.go — Instructional Text Formatting

The function that prints setup instructions (lines 264–292) uses 15+ raw fmt.Fprintln(os.Stderr, ...) calls to display YAML snippets. The YAML code is intentionally unformatted (correct), but the surrounding instructional messages would benefit from FormatInfoMessage:

// ❌ Current
fmt.Fprintln(os.Stderr, "To enable GitHub Copilot Agent integration, please add the following steps")

// ✅ Better
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("To enable GitHub Copilot Agent integration, please add the following steps"))

---

💡 Recommendations

1. High value / low effort: Replace raw bullet points with console.FormatListItem() across ~15 locations — each is a one-line change with clear visual improvement.

2. Medium value: Wrap instructional text in engine_secrets.go, preconditions.go, and mcp_list_tools.go with FormatInfoMessage / FormatWarningMessage to provide visual hierarchy and consistent iconography (ℹ, ⚠).

3. Low priority: The blank-line fmt.Fprintln(os.Stderr) spacing pattern (used extensively in audit_report_render.go) is acceptable as-is — these are structural separators, not content.

4. Consider a console.FormatInstruction() helper: Several multi-line instruction blocks in engine_secrets.go and preconditions.go follow the same pattern (empty line, instruction text, empty line). A dedicated formatter or a RenderInstructionBlock(title, steps []string) helper could unify these.

5. No changes needed to Huh forms: The interactive form implementations are well-structured, consistently themed, and accessibility-aware. No improvements required.

---

References:

• §23488147762

AI generated by Terminal Stylist · history

• expires on Mar 25, 2026, 12:01 PM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #22882.