Merge remote-tracking branch 'origin/main' into fix/prevent-session-hang

Author: newbiehwang

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: monthly
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/comment-on-release.yml

@@ -13,13 +13,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
 
       - name: Get previous release
         id: previous_release
-        uses: actions/github-script@v7
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: |
             const currentTag = '${{ github.event.release.tag_name }}';
@@ -53,7 +53,7 @@ jobs:
 
       - name: Get merged PRs between releases
         id: get_prs
-        uses: actions/github-script@v7
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: |
             const currentTag = '${{ github.event.release.tag_name }}';
@@ -103,7 +103,7 @@ jobs:
             return Array.from(prNumbers);
 
       - name: Comment on PRs
-        uses: actions/github-script@v7
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: |
             const prNumbers = ${{ steps.get_prs.outputs.result }};

.github/workflows/main-checks.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "v1.x"]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: ["main", "v1.x"]
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    uses: ./.github/workflows/shared.yml
+
+  all-green:
+    if: always()
+    needs: [checks]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
+        with:
+          jobs: ${{ toJSON(needs) }}

.github/workflows/main.yml

@@ -9,20 +9,20 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Configure Git Credentials
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
         with:
           enable-cache: true
           version: 0.9.5
 
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+      - uses: actions/cache@9255dc7a253b0ccc959486e2bca901246202afeb # v5.0.1
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache

.github/workflows/publish-docs-manually.yml

@@ -10,10 +10,10 @@ jobs:
     runs-on: ubuntu-latest
     needs: [checks]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
         with:
           enable-cache: true
           version: 0.9.5
@@ -25,7 +25,7 @@ jobs:
         run: uv build
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
         with:
           name: release-dists
           path: dist/
@@ -44,34 +44,34 @@ jobs:
 
     steps:
       - name: Retrieve release distributions
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
         with:
           name: release-dists
           path: dist/
 
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
 
   docs-publish:
     runs-on: ubuntu-latest
     needs: ["pypi-publish"]
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
       - name: Configure Git Credentials
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
         with:
           enable-cache: true
           version: 0.9.5
 
       - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-      - uses: actions/cache@v4
+      - uses: actions/cache@9255dc7a253b0ccc959486e2bca901246202afeb # v5.0.1
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache

.github/workflows/publish-pypi.yml

@@ -13,16 +13,16 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
         with:
           enable-cache: true
           version: 0.9.5
       - name: Install dependencies
         run: uv sync --frozen --all-extras --python 3.10
 
-      - uses: pre-commit/action@v3.0.1
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
         with:
           extra_args: --all-files --verbose
         env:
@@ -39,15 +39,15 @@ jobs:
         dep-resolution:
           - name: lowest-direct
             install-flags: "--upgrade --resolution lowest-direct"
-          - name: highest
-            install-flags: "--upgrade --resolution highest"
+          - name: locked
+            install-flags: "--frozen"
         os: [ubuntu-latest, windows-latest]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
         with:
           enable-cache: true
           version: 0.9.5
@@ -65,9 +65,9 @@ jobs:
   readme-snippets:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
 
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
         with:
           enable-cache: true
           version: 0.9.5

.github/workflows/pull-request-checks.yml

@@ -0,0 +1,40 @@
+name: Weekly Lockfile Update
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Every Thursday at 8:00 UTC
+    - cron: "0 8 * * 4"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update-lockfile:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.1
+
+      - uses: astral-sh/setup-uv@v7.2.0
+        with:
+          version: 0.9.5
+
+      - name: Update lockfile
+        run: |
+          echo '## Updated Dependencies' > pr_body.md
+          echo '' >> pr_body.md
+          echo '```' >> pr_body.md
+          uv lock --upgrade 2>&1 | tee -a pr_body.md
+          echo '```' >> pr_body.md
+
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@98357b18bf14b5342f975ff684046ec3b2a07725 # v7
+        with:
+          commit-message: "chore: update uv.lock with latest dependencies"
+          title: "chore: weekly dependency update"
+          body-path: pr_body.md
+          branch: weekly-lockfile-update
+          delete-branch: true
+          add-paths: uv.lock
+          labels: dependencies

.github/workflows/shared.yml

@@ -6,9 +6,9 @@ This document contains critical information about working with this codebase. Fo
 
 1. Package Management
    - ONLY use uv, NEVER pip
-   - Installation: `uv add package`
-   - Running tools: `uv run tool`
-   - Upgrading: `uv add --dev package --upgrade-package package`
+   - Installation: `uv add <package>`
+   - Running tools: `uv run <tool>`
+   - Upgrading: `uv lock --upgrade-package <package>`
    - FORBIDDEN: `uv pip install`, `@latest` syntax
 
 2. Code Quality
@@ -21,6 +21,7 @@ This document contains critical information about working with this codebase. Fo
 3. Testing Requirements
    - Framework: `uv run --frozen pytest`
    - Async testing: use anyio, not asyncio
+   - Do not use `Test` prefixed classes, use functions
    - Coverage: test edge cases and errors
    - New features require tests
    - Bug fixes require regression tests
@@ -51,6 +52,17 @@ This document contains critical information about working with this codebase. Fo
 - NEVER ever mention a `co-authored-by` or similar aspects. In particular, never
   mention the tool used to create the commit message or PR.
 
+## Breaking Changes
+
+When making breaking changes, document them in `docs/migration.md`. Include:
+
+- What changed
+- Why it changed
+- How to migrate existing code
+
+Search for related sections in the migration guide and group related changes together
+rather than adding new standalone sections.
+
 ## Python Tools
 
 ## Code Formatting
@@ -66,12 +78,11 @@ This document contains critical information about working with this codebase. Fo
    - Line wrapping:
      - Strings: use parentheses
      - Function calls: multi-line with proper indent
-     - Imports: split into multiple lines
+     - Imports: try to use a single line
 
 2. Type Checking
    - Tool: `uv run --frozen pyright`
    - Requirements:
-     - Explicit None checks for Optional
      - Type narrowing for strings
      - Version warnings can be ignored if checks pass
 
@@ -106,10 +117,6 @@ This document contains critical information about working with this codebase. Fo
      - Add None checks
      - Narrow string types
      - Match existing patterns
-   - Pytest:
-     - If the tests aren't finding the anyio pytest mark, try adding PYTEST_DISABLE_PLUGIN_AUTOLOAD=""
-       to the start of the pytest run command eg:
-       `PYTEST_DISABLE_PLUGIN_AUTOLOAD="" uv run --frozen pytest`
 
 3. Best Practices
    - Check git status before commits
@@ -127,6 +134,4 @@ This document contains critical information about working with this codebase. Fo
   - File ops: `except (OSError, PermissionError):`
   - JSON: `except json.JSONDecodeError:`
   - Network: `except (ConnectionError, TimeoutError):`
-- **Only catch `Exception` for**:
-  - Top-level handlers that must not crash
-  - Cleanup blocks (log at debug level)
+- **FORBIDDEN** `except Exception:` - unless in top-level handlers