[plan] Add preflight validation to compile command with `--validate` flag

[github-actions]

Objective

Enhance the gh aw compile command with comprehensive preflight validation that checks workflows before compilation to prevent failures and reduce wasted compilation time.

Context

The compile command (1,164 LOC) has only 17 error checks (1.5% of code), resulting in cryptic failures without prevention. Users need to detect issues early before attempting compilation.

Scope

Add validation that checks:

• Frontmatter syntax correctness
• Required fields presence
• Action version validity (not deprecated/archived)
• MCP server availability
• File system permissions
• GitHub API accessibility (for trial mode)

Approach

1. Validation Module (pkg/validation/preflight.go):

   • Create ValidateWorkflow(filePath string) (*ValidationReport, error) function
   • Check frontmatter syntax using existing parsers
   • Validate required fields against JSON schemas
   • Check action versions (detect deprecated/archived actions)
   • Verify MCP server references exist
   • Return structured ValidationReport with issues categorized by severity

2. Integration (pkg/cli/compile_command.go):

   • Add --validate flag (default: false for backwards compatibility)
   • Add --validate-only flag (validates without compiling)
   • Call ValidateWorkflow() before compilation when flag enabled
   • Display validation report using console formatting
   • Exit early on validation errors (unless --force specified)

3. Validation Report Structure:

   type ValidationReport struct {
       FilePath string
       Errors   []ValidationIssue  // Critical issues that prevent compilation
       Warnings []ValidationIssue  // Non-critical issues
       Infos    []ValidationIssue  // Suggestions/best practices
   }

Files to Modify

• Create: pkg/validation/preflight.go (validation logic)
• Create: pkg/validation/preflight_test.go (tests)
• Update: pkg/cli/compile_command.go (integrate validation)
• Update: pkg/cli/compile_command_test.go (add tests)
• Update: Documentation (validation examples)

Acceptance Criteria

• Add --validate flag to enable preflight validation before compilation
• Add --validate-only flag to validate without compiling
• Validation checks frontmatter syntax, required fields, action versions, MCP servers
• Reports validation results with severity levels (error/warning/info)
• Provides suggested fixes for each validation issue
• Integrates with existing compile command error handling
• Exits early on validation errors (unless --force flag used)
• Includes tests for validation scenarios
• Updates documentation with validation examples

Example Usage

# Validate before compiling
gh aw compile --validate ci-doctor.md

# Validate only, don't compile (CI mode)
gh aw compile --validate-only .github/workflows/*.md

# Force compile even with validation errors
gh aw compile --validate --force problem-workflow.md

References

• Existing validation: pkg/parser/frontmatter.go
• Schema validation: pkg/parser/schemas/
• Console formatting: pkg/console/console.go
• Similar patterns: validateCompileConfig() function
  Related to [plan] Implement CLI Resilience and Self-Healing Operations #5860

AI generated by Plan Command for discussion #5852