Add tag-triggered PyPI release workflow with OIDC trusted publishing

Release on `v*.*.*` tag push:
build → publish-testpypi → smoke-test → publish-pypi → github-release

Uses PyPI Trusted Publishing (OIDC), so no long-lived API tokens in
secrets. The pyproject.toml version is validated against the tag in
the build step so a mismatched tag fails fast before we burn an
immutable TestPyPI version.

`workflow_dispatch` supports a `testpypi_only` dry-run path for
testing the pipeline without touching real PyPI; pairs with
scaffolded `pypi` and `testpypi` GitHub environments (both need
`id-token: write`). One-time setup required on pypi.org +
test.pypi.org to register the trusted publisher before first run —
documented inline in the workflow header.

.github/workflows/release.yml

@@ -0,0 +1,199 @@
+name: Release to PyPI
+
+# Tag-triggered release for `qcal-copilot`. Pipeline:
+#
+#   build → publish-testpypi → smoke-test-testpypi → publish-pypi → github-release
+#
+# Uses PyPI Trusted Publishing (OIDC), so no long-lived tokens in secrets.
+# BEFORE this workflow can publish, configure the trusted publisher once on
+# each index:
+#
+#   TestPyPI: https://test.pypi.org/manage/account/publishing/
+#   PyPI:     https://pypi.org/manage/account/publishing/
+#
+# For both, register:
+#   repo owner:    athurlow
+#   repo name:     qcal
+#   workflow:      release.yml
+#   environment:   pypi           (for PyPI)
+#                  testpypi       (for TestPyPI)
+#
+# Matching GitHub environments `pypi` and `testpypi` must exist with
+# `id-token: write` permitted — that's the only way OIDC tokens get minted.
+#
+# Manual dry-run: Actions tab → Run workflow → set `testpypi_only: true`
+# to publish a pre-release to TestPyPI without touching PyPI. The tag push
+# path always publishes to both.
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      testpypi_only:
+        description: "Publish to TestPyPI only (skip PyPI + GitHub release)"
+        type: boolean
+        default: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  # -------------------------------------------------------------------------
+  # 1. Build sdist + wheel once. Downstream jobs consume the artifact so the
+  #    exact bytes published to TestPyPI are the same ones published to PyPI.
+  # -------------------------------------------------------------------------
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+
+      # Fail the release if pyproject.toml's version doesn't match the tag,
+      # so we never ship a 0.1.0 wheel tagged as v0.2.0 (or vice versa).
+      # Skipped on workflow_dispatch since there's no tag to compare against.
+      - name: Verify pyproject version matches tag
+        if: github.event_name == 'push'
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version=$(python -c "
+          import tomllib, pathlib
+          print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])
+          ")
+          if [ "${tag_version}" != "${pkg_version}" ]; then
+            echo "::error::Tag v${tag_version} does not match pyproject.toml version ${pkg_version}."
+            echo "Bump pyproject.toml or retag before pushing."
+            exit 1
+          fi
+          echo "Version check OK: ${pkg_version}"
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: List built artifacts
+        run: ls -la dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # -------------------------------------------------------------------------
+  # 2. Publish to TestPyPI first, always.
+  # -------------------------------------------------------------------------
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/qcal-copilot/
+    permissions:
+      id-token: write  # required for Trusted Publishing OIDC
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # TestPyPI sometimes has leftover versions from prior dry runs;
+          # don't fail the release over it.
+          skip-existing: true
+
+  # -------------------------------------------------------------------------
+  # 3. Smoke-test: install from TestPyPI in a clean runner and assert that
+  #    the CLI + Python imports work. If this fails, do NOT publish to PyPI.
+  # -------------------------------------------------------------------------
+  smoke-test-testpypi:
+    name: Smoke-test TestPyPI install
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install from TestPyPI
+        run: |
+          # TestPyPI doesn't mirror transitive deps — fall back to PyPI for those.
+          # Retry a few times because TestPyPI's CDN takes 30-60s to propagate
+          # a fresh upload before the new version becomes resolvable.
+          for attempt in 1 2 3 4 5; do
+            if python -m pip install \
+                --index-url https://test.pypi.org/simple/ \
+                --extra-index-url https://pypi.org/simple/ \
+                qcal-copilot; then
+              exit 0
+            fi
+            echo "Attempt ${attempt} failed, sleeping before retry..."
+            sleep 15
+          done
+          echo "::error::pip install from TestPyPI failed after 5 attempts."
+          exit 1
+
+      - name: Verify CLI + imports
+        run: |
+          qcal version
+          python -c "
+          import qcal
+          from qcal import analyzer, codegen, data, decoder, fit, simulator, config, cli
+          assert qcal.__version__, 'missing __version__'
+          print('smoke test OK, version =', qcal.__version__)
+          "
+
+  # -------------------------------------------------------------------------
+  # 4. Publish to real PyPI. Skipped on workflow_dispatch dry runs.
+  # -------------------------------------------------------------------------
+  publish-pypi:
+    name: Publish to PyPI
+    needs: smoke-test-testpypi
+    if: github.event_name == 'push' || github.event.inputs.testpypi_only != 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/qcal-copilot/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  # -------------------------------------------------------------------------
+  # 5. Attach the built wheel + sdist to a GitHub Release, with auto-generated
+  #    notes. Tag-push only.
+  # -------------------------------------------------------------------------
+  github-release:
+    name: Create GitHub Release
+    needs: publish-pypi
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true