update-prerelease-reference.yml

name: Update Prerelease Reference Pages

on:
  workflow_dispatch:
  push:
    branches:
      - prototype/ci-reference-pages  # TEMP: remove after testing
  schedule:
    # Run daily at 6am UTC
    - cron: "0 6 * * *"

jobs:
  check-and-update:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout prerelease branch
        uses: actions/checkout@v4
        with:
          ref: prerelease

      - name: Get current documented version
        id: current
        run: |
          version=$(jq -r '.version' docs/cli/cli-info.json)
          echo "version=$version" >> "$GITHUB_OUTPUT"
          echo "Current documented version: $version"

      - name: Get latest prerelease version
        id: latest
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # Find the latest prerelease from quarto-cli
          latest=$(gh api repos/quarto-dev/quarto-cli/releases \
            --jq '[.[] | select(.prerelease)] | .[0].tag_name' \
            | sed 's/^v//')
          echo "version=$latest" >> "$GITHUB_OUTPUT"
          echo "Latest prerelease version: $latest"

      - name: Check for existing PR
        id: check-pr
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # Check if there's already an open PR for this version
          pr_count=$(gh pr list \
            --base prerelease \
            --state open \
            --search "Update reference pages for v${{ steps.latest.outputs.version }}" \
            --json number \
            --jq 'length')
          echo "existing_pr=$pr_count" >> "$GITHUB_OUTPUT"
          echo "Existing PRs for this version: $pr_count"

      - name: Determine if update needed
        id: should-update
        run: |
          if [ "${{ steps.current.outputs.version }}" != "${{ steps.latest.outputs.version }}" ] && \
             [ "${{ steps.check-pr.outputs.existing_pr }}" = "0" ]; then
            echo "update=true" >> "$GITHUB_OUTPUT"
            echo "Update needed: new version available and no existing PR"
          else
            echo "update=false" >> "$GITHUB_OUTPUT"
            echo "No update needed"
          fi

      # --- Setup steps (only run if update needed) ---

      - name: Install Quarto (prerelease)
        if: steps.should-update.outputs.update == 'true'
        uses: quarto-dev/quarto-actions/setup@v2
        with:
          version: "pre-release"

      - name: Verify Quarto version
        if: steps.should-update.outputs.update == 'true'
        run: quarto --version

      - name: Clone quarto-cli at matching tag
        if: steps.should-update.outputs.update == 'true'
        run: |
          git clone --depth 1 --branch v${{ steps.latest.outputs.version }} \
            https://github.com/quarto-dev/quarto-cli.git \
            ../quarto-cli

      - name: Setup R
        if: steps.should-update.outputs.update == 'true'
        uses: r-lib/actions/setup-r@v2

      - name: Install R dependencies
        if: steps.should-update.outputs.update == 'true'
        uses: r-lib/actions/setup-r-dependencies@v2
        with:
          packages: |
            jsonlite
            knitr
            here
            tidyverse
            fansi
            xfun

      # --- Run reference generation scripts ---

      - name: Generate format/cell/project reference JSON
        if: steps.should-update.outputs.update == 'true'
        run: |
          quarto run tools/reference.ts

      - name: Generate CLI reference
        if: steps.should-update.outputs.update == 'true'
        run: |
          # Generate CLI info JSON
          quarto dev-call cli-info > docs/cli/cli-info.json
          # Generate markdown from JSON
          quarto run tools/reference-cli-generate-md.R

      # --- Create PR ---

      - name: Create branch and PR
        if: steps.should-update.outputs.update == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          version="${{ steps.latest.outputs.version }}"
          branch="auto/prerelease-reference-v${version}"

          git config user.name 'github-actions[bot]'
          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'

          git checkout -b "$branch"
          git add -A
          git commit -m "Update reference pages for v${version}"
          git push origin "$branch"

          gh pr create \
            --base prerelease \
            --head "$branch" \
            --title "Update reference pages for v${version}" \
            --body "$(cat <<EOF
          Automated update of reference documentation for Quarto prerelease v${version}.

          ## Changes
          - Format/cell/project reference JSON files (from \`tools/reference.ts\`)
          - CLI reference markdown files (from \`tools/reference-cli-generate-md.R\`)

          ## Review checklist
          - [ ] Spot check a few reference pages render correctly
          - [ ] No unexpected deletions
          EOF
          )"