build(ci): adopt prek for pre-commit hooks and CI autoformat

.envrc

@@ -1 +1,10 @@
 source .venv/bin/activate
+
+if ! command -v prek >/dev/null; then
+  echo "prek is not installed. Run: uv sync"
+  return 1
+fi
+
+if [[ ! -f .git/hooks/pre-commit ]] || ! grep -q "prek" .git/hooks/pre-commit; then
+  prek install --prepare-hooks -f
+fi

.github/workflows/build.yml

@@ -12,15 +12,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
         with:
           python-version: 3.13
 
       - run: |
           pip install uv
           uv build
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: ${{ github.sha }}
           path: dist/*

.github/workflows/pre-commit.yml

@@ -0,0 +1,92 @@
+name: pre-commit
+
+on:
+  pull_request:
+
+# Cancel in-progress runs on new pushes to the same ref.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  # Secrets cannot be referenced directly in `if` expressions. An unset secret
+  # is an empty string (not null), so compare against '' to detect its absence.
+  SECRET_ACCESS: ${{ toJSON(secrets.SENTRY_INTERNAL_APP_PRIVATE_KEY != '') }}
+
+jobs:
+  lint:
+    name: prek lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Get changed files
+        id: changes
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          # Paths to files will be available in the `${FILTER_NAME}_files` output.
+          list-files: json
+          # It doesn't make sense to lint deleted files.
+          filters: |
+            all:
+              - added|modified: '**/*'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: ~/.cache/prek
+          # setup-uv doesn't set env.pythonLocation, so key on the pinned
+          # Python version file instead to avoid reusing hooks across upgrades.
+          key: cache-epoch-1|${{ hashFiles('.python-version') }}|${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Setup prek
+        run: uv run prek prepare-hooks
+
+      - name: Run prek on changed files
+        id: prek
+        continue-on-error: true
+        env:
+          ALL_FILES: ${{ steps.changes.outputs.all_files }}
+        run: |
+          jq '.[]' --raw-output <<< "$ALL_FILES" |
+            xargs -r uv run prek run -q --files
+
+      - name: Get auth token
+        id: token
+        # Only push autofixes for trusted same-repo PRs; fork PRs run untrusted config.
+        if: >-
+          ${{
+            steps.prek.outcome == 'failure' &&
+            env.SECRET_ACCESS == 'true' &&
+            github.event_name == 'pull_request' &&
+            github.event.pull_request.head.repo.full_name == github.repository &&
+            !github.event.pull_request.draft
+          }}
+        uses: getsentry/action-github-app-token@d4b5da6c5e37703f8c3b3e43abb5705b46e159cc # v3.0.0
+        with:
+          app_id: ${{ vars.SENTRY_INTERNAL_APP_ID }}
+          private_key: ${{ secrets.SENTRY_INTERNAL_APP_PRIVATE_KEY }}
+
+      - name: Apply any prek fixes
+        if: ${{ steps.token.outcome == 'success' }}
+        uses: getsentry/action-github-commit@5972d5f578ad77306063449e718c0c2a6fbc4ae1 # v2.1.0
+        with:
+          github-token: ${{ steps.token.outputs.token }}
+          message: ':hammer_and_wrench: apply prek fixes'
+
+      - name: Fail job if prek failed
+        if: ${{ steps.prek.outcome == 'failure' }}
+        run: |
+          echo "prek checks failed. Please fix the issues and try again."
+          exit 1

.github/workflows/release.yml

@@ -34,14 +34,14 @@ jobs:
           app-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }}
           private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }}
 
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           token: ${{ steps.token.outputs.token }}
           fetch-depth: 0
           fetch-tags: true
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
 
       - name: Calculate version
         id: version
@@ -53,7 +53,7 @@ jobs:
           echo "new=$NEW" >> "$GITHUB_OUTPUT"
 
       - name: Prepare release
-        uses: getsentry/action-prepare-release@v1
+        uses: getsentry/action-prepare-release@c8e1c2009ab08259029170132c384f03c1064c0e # v1.6.6
         env:
           GITHUB_TOKEN: ${{ steps.token.outputs.token }}
         with:

.github/workflows/tests.yml

@@ -19,9 +19,9 @@ jobs:
     timeout-minutes: 10
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
     - name: Setup Python
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
       with:
         python-version: ${{ matrix.python }}
 

.pre-commit-config.yaml

@@ -9,6 +9,10 @@ repos:
     rev: v1.20.0
     hooks:
       - id: mypy
+        # Match CI's `mypy .`, which only type-checks `.py` files. The `bin/`
+        # CLI scripts are shebang'd Python that mypy's hook would otherwise
+        # pick up and flag on preexisting untyped code.
+        exclude: ^bin/
         additional_dependencies:
           - msgspec>=0.19.0
           - requests>=2.32.4

AGENTS.md

@@ -21,3 +21,12 @@ symmetric across providers and tools:
 
 Run `uv run pytest tests/`, `uv run ruff check src tests`, and
 `uv run mypy src` before committing.
+
+## Linting and formatting
+
+Linting and formatting are enforced with [prek](https://github.com/j178/prek)
+(a drop-in `pre-commit` runner) via `.pre-commit-config.yaml`. Running `uv sync`
+installs `prek`, and `direnv`/`.envrc` installs the git pre-commit hook
+automatically. Run the hooks manually with `uv run prek run --all-files`. CI
+runs the same hooks on every pull request and pushes any autofixes back to the
+branch.

pyproject.toml

@@ -44,7 +44,7 @@ select = [
 [dependency-groups]
 dev = [
     "mypy>=1.20.0",
-    "pre-commit>=4.5.1",
+    "prek>=0.3.6",
     "pyjwt[crypto]>=2.9.0",
     "pytest>=9.0.3",
     "pytest-cov>=7.1.0",