docs-update-cli-ref.yml

# Automatically updates the CLI Commands Guide when CLI commands or options
# change between releases.
#
# Triggers: Manual (for testing) or on release (production)
# Testing: Use dry_run mode to review outputs without creating PRs
# See: documentation/automation/cli-command-tracking/TESTING.md

name: Update CLI Documentation

on:
  workflow_dispatch:  # Manual trigger for testing
    inputs:
      old_version:
        description: 'Previous version (e.g., v1.14.0). Leave empty to auto-detect.'
        required: false
        type: string
      new_version:
        description: 'New version (e.g., v1.15.0). Leave empty to use HEAD.'
        required: false
        type: string
      dry_run:
        description: 'Dry run mode - generate files but do not create PR'
        required: false
        type: boolean
        default: true
      
  # Automatic triggering on releases
  # Uses edited to catch when release-action updates the release with artifacts
  release:
    types: [edited]

permissions:
  contents: write       # Create branches and commit files
  pull-requests: write  # Create PRs

jobs:
  update-docs:
    name: Update CLI Documentation
    runs-on: ubuntu-latest
    
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0  # Fetch all history for version comparison
          fetch-tags: true  # Fetch all tags so we can checkout version tags
      
      - name: Fetch upstream tags (for forks)
        if: github.repository != 'aaif-goose/goose'
        run: |
          # Add upstream remote and fetch tags (only needed when testing in forks)
          git remote add upstream https://github.com/aaif-goose/goose.git || git remote set-url upstream https://github.com/aaif-goose/goose.git
          git fetch upstream --tags --force
          echo "✅ Fetched tags from upstream (fork mode)"
          echo "Total tags available: $(git tag | wc -l)"
      
      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y jq ripgrep
      
      - name: Set up Rust
        uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1.17.0
        with:
          toolchain: stable
      
      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.11'
      
      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '20'
      
      - name: Install goose CLI
        run: |
          mkdir -p /home/runner/.local/bin
          curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \
            | CONFIGURE=false GOOSE_BIN_DIR=/home/runner/.local/bin bash
          echo "/home/runner/.local/bin" >> $GITHUB_PATH
          goose --version
      
      - name: Configure goose for CI
        env:
          GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'anthropic' }}
          GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'claude-opus-4-5' }}
        run: |
          mkdir -p ~/.config/goose
          cat <<EOF > ~/.config/goose/config.yaml
          GOOSE_PROVIDER: $GOOSE_PROVIDER
          GOOSE_MODEL: $GOOSE_MODEL
          keyring: false
          EOF

          # Also export into the job environment so later steps can log the values
          echo "GOOSE_PROVIDER=$GOOSE_PROVIDER" >> "$GITHUB_ENV"
          echo "GOOSE_MODEL=$GOOSE_MODEL" >> "$GITHUB_ENV"

          echo "✅ Created goose config:"
          cat ~/.config/goose/config.yaml
      
      - name: Determine versions to compare
        id: versions
        env:
          GH_TOKEN: ${{ github.token }}
          INPUT_OLD_VERSION: ${{ github.event.inputs.old_version }}
          INPUT_NEW_VERSION: ${{ github.event.inputs.new_version }}
          EVENT_NAME: ${{ github.event_name }}
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: |
          get_previous_release() {
            gh release list --limit 2 --json tagName --jq '.[].tagName' | sed -n '2p'
          }
          
          if [ -n "$INPUT_OLD_VERSION" ]; then
            OLD_VERSION="$INPUT_OLD_VERSION"
          else
            OLD_VERSION=$(get_previous_release)
          fi
          
          if [ -n "$INPUT_NEW_VERSION" ]; then
            NEW_VERSION="$INPUT_NEW_VERSION"
          elif [ "$EVENT_NAME" = "release" ]; then
            NEW_VERSION="$RELEASE_TAG"
          else
            NEW_VERSION="HEAD"  # For testing unreleased changes
          fi
          
          if [ -z "$OLD_VERSION" ] || [ -z "$NEW_VERSION" ]; then
            echo "Error: Could not determine versions to compare"
            exit 1
          fi
          
          echo "old_version=$OLD_VERSION" >> $GITHUB_OUTPUT
          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
          echo "OLD_VERSION=$OLD_VERSION" >> $GITHUB_ENV
          echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
          
          echo "✅ Comparing $OLD_VERSION → $NEW_VERSION"
      
      - name: Extract and compare CLI structures
        id: extract
        timeout-minutes: 30  # Building goose takes time
        working-directory: documentation/automation/cli-command-tracking
        env:
          GOOSE_REPO: ${{ github.workspace }}
        run: |
          set -o pipefail  # Ensure pipeline failures are caught
          
          mkdir -p output
          ./scripts/run-pipeline.sh "$OLD_VERSION" "$NEW_VERSION" 2>&1 | tee output/pipeline.log
          
          HAS_CHANGES=$(jq -r '.has_changes' output/cli-changes.json)
          echo "has_changes=$HAS_CHANGES" >> $GITHUB_OUTPUT
          
          if [ "$HAS_CHANGES" = "false" ]; then
            echo "✅ No changes detected"
          else
            echo "✅ Changes detected"
          fi
      
      - name: Update goose-cli-commands.md (AI synthesis)
        if: steps.extract.outputs.has_changes == 'true'
        timeout-minutes: 10
        working-directory: documentation/automation/cli-command-tracking/output
        env:
          CLI_COMMANDS_PATH: ${{ github.workspace }}/documentation/docs/guides/goose-cli-commands.md
        run: |
          echo "🔍 Environment diagnostics:"
          echo "  GOOSE_PROVIDER: $GOOSE_PROVIDER"
          echo "  GOOSE_MODEL: $GOOSE_MODEL"
          echo "  ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:0:8}..." # Show first 8 chars only
          echo "  CLI_COMMANDS_PATH: $CLI_COMMANDS_PATH"
          echo "  HOME: $HOME"
          echo "  PATH: $PATH"
          echo ""
          echo "📁 Goose config file:"
          cat ~/.config/goose/config.yaml || echo "Config file not found!"
          echo ""
          echo "📁 Current directory:"
          pwd
          ls -la
          echo ""
          echo "🤖 Applying changes to goose-cli-commands.md..."
          goose run --recipe ../recipes/update-cli-commands.yaml
      
      - name: Upload automation outputs
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: cli-docs-update-${{ steps.versions.outputs.old_version }}-to-${{ steps.versions.outputs.new_version }}
          path: |
            documentation/automation/cli-command-tracking/output/*.json
            documentation/automation/cli-command-tracking/output/*.md
            documentation/automation/cli-command-tracking/output/*.log
          retention-days: 30
      
      - name: Create Pull Request
        if: |
          steps.extract.outputs.has_changes == 'true' && 
          (github.event.inputs.dry_run != 'true' || github.event_name == 'release')
        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1  # v8.1.1
        with:
          branch: docs/auto-cli-commands-${{ steps.versions.outputs.new_version }}
          delete-branch: true
          
          commit-message: |
            docs: Update CLI commands for ${{ steps.versions.outputs.new_version }}
            
            Automated update based on CLI changes between ${{ steps.versions.outputs.old_version }} and ${{ steps.versions.outputs.new_version }}.
          
          title: "docs: Update CLI Commands Guide for ${{ steps.versions.outputs.new_version }}"
          body: |
            ## Summary

            This PR updates the CLI Commands Guide based on command and option changes detected between **${{ steps.versions.outputs.old_version }}** and **${{ steps.versions.outputs.new_version }}**.

            ### Type of Change
            - [x] Documentation

            ### AI Assistance
            - [x] This PR was created or reviewed with AI assistance

            #### 🤖 Automation Details
            
            - **Workflow**: docs-update-cli-ref.yml
            - **Triggered by**: ${{ github.event_name }}
            - **Previous version**: ${{ steps.versions.outputs.old_version }}
            - **New version**: ${{ steps.versions.outputs.new_version }}
            
            #### 📋 Changes Detected
            
            Review the workflow artifacts for detailed change analysis:
            - cli-changes.json - Structured diff of changes
            - cli-changes.md - Human-readable change documentation
            - update-summary.md - Summary of documentation updates applied
            
            Download artifacts from the [workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}).
            
            ### ✅ Review Checklist
            
            - [ ] Verify all CLI changes are accurately documented
            - [ ] Check that examples are updated correctly
            - [ ] Ensure new commands are in the correct sections
            - [ ] Confirm no unintended changes were made
            
            ### 🔗 Related
            
            - Release: ${{ github.event.release.html_url || 'N/A' }}
            
            ---
            
            *This PR was automatically generated by the CLI Documentation Automation workflow.*
          
          labels: |
            documentation
            automated
            cli-commands
      
      - name: Workflow summary
        if: always()
        env:
          OLD_VERSION: ${{ steps.versions.outputs.old_version }}
          NEW_VERSION: ${{ steps.versions.outputs.new_version }}
          HAS_CHANGES: ${{ steps.extract.outputs.has_changes }}
          DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
        run: |
          echo "## 📊 CLI Documentation Update Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Version Comparison**: $OLD_VERSION → $NEW_VERSION" >> $GITHUB_STEP_SUMMARY
          echo "**Changes Detected**: $HAS_CHANGES" >> $GITHUB_STEP_SUMMARY
          echo "**Dry Run Mode**: $DRY_RUN" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          
          if [ "$HAS_CHANGES" = "true" ]; then
            echo "### ✅ Documentation Updated" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "The CLI Commands Guide has been updated to reflect changes in $NEW_VERSION." >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            
            if [ "$DRY_RUN" = "true" ]; then
              echo "**Note**: Running in dry-run mode - no PR was created. Review the artifacts to see the generated changes." >> $GITHUB_STEP_SUMMARY
            else
              echo "A pull request has been created with the documentation updates." >> $GITHUB_STEP_SUMMARY
            fi
          else
            echo "### ℹ️ No Changes Needed" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "No CLI command changes were detected between $OLD_VERSION and $NEW_VERSION." >> $GITHUB_STEP_SUMMARY
          fi
          
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### 📦 Artifacts" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "Download the workflow artifacts to review:" >> $GITHUB_STEP_SUMMARY
          echo "- Extracted CLI structures" >> $GITHUB_STEP_SUMMARY
          echo "- Change detection results" >> $GITHUB_STEP_SUMMARY
          echo "- Human-readable change documentation" >> $GITHUB_STEP_SUMMARY
          echo "- Documentation update summary" >> $GITHUB_STEP_SUMMARY