docs.yml

name: API Docs

# Builds TypeDoc on every PR and every push to main. Pushes to main also
# deploy the generated output to GitHub Pages. The site is intended for
# contributors and curious users who want to read the TS-level shapes
# (ParsedInputs, command result types, etc.); user-facing usage docs live
# in README.md.
#
# One-time setup: enable Pages in the repo Settings (Settings > Pages >
# Source: GitHub Actions). The first run will fail until that's flipped.

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

permissions:
  contents: read # needed to check out and build the docs source

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

jobs:
  build:
    name: Build docs
    if: ${{ github.actor != 'dependabot[bot]' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
        with:
          version: 11
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
        with:
          node-version: 24
          cache: pnpm

      - run: pnpm install --frozen-lockfile
      - run: pnpm run docs

      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        with:
          path: docs

  deploy:
    name: Deploy to GitHub Pages
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      pages: write # deploys the Pages artifact produced by the build job
      id-token: write # required for GitHub Pages OIDC deployment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0