docs_pr_preview.yml

name: Docs PR preview

on:
  pull_request:
    paths:
      - "docs/**"
      - "frontend/src/site/**"
      - "frontend/public/**"
      - "public/**"
      - "scripts/build_github_pages_site.tsx"

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: docs-pr-preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout PR branch
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Validate route parity
        run: npm run validate:routes

      - name: Build UI (for compiled Tailwind CSS)
        run: npm run build:ui

      - name: Install Playwright browser (Chromium)
        run: npx playwright install --with-deps chromium

      - name: Build static site
        env:
          SITE_PREVIEW: "1"
          NEOTOMA_DOCS_SHOW_INTERNAL: "false"
        run: npm run build:site:pages

      - name: Validate locale parity
        run: npm run validate:locales

      - name: Validate site export
        run: npm run validate:site-export

      - name: Rewrite asset paths for subdirectory deploy
        env:
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          # Prerender and validation require root-absolute paths.
          # Rewrite all root-absolute static asset references so they resolve
          # under /pr-N/ when deployed to that subdirectory on dev.neotoma.io.
          find site_pages -name "*.html" -print0 | xargs -0 sed -i \
            -e "s|/assets/|/pr-${PR_NUMBER}/assets/|g" \
            -e "s|/neotoma-wordmark\.svg|/pr-${PR_NUMBER}/neotoma-wordmark.svg|g" \
            -e "s|/neotoma-hero\.png|/pr-${PR_NUMBER}/neotoma-hero.png|g" \
            -e "s|/neotoma-og-1200x630\.png|/pr-${PR_NUMBER}/neotoma-og-1200x630.png|g" \
            -e "s|/favicon\.ico|/pr-${PR_NUMBER}/favicon.ico|g" \
            -e "s|/favicon\.svg|/pr-${PR_NUMBER}/favicon.svg|g" \
            -e "s|/favicon-16x16\.png|/pr-${PR_NUMBER}/favicon-16x16.png|g" \
            -e "s|/favicon-32x32\.png|/pr-${PR_NUMBER}/favicon-32x32.png|g" \
            -e "s|/favicon-48x48\.png|/pr-${PR_NUMBER}/favicon-48x48.png|g" \
            -e "s|/apple-touch-icon\.png|/pr-${PR_NUMBER}/apple-touch-icon.png|g" \
            -e "s|/android-chrome-192x192\.png|/pr-${PR_NUMBER}/android-chrome-192x192.png|g" \
            -e "s|/android-chrome-512x512\.png|/pr-${PR_NUMBER}/android-chrome-512x512.png|g" \
            -e "s|/site\.webmanifest|/pr-${PR_NUMBER}/site.webmanifest|g"

      # The preview deploy pushes to the external markmhendrickson/neotoma-dev-site
      # repo using DEV_PAGES_DEPLOY_TOKEN. When that token is missing or expired the
      # deploy cannot succeed — but a docs preview is a convenience, not a gate, so a
      # bad/absent token must NOT paint every docs PR's checks red. We therefore gate
      # the deploy on token presence and mark it continue-on-error; the build/validation
      # steps above still run and still fail the check on real content problems.
      - name: Check deploy token presence
        id: deploy_token
        env:
          DEV_PAGES_DEPLOY_TOKEN: ${{ secrets.DEV_PAGES_DEPLOY_TOKEN }}
        run: |
          if [ -n "$DEV_PAGES_DEPLOY_TOKEN" ]; then
            echo "present=true" >> "$GITHUB_OUTPUT"
          else
            echo "present=false" >> "$GITHUB_OUTPUT"
            echo "::warning title=Docs preview not deployed::DEV_PAGES_DEPLOY_TOKEN is not set; skipping the preview deploy. The static site still built and validated above. See the preview-deploy rotation runbook to restore deploys."
          fi

      - name: Deploy PR preview
        id: deploy
        if: steps.deploy_token.outputs.present == 'true'
        continue-on-error: true
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.DEV_PAGES_DEPLOY_TOKEN }}
          external_repository: markmhendrickson/neotoma-dev-site
          publish_branch: gh-pages
          destination_dir: pr-${{ github.event.pull_request.number }}
          publish_dir: ./site_pages
          keep_files: true
          commit_message: "PR #${{ github.event.pull_request.number }} preview from ${{ github.sha }}"

      - name: Warn if preview deploy failed
        if: steps.deploy.outcome == 'failure'
        run: |
          echo "::warning title=Docs preview deploy failed::The static site built and validated, but pushing the preview to neotoma-dev-site failed (likely an expired DEV_PAGES_DEPLOY_TOKEN). This does not block the PR. See the preview-deploy rotation runbook to restore deploys."

      - name: Post preview URL as PR comment
        if: steps.deploy.outcome == 'success'
        uses: actions/github-script@v7
        with:
          script: |
            const pr = context.payload.pull_request.number;
            const previewUrl = `https://dev.neotoma.io/pr-${pr}/`;
            const body = [
              `### Docs preview`,
              ``,
              `**Preview URL:** ${previewUrl}`,
              ``,
              `Built from \`${{ github.sha }}\`. The preview is a static export — manifest-driven category ordering is not applied, but all doc content is rendered.`,
            ].join('\n');

            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: pr,
            });

            const existing = comments.find(c =>
              c.user.login === 'github-actions[bot]' && c.body.startsWith('### Docs preview')
            );

            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body,
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: pr,
                body,
              });
            }