[repository-quality] Repository Quality Improvement Report - CLI Output Consistency (2026-05-14)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - CLI Output Consistency

Analysis Date: 2026-05-14
Focus Area: Code Quality — CLI Output Consistency
Strategy Type: Standard
Custom Area: No

Executive Summary

Analysis of the pkg/cli/ package reveals a significant inconsistency in how diagnostic messages are written to stderr. Of the ~2,238 stderr write calls, approximately 699 (31%) bypass the established console.Format* helpers and write raw text via fmt.Fprintf/fmt.Fprintln. This breaks the visual language of the CLI — users see some messages with colour, icons, and formatting while others appear as plain text in the same session.

The pkg/console package provides a complete set of formatting helpers (FormatInfoMessage, FormatSuccessMessage, FormatWarningMessage, FormatErrorMessage, FormatProgressMessage, FormatCommandMessage, etc.) that are already heavily used (1,539 calls). The AGENTS.md development guide mandates their use for all diagnostic output. The gap is concentrated in older or less-reviewed files: mcp_inspect_mcp.go (68 unformatted message writes), audit_report_render.go (52), audit_report_render_findings.go (35), enable.go (24), and engine_secrets.go/preconditions.go.

Fixing this will improve the user experience, make the codebase consistent with documented conventions, and reduce friction for future contributors who look to existing code as examples.

Full Analysis Report

Focus Area: CLI Output Consistency

Current State Assessment

Metrics Collected:

Metric	Value	Status
Total stderr write calls in pkg/cli/	~2,238	⚠️
Console-formatted writes	1,539 (69%)	✅
Raw unformatted writes	699 (31%)	❌
Files with 20+ raw writes	8	❌
AGENTS.md compliance mandate	"ALWAYS use console formatting"	⚠️

Top Files by Unformatted Writes (excluding blank-line spacers):

File	Unformatted Msg Writes	Formatted Writes
mcp_inspect_mcp.go	68	mixed
audit_report_render.go	52	61
audit_report_render_findings.go	35	45
enable.go	24	13
engine_secrets.go	~28	~5
preconditions.go	~22	~5
shell_completion.go	~21	~0
deps_report.go	~20	~0

Findings

Strengths

• The pkg/console package is comprehensive with 15+ formatting helpers
• 69% of stderr writes already use console formatting — a solid majority
• audit_report_render.go blank-line spacers (fmt.Fprintln(os.Stderr)) are intentional and acceptable
• AGENTS.md clearly documents the requirement

Areas for Improvement

• [HIGH] enable.go: 24 raw writes for user-facing workflow enable/disable feedback messages — e.g., "Workflow %s is already enabled\n" should be FormatInfoMessage / FormatSuccessMessage
• [HIGH] mcp_inspect_mcp.go: 68 raw writes for MCP server inspection output — server names, tool listings, connection status
• [MEDIUM] engine_secrets.go: ~28 raw writes for PAT setup instructions — ideal for FormatInfoMessage and FormatCommandMessage
• [MEDIUM] preconditions.go: ~22 raw writes for authentication and GitHub Actions setup guidance
• [LOW] deps_report.go / shell_completion.go: ~20 raw writes each

Detailed Analysis

enable.go example violations:

// ❌ Current
fmt.Fprintf(os.Stderr, "Workflow %s is already enabled\n", name)
fmt.Fprintf(os.Stderr, "%sd workflow: %s\n", action, name)

// ✅ Target
fmt.Fprintln(os.Stderr, console.FormatInfoMessage(fmt.Sprintf("Workflow %s is already enabled", name)))
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage(fmt.Sprintf("%sd workflow: %s", action, name)))

engine_secrets.go example violations:

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

// ✅ Target
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("GitHub Copilot requires a fine-grained Personal Access Token (PAT)..."))
fmt.Fprintln(os.Stderr, console.FormatPromptMessage("Please create a token at:"))

preconditions.go example violations:

// ❌ Current
fmt.Fprintln(os.Stderr, "Please run the following command to authenticate:")
fmt.Fprintln(os.Stderr, "You can still add workflows, but they won't run until Actions is enabled.")

// ✅ Target
fmt.Fprintln(os.Stderr, console.FormatPromptMessage("Please run the following command to authenticate:"))
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("You can still add workflows, but they won't run until Actions is enabled."))

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Migrate enable.go to Console Formatting

Priority: High
Estimated Effort: Small
Focus Area: Code Quality — CLI Output Consistency

Description: Replace all raw fmt.Fprintf(os.Stderr, ...) and fmt.Fprintln(os.Stderr, ...) diagnostic message writes in pkg/cli/enable.go with the appropriate console.Format* helpers. Use FormatInfoMessage for status messages, FormatSuccessMessage for completed actions, FormatWarningMessage for already-done-nothing states, and FormatProgressMessage for in-progress messages. Blank-line spacers (fmt.Fprintln(os.Stderr)) are acceptable and should remain.

Acceptance Criteria:

• All diagnostic message writes in enable.go use console.Format* helpers
• fmt.Fprintf(os.Stderr, ...) with a message body is replaced; blank-line fmt.Fprintln(os.Stderr) may remain
• make build && make fmt && make lint passes with zero errors
• The enable/disable workflow user-visible output matches the rest of the CLI visually

Code Region: pkg/cli/enable.go

In `pkg/cli/enable.go`, replace all raw `fmt.Fprintf(os.Stderr, ...)` and `fmt.Fprintln(os.Stderr, "non-empty-string")` calls with the appropriate `console.Format*` helpers from `pkg/console/console.go`.

Guidelines:
- "already enabled/disabled" → `console.FormatInfoMessage(...)`
- "Enabling/Disabling workflow:" → `console.FormatProgressMessage(...)` or `console.FormatSuccessMessage(...)`  
- "The following workflows will be Xd:" → `console.FormatInfoMessage(...)`
- "Keeping enabled:" → `console.FormatInfoMessage(...)`
- Blank-line `fmt.Fprintln(os.Stderr)` calls are fine as-is

After changes run: `make build && make fmt && make lint`

---

Task 2: Migrate engine_secrets.go to Console Formatting

Priority: High
Estimated Effort: Small
Focus Area: Code Quality — CLI Output Consistency

Description: Replace all raw stderr writes in pkg/cli/engine_secrets.go with appropriate console.Format* helpers. This file outputs PAT setup instructions and token configuration guidance — currently all plain text. Using FormatInfoMessage, FormatPromptMessage, and FormatCommandMessage will make these instructions visually consistent with the rest of the CLI.

Acceptance Criteria:

• All diagnostic writes in engine_secrets.go use console.Format* helpers
• URL/token configuration lines use FormatCommandMessage or FormatInfoMessage
• make build && make fmt && make lint passes with zero errors

Code Region: pkg/cli/engine_secrets.go

In `pkg/cli/engine_secrets.go`, replace all raw `fmt.Fprintln(os.Stderr, "...")` calls with `console.Format*` helpers.

Guidelines:
- Instructional "please do X" → `console.FormatPromptMessage(...)`
- Informational descriptions → `console.FormatInfoMessage(...)`
- Commands to run (e.g., `gh secret set ...`) → `console.FormatCommandMessage(...)`
- Bullet point items (`  • Token name: ...`) → wrap in `console.FormatListItem(...)` or keep as `FormatInfoMessage`
- Blank spacer lines are fine as-is

After changes run: `make build && make fmt && make lint`

---

Task 3: Migrate preconditions.go to Console Formatting

Priority: Medium
Estimated Effort: Small
Focus Area: Code Quality — CLI Output Consistency

Description: Replace all raw stderr writes in pkg/cli/preconditions.go with console.Format* helpers. This file outputs authentication guidance and GitHub Actions enablement instructions — these are the first messages many users see when something is misconfigured, so visual polish here is high-impact.

Acceptance Criteria:

• All diagnostic writes in preconditions.go use console.Format* helpers
• Authentication guidance uses FormatWarningMessage or FormatPromptMessage
• Command suggestions use FormatCommandMessage
• make build && make fmt && make lint passes with zero errors

Code Region: pkg/cli/preconditions.go

In `pkg/cli/preconditions.go`, replace all raw `fmt.Fprintln(os.Stderr, "...")` calls with `console.Format*` helpers.

Guidelines:
- "Please run the following command" → `console.FormatPromptMessage(...)`
- "You can still add workflows, but..." → `console.FormatWarningMessage(...)`
- Specific commands to run → `console.FormatCommandMessage(...)`
- Blank spacer lines are fine as-is

After changes run: `make build && make fmt && make lint`

---

Task 4: Migrate mcp_inspect_mcp.go to Console Formatting

Priority: Medium
Estimated Effort: Medium
Focus Area: Code Quality — CLI Output Consistency

Description: pkg/cli/mcp_inspect_mcp.go has ~68 unformatted message writes — the highest count of any CLI file. This file outputs MCP server inspection output including server names, tool listings, and connection status. Replace raw writes with console.Format* helpers throughout.

Acceptance Criteria:

• All diagnostic message writes use console.Format* helpers or are intentional structured output
• Server names and connection info use FormatInfoMessage
• Tool/resource listings use FormatListItem where appropriate
• make build && make fmt && make lint passes with zero errors

Code Region: pkg/cli/mcp_inspect_mcp.go

In `pkg/cli/mcp_inspect_mcp.go`, replace all raw `fmt.Fprintf(os.Stderr, ...)` and `fmt.Fprintln(os.Stderr, "non-empty")` calls with `console.Format*` helpers.

Key patterns to address:
- Server name/version header line → `console.FormatInfoMessage(...)` or `console.FormatSectionHeader(...)`
- Stdout/stderr output from MCP processes (line-by-line streaming) — these may be intentionally raw; use judgement
- Connection status → `console.FormatSuccessMessage(...)` / `console.FormatErrorMessage(...)`
- Tool/resource names in listings → `console.FormatListItem(...)`

After changes run: `make build && make fmt && make lint`

---

Task 5: Migrate deps_report.go and shell_completion.go to Console Formatting

Priority: Low
Estimated Effort: Small
Focus Area: Code Quality — CLI Output Consistency

Description: Migrate the remaining ~20 raw stderr writes in pkg/cli/deps_report.go and pkg/cli/shell_completion.go to use console.Format* helpers. These are lower-priority files but completing them will bring the overall raw-write rate below 20%.

Acceptance Criteria:

• All diagnostic writes in both files use console.Format* helpers
• make build && make fmt && make lint passes with zero errors
• Raw unformatted write percentage across pkg/cli/ drops below 25%

Code Region: pkg/cli/deps_report.go, pkg/cli/shell_completion.go

In `pkg/cli/deps_report.go` and `pkg/cli/shell_completion.go`, replace raw `fmt.Fprintf(os.Stderr, ...)` and `fmt.Fprintln(os.Stderr, "non-empty")` calls with appropriate `console.Format*` helpers from `pkg/console/console.go`.

For each raw write, choose the most semantically accurate helper:
- Progress/status → `FormatProgressMessage`
- Info → `FormatInfoMessage`
- Success → `FormatSuccessMessage`  
- Warning → `FormatWarningMessage`
- Commands → `FormatCommandMessage`

After changes run: `make build && make fmt && make lint`

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-05-14	CLI Output Consistency	Standard	No	First run — baseline established

---

🎯 Recommendations

Immediate Actions (This Week)

1. Migrate enable.go to console formatting — Priority: High
2. Migrate engine_secrets.go to console formatting — Priority: High

Short-term Actions (This Month)

1. Migrate preconditions.go to console formatting — Priority: Medium
2. Migrate mcp_inspect_mcp.go to console formatting — Priority: Medium

Long-term Actions (This Quarter)

1. Add a custom linter rule (e.g., via linters/) to enforce console.Format* usage and prevent regressions — Priority: Low

---

📈 Success Metrics

• Unformatted stderr writes: 699 → <200 (71% reduction)
• Files with 20+ raw writes: 8 → 0
• Console formatting compliance rate: 69% → >90%

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 1 month

---

References:

• §25862293367

Generated by Repository Quality Improvement Agent · ● 8.8M · ◷

• expires on May 15, 2026, 1:25 PM UTC

[github-actions[bot]]

💥 WHOOSH! 🦸♂️

The Smoke Test Agent crashes through the wall...

KA-POW! Just zoomed by to leave my mark on this discussion! 💨
ZAP! ⚡ All systems nominal — Claude engine humming like a well-oiled jetpack! 🚀
BAM! 💥 Smoke test 25863982829 reporting in — mission accomplished!

...and just like that, off into the sunset! 🌅✨

🤖 Beep boop — this comic-strip moment brought to you by the smoke-claude workflow.

Warning

Firewall blocked 6 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• contentautofill.googleapis.com
• safebrowsingohttpgateway.googleapis.com
• www.google.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "contentautofill.googleapis.com"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

💥 [THE END] — Illustrated by Smoke Claude · ● 9.4M · ◷

[pelikhan]

/plan

[github-actions[bot]]

🚀 Plan Command has started processing this discussion comment

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #32379.