publish.yml

name: Publish spec to GitHub Pages

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

# Scopes for the automatic, run-scoped GITHUB_TOKEN. No secrets or personal
# access tokens are needed: `id-token` lets the deploy job mint a short-lived
# OIDC token proving which repo and ref it runs from, which `deploy-pages`
# trades for Pages deployment access.
permissions:
  contents: read # check out the repo
  pages: write # create a Pages deployment
  id-token: write # request the OIDC token that authenticates it

# Never run two publishes at once; let a newer commit supersede an in-flight one.
concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    name: Render ReSpec snapshot
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Assemble site
        run: |
          mkdir -p _site/live
          # The live, client-side-rendered ReSpec page, for editors.
          cp index.html spec.md _site/live/
          # Sources that llms.txt and the spec itself link to.
          cp spec.md llms.txt _site/

      - name: Render static snapshot
        # --localhost serves the directory over HTTP so ReSpec's
        # data-include of spec.md can be fetched (file:// cannot).
        # --haltonerror is omitted: ReSpec reports "At least one editor is
        # required" as an error, which would fail every build until the
        # document names its editors.
        run: >
          npx respec@latest
          --src index.html
          --out _site/index.html
          --localhost
          --disable-sandbox
          --timeout 60

      - name: Verify the snapshot contains the full spec text
        run: |
          for phrase in "maximum privacy" "Authorization Capabilities" "Error Type Registry"; do
            grep -qF "$phrase" _site/index.html \
              || { echo "::error::snapshot is missing expected text: $phrase"; exit 1; }
          done
          echo "Snapshot: $(wc -c < _site/index.html) bytes"

      - uses: actions/upload-pages-artifact@v5
        with:
          path: _site

  deploy:
    name: Deploy to Pages
    # Pull requests build the snapshot as a check, but must not publish it.
    if: github.event_name != 'pull_request'
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5