Terminal Stylist Audit: Console Output Analysis (gh-aw)

[github-actions[bot]]

This report analyzes console output patterns across all non-test Go source files in pkg/ and cmd/, evaluating consistency with the console formatting package and usage of the Charmbracelet ecosystem (Lipgloss, Huh, Bubble Tea).

Workflow Run: §23413900373

---

Summary

Metric	Count
Files scanned	~120 Go source files
Stderr outputs with console formatting	1,257 (72%)
Stderr outputs without console formatting	494 (28%)
Files using huh for interactive forms	9
Files using Lipgloss directly	5 (all in pkg/console/)
fmt.Println calls (structured stdout)	16 ✅

Overall, the codebase demonstrates strong adoption of the console formatting package. The majority of output is properly routed and styled. There are clear improvement opportunities concentrated in a small number of files.

---

✅ What's Working Well

Console Package Architecture
The pkg/console package is well-structured and provides a complete formatting toolkit:

• FormatSuccessMessage / FormatInfoMessage / FormatWarningMessage / FormatErrorMessage
• FormatProgressMessage / FormatCommandMessage / FormatPromptMessage / FormatVerboseMessage
• FormatListItem / FormatSectionHeader / FormatErrorWithSuggestions
• RenderStruct / RenderTable / RenderErrorBox

Lipgloss Integration (charm.land/lipgloss/v2)

• ✅ Adaptive colors (lipgloss.AdaptiveColor) used throughout for light/dark terminal compatibility
• ✅ TTY detection via isTTY() guards all styling (e.g., FormatSectionHeader bypasses styles when piped)
• ✅ Banner, table, list, and spinner all use Lipgloss for consistent visual identity
• ✅ Centralized color palette in pkg/styles/ shared across components

Huh Interactive Forms

• ✅ 9 files use huh for interactive CLI prompts (engine selection, schedule config, auth, git setup, etc.)
• ✅ Custom HuhTheme() in pkg/styles/huh_theme.go maps the Dracula-inspired palette to form fields
• ✅ Accessibility mode supported via console.IsAccessibleMode() passed to .WithAccessible()
• ✅ Field types used appropriately: NewInput, NewSelect, NewConfirm, NewMultiSelect
• ✅ Validation callbacks implemented on form fields

Stdout vs Stderr Routing

• ✅ All structured data (JSON, hashes, Mermaid graphs, tables) correctly goes to stdout
• ✅ All diagnostic messages go to stderr with console formatting

---

⚠️ Issues Found

1. audit_report_render.go — 90 unformatted outputs (highest count)

This file renders audit reports with manually-crafted bullet points instead of using console.FormatListItem:

// ❌ Current — manual bullet formatting
fmt.Fprintf(os.Stderr, "  • %s (%s)", file.Path, formattedSize)
fmt.Fprintf(os.Stderr, "    Reason: %s\n", tool.Reason)

// ✅ Better — use console.FormatListItem
fmt.Fprintln(os.Stderr, console.FormatListItem(fmt.Sprintf("%s (%s)", file.Path, formattedSize)))

Also uses many raw fmt.Fprintln(os.Stderr) blank lines for spacing — this is acceptable for layout, but a console.FormatCountMessage or similar could improve the item-count lines.

2. mcp_inspect_mcp.go — 41 unformatted outputs

Uses raw markdown-style bold syntax that renders literally in terminals:

// ❌ Current — markdown won't render in terminal
fmt.Fprintf(os.Stderr, "📋 **Name:** %s\n", foundTool.Name)
fmt.Fprintf(os.Stderr, "📝 **Description:** %s\n", foundTool.Description)
fmt.Fprintf(os.Stderr, "✅ **Status:** Allowed\n")

// ✅ Better — use console formatting + RenderStruct or Lipgloss styles
fmt.Fprintln(os.Stderr, console.FormatSectionHeader("Name: "+foundTool.Name))

This section would benefit significantly from console.RenderStruct or a structured lipgloss/table.

// ❌ Available tools fallback — unformatted
fmt.Fprintf(os.Stderr, "Available tools: ")
fmt.Fprintf(os.Stderr, "%s\n", strings.Join(toolNames, ", "))

// ✅ Better
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Available tools: "+strings.Join(toolNames, ", ")))

3. engine_secrets.go — 32 unformatted outputs

Mixed console-formatted and raw outputs. Instructional multi-line text uses raw stderr:

// ❌ Current
fmt.Fprintln(os.Stderr, "")
fmt.Fprintln(os.Stderr, "GitHub Copilot requires a fine-grained Personal Access Token (PAT)...")
fmt.Fprintln(os.Stderr, "Please create a token at:")
fmt.Fprintln(os.Stderr, console.FormatCommandMessage("  "+req.KeyURL))

// ✅ Better — wrap instructional block in FormatInfoMessage + FormatCommandMessage
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("GitHub Copilot requires a fine-grained Personal Access Token (PAT)..."))

4. preconditions.go — 27 unformatted outputs

Instructional setup messages without formatting:

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

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

5. copilot_setup.go — 19 unformatted outputs

Outputs YAML code blocks directly to stderr without a code formatter:

// ❌ Current — YAML block with no syntax highlighting or framing
fmt.Fprintln(os.Stderr, "      - name: Checkout repository")
fmt.Fprintln(os.Stderr, "        uses: actions/checkout@v6")

// ✅ Opportunity — a console.FormatCodeBlock() helper could frame this
// (currently no such function exists — opportunity to add one)

The verbose flag messages ("No version upgrade needed...") would benefit from FormatVerboseMessage rather than raw fmt.Fprintf(os.Stderr, ...).

6. add_interactive_workflow.go / add_interactive_git.go — 19 and 18 outputs

These files print instructional or status messages to stderr without console formatting.

---

Lipgloss-Specific Recommendations

View Lipgloss Recommendations

1. Library split is intentional and correct: pkg/console/ uses charm.land/lipgloss/v2 while pkg/styles/huh_theme.go uses github.com/charmbracelet/lipgloss (v1) — this is necessary because huh v0.8.0 depends on lipgloss v1. The comment in huh_theme.go already documents this. No action needed.

2. mcp_inspect_mcp.go tool details output is a prime candidate for a lipgloss two-column key-value layout, similar to how RenderStruct works. Consider refactoring the tool detail output to use console.RenderStruct with a typed struct instead of raw fmt.Fprintf with markdown-style bold.

3. Code block formatter missing: copilot_setup.go outputs YAML code snippets to stderr. A console.FormatCodeBlock(code string, language string) string helper using a faint/muted Lipgloss border could improve this visually.

4. Consistent border style: audit_report_render.go uses purely text-based section separation (blank lines). Consider using console.FormatSectionHeader for all section titles — it's already available and adds a styled border for TTY output.

---

Huh-Specific Recommendations

View Huh Recommendations

1. Theme consistency ✅: The HuhTheme() function correctly maps the color palette to all huh field states (focused, blurred, active, inactive). This is well-implemented.

2. Accessibility ✅: console.IsAccessibleMode() is correctly used with form.WithAccessible() in run_interactive.go. Check that all other form call sites (add_interactive_*.go) also apply this pattern.

3. add_interactive_auth.go uses huh.NewInput() for secret entry — consider adding EchoMode(huh.EchoPassword) if prompting for sensitive credentials.

4. Validation messages: Ensure all Validate() callbacks return user-friendly error strings. The huh library will display these inline, so they should be complete sentences without FormatErrorMessage wrapping (huh handles its own styling).

5. engine_secrets.go — the instructional text preceding huh prompts is output via raw fmt.Fprintln(os.Stderr, ...). Consider using huh.NewNote() fields within the form for contextual help text that renders in the form's styled context.

---

Top Files to Prioritize

File	Unformatted Lines	Priority	Key Issue
audit_report_render.go	90	Medium	Bullet items bypass FormatListItem
mcp_inspect_mcp.go	41	High	Markdown syntax in terminal, inconsistent formatting
engine_secrets.go	32	Medium	Mixed formatted/unformatted instructional text
preconditions.go	27	Medium	Instructional text without formatters
shell_completion.go	21	Low	Likely completion script output (may be intentional)
copilot_setup.go	19	Low	YAML blocks — may benefit from a new FormatCodeBlock helper
add_interactive_workflow.go	19	Medium	Status/instruction messages
add_interactive_git.go	18	Medium	Status/instruction messages

---

Recommended New Helper

The most impactful addition would be a code block formatter for terminal output:

// FormatCodeBlock formats a multi-line code snippet for terminal display.
// Uses a faint border and muted coloring to visually distinguish code from prose.
func FormatCodeBlock(code string) string {
    style := lipgloss.NewStyle().
        Border(lipgloss.RoundedBorder()).
        BorderForeground(styles.ColorComment).
        Padding(0, 1)
    return style.Render(code)
}

This would benefit copilot_setup.go and any future commands that display YAML/shell snippets to users.

---

References:

• §23413900373

AI generated by Terminal Stylist · history

• expires on Mar 23, 2026, 10:26 PM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-03-23T22:26:26.632Z.

Closed by Workflow