[Code Quality] Integrate console formatting with validation errors

[github-actions]

Description

Bridge the gap between validation errors (currently plain text) and CLI console formatting to provide consistent, styled error display. Currently 0 validation errors use console formatting, leading to inconsistent user experience between validation errors and other CLI output.

Current Situation

Console Formatting Gap:

• 0 validation errors use console.FormatErrorMessage()
• Validation errors appear as plain text without color/emphasis
• Inconsistent with CLI command error handling patterns
• 22 direct stderr writes bypass console formatting system
• Users see unstyled errors in CLI context where other errors are styled

Current Pattern:

// CLI command (using console formatting)
fmt.Fprintln(os.Stderr, console.FormatErrorMessage("Failed to process"))

// Validation error (plain text, inconsistent)
fmt.Fprintln(os.Stderr, err)

Proposed Architecture

Design Principle: Separation of concerns

• Validation layer: Plain text errors (testable, reusable, framework-agnostic)
• CLI layer: Console formatting wrapper (user-facing, styled, accessible)

This approach:

• ✅ Keeps validation logic pure and testable
• ✅ Allows validation errors to be used in non-CLI contexts
• ✅ Centralizes formatting logic in CLI layer
• ✅ Maintains existing test coverage

Implementation Plan

Phase 1: Create Formatting Helper (Day 1)

Create pkg/cli/validation_output.go:

package cli

import (
    "fmt"
    "os"
    "strings"
    
    "github.com/githubnext/gh-aw/pkg/console"
)

// FormatValidationError formats validation errors for console output
// Preserves structured error content while applying console styling
func FormatValidationError(err error) string {
    if err == nil {
        return ""
    }
    
    errMsg := err.Error()
    
    // Detect multi-line structured errors (like GitHubToolsetValidationError)
    if strings.Contains(errMsg, "\n\n") || strings.HasPrefix(errMsg, "ERROR:") {
        // Preserve structure, apply styling to header only
        return console.FormatErrorMessage(errMsg)
    }
    
    // Standard single-line or simple multi-line error
    return console.FormatErrorMessage(errMsg)
}

// PrintValidationError prints a validation error to stderr with formatting
func PrintValidationError(err error) {
    if err == nil {
        return
    }
    fmt.Fprintln(os.Stderr, FormatValidationError(err))
}

Phase 2: Update CLI Commands (Day 1-2)

Pattern:

// OLD
if err := ValidateWorkflow(config); err != nil {
    fmt.Fprintln(os.Stderr, err)
    return err
}

// NEW
if err := ValidateWorkflow(config); err != nil {
    PrintValidationError(err)
    return err
}

Commands to update (minimum 5):

1. pkg/cli/compile_command.go - RunCompileWorkflow
2. pkg/cli/run_command.go - RunRunWorkflow
3. pkg/cli/mcp_inspect_command.go - inspect operations
4. pkg/cli/audit_command.go - validation failures
5. pkg/cli/compile_validation.go - all validation error prints

Phase 3: Testing (Day 2)

Create pkg/cli/validation_output_test.go:

• Verify styling applied correctly
• Verify structured errors preserve formatting
• Verify error content unchanged (only styling added)
• Test both simple and complex error types

Example Transformation

Before:

$ gh aw compile invalid.md
missing required field 'engine'

After:

$ gh aw compile invalid.md
✖ missing required field 'engine'. Example:
  engine: copilot

(where ✖ and error text are styled with red color)

Success Criteria

• New file pkg/cli/validation_output.go with FormatValidationError helper
• Helper detects error types and formats appropriately
• At least 5 CLI commands updated to use new formatting helper
• Validation errors now displayed with console.FormatErrorMessage styling
• Complex validation errors (like GitHubToolsetValidationError) preserve structure
• Tests in validation_output_test.go verify formatting doesn't alter error content
• Run make agent-finish successfully

Expected Outcomes

• Consistent styled output for all CLI errors (validation + command)
• Improved user experience with color/emphasis on errors
• Better accessibility through console formatting system
• Maintains validation layer purity (no CLI dependencies)

Priority

Medium - User experience improvement

Estimated Effort

Medium (1-2 days)

Files to Create

• pkg/cli/validation_output.go (new file)
• pkg/cli/validation_output_test.go (new file)

Files to Update

• pkg/cli/compile_command.go
• pkg/cli/run_command.go
• pkg/cli/mcp_inspect_command.go
• pkg/cli/audit_command.go
• pkg/cli/compile_validation.go

Related Issues

• Related to closed issue [Code Quality] Add console error formatting to MCP validation code #11511 (added console formatting to MCP validation)
• This issue is more comprehensive, covering all validation error output

Source

Extracted from Repository Quality Improvement Report #11292 - Validation Message Clarity & Developer Guidance (Task 5)

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 12, 2026, 9:09 PM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster