[repository-quality] Repository Quality Improvement Report — Console Print Wrapper Gap

[github-actions[bot]]

🎯 Repository Quality Improvement Report — Console Print Wrapper Gap

Analysis Date: 2026-07-21
Focus Area: Console Print Wrapper Gap — Two-Step fmt.Fprintln(os.Stderr, console.Format*(...)) Anti-pattern
Strategy Type: Custom
Custom Area: Yes — discovered by profiling raw stderr call sites; the console package exposes Format* functions but no corresponding Print* wrappers, forcing all 185 consumer files to re-implement a boilerplate two-step write on every call.

Executive Summary

The pkg/console package exposes rich styled-output formatters (FormatSuccessMessageStderr, FormatWarningMessage, FormatInfoMessageStderr, etc.) but deliberately stops short of writing to os.Stderr. As a result every caller must combine fmt.Fprintln(os.Stderr, console.FormatXxx(...)) themselves — a two-step idiom repeated 1,640 times across the codebase, with an additional 239 raw fmt.Fprintf(os.Stderr, ...) calls that bypass console styling entirely.

This creates three concrete problems: (1) accidental stdout/stderr routing errors (callers could easily write os.Stdout instead of os.Stderr); (2) inconsistent newline handling (fmt.Fprint vs fmt.Fprintln vs fmt.Fprintf with \n); (3) no single place to intercept output for testing, WASM/non-TTY environments, or future observability hooks. The console package already has a WASM build-tag split (console_wasm.go) that handles environment differences — a pattern that Print* wrappers could extend effortlessly.

The fix is to add thin Print* wrappers that call fmt.Fprintln(os.Stderr, Format*(...)) internally, then migrate the highest-density call sites. A companion linter enforcing the new helpers would lock in the improvement permanently.

Full Analysis Report

Focus Area: Console Print Wrapper Gap

Current State Assessment

The pkg/console package (console.go + WASM variants) provides Format* functions that return styled strings but does not provide Print* helper functions that write directly to os.Stderr. Every consumer file must therefore compose the two steps manually.

Metrics Collected:

Metric	Value	Status
fmt.Fprintln(os.Stderr, console.Format*(...)) two-step calls	1,640	⚠️
fmt.Fprintf(os.Stderr, console.Format*(...)) variant	94	⚠️
Raw fmt.Fprintf(os.Stderr, "...") (no console styling)	239	❌
Files using the two-step pattern	46+	⚠️
console.Print* wrappers that write directly	1 (PrintBanner)	❌
WASM split already handled in console pkg	Yes (banner_wasm.go)	✅
Top file: pkg/cli/mcp_inspect_mcp.go	70 raw stderr calls	❌
Second worst: pkg/cli/engine_secrets.go	63 raw stderr calls	❌

Findings

Strengths

• pkg/console already has a WASM build-tag split proving the pattern for environment-aware wrappers.
• PrintBanner() is a successful precedent showing the Print-wrapper style.
• The Format* functions are well-named and cover all semantic message types (success, info, warning, error, progress, command, list item, section header, table header).

Areas for Improvement

• Missing Print* wrappers: PrintSuccessMessageStderr, PrintWarningMessage, PrintInfoMessageStderr, PrintErrorMessage, PrintProgressMessage, PrintCommandMessage, PrintListItemStderr, PrintSectionHeaderStderr, PrintTableHeaderStderr — all absent.
• Boilerplate two-step pattern: 1,640 call sites manually combine fmt.Fprintln + console.Format*.
• 239 raw bypasses: Plain fmt.Fprintf(os.Stderr, "...") with no styling — inconsistent visual output.
• No linter enforcement: Nothing prevents new code from adding raw stderr writes.

Detailed Analysis

Two-step idiom example (from pkg/cli/engine_secrets.go):

// Current — 38 occurrences in this file alone
fmt.Fprintln(os.Stderr, console.FormatWarningMessage("Optional secret "+req.Name+": ..."))
fmt.Fprintln(os.Stderr, console.FormatInfoMessage("Paste the current or replacement ..."))
fmt.Fprintln(os.Stderr, console.FormatSuccessMessage("Using existing "+req.Name+" secret"))

// Target — after adding Print* wrappers
console.PrintWarningMessage("Optional secret " + req.Name + ": ...")
console.PrintInfoMessage("Paste the current or replacement ...")
console.PrintSuccessMessage("Using existing " + req.Name + " secret")

Raw bypass example (from pkg/cli/engine_secrets.go:437):

// Current
fmt.Fprintf(os.Stderr, "%s requires a GitHub Personal Access Token (PAT).\n", req.Name)

// Target
console.PrintInfoMessageStderr(req.Name + " requires a GitHub Personal Access Token (PAT).")

Top-5 highest-density files:

File	Two-step + Raw calls
pkg/cli/mcp_inspect_mcp.go	70
pkg/cli/engine_secrets.go	63
pkg/cli/logs_metrics.go	52
pkg/cli/trial_repository.go	49
pkg/cli/shell_completion.go	48

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Add Print* wrappers to pkg/console/console.go

Priority: High
Estimated Effort: Small
Focus Area: Console Print Wrapper Gap

Description: Add PrintXxx thin-wrapper functions alongside each FormatXxx function in pkg/console/console.go (and matching no-op stubs in pkg/console/banner_wasm.go / other WASM split files where applicable). Each wrapper should call fmt.Fprintln(os.Stderr, FormatXxx(...)). Functions to add: PrintSuccessMessageStderr, PrintInfoMessageStderr, PrintWarningMessage, PrintErrorMessage, PrintProgressMessage, PrintCommandMessage, PrintListItemStderr, PrintSectionHeaderStderr, PrintTableHeaderStderr, PrintErrorTextStderr, PrintErrorChain.

Acceptance Criteria:

• Each FormatXxxStderr function in console.go has a matching PrintXxxStderr wrapper.
• PrintWarningMessage, PrintErrorMessage, PrintProgressMessage, PrintCommandMessage added for non-Stderr variants.
• Wrappers use fmt.Fprintln(os.Stderr, FormatXxx(...)) internally.
• WASM build-tag counterpart file (spinner_wasm.go or banner_wasm.go) does not need changes (wrappers naturally use os.Stderr which WASM stubs already handle).
• All existing tests pass (make test-unit).

Code Region: pkg/console/console.go

In `pkg/console/console.go`, add thin `Print*` wrapper functions alongside the existing `Format*` functions. For every `func FormatXxxStderr(text string) string` function, add a corresponding `func PrintXxxStderr(text string)` that calls `fmt.Fprintln(os.Stderr, FormatXxxStderr(text))`. Similarly add `PrintWarningMessage`, `PrintErrorMessage`, `PrintProgressMessage`, `PrintCommandMessage`, `PrintListItemStderr`, `PrintSectionHeaderStderr`, `PrintTableHeaderStderr`, `PrintErrorTextStderr`, `PrintErrorChain(err error)`. Place them immediately after their `Format*` counterpart. Do not change any existing functions. Run `make fmt` and `make test-unit` when done.

---

Task 2: Migrate pkg/cli/engine_secrets.go to Print* wrappers

Priority: High
Estimated Effort: Small
Focus Area: Console Print Wrapper Gap

Description: Replace all fmt.Fprintln(os.Stderr, console.FormatXxx(...)) and fmt.Fprintf(os.Stderr, ...) in pkg/cli/engine_secrets.go (63 raw stderr calls) with the new console.PrintXxx(...) wrappers added in Task 1. Where the raw fmt.Fprintf uses a format string without a console styling function, wrap the message in the appropriate semantic console.PrintInfoMessageStderr(...) or console.PrintWarningMessage(...) call.

Acceptance Criteria:

• Zero fmt.Fprintln(os.Stderr calls remain in engine_secrets.go.
• Zero fmt.Fprintf(os.Stderr calls remain in engine_secrets.go.
• The fmt import is removed if no longer needed, or only used for non-stderr formatting.
• make test-unit passes.

Code Region: pkg/cli/engine_secrets.go

In `pkg/cli/engine_secrets.go`, replace every `fmt.Fprintln(os.Stderr, console.FormatXxx(msg))` call with `console.PrintXxx(msg)` using the wrappers added in the companion task. For calls like `fmt.Fprintf(os.Stderr, "%s requires a ...", req.Name)`, replace with the appropriate `console.PrintInfoMessageStderr(req.Name + " requires a ...")`. Remove the `fmt` import if it is no longer used for anything else. Run `make fmt` and `make test-unit`.

---

Task 3: Migrate pkg/cli/mcp_inspect_mcp.go to Print* wrappers

Priority: High
Estimated Effort: Small
Focus Area: Console Print Wrapper Gap

Description: Replace all 70 raw stderr call sites in pkg/cli/mcp_inspect_mcp.go using the same approach as Task 2. This is the highest-density file in the codebase.

Acceptance Criteria:

• Zero fmt.Fprintln(os.Stderr calls remain in mcp_inspect_mcp.go.
• Zero fmt.Fprintf(os.Stderr calls remain in mcp_inspect_mcp.go.
• make test-unit passes.

Code Region: pkg/cli/mcp_inspect_mcp.go

In `pkg/cli/mcp_inspect_mcp.go`, replace every `fmt.Fprintln(os.Stderr, console.FormatXxx(msg))` call with `console.PrintXxx(msg)` using the Print* wrappers from the console package. For raw `fmt.Fprintf(os.Stderr, ...)` patterns, choose the appropriate semantic `console.PrintInfoMessageStderr` or `console.PrintWarningMessage` etc. Remove unused `fmt` or `os` imports. Run `make fmt` and `make test-unit`.

---

Task 4: Add fmtfprintlnstderr linter to enforce console.Print* usage

Priority: Medium
Estimated Effort: Medium
Focus Area: Console Print Wrapper Gap

Description: Add a new linter pkg/linters/fmtfprintlnstderr/fmtfprintlnstderr.go that flags fmt.Fprintln(os.Stderr, ...) and fmt.Fprintf(os.Stderr, ...) calls in pkg/ library code and suggests using console.PrintXxx(...) instead. Register it in pkg/linters/registry.go and pkg/linters/doc.go. Add testdata with at least 3 want-annotated violations and 2 allowed patterns (//nolint:fmtfprintlnstderr and os.Stdout variant).

Acceptance Criteria:

• Linter file at pkg/linters/fmtfprintlnstderr/fmtfprintlnstderr.go with Analyzer var.
• Registered in pkg/linters/registry.go alongside other linters.
• Entry added to pkg/linters/doc.go list.
• Testdata at pkg/linters/fmtfprintlnstderr/testdata/src/fmtfprintlnstderr/fmtfprintlnstderr.go with // want annotations.
• pkg/linters/spec_test.go updated to include the new analyzer in ContainsExpectedAnalyzers.
• make test-unit passes.

Code Region: pkg/linters/fmtfprintlnstderr/

Create a new Go analysis linter `fmtfprintlnstderr` in `pkg/linters/fmtfprintlnstderr/fmtfprintlnstderr.go`. The linter should flag calls of the form `fmt.Fprintln(os.Stderr, ...)` and `fmt.Fprintf(os.Stderr, ...)` in library packages under `pkg/` (skip `cmd/`), reporting: "use console.Print* instead of writing directly to os.Stderr". Follow the patterns in existing linters like `pkg/linters/rawloginlib/rawloginlib.go` for package-path filtering, nolint support, and generated-file skipping. Register the analyzer in `pkg/linters/registry.go` and add a bullet to `pkg/linters/doc.go`. Add testdata with 3+ `// want` annotations and a `spec_test.go` entry. Run `make test-unit`.

---

Task 5: Migrate pkg/workflow/ raw stderr calls to console.Print*

Priority: Medium
Estimated Effort: Medium
Focus Area: Console Print Wrapper Gap

Description: Replace the 134 raw fmt.Fprintf(os.Stderr, ...) calls across pkg/workflow/ (top files: dependabot.go:19, compiler_validators.go:12, compiler.go:10, pip_validation.go:7, lock_validation.go:6, claude_logs.go:6) with console.Print* wrappers. Because pkg/workflow is a library package, it should not write to os.Stderr directly — it should either return errors or use the console package, which already handles TTY/WASM differences.

Acceptance Criteria:

• Zero fmt.Fprintf(os.Stderr calls in pkg/workflow/dependabot.go, compiler_validators.go, compiler.go, pip_validation.go, lock_validation.go, claude_logs.go.
• Messages use the appropriate semantic console.PrintWarningMessage / console.PrintInfoMessageStderr / console.PrintErrorMessage wrappers.
• make test-unit passes.

Code Region: pkg/workflow/dependabot.go, pkg/workflow/compiler_validators.go, pkg/workflow/compiler.go, pkg/workflow/pip_validation.go, pkg/workflow/lock_validation.go, pkg/workflow/claude_logs.go

In the listed files under `pkg/workflow/`, replace every `fmt.Fprintf(os.Stderr, ...)` and `fmt.Fprintln(os.Stderr, ...)` call with the appropriate `console.PrintXxx(...)` wrapper from `pkg/console`. Import `github.com/github/gh-aw/pkg/console` where not already present. Choose the semantic wrapper based on context: progress/info messages → `console.PrintInfoMessageStderr`; warnings → `console.PrintWarningMessage`; errors → `console.PrintErrorMessage`. Run `make fmt` and `make test-unit`.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-07-17	Error Chain Transparency & Non-Wrapping fmt.Errorf Gap	Custom	Y	788 non-wrapping errorf calls identified; errgroup gap found
2026-07-16	Options Struct Pattern Adoption for High-Arity Functions	Custom	Y	2 funcs over 9-param limit; 21 at limit; options struct candidates
2026-07-15	Compile-Time Interface Satisfaction Assertions	Custom	Y	Zero var _ Interface = (*Type)(nil) guards in 21 interfaces
2026-07-14	Logger Name Collision & Instantiation Hygiene	Custom	Y	3 duplicate logger names; 6 var log shadowing
2026-07-08	Deprecated API Alias Proliferation & Zombie Callsite Cleanup	Custom	Y	3 deprecated API callsites; zombie no-op function found

---

🎯 Recommendations

Immediate Actions (This Week)

1. Add Print* wrappers to pkg/console/console.go (Task 1) — Priority: High
2. Migrate engine_secrets.go and mcp_inspect_mcp.go as pilot files (Tasks 2 & 3) — Priority: High

Short-term Actions (This Month)

1. Add fmtfprintlnstderr linter (Task 4) to prevent regression — Priority: Medium
2. Migrate pkg/workflow/ raw stderr calls (Task 5) — Priority: Medium

Long-term Actions (This Quarter)

1. Run systematic migration across all 46+ remaining pkg/cli/ files using the new Print* wrappers — Priority: Low

---

📈 Success Metrics

• Two-step pattern calls: 1,640 → 0
• Raw fmt.Fprintf(os.Stderr) calls: 239 → 0
• Files with raw stderr writes: 53 → 0
• console.Print* wrappers: 1 (PrintBanner) → 12+

---

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 2 weeks

---

References:

• §29833692144

Generated by ⚡ Repository Quality Improvement Agent · sonnet46 70.8 AIC · ⌖ 6.24 AIC · ⊞ 6.6K · ◷

• expires on Jul 22, 2026, 5:25 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-22T13:25:30.250Z.

Closed by Workflow