fix: add OS version to cache key to prevent binary incompatibility (#716)

## Summary

- Adds OS name and version (e.g., `ubuntu-22.04`, `macos-14`,
`windows-2022`) to cache keys to prevent binary incompatibility when
GitHub updates runner images
- Fixes issue where cached uv binaries compiled against older
glibc/library versions fail on newer runner OS versions

## Changes

- Added `getOSNameVersion()` function to `src/utils/platforms.ts` with
OS-specific detection for Linux (via `/etc/os-release`), macOS (Darwin
kernel version mapping), and Windows
- Updated cache key format to include OS version, bumped `CACHE_VERSION`
to `"2"`
- Added `cache-key` output to expose the generated cache key for
debugging
- Added `test-cache-key-os-version` job testing across multiple OS
versions
- Updated `docs/caching.md` with cache key documentation

Closes #703

.github/workflows/test.yml

@@ -385,10 +385,60 @@ jobs:
         with:
           persist-credentials: false
       - name: Install latest version
+        id: setup-uv
         uses: ./
+        with:
+          enable-cache: true
+      - name: Verify cache key contains alpine
+        run: |
+          echo "Cache key: $CACHE_KEY"
+          if echo "$CACHE_KEY" | grep -qv "alpine"; then
+            echo "Cache key does not contain 'alpine'"
+            exit 1
+          fi
+        shell: sh
+        env:
+          CACHE_KEY: ${{ steps.setup-uv.outputs.cache-key }}
       - run: uv sync
         working-directory: __tests__/fixtures/uv-project
 
+  test-cache-key-os-version:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-22.04
+            expected-os: "ubuntu-22.04"
+          - os: ubuntu-24.04
+            expected-os: "ubuntu-24.04"
+          - os: macos-14
+            expected-os: "macos-14"
+          - os: macos-15
+            expected-os: "macos-15"
+          - os: windows-2022
+            expected-os: "windows-2022"
+          - os: windows-2025
+            expected-os: "windows-2025"
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        with:
+          persist-credentials: false
+      - name: Setup uv
+        id: setup-uv
+        uses: ./
+        with:
+          enable-cache: true
+      - name: Verify cache key contains OS version
+        run: |
+          echo "Cache key: $CACHE_KEY"
+          if [[ "$CACHE_KEY" != *"${{ matrix.expected-os }}"* ]]; then
+            echo "Cache key does not contain expected OS version: ${{ matrix.expected-os }}"
+            exit 1
+          fi
+        shell: bash
+        env:
+          CACHE_KEY: ${{ steps.setup-uv.outputs.cache-key }}
+
   test-setup-cache:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -1002,6 +1052,7 @@ jobs:
       - test-python-version
       - test-activate-environment
       - test-musl
+      - test-cache-key-os-version
       - test-cache-local
       - test-cache-local-cache-disabled
       - test-cache-local-cache-disabled-but-explicit-path