action.yml

name: 'Usable PR Validator'
description: 'Validate Pull Requests against your Usable knowledge base standards using AI (OpenCode with OpenRouter, Anthropic, OpenAI, or Google Gemini) and Usable MCP integration'
author: 'Flowcore'

branding:
  icon: 'check-circle'
  color: 'green'

inputs:
  prompt-file:
    description: 'Path to validation prompt markdown file (optional if use-dynamic-prompts is enabled)'
    required: false
    default: ''
  use-dynamic-prompts:
    description: 'Fetch latest prompt from Usable API instead of using static prompt file'
    required: false
    default: 'false'
  prompt-fragment-id:
    description: 'Usable fragment UUID to use as prompt (required when use-dynamic-prompts is true)'
    required: false
    default: ''
  merge-custom-prompt:
    description: 'Merge fetched Usable prompt with custom prompt-file (only when both are provided)'
    required: false
    default: 'true'
  override-comment:
    description: 'User comment requesting validation override or clarification (typically from @usable mention)'
    required: false
    default: ''
  gemini-model:
    description: 'Gemini model to use (gemini-2.5-flash, gemini-2.0-flash, gemini-2.5-pro)'
    required: false
    default: 'gemini-2.5-flash'
  service-account-key-secret:
    description: 'Name of secret containing base64-encoded Gemini service account key'
    required: false
    default: 'GEMINI_SERVICE_ACCOUNT_KEY'
  mcp-server-url:
    description: 'HTTP URL of MCP server'
    required: false
    default: 'https://usable.dev/api/mcp'
  mcp-token-secret:
    description: 'Name of secret containing Usable API token'
    required: false
    default: 'USABLE_API_TOKEN'
  workspace-id:
    description: 'Usable workspace UUID (required - used to fetch MCP system prompt)'
    required: true
  fail-on-critical:
    description: 'Fail build when critical violations are found'
    required: false
    default: 'true'
  comment-mode:
    description: 'PR comment behavior: update, new, or none'
    required: false
    default: 'update'
  comment-title:
    description: 'Title for PR comment (used to identify which comment to update in multi-stage validations)'
    required: false
    default: 'Automated Standards Validation'
  artifact-retention-days:
    description: 'Days to retain validation report artifacts'
    required: false
    default: '30'
  max-retries:
    description: 'Maximum retry attempts for API failures'
    required: false
    default: '2'
  timeout-minutes:
    description: 'Maximum validation execution time in minutes'
    required: false
    default: '15'
  base-ref:
    description: 'Base reference for diff comparison (defaults to PR base branch). Useful for release-please branches to compare against last release tag.'
    required: false
    default: ''
  head-ref:
    description: 'Head reference for diff comparison (defaults to PR head branch)'
    required: false
    default: ''
  allow-web-fetch:
    description: 'Allow AI to use web_fetch tool for external resources (security consideration)'
    required: false
    default: 'false'
  provider:
    description: 'AI provider to use (opencode or gemini)'
    required: false
    default: 'opencode'
  opencode-provider:
    description: 'AI provider for OpenCode (e.g., openrouter, anthropic, openai)'
    required: false
    default: 'openrouter'
  opencode-model:
    description: 'Model ID for OpenCode (e.g., moonshotai/kimi-k2.5 for openrouter, claude-sonnet-4-5 for anthropic)'
    required: false
    default: 'moonshotai/kimi-k2.5'
  opencode-api-key-secret:
    description: 'Name of secret containing the API key for the configured opencode-provider'
    required: false
    default: 'OPENCODE_API_KEY'
  fallback-opencode-provider:
    description: 'Optional opencode-provider to fall back to when primary exhausts retries on retryable errors (e.g. 429/503/504/timeout). Empty disables fallback.'
    required: false
    default: ''
  fallback-opencode-model:
    description: 'Model ID for the fallback opencode-provider (required when fallback-opencode-provider is set)'
    required: false
    default: ''
  fallback-opencode-api-key-secret:
    description: 'Name of secret holding the fallback API key. Optional when fallback-opencode-provider equals opencode-provider (primary key is reused). Required when providers differ.'
    required: false
    default: ''

outputs:
  validation-status:
    description: 'Validation result: passed or failed'
    value: ${{ steps.validate.outputs.validation_status }}
  validation-passed:
    description: 'Boolean indicating if validation passed (true/false)'
    value: ${{ steps.validate.outputs.validation_passed }}
  critical-issues:
    description: 'Count of critical violations found'
    value: ${{ steps.validate.outputs.critical_issues }}
  report-artifact-name:
    description: 'Name of artifact containing validation report'
    value: ${{ steps.set-artifact-name.outputs.artifact_name }}

runs:
  using: 'composite'
  steps:
    - name: Validate inputs
      shell: bash
      run: |
        echo "::group::Validating inputs"
        
        # Check if workspace-id is provided
        if [ -z "${{ inputs.workspace-id }}" ]; then
          echo "::error::workspace-id is required"
          exit 1
        fi
        
        # Check if either prompt-file or use-dynamic-prompts is provided
        if [ -z "${{ inputs.prompt-file }}" ] && [ "${{ inputs.use-dynamic-prompts }}" != "true" ]; then
          echo "::error::Either prompt-file must be provided or use-dynamic-prompts must be enabled"
          exit 1
        fi
        
        # Check if prompt file exists (only if provided)
        if [ -n "${{ inputs.prompt-file }}" ] && [ ! -f "${{ inputs.prompt-file }}" ]; then
          echo "::error::Prompt file not found: ${{ inputs.prompt-file }}"
          exit 1
        fi
        
        # Validate comment mode
        if [[ ! "${{ inputs.comment-mode }}" =~ ^(update|new|none)$ ]]; then
          echo "::error::Invalid comment-mode. Must be: update, new, or none"
          exit 1
        fi
        
        # Validate boolean inputs
        if [[ ! "${{ inputs.use-dynamic-prompts }}" =~ ^(true|false)$ ]]; then
          echo "::error::Invalid use-dynamic-prompts. Must be: true or false"
          exit 1
        fi
        
        if [[ ! "${{ inputs.merge-custom-prompt }}" =~ ^(true|false)$ ]]; then
          echo "::error::Invalid merge-custom-prompt. Must be: true or false"
          exit 1
        fi
        
        if [[ ! "${{ inputs.allow-web-fetch }}" =~ ^(true|false)$ ]]; then
          echo "::error::Invalid allow-web-fetch. Must be: true or false"
          exit 1
        fi

        # Validate provider
        if [[ ! "${{ inputs.provider }}" =~ ^(opencode|gemini)$ ]]; then
          echo "::error::Invalid provider. Must be: opencode or gemini"
          exit 1
        fi

        # Validate fallback opencode-provider configuration
        FALLBACK_PROV="${{ inputs.fallback-opencode-provider }}"
        if [ -n "$FALLBACK_PROV" ]; then
          if [ "${{ inputs.provider }}" != "opencode" ]; then
            echo "::error::fallback-opencode-provider is only supported when provider=opencode"
            exit 1
          fi
          if [[ ! "$FALLBACK_PROV" =~ ^(openrouter|anthropic|openai)$ ]]; then
            echo "::error::Invalid fallback-opencode-provider. Must be: openrouter, anthropic, or openai"
            exit 1
          fi
          if [ -z "${{ inputs.fallback-opencode-model }}" ]; then
            echo "::error::fallback-opencode-model is required when fallback-opencode-provider is set"
            exit 1
          fi
          if [ "$FALLBACK_PROV" != "${{ inputs.opencode-provider }}" ] && [ -z "${{ inputs.fallback-opencode-api-key-secret }}" ]; then
            echo "::error::fallback-opencode-api-key-secret is required when fallback-opencode-provider differs from opencode-provider"
            exit 1
          fi
        fi

        echo "✅ All inputs validated successfully"
        echo "  Provider: ${{ inputs.provider }}"
        if [ -n "$FALLBACK_PROV" ]; then
          echo "  Fallback: ${FALLBACK_PROV}/${{ inputs.fallback-opencode-model }}"
        fi
        echo "::endgroup::"
    
    - name: Set Artifact Name
      id: set-artifact-name
      shell: bash
      run: |
        # Create a safe artifact name from the comment title
        TITLE="${{ inputs.comment-title }}"
        SAFE_NAME=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//')
        ARTIFACT_NAME="pr-validation-${SAFE_NAME}"
        echo "artifact_name=${ARTIFACT_NAME}" >> $GITHUB_OUTPUT
        echo "📦 Artifact name: ${ARTIFACT_NAME}"
    
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '20'
    
    - name: Install Gemini CLI
      if: inputs.provider == 'gemini'
      shell: bash
      run: |
        echo "::group::Installing Gemini CLI"
        npm install -g @google/gemini-cli@0.7.0
        echo "✅ Gemini CLI installed"
        echo "::endgroup::"

    - name: Install OpenCode CLI
      if: inputs.provider == 'opencode'
      shell: bash
      env:
        OPENCODE_PROVIDER: ${{ inputs.opencode-provider }}
        OPENCODE_SECRET_NAME: ${{ inputs.opencode-api-key-secret }}
      run: |
        ${{ github.action_path }}/scripts/setup-opencode.sh

    - name: Setup OpenCode Fallback Auth
      if: inputs.provider == 'opencode' && inputs.fallback-opencode-provider != '' && inputs.fallback-opencode-api-key-secret != ''
      shell: bash
      env:
        OPENCODE_PROVIDER: ${{ inputs.fallback-opencode-provider }}
        OPENCODE_SECRET_NAME: ${{ inputs.fallback-opencode-api-key-secret }}
      run: |
        ${{ github.action_path }}/scripts/setup-opencode.sh

    - name: Setup Git
      shell: bash
      env:
        BASE_REF: ${{ inputs.base-ref }}
        HEAD_REF: ${{ inputs.head-ref }}
        DEFAULT_BASE: ${{ github.event.pull_request.base.ref }}
        DEFAULT_HEAD: ${{ github.event.pull_request.head.ref }}
        MAX_RETRIES: ${{ inputs.max-retries }}
      run: |
        echo "::group::Configuring Git"
        git config --global user.email "action@github.com"
        git config --global user.name "GitHub Action"
        
        # Function to fetch ref with retry logic
        fetch_ref_with_retry() {
          local ref="$1"
          local ref_type="$2"
          local retry_count=0
          local max_retries="${MAX_RETRIES:-2}"
          
          while [ $retry_count -le $max_retries ]; do
            echo "Attempt $((retry_count + 1))/$((max_retries + 1)): Fetching $ref_type ref: $ref"
            
            # Try to fetch as a branch first
            if git fetch origin "$ref:refs/remotes/origin/$ref" 2>/dev/null; then
              echo "✅ Successfully fetched $ref_type ref as branch: $ref"
              return 0
            fi
            
            # Try as a tag
            if git fetch --tags origin "refs/tags/$ref:refs/tags/$ref" 2>/dev/null; then
              echo "✅ Successfully fetched $ref_type ref as tag: $ref"
              return 0
            fi
            
            # Try fetching all refs (fallback)
            if git fetch origin "+refs/heads/$ref:refs/remotes/origin/$ref" 2>/dev/null; then
              echo "✅ Successfully fetched $ref_type ref using explicit refspec: $ref"
              return 0
            fi
            
            retry_count=$((retry_count + 1))
            if [ $retry_count -le $max_retries ]; then
              wait_time=$((2 ** retry_count))
              echo "⚠️ Failed to fetch $ref. Retrying after ${wait_time} seconds..."
              sleep $wait_time
            else
              echo "::warning::Failed to fetch $ref_type ref: $ref after $((max_retries + 1)) attempts"
              return 1
            fi
          done
        }
        
        # Determine which refs to fetch
        BASE_TO_FETCH="${BASE_REF:-$DEFAULT_BASE}"
        HEAD_TO_FETCH="${HEAD_REF:-$DEFAULT_HEAD}"
        
        # Fetch base ref
        if [ -n "$BASE_TO_FETCH" ]; then
          if ! fetch_ref_with_retry "$BASE_TO_FETCH" "base"; then
            echo "::error::Failed to fetch base ref: $BASE_TO_FETCH"
            echo "This may cause diff operations to fail."
          fi
        else
          echo "::warning::No base ref specified"
        fi
        
        # Fetch head ref
        if [ -n "$HEAD_TO_FETCH" ]; then
          if ! fetch_ref_with_retry "$HEAD_TO_FETCH" "head"; then
            echo "::error::Failed to fetch head ref: $HEAD_TO_FETCH"
            echo "This may cause diff operations to fail."
          fi
        else
          echo "::warning::No head ref specified"
        fi
        
        # Verify refs are available for diff
        echo ""
        echo "Verifying refs..."
        if [ -n "$BASE_TO_FETCH" ]; then
          if git rev-parse "origin/$BASE_TO_FETCH" >/dev/null 2>&1; then
            echo "✅ Base ref available: origin/$BASE_TO_FETCH"
          elif git rev-parse "$BASE_TO_FETCH" >/dev/null 2>&1; then
            echo "✅ Base ref available: $BASE_TO_FETCH"
          else
            echo "::warning::Base ref not found locally: $BASE_TO_FETCH"
          fi
        fi
        
        if [ -n "$HEAD_TO_FETCH" ]; then
          if git rev-parse "origin/$HEAD_TO_FETCH" >/dev/null 2>&1; then
            echo "✅ Head ref available: origin/$HEAD_TO_FETCH"
          elif git rev-parse "$HEAD_TO_FETCH" >/dev/null 2>&1; then
            echo "✅ Head ref available: $HEAD_TO_FETCH"
          else
            echo "::warning::Head ref not found locally: $HEAD_TO_FETCH"
          fi
        fi
        
        echo ""
        echo "✅ Git configured"
        echo "::endgroup::"
    
    - name: Setup Gemini Authentication
      if: inputs.provider == 'gemini'
      shell: bash
      env:
        SECRET_NAME: ${{ inputs.service-account-key-secret }}
      run: |
        ${{ github.action_path }}/scripts/setup-gemini.sh

    - name: Setup MCP Server
      shell: bash
      env:
        MCP_URL: ${{ inputs.mcp-server-url }}
        MCP_SECRET_NAME: ${{ inputs.mcp-token-secret }}
        WORKSPACE_ID: ${{ inputs.workspace-id }}
        PROVIDER: ${{ inputs.provider }}
        OPENCODE_PROVIDER: ${{ inputs.opencode-provider }}
        OPENCODE_MODEL: ${{ inputs.opencode-model }}
        FALLBACK_OPENCODE_PROVIDER: ${{ inputs.fallback-opencode-provider }}
      run: |
        ${{ github.action_path }}/scripts/setup-mcp.sh
    
    - name: Fetch Prompts from Usable
      shell: bash
      env:
        USE_DYNAMIC_PROMPTS: ${{ inputs.use-dynamic-prompts }}
        PROMPT_FRAGMENT_ID: ${{ inputs.prompt-fragment-id }}
        WORKSPACE_ID: ${{ inputs.workspace-id }}
        CUSTOM_PROMPT_FILE: ${{ inputs.prompt-file }}
        MERGE_CUSTOM_PROMPT: ${{ inputs.merge-custom-prompt }}
        MCP_SECRET_NAME: ${{ inputs.mcp-token-secret }}
        ACTION_PATH: ${{ github.action_path }}
      run: |
        ${{ github.action_path }}/scripts/fetch-prompt.sh
    
    - name: Run Validation
      id: validate
      shell: bash
      env:
        PROMPT_FILE: ${{ inputs.prompt-file }}
        USE_DYNAMIC_PROMPTS: ${{ inputs.use-dynamic-prompts }}
        PROVIDER: ${{ inputs.provider }}
        GEMINI_MODEL: ${{ inputs.gemini-model }}
        OPENCODE_PROVIDER: ${{ inputs.opencode-provider }}
        OPENCODE_MODEL: ${{ inputs.opencode-model }}
        FALLBACK_OPENCODE_PROVIDER: ${{ inputs.fallback-opencode-provider }}
        FALLBACK_OPENCODE_MODEL: ${{ inputs.fallback-opencode-model }}
        MAX_RETRIES: ${{ inputs.max-retries }}
        PR_NUMBER: ${{ github.event.pull_request.number }}
        PR_TITLE: ${{ github.event.pull_request.title }}
        PR_DESCRIPTION: ${{ github.event.pull_request.body }}
        PR_URL: ${{ github.event.pull_request.html_url }}
        PR_AUTHOR: ${{ github.event.pull_request.user.login }}
        PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ', ') }}
        BASE_BRANCH: ${{ inputs.base-ref || github.event.pull_request.base.ref }}
        HEAD_BRANCH: ${{ inputs.head-ref || github.event.pull_request.head.ref }}
        OVERRIDE_COMMENT: ${{ inputs.override-comment }}
        COMMENT_AUTHOR: ${{ env.COMMENT_AUTHOR }}
        ALLOW_WEB_FETCH: ${{ inputs.allow-web-fetch }}
        GIT_PAGER: cat
      run: |
        ${{ github.action_path }}/scripts/validate.sh
    
    - name: Post PR Comment
      if: inputs.comment-mode != 'none' && always()
      uses: actions/github-script@v7
      with:
        github-token: ${{ github.token }}
        script: |
          const fs = require('fs');
          const commentMode = '${{ inputs.comment-mode }}';
          const commentTitle = '${{ inputs.comment-title }}';
          const reportPath = '/tmp/validation-report.md';
          
          if (!fs.existsSync(reportPath)) {
            console.log('⚠️ No validation report found to post');
            return;
          }
          
          const report = fs.readFileSync(reportPath, 'utf8');
          // Create a unique marker based on the comment title
          const markerId = commentTitle.toLowerCase().replace(/[^a-z0-9]+/g, '-');
          const marker = `<!-- usable-pr-validator:${markerId} -->`;
          
          const provider = '${{ inputs.provider }}';
          const modelInfo = provider === 'opencode'
            ? '${{ inputs.opencode-provider }}/${{ inputs.opencode-model }}'
            : 'Google Gemini ${{ inputs.gemini-model }}';

          const commentBody = marker + '\n## 🤖 ' + commentTitle + '\n\n' +
            report + '\n\n---\n<details>\n<summary>📊 Validation Statistics</summary>\n\n' +
            '- **Model**: ' + modelInfo + '\n' +
            '- **Standards Source**: ${{ inputs.mcp-server-url }}\n' +
            '- **Commit**: ' + context.payload.pull_request.head.sha.substring(0, 7) + '\n' +
            '- **Triggered by**: @' + context.actor + '\n\n' +
            '</details>';

          const { data: comments } = await github.rest.issues.listComments({
            owner: context.repo.owner,
            repo: context.repo.repo,
            issue_number: context.payload.pull_request.number,
          });
          
          const existingComment = comments.find(comment => 
            comment.body.includes(marker)
          );
          
          if (commentMode === 'update' && existingComment) {
            await github.rest.issues.updateComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              comment_id: existingComment.id,
              body: commentBody,
            });
            console.log('✅ Updated existing PR comment');
          } else {
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: commentBody,
            });
            console.log('✅ Created new PR comment');
          }
    
    - name: Upload Validation Report
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: ${{ steps.set-artifact-name.outputs.artifact_name }}
        path: /tmp/validation-report.md
        retention-days: ${{ fromJSON(inputs.artifact-retention-days) }}
        if-no-files-found: warn
    
    - name: Upload Full Output
      if: always()
      uses: actions/upload-artifact@v4
      with:
        name: ${{ steps.set-artifact-name.outputs.artifact_name }}-full
        path: /tmp/validation-full-output.md
        retention-days: ${{ fromJSON(inputs.artifact-retention-days) }}
        if-no-files-found: warn
    
    - name: Cleanup Secrets
      if: always()
      shell: bash
      run: |
        # Remove temporary files containing sensitive data
        rm -f /tmp/service-account.json
        rm -f /tmp/gemini-settings.json
        rm -f /tmp/gemini-stderr.log
        rm -f /tmp/opencode.json
        rm -f ./opencode.json
        echo "✅ Temporary files cleaned up"
    
    - name: Fail on Critical Violations
      if: inputs.fail-on-critical == 'true' && steps.validate.outputs.validation_passed == 'false'
      shell: bash
      run: |
        echo "::error::❌ Critical violations found in PR validation"
        echo "Critical issues: ${{ steps.validate.outputs.critical_issues }}"
        exit 1