# Publish the documentation website to GitHub Pages. This workflow is manual-only
# (workflow_dispatch) and intentionally does not listen to pull_request or push:
# the site presents a released snapshot, so publication is an explicit act from a
# dsh-v* tag and must never appear as a PR check. `release:verify` rejects every
# other ref, and the github-pages environment repeats that restriction as a
# deployment tag policy with required reviewers.
#
# The build signal does not depend on this workflow. Every pull request builds
# the production site through `check:ci:static`, and ci-master.yml builds it
# again on master.
name: Deploy documentation

on:
  workflow_dispatch:

concurrency:
  group: github-pages
  cancel-in-progress: false

permissions:
  contents: read

env:
  PRIMARY_NODE_VERSION: '24'
  # Projected source links target the public repository, whose history can
  # differ from this workflow's source repository. This stays on master rather
  # than following the dispatched tag: that repository advances only to each
  # release commit, so its master never carries unreleased work, and it retains
  # only the most recent tags — following the tag would leave every projected
  # source link on an older deploy unresolvable.
  DOCS_REPOSITORY_REF: master
  # CI runs must never report to the production telemetry endpoint baked
  # into apps/cli/cordis.yml (AppCLIEntry disables the row when set).
  DSH_TELEMETRY_DISABLED: '1'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: read
    steps:
      # Complete history: the release scripts read tags.
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
          persist-credentials: false

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v6
        with:
          node-version: ${{ env.PRIMARY_NODE_VERSION }}
          cache: pnpm

      - name: Install (immutable)
        run: pnpm install --frozen-lockfile

      # One definition of "released" for the site and the npm sequence: this
      # rejects every ref that is not a dsh-v* tag naming the version this tree
      # carries.
      - name: Verify release version
        env:
          RELEASE_PUBLISH: 'true'
        run: pnpm run release:verify --family dsh

      - name: Configure Pages
        id: pages
        uses: actions/configure-pages@v6

      - name: Verify and build documentation
        env:
          DOCS_BASE: ${{ steps.pages.outputs.base_path }}/
        run: pnpm run doc-sync

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: website/.dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5