name: Sync man pages

# Keeps Hutch/Resources/man-pages.json — the official man-page list the More tab
# renders — in step with man.sr.ht, so the catalog is never hand-maintained.
#
# scripts/sync_man_pages.py re-derives the list from the man.sr.ht landing page.
# If the result differs from the committed copy, this opens (or updates) a pull
# request with the change. The script refuses to write a suspiciously short list,
# so an upstream markup change can't silently gut the catalog.
#
# Note: PRs opened with the default GITHUB_TOKEN do not themselves trigger other
# workflows (GitHub blocks that to avoid recursion), so the Tests workflow won't
# run on the auto-PR. That's fine here — the change is a bundled JSON resource —
# and a maintainer can push an empty commit to run CI if they ever want it.
on:
  schedule:
    # Weekly, Mondays 06:00 UTC. Upstream churns rarely; this is frequent enough.
    - cron: "0 6 * * 1"
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

concurrency:
  group: sync-man-pages
  cancel-in-progress: true

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Regenerate man page catalog
        run: python3 scripts/sync_man_pages.py

      - name: Open pull request on change
        uses: peter-evans/create-pull-request@22a9089034f40e5a961c8808d113e2c98fb63676 # v7
        with:
          add-paths: Hutch/Resources/man-pages.json
          branch: automated/man-page-catalog
          delete-branch: true
          commit-message: "Sync bundled man page catalog with man.sr.ht"
          title: "Sync bundled man page catalog"
          body: |
            Automated update: the official man-page list on man.sr.ht changed.

            Regenerated by `scripts/sync_man_pages.py`. Review the diff to
            `Hutch/Resources/man-pages.json` before merging.
          labels: documentation