chore: update known checksums for 0.12.20 (#1076)

chore: update known checksums for 0.12.20

Co-authored-by: eifinger <1481961+eifinger@users.noreply.github.com>

.agents/skills/dependabot-pr-rollup/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: dependabot-pr-rollup
+description: Find open Dependabot PRs for the current GitHub repo, compare each PR head to its base branch, replay only the net dependency changes in a fresh worktree and branch, run npm validation, then commit, push, and open a pull request labeled dependencies. Use when you want to batch or manually replicate active Dependabot updates.
+license: MIT
+compatibility: Requires git, git worktree, gh CLI auth, npm, and a GitHub repo with an origin remote.
+---
+
+# Dependabot PR Rollup
+
+## When to use
+
+Use this skill when the user wants to:
+- find all open Dependabot PRs in the current repo
+- reproduce their net effect in one local branch
+- validate the result with the repo's standard npm checks
+- commit and push the validated changes, then open a PR labeled `dependencies`
+
+## Workflow
+
+1. Inspect the current checkout state, but do not reuse a dirty worktree.
+2. List open Dependabot PRs with `gh pr list --state open --author app/dependabot`.
+3. For each PR, collect the title, base branch, head branch, changed files, and relevant diffs.
+4. Compare each PR head against `origin/<base>` instead of trusting the PR title. Dependabot PRs can already be partially merged, superseded by newer versions, or have no remaining net effect.
+5. Create a new worktree and branch from `origin/<base>`.
+6. Reproduce only the remaining dependency changes in the new worktree.
+   - Inspect `package.json` before editing.
+   - Run `npm ci --ignore-scripts` before applying updates.
+   - Use `npm install ... --ignore-scripts` for direct dependency changes so `package-lock.json` stays in sync.
+   - When updating `@biomejs/biome`, also update the Biome schema URL version in `biome.json` to match the installed Biome version.
+7. Run `npm run all`.
+8. Commit the changed source, lockfile, and generated artifacts, then push the branch.
+9. Always open a pull request for the rollup and add the `dependencies` label to it. Pass `--label dependencies` to `gh pr create`, or add the label immediately afterward with `gh pr edit --add-label dependencies`.
+
+## Repo-specific notes
+
+- Use `gh` for GitHub operations.
+- Keep the user's original checkout untouched by working in a separate worktree.
+- In this repo, `npm run all` is the safest validation command because it runs build, check, package, and test.
+- If dependency changes affect bundled output, include the regenerated `dist/` files.
+
+## Report back
+
+Always report:
+- open Dependabot PRs found
+- which PRs required no net changes
+- new branch name
+- new worktree path
+- files changed
+- `npm run all` result
+- commit SHA and PR URL
+- confirmation that the PR has the `dependencies` label

.gitattributes

@@ -1,2 +1,3 @@
 * text=auto eol=lf
 dist/** -diff linguist-generated=true
+src/download/checksum/known-checksums.json linguist-generated=true

.github/actionlint.yaml

@@ -8,6 +8,10 @@ self-hosted-runner:
 # Empty array means no configuration variable is allowed.
 config-variables: null
 paths:
+  .github/workflows/**/*.{yml,yaml}:
+    ignore:
+      - 'specifying action "\$/" in invalid format because ref is missing'
+      - 'reusable workflow call "\$/.+" at "uses" is not following the format'
   .github/workflows/test.yml:
     ignore:
       - 'invalid runner name.+'

.github/copilot-instructions.md

@@ -1,225 +0,0 @@
-# Copilot Instructions for setup-uv
-
-This document provides essential information for GitHub Copilot coding agents working on the `astral-sh/setup-uv` repository.
-
-## Repository Overview
-
-**setup-uv** is a GitHub Action that sets up the [uv](https://docs.astral.sh/uv/) Python package installer in GitHub Actions workflows. It's a TypeScript-based action that downloads uv binaries, manages caching, handles version resolution, and configures the environment for subsequent workflow steps.
-
-### Key Features
-- Downloads and installs specific uv versions from GitHub releases
-- Supports version resolution from config files (pyproject.toml, uv.toml, .tool-versions)
-- Implements intelligent caching for both uv cache and Python installations
-- Provides cross-platform support (Linux, macOS, Windows, including ARM architectures)
-- Includes problem matchers for Python error reporting
-- Supports environment activation and custom tool directories
-
-## Repository Structure
-
-**Size**: Small-medium repository (~50 source files, ~400 total files including dependencies)
-**Languages**: TypeScript (primary), JavaScript (compiled output), JSON (configuration)
-**Runtime**: Node.js 24 (GitHub Actions runtime)
-**Key Dependencies**: @actions/core, @actions/cache, @actions/tool-cache, @octokit/core
-
-### Core Architecture
-```
-src/
-├── setup-uv.ts          # Main entry point and orchestration
-├── save-cache.ts        # Post-action cache saving logic
-├── update-known-versions.ts  # Maintenance script for version updates
-├── cache/               # Cache management functionality
-├── download/            # Version resolution and binary downloading
-├── utils/               # Input parsing, platform detection, configuration
-└── version/             # Version resolution from various file formats
-```
-
-### Key Files and Locations
-- **Action Definition**: `action.yml` - Defines all inputs/outputs and entry points
-- **Main Source**: `src/setup-uv.ts` - Primary action logic
-- **Configuration**: `biome.json` (linting), `tsconfig.json` (TypeScript), `jest.config.js` (testing)
-- **Compiled Output**: `dist/` - Contains compiled Node.js bundles (auto-generated, committed)
-- **Test Fixtures**: `__tests__/fixtures/` - Sample projects for different configuration scenarios
-- **Workflows**: `.github/workflows/test.yml` - Comprehensive CI/CD pipeline
-
-## Build and Development Process
-
-### Prerequisites
-- Node.js 24+ (matches GitHub Actions runtime)
-- npm (included with Node.js)
-
-### Essential Commands (ALWAYS run in this order)
-
-#### 1. Install Dependencies
-```bash
-npm install
-```
-**Timing**: ~20-30 seconds  
-**Note**: Always run this first after cloning or when package.json changes
-
-#### 2. Build TypeScript
-```bash
-npm run build
-```
-**Timing**: ~5-10 seconds  
-**Purpose**: Compiles TypeScript source to JavaScript in `lib/` directory
-
-#### 3. Lint and Format Code
-```bash
-npm run check
-```
-**Timing**: ~2-5 seconds  
-**Tool**: Biome (replaces ESLint/Prettier)  
-**Auto-fixes**: Formatting, import organization, basic linting issues
-
-#### 4. Package for Distribution
-```bash
-npm run package
-```
-**Timing**: ~20-30 seconds  
-**Purpose**: Creates bundled distributions in `dist/` using @vercel/ncc  
-**Critical**: This step MUST be run before committing - the `dist/` files are used by GitHub Actions
-
-#### 5. Run Tests
-```bash
-npm test
-```
-**Timing**: ~10-15 seconds  
-**Framework**: Jest with TypeScript support  
-**Coverage**: Unit tests for version resolution, input parsing, checksum validation
-
-#### 6. Complete Validation (Recommended)
-```bash
-npm run all
-```
-**Timing**: ~60-90 seconds  
-**Purpose**: Runs build → check → package → test in sequence  
-**Use**: Before making pull requests or when unsure about build state
-
-### Important Build Notes
-
-**CRITICAL**: Always run `npm run package` after making code changes. The `dist/` directory contains the compiled bundles that GitHub Actions actually executes. Forgetting this step will cause your changes to have no effect.
-
-**TypeScript Warnings**: You may see ts-jest warnings about "isolatedModules" - these are harmless and don't affect functionality.
-
-**Biome**: This project uses Biome instead of ESLint/Prettier. Run `npm run check` to fix formatting and linting issues automatically.
-
-## Testing Strategy
-
-### Unit Tests
-- **Location**: `__tests__/` directory
-- **Framework**: Jest with ts-jest transformer
-- **Coverage**: Version resolution, input parsing, checksum validation, utility functions
-
-### Integration Tests
-- **Location**: `.github/workflows/test.yml` 
-- **Scope**: Full end-to-end testing across multiple platforms and scenarios
-- **Key Test Categories**:
-  - Version installation (specific, latest, semver ranges)
-  - Cache behavior (setup, restore, invalidation)
-  - Cross-platform compatibility (Ubuntu, macOS, Windows, ARM)
-  - Configuration file parsing (pyproject.toml, uv.toml, requirements.txt)
-  - Error handling and edge cases
-
-### Test Fixtures
-Located in `__tests__/fixtures/`, these provide sample projects with different configurations:
-- `pyproject-toml-project/` - Standard Python project with uv version specification
-- `uv-toml-project/` - Project using uv.toml configuration
-- `requirements-txt-project/` - Legacy requirements.txt format
-- `cache-dir-defined-project/` - Custom cache directory configuration
-
-## Continuous Integration
-
-### GitHub Workflows
-
-#### Primary Test Suite (`.github/workflows/test.yml`)
-- **Triggers**: PRs, pushes to main, manual dispatch
-- **Matrix**: Multiple OS (Ubuntu, macOS, Windows), architecture (x64, ARM), and configuration combinations
-- **Duration**: ~20-30 minutes for full matrix
-- **Key Validations**:
-  - Cross-platform installation and functionality
-  - Cache behavior and performance
-  - Version resolution from various sources
-  - Tool directory configurations
-  - Problem matcher functionality
-
-#### Maintenance Workflows
-- **CodeQL Analysis**: Security scanning on pushes/PRs
-- **Update Known Versions**: Daily job to sync with latest uv releases
-- **Dependabot**: Automated dependency updates
-
-### Pre-commit Validation
-The CI runs these checks that you should run locally:
-1. `npm run all` - Complete build and test suite
-2. ActionLint - GitHub Actions workflow validation
-3. Change detection - Ensures no uncommitted build artifacts
-
-## Key Configuration Files
-
-### Action Configuration (`action.yml`)
-Defines 20+ inputs including version specifications, cache settings, tool directories, and environment options. This file is the authoritative source for understanding available action parameters.
-
-### TypeScript Configuration (`tsconfig.json`)
-- Target: ES2024
-- Module: nodenext (Node.js modules)
-- Strict mode enabled
-- Output directory: `lib/`
-
-### Linting Configuration (`biome.json`)
-- Formatter and linter combined
-- Enforces consistent code style
-- Automatically organizes imports and sorts object keys
-
-## Common Development Patterns
-
-### Making Code Changes
-1. Edit TypeScript source files in `src/`
-2. Run `npm run build` to compile
-3. Run `npm run check` to format and lint
-4. Run `npm run package` to update distribution bundles
-5. Run `npm test` to verify functionality
-6. Commit all changes including `dist/` files
-
-### Adding New Features
-- Follow existing patterns in `src/utils/inputs.ts` for new action inputs
-- Update `action.yml` to declare new inputs/outputs
-- Add corresponding tests in `__tests__/`
-- Update README.md with usage examples
-
-### Cache-Related Changes
-- Cache logic is complex and affects performance significantly
-- Test with multiple cache scenarios (hit, miss, invalidation)
-- Consider impact on both GitHub-hosted and self-hosted runners
-- Validate cache key generation and dependency detection
-
-### Version Resolution Changes
-- Version resolution supports multiple file formats and precedence rules
-- Test with fixtures in `__tests__/fixtures/`
-- Consider backward compatibility with existing projects
-- Validate semver and PEP 440 specification handling
-
-## Troubleshooting
-
-### Build Failures
-- **"Module not found"**: Run `npm install` to ensure dependencies are installed
-- **TypeScript errors**: Check `tsconfig.json` and ensure all imports are valid
-- **Test failures**: Check if test fixtures have been modified or if logic changes broke assumptions
-
-### Action Failures in Workflows
-- **Changes not taking effect**: Ensure `npm run package` was run and `dist/` files committed
-- **Version resolution issues**: Check version specification format and file existence
-- **Cache problems**: Verify cache key generation and dependency glob patterns
-
-### Common Gotchas
-- **Forgetting to package**: Code changes won't work without running `npm run package`
-- **Platform differences**: Windows paths use backslashes, test cross-platform behavior
-- **Cache invalidation**: Cache keys are sensitive to dependency file changes
-- **Tool directory permissions**: Some platforms require specific directory setups
-
-## Trust These Instructions
-
-These instructions are comprehensive and current. Only search for additional information if:
-- You encounter specific error messages not covered here
-- You need to understand implementation details of specific functions
-- The instructions appear outdated (check repository commit history)
-
-For most development tasks, following the build process and development patterns outlined above will be sufficient.

.github/dependabot.yml

@@ -4,8 +4,12 @@ updates:
     directory: /
     schedule:
       interval: daily
+    cooldown:
+      default-days: 30
 
   - package-ecosystem: npm
     directory: /
     schedule:
       interval: daily
+    cooldown:
+      default-days: 30

.github/release-drafter.yml

@@ -19,7 +19,7 @@ categories:
     labels:
       - "maintenance"
       - "ci"
-      - "update-known-versions"
+      - "update-known-checksums"
   - title: "📚 Documentation"
     labels:
       - "documentation"

.github/scripts/check-all-tests-passed-needs.js

@@ -1,16 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-var fs = require("node:fs");
-var yaml = require("js-yaml");
-var workflow = yaml.load(fs.readFileSync("../workflows/test.yml", "utf8"));
-var jobs = Object.keys(workflow.jobs);
-var allTestsPassed = workflow.jobs["all-tests-passed"];
-var needs = allTestsPassed.needs || [];
-var expectedNeeds = jobs.filter(function (j) { return j !== "all-tests-passed"; });
-var missing = expectedNeeds.filter(function (j) { return !needs.includes(j); });
-if (missing.length > 0) {
-    console.error("Missing jobs in all-tests-passed needs: ".concat(missing.join(", ")));
-    console.info("Please add the missing jobs to the needs section of all-tests-passed in test.yml.");
-    process.exit(1);
-}
-console.log("All jobs in test.yml are in the needs section of all-tests-passed.");

.github/scripts/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "es2022",
+    "types": ["node"]
+  },
+  "include": ["check-all-tests-passed-needs.ts"]
+}

.github/workflows/codeql-analysis.yml

@@ -41,13 +41,13 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@e296a935590eb16afc0c0108289f68c87e2a89a5 # v4.30.7
+        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
         with:
           languages: ${{ matrix.language }}
           source-root: src
@@ -59,7 +59,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@e296a935590eb16afc0c0108289f68c87e2a89a5 # v4.30.7
+        uses: github/codeql-action/autobuild@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -73,4 +73,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@e296a935590eb16afc0c0108289f68c87e2a89a5 # v4.30.7
+        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7

.github/workflows/release-drafter.yml

@@ -19,6 +19,8 @@ jobs:
       pull-requests: read
     steps:
       - name: 🚀 Run Release Drafter
-        uses: release-drafter/release-drafter@b1476f6e6eb133afa41ed8589daba6dc69b4d3f5 # v6.1.0
+        uses: release-drafter/release-drafter@34d80673e067bdc0c24568d3af899c216adcfaa9 # v7.7.0
+        with:
+          commitish: ${{ github.sha }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,124 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version (e.g., 8.1.0)"
+        required: true
+        type: string
+
+permissions: {}
+
+jobs:
+  validate-release:
+    name: Validate release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Validate version and draft release
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ inputs.version }}
+          TAG: v${{ inputs.version }}
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            echo "::error::Version must match MAJOR.MINOR.PATCH (e.g., 8.1.0)"
+            exit 1
+          fi
+
+          RELEASE_JSON=$(gh release view "$TAG" --json isDraft,targetCommitish 2>&1) || {
+            echo "::error::No release found for $TAG"
+            exit 1
+          }
+
+          IS_DRAFT=$(echo "$RELEASE_JSON" | jq -r '.isDraft')
+          TARGET=$(echo "$RELEASE_JSON" | jq -r '.targetCommitish')
+
+          if [[ "$IS_DRAFT" != "true" ]]; then
+            echo "::error::Release $TAG already exists and is not a draft"
+            exit 1
+          fi
+
+          if [[ "$TARGET" != "$GITHUB_SHA" ]]; then
+            echo "::error::Draft release target ($TARGET) does not match current commit ($GITHUB_SHA)"
+            exit 1
+          fi
+
+  release-gate:
+    # N.B. This name should not change, it is used for downstream checks.
+    name: release-gate
+    needs:
+      - validate-release
+    runs-on: ubuntu-latest
+    environment:
+      name: release-gate
+    steps:
+      - run: echo "Release approved"
+
+  create-deployment:
+    name: create-deployment
+    needs:
+      - validate-release
+      - release-gate
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+    steps:
+      - run: echo "Release deployment created"
+
+  release:
+    name: Release
+    needs:
+      - validate-release
+      - release-gate
+      - create-deployment
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish release
+        env:
+          GH_REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ inputs.version }}
+          TAG: v${{ inputs.version }}
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then
+            echo "::error::Version must match MAJOR.MINOR.PATCH (e.g., 8.1.0)"
+            exit 1
+          fi
+
+          RELEASE_JSON=$(gh release view "$TAG" --json isDraft,targetCommitish 2>&1) || {
+            echo "::error::No release found for $TAG"
+            exit 1
+          }
+
+          IS_DRAFT=$(echo "$RELEASE_JSON" | jq -r '.isDraft')
+          TARGET=$(echo "$RELEASE_JSON" | jq -r '.targetCommitish')
+
+          if [[ "$IS_DRAFT" != "true" ]]; then
+            echo "::error::Release $TAG already exists and is not a draft"
+            exit 1
+          fi
+
+          if [[ "$TARGET" != "$GITHUB_SHA" ]]; then
+            echo "::error::Draft release target ($TARGET) does not match current commit ($GITHUB_SHA)"
+            exit 1
+          fi
+
+          echo "Publishing draft release $TAG"
+          gh release edit "$TAG" --draft=false
+
+  update-docs:
+    name: Update docs
+    needs:
+      - release
+    uses: $/.github/workflows/update-docs.yml
+    permissions:
+      contents: write
+      pull-requests: write
+    with:
+      tag: v${{ inputs.version }}

.github/workflows/update-docs.yml

@@ -0,0 +1,75 @@
+name: "Update docs"
+on:
+  workflow_call:
+    inputs:
+      tag:
+        description: "Release tag to update docs for (e.g., v8.2.0)"
+        required: true
+        type: string
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  update-docs:
+    continue-on-error: ${{ github.event_name == 'workflow_call' }}
+    runs-on: ubuntu-24.04-arm
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+      - name: Get tag info
+        id: tag-info
+        run: |
+          if [ -n "$INPUT_TAG" ]; then
+            TAG_NAME="$INPUT_TAG"
+          else
+            TAG_NAME=$(git tag --list 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
+          fi
+
+          if [[ ! "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Tag must match vMAJOR.MINOR.PATCH (e.g., v8.2.0)"
+            exit 1
+          fi
+
+          COMMIT_SHA=$(git rev-list -n 1 "$TAG_NAME")
+          echo "tag=$TAG_NAME" >> "$GITHUB_OUTPUT"
+          echo "sha=$COMMIT_SHA" >> "$GITHUB_OUTPUT"
+        env:
+          INPUT_TAG: ${{ inputs.tag }}
+      - name: Update references in docs
+        run: |
+          OLD_REF=$(grep -oh 'astral-sh/setup-uv@[a-f0-9]\{40\} # v[0-9][^ ]*' README.md docs/*.md | head -1)
+          OLD_SHA=$(echo "$OLD_REF" | sed 's/astral-sh\/setup-uv@\([a-f0-9]*\) # .*/\1/')
+          OLD_VERSION=$(echo "$OLD_REF" | sed 's/astral-sh\/setup-uv@[a-f0-9]* # \(v[^ ]*\)/\1/')
+          echo "Replacing $OLD_SHA # $OLD_VERSION with $NEW_SHA # $NEW_VERSION"
+          find README.md docs/ -type f \( -name "*.md" \) -exec \
+            sed -i "s|$OLD_SHA # $OLD_VERSION|$NEW_SHA # $NEW_VERSION|g" {} +
+        env:
+          NEW_SHA: ${{ steps.tag-info.outputs.sha }}
+          NEW_VERSION: ${{ steps.tag-info.outputs.tag }}
+      - name: Check for changes
+        id: changes-exist
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+              echo "changes-exist=true" >> "$GITHUB_OUTPUT"
+          else
+              echo "changes-exist=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Create Pull Request
+        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          commit-message: "docs: update version references to ${{ steps.tag-info.outputs.tag }}"
+          title: "docs: update version references to ${{ steps.tag-info.outputs.tag }}"
+          body: |
+            Update `uses: astral-sh/setup-uv@...` references in documentation to
+            `${{ steps.tag-info.outputs.sha }} # ${{ steps.tag-info.outputs.tag }}`.
+          base: main
+          labels: "automated-pr,documentation"
+          branch: update-docs-${{ steps.tag-info.outputs.tag }}
+          delete-branch: true

.github/workflows/update-known-checksums.yml

@@ -0,0 +1,56 @@
+name: "Update known checksums"
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * *" # Run every day at 4am UTC
+  repository_dispatch:
+    types: [ pypi_release ]
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04-arm
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: true
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - name: Update known checksums
+        id: update-known-checksums
+        run:
+          node dist/update-known-checksums/index.cjs
+          src/download/checksum/known-checksums.json
+      - name: Check for changes
+        id: changes-exist
+        run: |
+          git status --porcelain
+          if [ -n "$(git status --porcelain)" ]; then
+              echo "changes-exist=true" >> "$GITHUB_OUTPUT"
+          else
+              echo "changes-exist=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Compile changes
+        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
+        run: npm ci --ignore-scripts && npm run all
+      - name: Create Pull Request
+        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          commit-message: "chore: update known checksums"
+          title:
+            "chore: update known checksums for ${{
+            steps.update-known-checksums.outputs.latest-version }}"
+          body:
+            "chore: update known checksums for ${{
+            steps.update-known-checksums.outputs.latest-version }}"
+          base: main
+          labels: "automated-pr,update-known-checksums"
+          branch: update-known-checksums-pr
+          delete-branch: true

.github/workflows/update-known-versions.yml

@@ -1,70 +0,0 @@
-name: "Update known versions"
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: "0 4 * * *" # Run every day at 4am UTC
-  repository_dispatch:
-    types: [ pypi_release ]
-
-permissions: {}
-
-jobs:
-  build:
-    runs-on: ubuntu-24.04-arm
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-        with:
-          persist-credentials: true
-      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: "20"
-      - name: Update known versions
-        id: update-known-versions
-        run:
-          node dist/update-known-versions/index.js
-          src/download/checksum/known-checksums.ts
-          version-manifest.json
-          ${{ secrets.GITHUB_TOKEN }}
-      - name: Check for changes
-        id: changes-exist
-        run: |
-          git status --porcelain
-          if [ -n "$(git status --porcelain)" ]; then
-              echo "changes-exist=true" >> "$GITHUB_OUTPUT"
-          else
-              echo "changes-exist=false" >> "$GITHUB_OUTPUT"
-          fi
-      - name: Compile changes
-        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
-        run: npm ci && npm run all
-      - name: Commit and push changes
-        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' }}
-        id: commit-and-push
-        continue-on-error: true
-        run: |
-          git config user.name "$GITHUB_ACTOR"
-          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
-          git add .
-          git commit -m "chore: update known versions for $LATEST_VERSION"
-          git push origin HEAD:refs/heads/main
-        env:
-          LATEST_VERSION: ${{ steps.update-known-versions.outputs.latest-version }}
-
-      - name: Create Pull Request
-        if: ${{ steps.changes-exist.outputs.changes-exist == 'true' && steps.commit-and-push.outcome != 'success' }}
-        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
-        with:
-          commit-message: "chore: update known checksums"
-          title:
-            "chore: update known checksums for ${{
-            steps.update-known-versions.outputs.latest-version }}"
-          body:
-            "chore: update known checksums for ${{
-            steps.update-known-versions.outputs.latest-version }}"
-          base: main
-          labels: "automated-pr,update-known-versions"
-          branch: update-known-versions-pr
-          delete-branch: true

.github/workflows/update-major-minor-tags.yml

@@ -1,51 +0,0 @@
----
-name: Update Major Minor Tags
-
-on:
-  push:
-    branches-ignore:
-      - "**"
-    tags:
-      - "v*.*.*"
-
-permissions: {}
-
-jobs:
-  update_major_minor_tags:
-    name: Make sure major and minor tags are up to date on a patch release
-    runs-on: ubuntu-24.04-arm
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-        with:
-          persist-credentials: true # needed for git push below
-      - name: Update Major Minor Tags
-        run: |
-          set -x
-
-          cd "${GITHUB_WORKSPACE}" || exit
-
-          # Set up variables.
-          TAG="${GITHUB_REF#refs/tags/}" # v1.2.3
-          MINOR="${TAG%.*}"              # v1.2
-          MAJOR="${MINOR%.*}"            # v1
-
-          if [ "${GITHUB_REF}" = "${TAG}" ]; then
-            echo "This workflow is not triggered by tag push: GITHUB_REF=${GITHUB_REF}"
-            exit 1
-          fi
-
-          MESSAGE="Release ${TAG}"
-
-          # Set up Git.
-          git config user.name "${GITHUB_ACTOR}"
-          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
-
-          # Update MAJOR/MINOR tag
-          git tag -fa "${MAJOR}" -m "${MESSAGE}"
-          git tag -fa "${MINOR}" -m "${MESSAGE}"
-
-          # Push
-          git push --force origin "${MINOR}"
-          git push --force origin "${MAJOR}"

.gitignore

@@ -100,3 +100,6 @@ lib/**/*
 
 # Idea IDEs (PyCharm, WebStorm, IntelliJ, etc)
 .idea/
+
+# Compiled scripts
+.github/scripts/*.js

.npmrc

@@ -0,0 +1,3 @@
+engine-strict = true
+ignore-scripts = true
+min-release-age = 7

.nvmrc

@@ -0,0 +1 @@
+24.19.0

AGENTS.md

@@ -0,0 +1,18 @@
+# setup-uv agent notes
+
+This repository is a TypeScript-based GitHub Action for installing `uv` in GitHub Actions workflows. It also supports restoring/saving the `uv` cache and optional managed-Python caching.
+
+- The published action runs the committed bundles in `dist/`, not the TypeScript in `src/`. After any code change, run `npm run package` and commit the resulting `dist/` updates.
+- Standard local validation is:
+  1. `npm ci --ignore-scripts`
+  2. `npm run all`
+- `npm run check` uses Biome (not ESLint/Prettier) and rewrites files in place.
+- User-facing changes are usually multi-file changes. If you add or change inputs, outputs, or behavior, update `action.yml`, `action-types.yml`, the implementation in `src/`, tests in `__tests__/`, relevant docs/README, and then re-package.
+- The easiest areas to regress are version resolution and caching. When touching them, add or update tests for precedence, cache invalidation, and cross-platform path behavior.
+- Workflow edits have extra CI-only checks (`actionlint` and `zizmor`); `npm run all` does not cover them.
+- Source is authored with bundler-friendly TypeScript, but published action artifacts in `dist/` are bundled as CommonJS for maximum GitHub Actions runtime compatibility with `@actions/*` dependencies.
+- Keep these concerns separate when changing module formats:
+  - `src/` and tests may use modern ESM-friendly TypeScript patterns.
+  - `dist/` should prioritize runtime reliability over format purity.
+  - Do not switch published bundles to ESM without validating the actual committed artifacts under the target Node runtime.
+- Before finishing, make sure validation does not leave generated or formatting-only diffs behind.

README.md

@@ -12,28 +12,11 @@ Set up your GitHub Actions workflow with a specific version of [uv](https://docs
 
 - [Usage](#usage)
   - [Install a required-version or latest (default)](#install-a-required-version-or-latest-default)
-  - [Install the latest version](#install-the-latest-version)
+  - [Inputs](#inputs)
-  - [Install a specific version](#install-a-specific-version)
+  - [Outputs](#outputs)
-  - [Install a version by supplying a semver range or pep440 specifier](#install-a-version-by-supplying-a-semver-range-or-pep440-specifier)
-  - [Install a version defined in a requirements or config file](#install-a-version-defined-in-a-requirements-or-config-file)
   - [Python version](#python-version)
-  - [Activate environment](#activate-environment)
   - [Working directory](#working-directory)
-  - [Validate checksum](#validate-checksum)
+- [Advanced Configuration](#advanced-configuration)
-  - [Enable Caching](#enable-caching)
-    - [Cache dependency glob](#cache-dependency-glob)
-    - [Restore cache](#restore-cache)
-    - [Save cache](#save-cache)
-  - [Local cache path](#local-cache-path)
-  - [Disable cache pruning](#disable-cache-pruning)
-  - [Cache Python installs](#cache-python-installs)
-  - [Ignore nothing to cache](#ignore-nothing-to-cache)
-  - [GitHub authentication token](#github-authentication-token)
-  - [UV_TOOL_DIR](#uv_tool_dir)
-  - [UV_TOOL_BIN_DIR](#uv_tool_bin_dir)
-  - [Tilde Expansion](#tilde-expansion)
-  - [Manifest file](#manifest-file)
-  - [Add problem matchers](#add-problem-matchers)
 - [How it works](#how-it-works)
 - [FAQ](#faq)
 
@@ -43,7 +26,7 @@ Set up your GitHub Actions workflow with a specific version of [uv](https://docs
 
 ```yaml
 - name: Install the latest version of uv
-  uses: astral-sh/setup-uv@v6
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 ```
 
 If you do not specify a version, this action will look for a [required-version](https://docs.astral.sh/uv/reference/settings/#required-version)
@@ -52,75 +35,140 @@ in a `uv.toml` or `pyproject.toml` file in the repository root. If none is found
 For an example workflow, see
 [here](https://github.com/charliermarsh/autobot/blob/e42c66659bf97b90ca9ff305a19cc99952d0d43f/.github/workflows/ci.yaml).
 
-### Install the latest version
+### Inputs
+
+All inputs and their defaults.
+Have a look under [Advanced Configuration](#advanced-configuration) for detailed documentation on most of them.
 
 ```yaml
-- name: Install the latest version of uv
+- name: Install uv with all available options
-  uses: astral-sh/setup-uv@v6
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
-    version: "latest"
+    # The version of uv to install, e.g., "0.5.0", "latest", or "latest-known" (default: searches for version in config files, then latest)
+    version: ""
+
+    # Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. A selected .tool-versions file can also provide the Python version (default: searches uv.toml then pyproject.toml)
+    version-file: ""
+
+    # Resolution strategy when resolving version ranges: 'highest' or 'lowest'
+    resolution-strategy: "highest"
+
+    # The version of Python to set UV_PYTHON to (overrides the Python version from .tool-versions)
+    python-version: ""
+
+    # Use uv venv to activate a venv ready to be used by later steps
+    activate-environment: "false"
+
+    # Custom path for the virtual environment when using activate-environment (default: .venv in the working directory)
+    venv-path: ""
+
+    # Pass --no-project when creating the venv with activate-environment.
+    no-project: "false"
+
+    # The directory to execute all commands in and look for files such as pyproject.toml
+    working-directory: ""
+
+    # The checksum of the uv version to install
+    checksum: ""
+
+    # Used when downloading uv from GitHub releases
+    github-token: ${{ github.token }}
+
+    # Enable the GitHub Actions cache for uv: true, false, or auto (enabled on GitHub-hosted runners except for release, tag push, pull_request_target, and workflow_run events; disabled on self-hosted runners)
+    enable-cache: "auto"
+
+    # Glob pattern to match files relative to the repository root to control the cache
+    cache-dependency-glob: |
+      **/*requirements*.txt
+      **/*requirements*.in
+      **/*constraints*.txt
+      **/*constraints*.in
+      **/pyproject.toml
+      **/uv.lock
+      **/*.py.lock
+
+    # Whether to restore the cache if found
+    restore-cache: "true"
+
+    # Whether to save the cache after the run: true, false, or auto (disabled for merge_group events)
+    save-cache: "auto"
+
+    # Suffix for the cache key
+    cache-suffix: ""
+
+    # Local path to store the cache (default: "" - uses system temp directory)
+    cache-local-path: ""
+
+    # Prune cache before saving
+    prune-cache: "false"
+
+    # Upload managed Python installations to the GitHub Actions cache
+    cache-python: "false"
+
+    # Ignore when nothing is found to cache
+    ignore-nothing-to-cache: "false"
+
+    # Ignore when the working directory is empty
+    ignore-empty-workdir: "false"
+
+    # Custom path to set UV_TOOL_DIR to
+    tool-dir: ""
+
+    # Custom path to set UV_TOOL_BIN_DIR to
+    tool-bin-dir: ""
+
+    # URL to a custom manifest file in the astral-sh/versions format
+    manifest-file: ""
+
+    # Download uv from the Astral mirror instead of directly from GitHub Releases
+    download-from-astral-mirror: "true"
+
+    # Add problem matchers
+    add-problem-matchers: "true"
+
+    # Suppress info-level log output. Only warnings and errors are shown
+    quiet: "false"
 ```
 
-### Install a specific version
+### Outputs
 
-```yaml
+- `uv-version`: The installed uv version. Useful when using latest.
-- name: Install a specific version of uv
+- `uv-path`: The path to the installed uv binary.
-  uses: astral-sh/setup-uv@v6
+- `uvx-path`: The path to the installed uvx binary.
-  with:
+- `cache-hit`: A boolean value to indicate a cache entry was found.
-    version: "0.4.4"
+- `venv`: Path to the activated venv if activate-environment is true.
-```
+- `python-version`: The Python version that was set.
-
+- `python-runtime-id`: An opaque identifier reported by uv for the activated venv's Python runtime. Empty when `activate-environment` is false.
-### Install a version by supplying a semver range or pep440 specifier
+- `python-cache-hit`: A boolean value to indicate the Python cache entry was found.
-
-You can specify a [semver range](https://github.com/npm/node-semver?tab=readme-ov-file#ranges)
-or [pep440 specifier](https://peps.python.org/pep-0440/#version-specifiers)
-to install the latest version that satisfies the range.
-
-```yaml
-- name: Install a semver range of uv
-  uses: astral-sh/setup-uv@v6
-  with:
-    version: ">=0.4.0"
-```
-
-```yaml
-- name: Pinning a minor version of uv
-  uses: astral-sh/setup-uv@v6
-  with:
-    version: "0.4.x"
-```
-
-```yaml
-- name: Install a pep440-specifier-satisfying version of uv
-  uses: astral-sh/setup-uv@v6
-  with:
-    version: ">=0.4.25,<0.5"
-```
-
-### Install a version defined in a requirements or config file
-
-You can use the `version-file` input to specify a file that contains the version of uv to install.
-This can either be a `pyproject.toml` or `uv.toml` file which defines a `required-version` or
-uv defined as a dependency in `pyproject.toml` or `requirements.txt`.
-
-[asdf](https://asdf-vm.com/) `.tool-versions` is also supported, but without the `ref` syntax.
-
-```yaml
-- name: Install uv based on the version defined in pyproject.toml
-  uses: astral-sh/setup-uv@v6
-  with:
-    version-file: "pyproject.toml"
-```
 
 ### Python version
 
 You can use the input `python-version` to set the environment variable `UV_PYTHON` for the rest of your workflow
 
-This will override any python version specifications in `pyproject.toml` and `.python-version`
+This will override any python version specifications in `pyproject.toml`, `.python-version`, and
+an explicitly selected `.tool-versions` file.
+
+When `version-file` points to `.tool-versions`, its `python` entry is used if neither
+`python-version` nor `UV_PYTHON` is set:
+
+```text
+uv 0.12.3
+python 3.13
+```
+
+```yaml
+- uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version-file: ".tool-versions"
+```
+
+Only a single Python version is supported. Filesystem paths are not supported for uv or Python.
+Multiple Python fallback versions and the asdf `ref:`, `path:`, and `system` forms are ignored with
+a warning.
 
 ```yaml
 - name: Install the latest version of uv and set the python version to 3.13t
-  uses: astral-sh/setup-uv@v6
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     python-version: 3.13t
 - run: uv pip install --python=3.13t pip
@@ -138,398 +186,45 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - name: Install the latest version of uv and set the python version
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Test with python ${{ matrix.python-version }}
         run: uv run --frozen pytest
 ```
 
-### Activate environment
-
-You can set `activate-environment` to `true` to automatically activate a venv.
-This allows directly using it in later steps:
-
-```yaml
-- name: Install the latest version of uv and activate the environment
-  uses: astral-sh/setup-uv@v6
-  with:
-    activate-environment: true
-- run: uv pip install pip
-```
-
-> [!WARNING]
->
-> Activating the environment adds your dependencies to the `PATH`, which could break some workflows.
-> For example, if you have a dependency which requires uv, e.g., `hatch`, activating the
-> environment will shadow the `uv` binary installed by this action and may result in a different uv
-> version being used.
->
-> We do not recommend using this setting for most use-cases. Instead, use `uv run` to execute
-> commands in the environment.
-
 ### Working directory
 
 You can set the working directory with the `working-directory` input.
 This controls where we look for `pyproject.toml`, `uv.toml` and `.python-version` files
 which are used to determine the version of uv and python to install.
 
-It also controls where [the venv gets created](#activate-environment).
+It also controls where [the venv gets created](#activate-environment), unless `venv-path` is set.
 
 ```yaml
 - name: Install uv based on the config files in the working-directory
-  uses: astral-sh/setup-uv@v6
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     working-directory: my/subproject/dir
 ```
 
-### Validate checksum
+## Advanced Configuration
 
-You can specify a checksum to validate the downloaded executable. Checksums up to the default version
+For more advanced configuration options, see our detailed documentation:
-are automatically verified by this action. The sha256 hashes can be found on the
-[releases page](https://github.com/astral-sh/uv/releases) of the uv repo.
 
-```yaml
+- **[Advanced Version Configuration](docs/advanced-version-configuration.md)** - Resolution strategies and version files
-- name: Install a specific version and validate the checksum
+- **[Caching](docs/caching.md)** - Complete guide to caching configuration
-  uses: astral-sh/setup-uv@v6
+- **[Environment and Tools](docs/environment-and-tools.md)** - Environment activation, tool directories, authentication, and environment variables
-  with:
+- **[Customization](docs/customization.md)** - Checksum validation, custom manifests, and problem matchers
-    version: "0.3.1"
-    checksum: "e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"
-```
-
-### Enable caching
-
-> [!NOTE]
-> The cache is pruned before it is uploaded to the GitHub Actions cache. This can lead to
-> a small or empty cache. See [Disable cache pruning](#disable-cache-pruning) for more details.
-
-If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be uploaded to
-the GitHub Actions cache. This can speed up runs that reuse the cache by several minutes.
-Caching is enabled by default on GitHub-hosted runners.
-
-> [!TIP]
->
-> On self-hosted runners this is usually not needed since the cache generated by uv on the runner's
-> filesystem is not removed after a run. For more details see [Local cache path](#local-cache-path).
-
-You can optionally define a custom cache key suffix.
-
-```yaml
-- name: Enable caching and define a custom cache key suffix
-  id: setup-uv
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    cache-suffix: "optional-suffix"
-```
-
-When the cache was successfully restored, the output `cache-hit` will be set to `true` and you can
-use it in subsequent steps. For example, to use the cache in the above case:
-
-```yaml
-- name: Do something if the cache was restored
-  if: steps.setup-uv.outputs.cache-hit == 'true'
-  run: echo "Cache was restored"
-```
-
-#### Cache dependency glob
-
-If you want to control when the GitHub Actions cache is invalidated, specify a glob pattern with the
-`cache-dependency-glob` input. The GitHub Actions cache will be invalidated if any file matching the glob pattern
-changes. If you use relative paths, they are relative to the repository root.
-
-> [!NOTE]
->
-> You can look up supported patterns [here](https://github.com/actions/toolkit/tree/main/packages/glob#patterns)
->
-> The default is
-> ```yaml
-> cache-dependency-glob: |
->   **/*requirements*.txt
->   **/*requirements*.in
->   **/*constraints*.txt
->   **/*constraints*.in
->   **/pyproject.toml
->   **/uv.lock
->   **/*.py.lock
-> ```
-
-```yaml
-- name: Define a cache dependency glob
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    cache-dependency-glob: "**/pyproject.toml"
-```
-
-```yaml
-- name: Define a list of cache dependency globs
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    cache-dependency-glob: |
-      **/requirements*.txt
-      **/pyproject.toml
-```
-
-```yaml
-- name: Define an absolute cache dependency glob
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    cache-dependency-glob: "/tmp/my-folder/requirements*.txt"
-```
-
-```yaml
-- name: Never invalidate the cache
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    cache-dependency-glob: ""
-```
-
-#### Restore cache
-
-Restoring an existing cache can be enabled or disabled with the `restore-cache` input.
-By default, the cache will be restored.
-
-```yaml
-- name: Don't restore an existing cache
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    restore-cache: false
-```
-
-#### Save cache
-
-You can also disable saving the cache after the run with the `save-cache` input.
-This can be useful to save cache storage when you know you will not use the cache of the run again.
-By default, the cache will be saved.
-
-```yaml
-- name: Don't save the cache after the run
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    save-cache: false
-```
-
-### Local cache path
-
-If caching is enabled, this action controls where uv stores its cache on the runner's filesystem
-by setting `UV_CACHE_DIR`.
-
-It defaults to `setup-uv-cache` in the `TMP` dir, `D:\a\_temp\uv-tool-dir` on Windows and
-`/tmp/setup-uv-cache` on Linux/macOS. You can change the default by specifying the path with the
-`cache-local-path` input.
-
-> [!NOTE]
-> If the environment variable `UV_CACHE_DIR` is already set this action will not override it.
-> If you configured [cache-dir](https://docs.astral.sh/uv/reference/settings/#cache-dir) in your
-> config file then it is also respected and this action will not set `UV_CACHE_DIR`.
-
-```yaml
-- name: Define a custom uv cache path
-  uses: astral-sh/setup-uv@v6
-  with:
-    cache-local-path: "/path/to/cache"
-```
-
-### Disable cache pruning
-
-By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining any
-wheels that were built from source. On GitHub-hosted runners, it's typically faster to omit those
-pre-built wheels from the cache (and instead re-download them from the registry on each run).
-However, on self-hosted or local runners, preserving the cache may be more efficient. See
-the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration) for
-more information.
-
-If you want to persist the entire cache across runs, disable cache pruning with the `prune-cache`
-input.
-
-```yaml
-- name: Don't prune the cache before saving it
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    prune-cache: false
-```
-
-### Cache Python installs
-
-By default, the Python install dir (`uv python dir` / `UV_PYTHON_INSTALL_DIR`) is not cached,
-for the same reason that the dependency cache is pruned.
-If you want to cache Python installs along with your dependencies, set the `cache-python` input to `true`.
-
-```yaml
-- name: Cache Python installs
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    cache-python: true
-```
-
-### Ignore nothing to cache
-
-By default, the action will fail if caching is enabled but there is nothing to upload (the uv cache directory does not exist).
-If you want to ignore this, set the `ignore-nothing-to-cache` input to `true`.
-
-```yaml
-- name: Ignore nothing to cache
-  uses: astral-sh/setup-uv@v6
-  with:
-    enable-cache: true
-    ignore-nothing-to-cache: true
-```
-
-### Ignore empty workdir
-
-By default, the action will warn if the workdir is empty, because this is usually the case when
-`actions/checkout` is configured to run after `setup-uv`, which is not supported.
-
-If you want to ignore this, set the `ignore-empty-workdir` input to `true`.
-
-```yaml
-- name: Ignore empty workdir
-  uses: astral-sh/setup-uv@v6
-  with:
-    ignore-empty-workdir: true
-```
-
-### GitHub authentication token
-
-This action uses the GitHub API to fetch the uv release artifacts. To avoid hitting the GitHub API
-rate limit too quickly, an authentication token can be provided via the `github-token` input. By
-default, the `GITHUB_TOKEN` secret is used, which is automatically provided by GitHub Actions.
-
-If the default
-[permissions for the GitHub token](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)
-are not sufficient, you can provide a custom GitHub token with the necessary permissions.
-
-```yaml
-- name: Install the latest version of uv with a custom GitHub token
-  uses: astral-sh/setup-uv@v6
-  with:
-    github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
-```
-
-### UV_TOOL_DIR
-
-On Windows `UV_TOOL_DIR` is set to `uv-tool-dir` in the `TMP` dir (e.g. `D:\a\_temp\uv-tool-dir`).
-On GitHub hosted runners this is on the much faster `D:` drive.
-
-On all other platforms the tool environments are placed in the
-[default location](https://docs.astral.sh/uv/concepts/tools/#tools-directory).
-
-If you want to change this behaviour (especially on self-hosted runners) you can use the `tool-dir`
-input:
-
-```yaml
-- name: Install the latest version of uv with a custom tool dir
-  uses: astral-sh/setup-uv@v6
-  with:
-    tool-dir: "/path/to/tool/dir"
-```
-
-### UV_TOOL_BIN_DIR
-
-On Windows `UV_TOOL_BIN_DIR` is set to `uv-tool-bin-dir` in the `TMP` dir (e.g.
-`D:\a\_temp\uv-tool-bin-dir`). On GitHub hosted runners this is on the much faster `D:` drive. This
-path is also automatically added to the PATH.
-
-On all other platforms the tool binaries get installed to the
-[default location](https://docs.astral.sh/uv/concepts/tools/#the-bin-directory).
-
-If you want to change this behaviour (especially on self-hosted runners) you can use the
-`tool-bin-dir` input:
-
-```yaml
-- name: Install the latest version of uv with a custom tool bin dir
-  uses: astral-sh/setup-uv@v6
-  with:
-    tool-bin-dir: "/path/to/tool-bin/dir"
-```
-
-### Tilde Expansion
-
-This action supports expanding the `~` character to the user's home directory for the following inputs:
-
-- `version-file`
-- `cache-local-path`
-- `tool-dir`
-- `tool-bin-dir`
-- `cache-dependency-glob`
-
-```yaml
-- name: Expand the tilde character
-  uses: astral-sh/setup-uv@v6
-  with:
-    cache-local-path: "~/path/to/cache"
-    tool-dir: "~/path/to/tool/dir"
-    tool-bin-dir: "~/path/to/tool-bin/dir"
-    cache-dependency-glob: "~/my-cache-buster"
-```
-
-### Manifest file
-
-The `manifest-file` input allows you to specify a JSON manifest that lists available uv versions,
-architectures, and their download URLs. By default, this action uses the manifest file contained
-in this repository, which is automatically updated with each release of uv.
-
-The manifest file contains an array of objects, each describing a version,
-architecture, platform, and the corresponding download URL. For example:
-
-```json
-[
-  {
-    "version": "0.7.13",
-    "artifactName": "uv-aarch64-apple-darwin.tar.gz",
-    "arch": "aarch64",
-    "platform": "apple-darwin",
-    "downloadUrl": "https://github.com/astral-sh/uv/releases/download/0.7.13/uv-aarch64-apple-darwin.tar.gz"
-  },
-  ...
-]
-```
-
-You can supply a custom manifest file URL to define additional versions,
-architectures, or different download URLs.
-This is useful if you maintain your own uv builds or want to override the default sources.
-
-```yaml
-- name: Use a custom manifest file
-  uses: astral-sh/setup-uv@v6
-  with:
-    manifest-file: "https://example.com/my-custom-manifest.json"
-```
-
-> [!NOTE]
-> When you use a custom manifest file and do not set the `version` input, its default value is `latest`.
-> This means the action will install the latest version available in the custom manifest file.
-> This is different from the default behavior of installing the latest version from the official uv releases.
-
-### Add problem matchers
-
-This action automatically adds
-[problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)
-for python errors.
-
-You can disable this by setting the `add-problem-matchers` input to `false`.
-
-```yaml
-- name: Install the latest version of uv without problem matchers
-  uses: astral-sh/setup-uv@v6
-  with:
-    add-problem-matchers: false
-```
 
 ## How it works
 
-This action downloads uv from the uv repo's official
+By default, this action resolves uv versions from the
-[GitHub Releases](https://github.com/astral-sh/uv) and uses the
+[`astral-sh/versions`](https://github.com/astral-sh/versions) manifest and downloads uv from the
-[GitHub Actions Toolkit](https://github.com/actions/toolkit) to cache it as a tool to speed up
+official [GitHub Releases](https://github.com/astral-sh/uv).
-consecutive runs on self-hosted runners.
+
+It then uses the [GitHub Actions Toolkit](https://github.com/actions/toolkit) to cache uv as a
+tool to speed up consecutive runs on self-hosted runners.
 
 The installed version of uv is then added to the runner PATH, enabling later steps to invoke it
 by name (`uv`).
@@ -541,7 +236,8 @@ by name (`uv`).
 With `setup-uv`, you can install a specific version of Python using `uv python install` rather than
 relying on `actions/setup-python`.
 
-Using `actions/setup-python` can be faster, because GitHub caches the Python versions alongside the runner.
+Using `actions/setup-python` can be faster (~1s), because GitHub includes several Python versions in the runner image
+which are available to get activated by `actions/setup-python` without having to download them.
 
 For example:
 
@@ -549,7 +245,7 @@ For example:
 - name: Checkout the repository
   uses: actions/checkout@main
 - name: Install the latest version of uv
-  uses: astral-sh/setup-uv@v6
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
 - name: Test
@@ -561,7 +257,7 @@ To install a specific version of Python, use
 
 ```yaml
 - name: Install the latest version of uv
-  uses: astral-sh/setup-uv@v6
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
   with:
     enable-cache: true
 - name: Install Python 3.12
@@ -580,7 +276,7 @@ output:
   uses: actions/checkout@main
 - name: Install the default version of uv
   id: setup-uv
-  uses: astral-sh/setup-uv@v6
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
 - name: Print the installed version
   run: echo "Installed uv version is ${{ steps.setup-uv.outputs.uv-version }}"
 ```
@@ -589,14 +285,13 @@ output:
 
 **Yes!**
 
-The cache key gets computed by using the [cache-dependency-glob](#cache-dependency-glob).
+The cache key gets computed by using the cache-dependency-glob (see [Caching documentation](docs/caching.md)).
 
-If you
+If you have jobs which use the same dependency definitions from `requirements.txt` or
-have jobs which use the same dependency definitions from `requirements.txt` or
 `pyproject.toml` but different
 [resolution strategies](https://docs.astral.sh/uv/concepts/resolution/#resolution-strategy),
 each job will have different dependencies or dependency versions.
-But if you do not add the resolution strategy as a [cache-suffix](#enable-caching),
+But if you do not add the resolution strategy as a cache-suffix (see [Caching documentation](docs/caching.md)),
 they will have the same cache key.
 
 This means the first job which starts uploading its cache will win and all other job will fail
@@ -609,15 +304,15 @@ You might see errors like
 ### Why do I see warnings like `No GitHub Actions cache found for key`
 
 When a workflow runs for the first time on a branch and has a new cache key, because the
-[cache-dependency-glob](#cache-dependency-glob) found changed files (changed dependencies),
+cache-dependency-glob (see [Caching documentation](docs/caching.md)) found changed files (changed dependencies),
 the cache will not be found and the warning `No GitHub Actions cache found for key` will be printed.
 
 While this might be irritating at first, it is expected behaviour and the cache will be created
 and reused in later workflows.
 
-The reason for the warning is, that we have to way to know if this is the first run of a new
+The reason for the warning is that we have to way to know if this is the first run of a new
-cache key or the user accidentally misconfigured the [cache-dependency-glob](#cache-dependency-glob)
+cache key or the user accidentally misconfigured the cache-dependency-glob
-or [cache-suffix](#enable-caching) and the cache never gets used.
+or cache-suffix (see [Caching documentation](docs/caching.md)) and the cache never gets used.
 
 ### Do I have to run `actions/checkout` before or after `setup-uv`?
 
@@ -628,7 +323,7 @@ Running `actions/checkout` after `setup-uv` **is not supported**.
 
 ### Does `setup-uv` also install my project or its dependencies automatically?
 
-No, `setup-uv` alone wont install any libraries from your `pyproject.toml` or `requirements.txt`, it only sets up `uv`.
+No, `setup-uv` alone won't install any libraries from your `pyproject.toml` or `requirements.txt`, it only sets up `uv`.
 You should run `uv sync` or `uv pip install .` separately, or use `uv run ...` to ensure necessary dependencies are installed.
 
 ### Why is a changed cache not detected and not the full cache uploaded?
@@ -642,11 +337,11 @@ if an uploaded cache exists for this key.
 If yes (e.g. contents of `uv.lock` did not change since last run) the dependencies in the cache
 are up to date and the cache will be downloaded and used.
 
-Details on determining which files will lead to different caches can be read under
+Details on determining which files will lead to different caches can be read in the
-[cache-dependency-glob](#cache-dependency-glob)
+[Caching documentation](docs/caching.md).
 
 Some dependencies will never be uploaded to the cache and will be downloaded again on each run
-as described in [disable-cache-pruning](#disable-cache-pruning)
+as described in the [Caching documentation](docs/caching.md).
 
 ## Acknowledgements
 

SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+Report suspected vulnerabilities according to [Astral's security policy](https://github.com/astral-sh/.github/blob/main/SECURITY.md).
+
+For this repository's security boundaries and reporting criteria, see the [setup-uv threat model](docs/threat-model.md).

__tests__/cache/restore-cache.test.ts

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import { createSetupInputs } from "../helpers/setup-inputs";
+
+const mockRestoreCache = jest.fn();
+const mockSaveState = jest.fn();
+const mockSetOutput = jest.fn();
+
+jest.unstable_mockModule("@actions/cache", () => ({
+  restoreCache: mockRestoreCache,
+}));
+
+jest.unstable_mockModule("@actions/core", () => ({
+  saveState: mockSaveState,
+  setOutput: mockSetOutput,
+}));
+
+jest.unstable_mockModule("../../src/hash/hash-files", () => ({
+  hashFiles: jest.fn(async () => "dependencyhash"),
+}));
+
+jest.unstable_mockModule("../../src/utils/logging", () => ({
+  info: jest.fn(),
+  warning: jest.fn(),
+}));
+
+jest.unstable_mockModule("../../src/utils/platforms", () => ({
+  getArch: jest.fn(() => "x86_64"),
+  getOSNameVersion: jest.fn(() => "ubuntu-24.04"),
+  getPlatform: jest.fn(async () => "unknown-linux-gnu"),
+}));
+
+const { restoreCache } = await import("../../src/cache/restore-cache");
+
+function cacheKeyOutput(): string {
+  const call = mockSetOutput.mock.calls.find(([name]) => name === "cache-key");
+  expect(call).toBeDefined();
+  return call?.[1] as string;
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe("restoreCache", () => {
+  it("encodes Python version ranges before adding them to the cache key", async () => {
+    await restoreCache(createSetupInputs(), ">3.10.11,<3.11");
+
+    const cacheKey = cacheKeyOutput();
+
+    expect(cacheKey).not.toContain(",");
+    expect(cacheKey).toContain("-%3E3.10.11%2C%3C3.11-");
+  });
+
+  it("encodes cache suffixes before adding them to the cache key", async () => {
+    const inputs = createSetupInputs({ cacheSuffix: "tests-3.10,3.11" });
+
+    await restoreCache(inputs, "3.11");
+
+    const cacheKey = cacheKeyOutput();
+
+    expect(cacheKey).not.toContain(",");
+    expect(cacheKey).toContain("-tests-3.10%2C3.11");
+  });
+
+  it("uses an unpruned cache key by default", async () => {
+    const inputs = createSetupInputs({ cacheSuffix: "tests-3.11" });
+
+    await restoreCache(inputs, "3.11");
+
+    expect(cacheKeyOutput()).toBe(
+      "setup-uv-2-x86_64-unknown-linux-gnu-ubuntu-24.04-3.11-dependencyhash-tests-3.11",
+    );
+  });
+});

__tests__/download/checksum/checksum.test.ts

@@ -4,10 +4,11 @@ import {
   validateChecksum,
 } from "../../../src/download/checksum/checksum";
 
-test("checksum should match", async () => {
+const validChecksum =
-  const validChecksum =
   "f3da96ec7e995debee7f5d52ecd034dfb7074309a1da42f76429ecb814d813a3";
-  const filePath = "__tests__/fixtures/checksumfile";
+const filePath = "__tests__/fixtures/checksumfile";
+
+test("checksum should match", async () => {
   // string params don't matter only test the checksum mechanism, not known checksums
   await validateChecksum(
     validChecksum,
@@ -18,6 +19,56 @@ test("checksum should match", async () => {
   );
 });
 
+test("provided checksum beats known checksums", async () => {
+  await validateChecksum(
+    validChecksum,
+    filePath,
+    "x86_64",
+    "unknown-linux-gnu",
+    "0.3.0",
+    "incorrect-manifest-checksum",
+  );
+});
+
+test("known checksums beat manifest checksums", async () => {
+  await expect(
+    validateChecksum(
+      undefined,
+      filePath,
+      "x86_64",
+      "unknown-linux-gnu",
+      "0.3.0",
+      validChecksum,
+    ),
+  ).rejects.toThrow("did not match");
+});
+
+test("manifest checksums are used when no known checksum exists", async () => {
+  await expect(
+    validateChecksum(
+      undefined,
+      filePath,
+      "aarch64",
+      "pc-windows-msvc",
+      "1.2.3",
+      "incorrect-manifest-checksum",
+    ),
+  ).rejects.toThrow("did not match");
+});
+
+test("empty manifest checksums are rejected", async () => {
+  await expect(
+    validateChecksum(
+      undefined,
+      filePath,
+      "aarch64",
+      "pc-windows-msvc",
+      "1.2.3",
+      "",
+    ),
+  ).rejects.toThrow("No checksum found");
+});
+
 type KnownVersionFixture = { version: string; known: boolean };
 
 it.each<KnownVersionFixture>([

__tests__/download/checksum/known-version.test.ts

@@ -0,0 +1,20 @@
+import { expect, it, jest } from "@jest/globals";
+
+jest.unstable_mockModule(
+  "../../../src/download/checksum/known-checksums",
+  () => ({
+    KNOWN_CHECKSUMS: {
+      "aarch64-apple-darwin-1.9.0": "checksum",
+      "x86_64-unknown-linux-gnu-1.8.0": "checksum",
+      "x86_64-unknown-linux-gnu-1.10.0": "checksum",
+    },
+  }),
+);
+
+const { getLatestKnownVersion } = await import(
+  "../../../src/download/checksum/known-version"
+);
+
+it("returns the highest version with a built-in checksum", () => {
+  expect(getLatestKnownVersion()).toBe("1.10.0");
+});

__tests__/download/checksum/update-known-checksums.test.ts

@@ -0,0 +1,27 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { expect, test } from "@jest/globals";
+import { updateChecksums } from "../../../src/download/checksum/update-known-checksums";
+
+test("serializes checksum entries as JSON data", async () => {
+  const tempDirectory = await fs.mkdtemp(
+    path.join(os.tmpdir(), "setup-uv-checksums-test-"),
+  );
+  const outputPath = path.join(tempDirectory, "known-checksums.json");
+  const key = 'platform-1.0.0"\n};\nglobalThis.compromised = true;';
+  const checksum = 'checksum"\\\nvalue';
+
+  try {
+    await updateChecksums(outputPath, [
+      { checksum, key },
+      { checksum: "duplicate", key },
+    ]);
+
+    const content = await fs.readFile(outputPath, "utf8");
+    expect(JSON.parse(content)).toEqual({ [key]: checksum });
+    expect(content.endsWith("\n")).toBe(true);
+  } finally {
+    await fs.rm(tempDirectory, { force: true, recursive: true });
+  }
+});

__tests__/download/custom-manifest.json

@@ -1,9 +0,0 @@
-[
-  {
-    "arch": "x86_64",
-    "artifactName": "uv-x86_64-unknown-linux-gnu.tar.gz",
-    "downloadUrl": "https://release.pyx.dev/0.7.12-alpha.1/uv-x86_64-unknown-linux-gnu.tar.gz",
-    "platform": "unknown-linux-gnu",
-    "version": "0.7.12-alpha.1"
-  }
-]

__tests__/download/custom-manifest.ndjson

@@ -0,0 +1 @@
+{"version":"0.9.26","artifacts":[{"platform":"x86_64-unknown-linux-gnu","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz","archive_format":"tar.gz","sha256":"30ccbf0a66dc8727a02b0e245c583ee970bdafecf3a443c1686e1b30ec4939e8"}]}

__tests__/download/download-version.test.ts

@@ -0,0 +1,484 @@
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import * as semver from "semver";
+import { VERSIONS_MANIFEST_URL } from "../../src/utils/constants";
+
+const mockInfo = jest.fn();
+const mockWarning = jest.fn();
+
+jest.unstable_mockModule("@actions/core", () => ({
+  debug: jest.fn(),
+  info: mockInfo,
+  warning: mockWarning,
+}));
+
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockDownloadTool = jest.fn<any>();
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockExtractTar = jest.fn<any>();
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockExtractZip = jest.fn<any>();
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockCacheDir = jest.fn<any>();
+
+jest.unstable_mockModule("@actions/tool-cache", () => ({
+  cacheDir: mockCacheDir,
+  downloadTool: mockDownloadTool,
+  evaluateVersions: (versions: string[], range: string) =>
+    semver.maxSatisfying(versions, range) ?? "",
+  extractTar: mockExtractTar,
+  extractZip: mockExtractZip,
+  find: () => "",
+  findAllVersions: () => [],
+  isExplicitVersion: (version: string) => semver.valid(version) !== null,
+}));
+
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockGetLatestVersion = jest.fn<any>();
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockGetAllVersions = jest.fn<any>();
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockGetFirstMatchingVersion = jest.fn<any>();
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockGetArtifact = jest.fn<any>();
+
+jest.unstable_mockModule("../../src/download/manifest", () => ({
+  getAllVersions: mockGetAllVersions,
+  getArtifact: mockGetArtifact,
+  getFirstMatchingVersion: mockGetFirstMatchingVersion,
+  getLatestVersion: mockGetLatestVersion,
+}));
+
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockValidateChecksum = jest.fn<any>();
+
+jest.unstable_mockModule("../../src/download/checksum/checksum", () => ({
+  validateChecksum: mockValidateChecksum,
+}));
+
+const mockGetLatestKnownVersion = jest.fn(() => "0.9.25");
+
+jest.unstable_mockModule("../../src/download/checksum/known-version", () => ({
+  getLatestKnownVersion: mockGetLatestKnownVersion,
+}));
+
+const { downloadVersion, resolveVersion, rewriteToMirror } = await import(
+  "../../src/download/download-version"
+);
+
+describe("download-version", () => {
+  beforeEach(() => {
+    mockInfo.mockReset();
+    mockWarning.mockReset();
+    mockDownloadTool.mockReset();
+    mockExtractTar.mockReset();
+    mockExtractZip.mockReset();
+    mockCacheDir.mockReset();
+    mockGetLatestVersion.mockReset();
+    mockGetAllVersions.mockReset();
+    mockGetFirstMatchingVersion.mockReset();
+    mockGetArtifact.mockReset();
+    mockValidateChecksum.mockReset();
+    mockGetLatestKnownVersion.mockClear();
+
+    mockDownloadTool.mockResolvedValue("/tmp/downloaded");
+    mockExtractTar.mockResolvedValue("/tmp/extracted");
+    mockExtractZip.mockResolvedValue("/tmp/extracted");
+    mockCacheDir.mockResolvedValue("/tmp/cached");
+  });
+
+  describe("resolveVersion", () => {
+    it("uses the default manifest to resolve latest", async () => {
+      mockGetLatestVersion.mockResolvedValue("0.9.26");
+
+      const version = await resolveVersion("latest", undefined);
+
+      expect(version).toBe("0.9.26");
+      expect(mockGetLatestVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetLatestVersion).toHaveBeenCalledWith(undefined);
+    });
+
+    it("resolves latest-known without reading the manifest", async () => {
+      const version = await resolveVersion("latest-known", undefined);
+
+      expect(version).toBe("0.9.25");
+      expect(mockGetLatestKnownVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetLatestVersion).not.toHaveBeenCalled();
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+      expect(mockGetFirstMatchingVersion).not.toHaveBeenCalled();
+    });
+
+    it("stops at the first matching version in the default manifest", async () => {
+      mockGetFirstMatchingVersion.mockImplementation(
+        (predicate: (version: string) => boolean) =>
+          ["0.9.26", "0.9.25"].find(predicate),
+      );
+
+      const version = await resolveVersion("^0.9.0", undefined);
+
+      expect(version).toBe("0.9.26");
+      expect(mockGetFirstMatchingVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+    });
+
+    it("streams ranges when the default manifest URL is explicit", async () => {
+      mockGetFirstMatchingVersion.mockImplementation(
+        (predicate: (version: string) => boolean) =>
+          ["0.9.26", "0.9.25"].find(predicate),
+      );
+
+      const version = await resolveVersion("^0.9.0", VERSIONS_MANIFEST_URL);
+
+      expect(version).toBe("0.9.26");
+      expect(mockGetFirstMatchingVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+    });
+
+    it("streams PEP 440 ranges from the default manifest", async () => {
+      mockGetFirstMatchingVersion.mockImplementation(
+        (predicate: (version: string) => boolean) =>
+          ["0.9.26", "0.9.25"].find(predicate),
+      );
+
+      const version = await resolveVersion("!=0.9.26", undefined);
+
+      expect(version).toBe("0.9.25");
+      expect(mockGetFirstMatchingVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+    });
+
+    it("treats == exact pins as explicit versions", async () => {
+      const version = await resolveVersion("==0.9.26", undefined);
+
+      expect(version).toBe("0.9.26");
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+      expect(mockGetLatestVersion).not.toHaveBeenCalled();
+    });
+
+    it("uses latest for minimum-only ranges when using the highest strategy", async () => {
+      mockGetLatestVersion.mockResolvedValue("0.9.26");
+
+      const version = await resolveVersion(">=0.9.0", undefined, "highest");
+
+      expect(version).toBe("0.9.26");
+      expect(mockGetLatestVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetLatestVersion).toHaveBeenCalledWith(undefined);
+      expect(mockGetAllVersions).not.toHaveBeenCalled();
+    });
+
+    it("uses the lowest compatible version when requested", async () => {
+      mockGetAllVersions.mockResolvedValue(["0.9.26", "0.9.25"]);
+
+      const version = await resolveVersion("^0.9.0", undefined, "lowest");
+
+      expect(version).toBe("0.9.25");
+      expect(mockGetAllVersions).toHaveBeenCalledTimes(1);
+      expect(mockGetAllVersions).toHaveBeenCalledWith(undefined);
+    });
+
+    it("uses manifest-file when provided", async () => {
+      mockGetAllVersions.mockResolvedValue(["0.9.26", "0.9.25"]);
+
+      const version = await resolveVersion(
+        "^0.9.0",
+        "https://example.com/custom.ndjson",
+      );
+
+      expect(version).toBe("0.9.26");
+      expect(mockGetAllVersions).toHaveBeenCalledWith(
+        "https://example.com/custom.ndjson",
+      );
+    });
+  });
+
+  describe("downloadVersion", () => {
+    it("fails when manifest lookup fails", async () => {
+      mockGetArtifact.mockRejectedValue(new Error("manifest unavailable"));
+
+      await expect(
+        downloadVersion(
+          "unknown-linux-gnu",
+          "x86_64",
+          "0.9.26",
+          undefined,
+          "token",
+        ),
+      ).rejects.toThrow("manifest unavailable");
+
+      expect(mockDownloadTool).not.toHaveBeenCalled();
+      expect(mockValidateChecksum).not.toHaveBeenCalled();
+    });
+
+    it("fails when no matching artifact exists in the default manifest", async () => {
+      mockGetArtifact.mockResolvedValue(undefined);
+
+      await expect(
+        downloadVersion(
+          "unknown-linux-gnu",
+          "x86_64",
+          "0.9.26",
+          undefined,
+          "token",
+        ),
+      ).rejects.toThrow(
+        "Could not find artifact for version 0.9.26, arch x86_64, platform unknown-linux-gnu in https://raw.githubusercontent.com/astral-sh/versions/main/v1/uv.ndjson .",
+      );
+
+      expect(mockDownloadTool).not.toHaveBeenCalled();
+      expect(mockValidateChecksum).not.toHaveBeenCalled();
+    });
+
+    it("uses the default manifest checksum as a fallback", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "manifest-checksum",
+        downloadUrl: "https://example.com/uv.tar.gz",
+      });
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        undefined,
+        "token",
+      );
+
+      expect(mockValidateChecksum).toHaveBeenCalledWith(
+        undefined,
+        "/tmp/downloaded",
+        "x86_64",
+        "unknown-linux-gnu",
+        "0.9.26",
+        "manifest-checksum",
+      );
+    });
+
+    it("rewrites GitHub Releases URLs to the Astral mirror", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "abc123",
+        downloadUrl:
+          "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+      });
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        undefined,
+        "token",
+      );
+
+      expect(mockDownloadTool).toHaveBeenCalledWith(
+        "https://releases.astral.sh/github/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+        undefined,
+        undefined,
+      );
+    });
+
+    it("does not send the token to non-GitHub URLs from the default manifest", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "abc123",
+        downloadUrl: "https://example.com/uv.tar.gz",
+      });
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        undefined,
+        "token",
+      );
+
+      expect(mockDownloadTool).toHaveBeenCalledWith(
+        "https://example.com/uv.tar.gz",
+        undefined,
+        undefined,
+      );
+    });
+
+    it("does not send the token to GitHub lookalike hosts", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "abc123",
+        downloadUrl: "https://github.com.evil.test/uv.tar.gz",
+      });
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        undefined,
+        "token",
+      );
+
+      expect(mockDownloadTool).toHaveBeenCalledWith(
+        "https://github.com.evil.test/uv.tar.gz",
+        undefined,
+        undefined,
+      );
+    });
+
+    it("falls back to GitHub Releases when the mirror fails", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "abc123",
+        downloadUrl:
+          "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+      });
+
+      mockDownloadTool
+        .mockRejectedValueOnce(new Error("mirror unavailable"))
+        .mockResolvedValueOnce("/tmp/downloaded");
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        undefined,
+        "token",
+      );
+
+      expect(mockDownloadTool).toHaveBeenCalledTimes(2);
+      expect(mockDownloadTool).toHaveBeenNthCalledWith(
+        1,
+        "https://releases.astral.sh/github/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+        undefined,
+        undefined,
+      );
+      expect(mockDownloadTool).toHaveBeenNthCalledWith(
+        2,
+        "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+        undefined,
+        "token",
+      );
+      expect(mockWarning).toHaveBeenCalledWith(
+        "Failed to download from mirror, falling back to GitHub Releases: mirror unavailable",
+      );
+    });
+
+    it("does not fall back for non-GitHub URLs", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "abc123",
+        downloadUrl: "https://example.com/uv.tar.gz",
+      });
+
+      mockDownloadTool.mockRejectedValue(new Error("download failed"));
+
+      await expect(
+        downloadVersion(
+          "unknown-linux-gnu",
+          "x86_64",
+          "0.9.26",
+          undefined,
+          "token",
+        ),
+      ).rejects.toThrow("download failed");
+
+      expect(mockDownloadTool).toHaveBeenCalledTimes(1);
+    });
+
+    it("uses manifest-file checksum metadata when checksum input is unset", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "manifest-checksum",
+        downloadUrl: "https://example.com/custom-uv.tar.gz",
+      });
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        "",
+        "token",
+        "https://example.com/custom.ndjson",
+      );
+
+      expect(mockValidateChecksum).toHaveBeenCalledWith(
+        "manifest-checksum",
+        "/tmp/downloaded",
+        "x86_64",
+        "unknown-linux-gnu",
+        "0.9.26",
+        "manifest-checksum",
+      );
+    });
+
+    it("prefers checksum input over manifest-file checksum metadata", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "manifest-checksum",
+        downloadUrl: "https://example.com/custom-uv.tar.gz",
+      });
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        "user-checksum",
+        "token",
+        "https://example.com/custom.ndjson",
+      );
+
+      expect(mockValidateChecksum).toHaveBeenCalledWith(
+        "user-checksum",
+        "/tmp/downloaded",
+        "x86_64",
+        "unknown-linux-gnu",
+        "0.9.26",
+        "manifest-checksum",
+      );
+    });
+
+    it("skips the Astral mirror when downloadFromAstralMirror is false", async () => {
+      mockGetArtifact.mockResolvedValue({
+        archiveFormat: "tar.gz",
+        checksum: "abc123",
+        downloadUrl:
+          "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+      });
+
+      await downloadVersion(
+        "unknown-linux-gnu",
+        "x86_64",
+        "0.9.26",
+        undefined,
+        "token",
+        undefined,
+        false,
+      );
+
+      expect(mockDownloadTool).toHaveBeenCalledWith(
+        "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+        undefined,
+        "token",
+      );
+      expect(mockDownloadTool).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("rewriteToMirror", () => {
+    it("rewrites a GitHub Releases URL to the Astral mirror", () => {
+      expect(
+        rewriteToMirror(
+          "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+        ),
+      ).toBe(
+        "https://releases.astral.sh/github/uv/releases/download/0.9.26/uv-x86_64-unknown-linux-gnu.tar.gz",
+      );
+    });
+
+    it("returns undefined for non-GitHub URLs", () => {
+      expect(rewriteToMirror("https://example.com/uv.tar.gz")).toBeUndefined();
+    });
+
+    it("returns undefined for a different GitHub repo", () => {
+      expect(
+        rewriteToMirror(
+          "https://github.com/other/repo/releases/download/v1.0/file.tar.gz",
+        ),
+      ).toBeUndefined();
+    });
+  });
+});

__tests__/download/manifest.test.ts

@@ -0,0 +1,370 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  jest,
+} from "@jest/globals";
+
+// biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
+const mockFetch = jest.fn<any>();
+
+jest.unstable_mockModule("@actions/core", () => ({
+  debug: jest.fn(),
+  info: jest.fn(),
+}));
+
+jest.unstable_mockModule("../../src/utils/fetch", () => ({
+  fetch: mockFetch,
+}));
+
+const {
+  MANIFEST_FETCH_ATTEMPTS,
+  clearManifestCache,
+  fetchManifest,
+  getAllVersions,
+  getArtifact,
+  getFirstMatchingVersion,
+  getLatestVersion,
+  parseManifest,
+} = await import("../../src/download/manifest");
+
+const sampleManifestResponse = `{"version":"0.9.26","artifacts":[{"platform":"aarch64-apple-darwin","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.26/uv-aarch64-apple-darwin.tar.gz","archive_format":"tar.gz","sha256":"fcf0a9ea6599c6ae28a4c854ac6da76f2c889354d7c36ce136ef071f7ab9721f"},{"platform":"x86_64-pc-windows-msvc","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-pc-windows-msvc.zip","archive_format":"zip","sha256":"eb02fd95d8e0eed462b4a67ecdd320d865b38c560bffcda9a0b87ec944bdf036"}]}
+{"version":"0.9.25","artifacts":[{"platform":"aarch64-apple-darwin","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.25/uv-aarch64-apple-darwin.tar.gz","archive_format":"tar.gz","sha256":"606b3c6949d971709f2526fa0d9f0fd23ccf60e09f117999b406b424af18a6a6"}]}`;
+
+const multiVariantManifestResponse = `{"version":"0.9.26","artifacts":[{"platform":"aarch64-apple-darwin","variant":"python-managed","url":"https://github.com/astral-sh/uv/releases/download/0.9.26/uv-aarch64-apple-darwin-managed.tar.gz","archive_format":"tar.gz","sha256":"managed-checksum"},{"platform":"aarch64-apple-darwin","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.26/uv-aarch64-apple-darwin.zip","archive_format":"zip","sha256":"default-checksum"}]}`;
+
+function createMockResponse(
+  ok: boolean,
+  status: number,
+  statusText: string,
+  data: string,
+) {
+  return {
+    body: null,
+    ok,
+    status,
+    statusText,
+    text: async () => data,
+  };
+}
+
+function createStreamingMockResponse(
+  chunks: string[],
+  cancel: () => void | Promise<void> = () => {},
+  close = false,
+) {
+  const encoder = new TextEncoder();
+  return {
+    body: new ReadableStream<Uint8Array>({
+      cancel,
+      start(controller) {
+        for (const chunk of chunks) {
+          controller.enqueue(encoder.encode(chunk));
+        }
+        if (close) {
+          controller.close();
+        }
+      },
+    }),
+    ok: true,
+    status: 200,
+    statusText: "OK",
+    text: async () => chunks.join(""),
+  };
+}
+
+describe("manifest", () => {
+  beforeEach(() => {
+    clearManifestCache();
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe("fetchManifest", () => {
+    it("fetches and parses manifest data", async () => {
+      mockFetch.mockResolvedValue(
+        createMockResponse(true, 200, "OK", sampleManifestResponse),
+      );
+
+      const versions = await fetchManifest();
+
+      expect(versions).toHaveLength(2);
+      expect(versions[0]?.version).toBe("0.9.26");
+      expect(versions[1]?.version).toBe("0.9.25");
+    });
+
+    it("retries network failures", async () => {
+      jest.useFakeTimers();
+      mockFetch
+        .mockRejectedValueOnce(new Error("request timed out"))
+        .mockResolvedValueOnce(
+          createMockResponse(true, 200, "OK", sampleManifestResponse),
+        );
+
+      const result = fetchManifest();
+      await jest.runAllTimersAsync();
+
+      await expect(result).resolves.toHaveLength(2);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it("stops after the configured number of network failures", async () => {
+      jest.useFakeTimers();
+      mockFetch.mockRejectedValue(new Error("request timed out"));
+
+      const result = expect(fetchManifest()).rejects.toThrow(
+        "request timed out",
+      );
+      await jest.runAllTimersAsync();
+
+      await result;
+      expect(mockFetch).toHaveBeenCalledTimes(MANIFEST_FETCH_ATTEMPTS);
+    });
+
+    it("throws on a failed fetch", async () => {
+      mockFetch.mockResolvedValue(
+        createMockResponse(false, 500, "Internal Server Error", ""),
+      );
+
+      await expect(fetchManifest()).rejects.toThrow(
+        "Failed to fetch manifest data: 500 Internal Server Error",
+      );
+    });
+
+    it("caches results per URL", async () => {
+      mockFetch.mockResolvedValue(
+        createMockResponse(true, 200, "OK", sampleManifestResponse),
+      );
+
+      await fetchManifest("https://example.com/custom.ndjson");
+      await fetchManifest("https://example.com/custom.ndjson");
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("getAllVersions", () => {
+    it("returns all version strings", async () => {
+      mockFetch.mockResolvedValue(
+        createMockResponse(true, 200, "OK", sampleManifestResponse),
+      );
+
+      const versions = await getAllVersions(
+        "https://example.com/custom.ndjson",
+      );
+
+      expect(versions).toEqual(["0.9.26", "0.9.25"]);
+    });
+  });
+
+  describe("getLatestVersion", () => {
+    it("returns the first version string", async () => {
+      mockFetch.mockResolvedValue(
+        createMockResponse(true, 200, "OK", sampleManifestResponse),
+      );
+
+      await expect(
+        getLatestVersion("https://example.com/custom.ndjson"),
+      ).resolves.toBe("0.9.26");
+    });
+
+    it("stops reading the default manifest after the first record", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      const cancel = jest.fn();
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse(
+          [
+            latestVersion.slice(0, 100),
+            `${latestVersion.slice(100)}\n`,
+            "invalid trailing data\n",
+          ],
+          cancel,
+        ),
+      );
+
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+      await expect(
+        getArtifact("0.9.26", "aarch64", "apple-darwin"),
+      ).resolves.toBeDefined();
+
+      expect(cancel).toHaveBeenCalledTimes(1);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not fail when canceling the remaining response fails", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse([`${latestVersion}\n`], () =>
+          Promise.reject(new Error("cancel failed")),
+        ),
+      );
+
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+    });
+  });
+
+  describe("getFirstMatchingVersion", () => {
+    it("stops at the first matching record", async () => {
+      const cancel = jest.fn();
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse(
+          [`${sampleManifestResponse}\n`, "invalid trailing data\n"],
+          cancel,
+        ),
+      );
+
+      await expect(
+        getFirstMatchingVersion((version) => version === "0.9.25"),
+      ).resolves.toBe("0.9.25");
+
+      expect(cancel).toHaveBeenCalledTimes(1);
+    });
+
+    it("caches a fully consumed response stream", async () => {
+      mockFetch.mockResolvedValue(
+        createStreamingMockResponse(
+          [`${sampleManifestResponse}\n`],
+          undefined,
+          true,
+        ),
+      );
+
+      await expect(
+        getFirstMatchingVersion((version) => version === "0.0.1"),
+      ).resolves.toBeUndefined();
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("getArtifact", () => {
+    beforeEach(() => {
+      mockFetch.mockResolvedValue(
+        createMockResponse(true, 200, "OK", sampleManifestResponse),
+      );
+    });
+
+    it("finds an artifact by version and platform", async () => {
+      const artifact = await getArtifact("0.9.26", "aarch64", "apple-darwin");
+
+      expect(artifact).toEqual({
+        archiveFormat: "tar.gz",
+        checksum:
+          "fcf0a9ea6599c6ae28a4c854ac6da76f2c889354d7c36ce136ef071f7ab9721f",
+        downloadUrl:
+          "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-aarch64-apple-darwin.tar.gz",
+      });
+    });
+
+    it("finds a windows artifact", async () => {
+      const artifact = await getArtifact("0.9.26", "x86_64", "pc-windows-msvc");
+
+      expect(artifact).toEqual({
+        archiveFormat: "zip",
+        checksum:
+          "eb02fd95d8e0eed462b4a67ecdd320d865b38c560bffcda9a0b87ec944bdf036",
+        downloadUrl:
+          "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-pc-windows-msvc.zip",
+      });
+    });
+
+    it("prefers the default variant when multiple artifacts share a platform", async () => {
+      mockFetch.mockResolvedValue(
+        createMockResponse(true, 200, "OK", multiVariantManifestResponse),
+      );
+
+      const artifact = await getArtifact("0.9.26", "aarch64", "apple-darwin");
+
+      expect(artifact).toEqual({
+        archiveFormat: "zip",
+        checksum: "default-checksum",
+        downloadUrl:
+          "https://github.com/astral-sh/uv/releases/download/0.9.26/uv-aarch64-apple-darwin.zip",
+      });
+    });
+
+    it("returns undefined for an unknown version", async () => {
+      const artifact = await getArtifact("0.0.1", "aarch64", "apple-darwin");
+
+      expect(artifact).toBeUndefined();
+    });
+
+    it("returns undefined for an unknown platform", async () => {
+      const artifact = await getArtifact(
+        "0.9.26",
+        "aarch64",
+        "unknown-linux-musl",
+      );
+
+      expect(artifact).toBeUndefined();
+    });
+
+    it("does not cache records from a failed stream read", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      mockFetch
+        .mockResolvedValueOnce(
+          createStreamingMockResponse([
+            `${latestVersion}\n`,
+            "invalid manifest record\n",
+          ]),
+        )
+        .mockResolvedValueOnce(
+          createMockResponse(true, 200, "OK", sampleManifestResponse),
+        );
+
+      await expect(
+        getArtifact("0.0.1", "aarch64", "apple-darwin"),
+      ).rejects.toThrow("Failed to parse manifest data");
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not cache records when the response stream fails", async () => {
+      const [latestVersion] = sampleManifestResponse.split("\n");
+      const encoder = new TextEncoder();
+      let sentVersion = false;
+      const body = new ReadableStream<Uint8Array>({
+        pull(controller) {
+          if (!sentVersion) {
+            sentVersion = true;
+            controller.enqueue(encoder.encode(`${latestVersion}\n`));
+            return;
+          }
+          controller.error(new Error("response stream failed"));
+        },
+      });
+      mockFetch
+        .mockResolvedValueOnce({
+          body,
+          ok: true,
+          status: 200,
+          statusText: "OK",
+        })
+        .mockResolvedValueOnce(
+          createMockResponse(true, 200, "OK", sampleManifestResponse),
+        );
+
+      await expect(
+        getArtifact("0.0.1", "aarch64", "apple-darwin"),
+      ).rejects.toThrow("response stream failed");
+      await expect(getLatestVersion()).resolves.toBe("0.9.26");
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("parseManifest", () => {
+    it("throws for malformed manifest data", () => {
+      expect(() => parseManifest('{"version":"0.1.0"', "test-source")).toThrow(
+        "Failed to parse manifest data from test-source",
+      );
+    });
+  });
+});

__tests__/fixtures/.tool-versions

@@ -1 +1,2 @@
 uv 0.5.15
+python 3.13.1t

__tests__/fixtures/old-python-constraint-project/pyproject.toml

@@ -9,5 +9,5 @@ dependencies = [
 ]
 
 [build-system]
-requires = ["hatchling"]
+requires = ["uv_build>=0.9.22,<0.10.0"]
-build-backend = "hatchling.build"
+build-backend = "uv_build"

__tests__/fixtures/old-python-constraint-project/uv.lock

@@ -1,33 +1,9 @@
 version = 1
-requires-python = ">=3.12"
+revision = 3
+requires-python = ">=3.8, <=3.9"
 
 [[package]]
-name = "ruff"
+name = "old-python-constraint-project"
-version = "0.6.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/23/f4/279d044f66b79261fd37df76bf72b64471afab5d3b7906a01499c4451910/ruff-0.6.2.tar.gz", hash = "sha256:239ee6beb9e91feb8e0ec384204a763f36cb53fb895a1a364618c6abb076b3be", size = 2460281 }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/72/4b/47dd7a69287afb4069fa42c198e899463605460a58120196711bfcf0446b/ruff-0.6.2-py3-none-linux_armv6l.whl", hash = "sha256:5c8cbc6252deb3ea840ad6a20b0f8583caab0c5ef4f9cca21adc5a92b8f79f3c", size = 9695871 },
-    { url = "https://files.pythonhosted.org/packages/ae/c3/8aac62ac4638c14a740ee76a755a925f2d0d04580ab790a9887accb729f6/ruff-0.6.2-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:17002fe241e76544448a8e1e6118abecbe8cd10cf68fde635dad480dba594570", size = 9459354 },
-    { url = "https://files.pythonhosted.org/packages/2f/cf/77fbd8d4617b9b9c503f9bffb8552c4e3ea1a58dc36975e7a9104ffb0f85/ruff-0.6.2-py3-none-macosx_11_0_arm64.whl", hash = "sha256:3dbeac76ed13456f8158b8f4fe087bf87882e645c8e8b606dd17b0b66c2c1158", size = 9163871 },
-    { url = "https://files.pythonhosted.org/packages/05/1c/765192bab32b79efbb498b06f0b9dcb3629112b53b8777ae1d19b8209e09/ruff-0.6.2-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:094600ee88cda325988d3f54e3588c46de5c18dae09d683ace278b11f9d4d534", size = 10096250 },
-    { url = "https://files.pythonhosted.org/packages/08/d0/86f3cb0f6934c99f759c232984a5204d67a26745cad2d9edff6248adf7d2/ruff-0.6.2-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:316d418fe258c036ba05fbf7dfc1f7d3d4096db63431546163b472285668132b", size = 9475376 },
-    { url = "https://files.pythonhosted.org/packages/cd/cc/4c8d0e225b559a3fae6092ec310d7150d3b02b4669e9223f783ef64d82c0/ruff-0.6.2-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d72b8b3abf8a2d51b7b9944a41307d2f442558ccb3859bbd87e6ae9be1694a5d", size = 10295634 },
-    { url = "https://files.pythonhosted.org/packages/db/96/d2699cfb1bb5a01c68122af43454c76c31331e1c8a9bd97d653d7c82524b/ruff-0.6.2-py3-none-manylinux_2_17_ppc64.manylinux2014_ppc64.whl", hash = "sha256:2aed7e243be68487aa8982e91c6e260982d00da3f38955873aecd5a9204b1d66", size = 11024941 },
-    { url = "https://files.pythonhosted.org/packages/8b/a9/6ecd66af8929e0f2a1ed308a4137f3521789f28f0eb97d32c2ca3aa7000c/ruff-0.6.2-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d371f7fc9cec83497fe7cf5eaf5b76e22a8efce463de5f775a1826197feb9df8", size = 10606894 },
-    { url = "https://files.pythonhosted.org/packages/e4/73/2ee4cd19f44992fedac1cc6db9e3d825966072f6dcbd4032f21cbd063170/ruff-0.6.2-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a8f310d63af08f583363dfb844ba8f9417b558199c58a5999215082036d795a1", size = 11552886 },
-    { url = "https://files.pythonhosted.org/packages/60/4c/c0f1cd35ce4a93c54a6bb1ee6934a3a205fa02198dd076678193853ceea1/ruff-0.6.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7db6880c53c56addb8638fe444818183385ec85eeada1d48fc5abe045301b2f1", size = 10264945 },
-    { url = "https://files.pythonhosted.org/packages/c4/89/e45c9359b9cdd4245512ea2b9f2bb128a997feaa5f726fc9e8c7a66afadf/ruff-0.6.2-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:1175d39faadd9a50718f478d23bfc1d4da5743f1ab56af81a2b6caf0a2394f23", size = 10100007 },
-    { url = "https://files.pythonhosted.org/packages/06/74/0bd4e0a7ed5f6908df87892f9bf60a2356c0fd74102d8097298bd9b4f346/ruff-0.6.2-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:5b939f9c86d51635fe486585389f54582f0d65b8238e08c327c1534844b3bb9a", size = 9559267 },
-    { url = "https://files.pythonhosted.org/packages/54/03/3dc6dc9419f276f05805bf888c279e3e0b631284abd548d9e87cebb93aec/ruff-0.6.2-py3-none-musllinux_1_2_i686.whl", hash = "sha256:d0d62ca91219f906caf9b187dea50d17353f15ec9bb15aae4a606cd697b49b4c", size = 9905304 },
-    { url = "https://files.pythonhosted.org/packages/5c/5b/d6a72a6a6bbf097c09de468326ef5fa1c9e7aa5e6e45979bc0d984b0dbe7/ruff-0.6.2-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:7438a7288f9d67ed3c8ce4d059e67f7ed65e9fe3aa2ab6f5b4b3610e57e3cb56", size = 10341480 },
-    { url = "https://files.pythonhosted.org/packages/79/a9/0f2f21fe15ba537c46598f96aa9ae4a3d4b9ec64926664617ca6a8c772f4/ruff-0.6.2-py3-none-win32.whl", hash = "sha256:279d5f7d86696df5f9549b56b9b6a7f6c72961b619022b5b7999b15db392a4da", size = 7961901 },
-    { url = "https://files.pythonhosted.org/packages/b0/80/fff12ffe11853d9f4ea3e5221e6dd2e93640a161c05c9579833e09ad40a7/ruff-0.6.2-py3-none-win_amd64.whl", hash = "sha256:d9f3469c7dd43cd22eb1c3fc16926fb8258d50cb1b216658a07be95dd117b0f2", size = 8783320 },
-    { url = "https://files.pythonhosted.org/packages/56/91/577cdd64cce5e74d3f8b5ecb93f29566def569c741eb008aed4f331ef821/ruff-0.6.2-py3-none-win_arm64.whl", hash = "sha256:f28fcd2cd0e02bdf739297516d5643a945cc7caf09bd9bcb4d932540a5ea4fa9", size = 8225886 },
-]
-
-[[package]]
-name = "uv-project"
 version = "0.1.0"
 source = { editable = "." }
 dependencies = [
@@ -35,4 +11,30 @@ dependencies = [
 ]
 
 [package.metadata]
-requires-dist = [{ name = "ruff" }]
+requires-dist = [{ name = "ruff", specifier = ">=0.6.2" }]
+
+[[package]]
+name = "ruff"
+version = "0.14.10"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/57/08/52232a877978dd8f9cf2aeddce3e611b40a63287dfca29b6b8da791f5e8d/ruff-0.14.10.tar.gz", hash = "sha256:9a2e830f075d1a42cd28420d7809ace390832a490ed0966fe373ba288e77aaf4", size = 5859763, upload-time = "2025-12-18T19:28:57.98Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/60/01/933704d69f3f05ee16ef11406b78881733c186fe14b6a46b05cfcaf6d3b2/ruff-0.14.10-py3-none-linux_armv6l.whl", hash = "sha256:7a3ce585f2ade3e1f29ec1b92df13e3da262178df8c8bdf876f48fa0e8316c49", size = 13527080, upload-time = "2025-12-18T19:29:25.642Z" },
+    { url = "https://files.pythonhosted.org/packages/df/58/a0349197a7dfa603ffb7f5b0470391efa79ddc327c1e29c4851e85b09cc5/ruff-0.14.10-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:674f9be9372907f7257c51f1d4fc902cb7cf014b9980152b802794317941f08f", size = 13797320, upload-time = "2025-12-18T19:29:02.571Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/82/36be59f00a6082e38c23536df4e71cdbc6af8d7c707eade97fcad5c98235/ruff-0.14.10-py3-none-macosx_11_0_arm64.whl", hash = "sha256:d85713d522348837ef9df8efca33ccb8bd6fcfc86a2cde3ccb4bc9d28a18003d", size = 12918434, upload-time = "2025-12-18T19:28:51.202Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/00/45c62a7f7e34da92a25804f813ebe05c88aa9e0c25e5cb5a7d23dd7450e3/ruff-0.14.10-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6987ebe0501ae4f4308d7d24e2d0fe3d7a98430f5adfd0f1fead050a740a3a77", size = 13371961, upload-time = "2025-12-18T19:29:04.991Z" },
+    { url = "https://files.pythonhosted.org/packages/40/31/a5906d60f0405f7e57045a70f2d57084a93ca7425f22e1d66904769d1628/ruff-0.14.10-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:16a01dfb7b9e4eee556fbfd5392806b1b8550c9b4a9f6acd3dbe6812b193c70a", size = 13275629, upload-time = "2025-12-18T19:29:21.381Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/60/61c0087df21894cf9d928dc04bcd4fb10e8b2e8dca7b1a276ba2155b2002/ruff-0.14.10-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7165d31a925b7a294465fa81be8c12a0e9b60fb02bf177e79067c867e71f8b1f", size = 14029234, upload-time = "2025-12-18T19:29:00.132Z" },
+    { url = "https://files.pythonhosted.org/packages/44/84/77d911bee3b92348b6e5dab5a0c898d87084ea03ac5dc708f46d88407def/ruff-0.14.10-py3-none-manylinux_2_17_ppc64.manylinux2014_ppc64.whl", hash = "sha256:c561695675b972effb0c0a45db233f2c816ff3da8dcfbe7dfc7eed625f218935", size = 15449890, upload-time = "2025-12-18T19:28:53.573Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/36/480206eaefa24a7ec321582dda580443a8f0671fdbf6b1c80e9c3e93a16a/ruff-0.14.10-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4bb98fcbbc61725968893682fd4df8966a34611239c9fd07a1f6a07e7103d08e", size = 15123172, upload-time = "2025-12-18T19:29:23.453Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/38/68e414156015ba80cef5473d57919d27dfb62ec804b96180bafdeaf0e090/ruff-0.14.10-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f24b47993a9d8cb858429e97bdf8544c78029f09b520af615c1d261bf827001d", size = 14460260, upload-time = "2025-12-18T19:29:27.808Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/19/9e050c0dca8aba824d67cc0db69fb459c28d8cd3f6855b1405b3f29cc91d/ruff-0.14.10-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:59aabd2e2c4fd614d2862e7939c34a532c04f1084476d6833dddef4afab87e9f", size = 14229978, upload-time = "2025-12-18T19:29:11.32Z" },
+    { url = "https://files.pythonhosted.org/packages/51/eb/e8dd1dd6e05b9e695aa9dd420f4577debdd0f87a5ff2fedda33c09e9be8c/ruff-0.14.10-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:213db2b2e44be8625002dbea33bb9c60c66ea2c07c084a00d55732689d697a7f", size = 14338036, upload-time = "2025-12-18T19:29:09.184Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/12/f3e3a505db7c19303b70af370d137795fcfec136d670d5de5391e295c134/ruff-0.14.10-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:b914c40ab64865a17a9a5b67911d14df72346a634527240039eb3bd650e5979d", size = 13264051, upload-time = "2025-12-18T19:29:13.431Z" },
+    { url = "https://files.pythonhosted.org/packages/08/64/8c3a47eaccfef8ac20e0484e68e0772013eb85802f8a9f7603ca751eb166/ruff-0.14.10-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:1484983559f026788e3a5c07c81ef7d1e97c1c78ed03041a18f75df104c45405", size = 13283998, upload-time = "2025-12-18T19:29:06.994Z" },
+    { url = "https://files.pythonhosted.org/packages/12/84/534a5506f4074e5cc0529e5cd96cfc01bb480e460c7edf5af70d2bcae55e/ruff-0.14.10-py3-none-musllinux_1_2_i686.whl", hash = "sha256:c70427132db492d25f982fffc8d6c7535cc2fd2c83fc8888f05caaa248521e60", size = 13601891, upload-time = "2025-12-18T19:28:55.811Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/1e/14c916087d8598917dbad9b2921d340f7884824ad6e9c55de948a93b106d/ruff-0.14.10-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:5bcf45b681e9f1ee6445d317ce1fa9d6cba9a6049542d1c3d5b5958986be8830", size = 14336660, upload-time = "2025-12-18T19:29:16.531Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/1c/d7b67ab43f30013b47c12b42d1acd354c195351a3f7a1d67f59e54227ede/ruff-0.14.10-py3-none-win32.whl", hash = "sha256:104c49fc7ab73f3f3a758039adea978869a918f31b73280db175b43a2d9b51d6", size = 13196187, upload-time = "2025-12-18T19:29:19.006Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/9c/896c862e13886fae2af961bef3e6312db9ebc6adc2b156fe95e615dee8c1/ruff-0.14.10-py3-none-win_amd64.whl", hash = "sha256:466297bd73638c6bdf06485683e812db1c00c7ac96d4ddd0294a338c62fdc154", size = 14661283, upload-time = "2025-12-18T19:29:30.16Z" },
+    { url = "https://files.pythonhosted.org/packages/74/31/b0e29d572670dca3674eeee78e418f20bdf97fa8aa9ea71380885e175ca0/ruff-0.14.10-py3-none-win_arm64.whl", hash = "sha256:e51d046cf6dda98a4633b8a8a771451107413b0f07183b2bef03f075599e44e6", size = 13729839, upload-time = "2025-12-18T19:28:48.636Z" },
+]

__tests__/helpers/setup-inputs.ts

@@ -0,0 +1,36 @@
+import { CacheLocalSource, type SetupInputs } from "../../src/utils/inputs";
+
+export function createSetupInputs(
+  overrides: Partial<SetupInputs> = {},
+): SetupInputs {
+  return {
+    activateEnvironment: false,
+    addProblemMatchers: false,
+    cacheDependencyGlob: "uv.lock",
+    cacheLocalPath: {
+      path: "/tmp/setup-uv-cache",
+      source: CacheLocalSource.Input,
+    },
+    cachePython: false,
+    cacheSuffix: "",
+    checksum: "",
+    downloadFromAstralMirror: false,
+    enableCache: true,
+    githubToken: "",
+    ignoreEmptyWorkdir: false,
+    ignoreNothingToCache: false,
+    noProject: false,
+    pruneCache: false,
+    pythonDir: "/tmp/uv-python-dir",
+    pythonVersion: "",
+    quiet: false,
+    resolutionStrategy: "highest",
+    restoreCache: false,
+    saveCache: true,
+    venvPath: "/workspace/.venv",
+    version: "",
+    versionFile: "",
+    workingDirectory: "/workspace",
+    ...overrides,
+  };
+}

__tests__/utils/inputs.test.ts

@@ -1,13 +1,6 @@
-jest.mock("@actions/core", () => {
+import fs from "node:fs";
-  return {
+import os from "node:os";
-    debug: jest.fn(),
+import path from "node:path";
-    getBooleanInput: jest.fn(
-      (name: string) => (mockInputs[name] ?? "") === "true",
-    ),
-    getInput: jest.fn((name: string) => mockInputs[name] ?? ""),
-  };
-});
-
 import {
   afterEach,
   beforeEach,
@@ -17,70 +10,441 @@ import {
   jest,
 } from "@jest/globals";
 
-// Will be mutated per test before (re-)importing the module under test
 let mockInputs: Record<string, string> = {};
+const tempDirs: string[] = [];
+const ORIGINAL_GITHUB_EVENT_NAME = process.env.GITHUB_EVENT_NAME;
+const ORIGINAL_GITHUB_REF = process.env.GITHUB_REF;
 const ORIGINAL_HOME = process.env.HOME;
+const ORIGINAL_RUNNER_ENVIRONMENT = process.env.RUNNER_ENVIRONMENT;
+const ORIGINAL_RUNNER_TEMP = process.env.RUNNER_TEMP;
+const ORIGINAL_UV_CACHE_DIR = process.env.UV_CACHE_DIR;
+const ORIGINAL_UV_PYTHON = process.env.UV_PYTHON;
+const ORIGINAL_UV_PYTHON_INSTALL_DIR = process.env.UV_PYTHON_INSTALL_DIR;
+
+const mockDebug = jest.fn();
+const mockGetBooleanInput = jest.fn(
+  (name: string) => (mockInputs[name] ?? "") === "true",
+);
+const mockGetInput = jest.fn((name: string) => mockInputs[name] ?? "");
+const mockInfo = jest.fn();
+const mockWarning = jest.fn();
+
+jest.unstable_mockModule("@actions/core", () => ({
+  debug: mockDebug,
+  getBooleanInput: mockGetBooleanInput,
+  getInput: mockGetInput,
+  info: mockInfo,
+  warning: mockWarning,
+}));
+
+const { CacheLocalSource, loadInputs } = await import("../../src/utils/inputs");
+
+function createTempProject(files: Record<string, string> = {}): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "setup-uv-inputs-test-"));
+  tempDirs.push(dir);
+
+  for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path.join(dir, relativePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  return dir;
+}
+
+function resetEnvironment(): void {
+  jest.clearAllMocks();
+  mockInputs = {};
+  delete process.env.GITHUB_EVENT_NAME;
+  delete process.env.GITHUB_REF;
+  process.env.HOME = "/home/testuser";
+  delete process.env.RUNNER_ENVIRONMENT;
+  delete process.env.RUNNER_TEMP;
+  delete process.env.UV_CACHE_DIR;
+  delete process.env.UV_PYTHON;
+  delete process.env.UV_PYTHON_INSTALL_DIR;
+}
+
+function restoreEnvironment(): void {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { force: true, recursive: true });
+  }
+
+  process.env.GITHUB_EVENT_NAME = ORIGINAL_GITHUB_EVENT_NAME;
+  process.env.GITHUB_REF = ORIGINAL_GITHUB_REF;
+  process.env.HOME = ORIGINAL_HOME;
+  process.env.RUNNER_ENVIRONMENT = ORIGINAL_RUNNER_ENVIRONMENT;
+  process.env.RUNNER_TEMP = ORIGINAL_RUNNER_TEMP;
+  process.env.UV_CACHE_DIR = ORIGINAL_UV_CACHE_DIR;
+  process.env.UV_PYTHON = ORIGINAL_UV_PYTHON;
+  process.env.UV_PYTHON_INSTALL_DIR = ORIGINAL_UV_PYTHON_INSTALL_DIR;
+}
+
+beforeEach(resetEnvironment);
+afterEach(restoreEnvironment);
+
+describe("loadInputs", () => {
+  it("loads defaults for a github-hosted runner", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "auto";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(true);
+    expect(inputs.cacheLocalPath).toEqual({
+      path: "/runner-temp/setup-uv-cache",
+      source: CacheLocalSource.Default,
+    });
+    expect(inputs.pythonDir).toBe("/runner-temp/uv-python-dir");
+    expect(inputs.venvPath).toBe("/workspace/.venv");
+    expect(inputs.manifestFile).toBeUndefined();
+    expect(inputs.resolutionStrategy).toBe("highest");
+  });
+
+  it("uses the Python version from an explicitly selected .tool-versions file", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13.1t\n",
+    });
+    mockInputs["version-file"] = ".tool-versions";
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("3.13.1t");
+  });
+
+  it("prefers the python-version input over .tool-versions", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13\n",
+    });
+    mockInputs["version-file"] = ".tool-versions";
+    mockInputs["python-version"] = "3.12";
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("3.12");
+  });
+
+  it("preserves UV_PYTHON instead of overriding it from .tool-versions", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13\n",
+    });
+    mockInputs["version-file"] = ".tool-versions";
+    process.env.UV_PYTHON = "3.11";
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("");
+    expect(process.env.UV_PYTHON).toBe("3.11");
+  });
+
+  it("does not discover .tool-versions from the working directory", () => {
+    mockInputs["working-directory"] = createTempProject({
+      ".tool-versions": "uv 0.12.3\npython 3.13\n",
+    });
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonVersion).toBe("");
+  });
+
+  it.each(["pull_request_target", "workflow_run", "release"])(
+    "disables automatic caching for the %s event",
+    (eventName) => {
+      mockInputs["working-directory"] = "/workspace";
+      mockInputs["enable-cache"] = "auto";
+      process.env.RUNNER_ENVIRONMENT = "github-hosted";
+      process.env.RUNNER_TEMP = "/runner-temp";
+      process.env.GITHUB_EVENT_NAME = eventName;
+
+      const inputs = loadInputs();
+
+      expect(inputs.enableCache).toBe(false);
+      expect(mockInfo).toHaveBeenCalledWith(
+        `Caching is disabled for the ${eventName} event`,
+      );
+    },
+  );
+
+  it("disables automatic caching for tag pushes", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "auto";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "push";
+    process.env.GITHUB_REF = "refs/tags/v1.0.0";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(false);
+    expect(mockInfo).toHaveBeenCalledWith("Caching is disabled for tag pushes");
+  });
+
+  it("enables automatic caching for branch pushes", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "auto";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "push";
+    process.env.GITHUB_REF = "refs/heads/main";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(true);
+  });
+
+  it("honors explicitly enabled caching for sensitive events", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "true";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "release";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(true);
+  });
+
+  it("restores but does not save cache automatically for merge groups", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["enable-cache"] = "auto";
+    mockInputs["restore-cache"] = "true";
+    mockInputs["save-cache"] = "auto";
+    process.env.RUNNER_ENVIRONMENT = "github-hosted";
+    process.env.RUNNER_TEMP = "/runner-temp";
+    process.env.GITHUB_EVENT_NAME = "merge_group";
+
+    const inputs = loadInputs();
+
+    expect(inputs.enableCache).toBe(true);
+    expect(inputs.restoreCache).toBe(true);
+    expect(inputs.saveCache).toBe(false);
+    expect(mockInfo).toHaveBeenCalledWith(
+      "Cache saving is disabled for the merge_group event",
+    );
+  });
+
+  it.each([
+    ["true", true],
+    ["false", false],
+  ])("honors save-cache %s for merge groups", (saveCacheInput, expected) => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["save-cache"] = saveCacheInput;
+    process.env.GITHUB_EVENT_NAME = "merge_group";
+
+    const inputs = loadInputs();
+
+    expect(inputs.saveCache).toBe(expected);
+    expect(mockInfo).not.toHaveBeenCalledWith(
+      "Cache saving is disabled for the merge_group event",
+    );
+  });
+
+  it("automatically saves cache for other events", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["save-cache"] = "auto";
+    process.env.GITHUB_EVENT_NAME = "push";
+
+    const inputs = loadInputs();
+
+    expect(inputs.saveCache).toBe(true);
+  });
+
+  it("uses cache-dir from pyproject.toml when present", () => {
+    mockInputs["working-directory"] = createTempProject({
+      "pyproject.toml": `[project]
+name = "uv-project"
+version = "0.1.0"
+
+[tool.uv]
+cache-dir = "/tmp/pyproject-toml-defined-cache-path"
+`,
+    });
+
+    const inputs = loadInputs();
+
+    expect(inputs.cacheLocalPath).toEqual({
+      path: "/tmp/pyproject-toml-defined-cache-path",
+      source: CacheLocalSource.Config,
+    });
+    expect(mockInfo).toHaveBeenCalledWith(
+      expect.stringContaining("Found cache-dir in"),
+    );
+  });
+
+  it("uses UV_CACHE_DIR from the environment", () => {
+    mockInputs["working-directory"] = createTempProject();
+    process.env.UV_CACHE_DIR = "/env/cache-dir";
+
+    const inputs = loadInputs();
+
+    expect(inputs.cacheLocalPath).toEqual({
+      path: "/env/cache-dir",
+      source: CacheLocalSource.Env,
+    });
+    expect(mockInfo).toHaveBeenCalledWith(
+      "UV_CACHE_DIR is already set to /env/cache-dir",
+    );
+  });
+
+  it("uses UV_PYTHON_INSTALL_DIR from the environment", () => {
+    mockInputs["working-directory"] = "/workspace";
+    process.env.UV_PYTHON_INSTALL_DIR = "/env/python-dir";
+
+    const inputs = loadInputs();
+
+    expect(inputs.pythonDir).toBe("/env/python-dir");
+    expect(mockInfo).toHaveBeenCalledWith(
+      "UV_PYTHON_INSTALL_DIR is already set to /env/python-dir",
+    );
+  });
+
+  it("warns when parsing a malformed pyproject.toml for cache-dir", () => {
+    mockInputs["working-directory"] = createTempProject({
+      "pyproject.toml": `[project]
+name = "malformed-pyproject-toml-project"
+version = "0.1.0"
+
+[malformed-toml
+`,
+    });
+
+    const inputs = loadInputs();
+
+    expect(inputs.cacheLocalPath).toBeUndefined();
+    expect(mockWarning).toHaveBeenCalledWith(
+      expect.stringContaining("Error while parsing pyproject.toml:"),
+    );
+  });
+
+  it("throws for an invalid resolution strategy", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["resolution-strategy"] = "middle";
+
+    expect(() => loadInputs()).toThrow(
+      "Invalid resolution-strategy: middle. Must be 'highest' or 'lowest'.",
+    );
+  });
+});
 
 describe("cacheDependencyGlob", () => {
-  beforeEach(() => {
+  it("returns empty string when input not provided", () => {
-    jest.resetModules();
-    mockInputs = {};
-    process.env.HOME = "/home/testuser";
-  });
-
-  afterEach(() => {
-    process.env.HOME = ORIGINAL_HOME;
-  });
-
-  it("returns empty string when input not provided", async () => {
     mockInputs["working-directory"] = "/workspace";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+
-    expect(cacheDependencyGlob).toBe("");
+    const inputs = loadInputs();
+
+    expect(inputs.cacheDependencyGlob).toBe("");
   });
 
-  it("resolves a single relative path", async () => {
+  it.each([
+    ["requirements.txt", "/workspace/requirements.txt"],
+    ["./uv.lock", "/workspace/uv.lock"],
+  ])("resolves %s to %s", (globInput, expected) => {
     mockInputs["working-directory"] = "/workspace";
-    mockInputs["cache-dependency-glob"] = "requirements.txt";
+    mockInputs["cache-dependency-glob"] = globInput;
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+
-    expect(cacheDependencyGlob).toBe("/workspace/requirements.txt");
+    const inputs = loadInputs();
+
+    expect(inputs.cacheDependencyGlob).toBe(expected);
   });
 
-  it("strips leading ./ from relative path", async () => {
+  it("handles multiple lines, trimming whitespace, tilde expansion and absolute paths", () => {
-    mockInputs["working-directory"] = "/workspace";
-    mockInputs["cache-dependency-glob"] = "./uv.lock";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
-    expect(cacheDependencyGlob).toBe("/workspace/uv.lock");
-  });
-
-  it("handles multiple lines, trimming whitespace, tilde expansion and absolute paths", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["cache-dependency-glob"] =
       "  ~/.cache/file1\n ./rel/file2  \nfile3.txt";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+
-    expect(cacheDependencyGlob).toBe(
+    const inputs = loadInputs();
+
+    expect(inputs.cacheDependencyGlob).toBe(
       [
-        "/home/testuser/.cache/file1", // expanded tilde, absolute path unchanged
+        "/home/testuser/.cache/file1",
-        "/workspace/rel/file2", // ./ stripped and resolved
+        "/workspace/rel/file2",
-        "/workspace/file3.txt", // relative path resolved
+        "/workspace/file3.txt",
       ].join("\n"),
     );
   });
 
-  it("keeps absolute path unchanged in multiline input", async () => {
+  it.each([
-    mockInputs["working-directory"] = "/workspace";
+    [
-    mockInputs["cache-dependency-glob"] = "/abs/path.lock\nrelative.lock";
+      "/abs/path.lock\nrelative.lock",
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
-    expect(cacheDependencyGlob).toBe(
       ["/abs/path.lock", "/workspace/relative.lock"].join("\n"),
-    );
+    ],
+    [
+      "!/abs/path.lock\n!relative.lock",
+      ["!/abs/path.lock", "!/workspace/relative.lock"].join("\n"),
+    ],
+  ])("normalizes multiline glob %s", (globInput, expected) => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["cache-dependency-glob"] = globInput;
+
+    const inputs = loadInputs();
+
+    expect(inputs.cacheDependencyGlob).toBe(expected);
+  });
+});
+
+describe("tool directories", () => {
+  it("expands tilde for tool-bin-dir and tool-dir", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["tool-bin-dir"] = "~/tool-bin-dir";
+    mockInputs["tool-dir"] = "~/tool-dir";
+
+    const inputs = loadInputs();
+
+    expect(inputs.toolBinDir).toBe("/home/testuser/tool-bin-dir");
+    expect(inputs.toolDir).toBe("/home/testuser/tool-dir");
+  });
+});
+
+describe("cacheLocalPath", () => {
+  it("expands tilde in cache-local-path", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["cache-local-path"] = "~/uv-cache/cache-local-path";
+
+    const inputs = loadInputs();
+
+    expect(inputs.cacheLocalPath).toEqual({
+      path: "/home/testuser/uv-cache/cache-local-path",
+      source: CacheLocalSource.Input,
+    });
+  });
+});
+
+describe("venvPath", () => {
+  it("defaults to .venv in the working directory", () => {
+    mockInputs["working-directory"] = "/workspace";
+
+    const inputs = loadInputs();
+
+    expect(inputs.venvPath).toBe("/workspace/.venv");
   });
 
-  it("handles exclusions in relative paths correct", async () => {
+  it.each([
+    ["custom-venv", "/workspace/custom-venv"],
+    ["custom-venv/", "/workspace/custom-venv"],
+    ["/tmp/custom-venv", "/tmp/custom-venv"],
+    ["~/.venv", "/home/testuser/.venv"],
+  ])("resolves venv-path %s to %s", (venvPathInput, expected) => {
     mockInputs["working-directory"] = "/workspace";
-    mockInputs["cache-dependency-glob"] = "!/abs/path.lock\n!relative.lock";
+    mockInputs["activate-environment"] = "true";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+    mockInputs["venv-path"] = venvPathInput;
-    expect(cacheDependencyGlob).toBe(
+
-      ["!/abs/path.lock", "!/workspace/relative.lock"].join("\n"),
+    const inputs = loadInputs();
+
+    expect(inputs.venvPath).toBe(expected);
+  });
+
+  it("warns when venv-path is set but activate-environment is false", () => {
+    mockInputs["working-directory"] = "/workspace";
+    mockInputs["venv-path"] = "custom-venv";
+
+    const inputs = loadInputs();
+
+    expect(inputs.activateEnvironment).toBe(false);
+    expect(inputs.venvPath).toBe("/workspace/custom-venv");
+    expect(mockWarning).toHaveBeenCalledWith(
+      "venv-path is only used when activate-environment is true",
     );
   });
 });

__tests__/utils/python-runtime.test.ts

@@ -0,0 +1,86 @@
+import { promisify } from "node:util";
+import { beforeEach, expect, it, jest } from "@jest/globals";
+import { createSetupInputs } from "../helpers/setup-inputs";
+
+const mockExecFile =
+  jest.fn<
+    (...args: unknown[]) => Promise<{ stdout: string; stderr: string }>
+  >();
+const inputs = createSetupInputs({
+  activateEnvironment: true,
+  pythonVersion: "3.15t",
+});
+
+jest.unstable_mockModule("node:child_process", () => ({
+  // execFile's custom promisifier returns both stdout and stderr.
+  execFile: Object.assign(mockExecFile, { [promisify.custom]: mockExecFile }),
+}));
+
+const { getPythonRuntimeId } = await import("../../src/utils/python-runtime");
+
+beforeEach(() => {
+  mockExecFile.mockReset();
+  mockExecFile.mockResolvedValue({
+    stderr: "",
+    stdout: '[{"key":"cpython-3.13.1-linux-x86_64-gnu"}]\r\n',
+  });
+});
+
+it("does not query uv without environment activation", async () => {
+  expect(
+    await getPythonRuntimeId({ ...inputs, activateEnvironment: false }),
+  ).toBe("");
+  expect(mockExecFile).not.toHaveBeenCalled();
+});
+
+it.each([
+  "cpython-3.13.1-linux-x86_64-gnu",
+  "cpython-3.15.0rc1+freethreaded-macos-aarch64-none",
+  "cpython-3.15.0rc2+freethreaded-windows-x86_64-none",
+  "pypy-3.11.15-linux-x86_64-gnu",
+])("returns uv's opaque runtime key unchanged: %s", async (key) => {
+  mockExecFile.mockResolvedValue({
+    stderr: "",
+    stdout: `${JSON.stringify([{ key }])}\r\n`,
+  });
+  expect(await getPythonRuntimeId(inputs)).toBe(key);
+});
+
+it.each(['/runner temp/a "quoted" venv', "C:\\runner temp\\custom venv"])(
+  "queries the exact venv directory: %s",
+  async (venvPath) => {
+    await getPythonRuntimeId({ ...inputs, venvPath });
+    expect(mockExecFile).toHaveBeenCalledWith(
+      "uv",
+      [
+        "python",
+        "list",
+        venvPath,
+        "--only-installed",
+        "--output-format",
+        "json",
+      ],
+      { encoding: "utf8" },
+    );
+  },
+);
+
+it.each([
+  new Error("uv failed"),
+  "not JSON",
+  "null",
+  "{}",
+  "[]",
+  '[{"key":""}]',
+  '[{"key":123}]',
+  '[{"key":"first"},{"key":"second"}]',
+])("rejects uv failure or invalid results: %s", async (result) => {
+  if (result instanceof Error) {
+    mockExecFile.mockRejectedValue(result);
+  } else {
+    mockExecFile.mockResolvedValue({ stderr: "", stdout: result });
+  }
+  await expect(getPythonRuntimeId(inputs)).rejects.toThrow(
+    "Failed to identify the activated environment's Python runtime:",
+  );
+});

__tests__/version/requirements-file.test.ts

@@ -1,5 +1,9 @@
 import { expect, test } from "@jest/globals";
-import { getUvVersionFromFile } from "../../src/version/resolve";
+import { getUvVersionFromFile } from "../../src/version/file-parser";
+import {
+  getUvVersionFromPyprojectContent,
+  getUvVersionFromRequirementsText,
+} from "../../src/version/requirements-file";
 
 test("ignores dependencies starting with uv", async () => {
   const parsedVersion = getUvVersionFromFile(
@@ -7,3 +11,27 @@ test("ignores dependencies starting with uv", async () => {
   );
   expect(parsedVersion).toBe("0.6.17");
 });
+
+test.each([
+  ["without space before marker", "uv==0.11.20; sys_platform != 'emscripten'"],
+  ["with space before marker", "uv==0.11.20 ; sys_platform != 'emscripten'"],
+])(
+  "strips PEP 508 markers from pyproject dependency groups %s",
+  (_, dependency) => {
+    const parsedVersion = getUvVersionFromPyprojectContent(`[dependency-groups]
+test = [
+  "${dependency}",
+]
+`);
+
+    expect(parsedVersion).toBe("==0.11.20");
+  },
+);
+
+test("strips PEP 508 markers from requirements dependencies", () => {
+  const parsedVersion = getUvVersionFromRequirementsText(
+    "uv==0.11.20; sys_platform != 'emscripten'",
+  );
+
+  expect(parsedVersion).toBe("==0.11.20");
+});

__tests__/version/requirements-hashes-file.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "@jest/globals";
-import { getUvVersionFromFile } from "../../src/version/resolve";
+import { getUvVersionFromFile } from "../../src/version/file-parser";
 
 test("ignores dependencies starting with uv", async () => {
   const parsedVersion = getUvVersionFromFile(

__tests__/version/tool-versions-file.test.ts

@@ -1,115 +1,211 @@
-jest.mock("node:fs");
+import { beforeEach, describe, expect, it, jest } from "@jest/globals";
-jest.mock("@actions/core", () => ({
+
-  warning: jest.fn(),
+const mockReadFileSync = jest.fn();
+const mockWarning = jest.fn();
+
+jest.unstable_mockModule("node:fs", () => ({
+  default: {
+    readFileSync: mockReadFileSync,
+  },
 }));
 
-import fs from "node:fs";
+jest.unstable_mockModule("@actions/core", () => ({
-import * as core from "@actions/core";
+  warning: mockWarning,
-import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+}));
-import { getUvVersionFromToolVersions } from "../../src/version/tool-versions-file";
 
-const mockedFs = fs as jest.Mocked<typeof fs>;
+async function getVersionFromToolVersions(filePath: string) {
-const mockedCore = core as jest.Mocked<typeof core>;
+  const { getUvVersionFromToolVersions } = await import(
+    "../../src/version/tool-versions-file"
+  );
+
+  return getUvVersionFromToolVersions(filePath);
+}
+
+async function getPythonVersionFromToolVersions(filePath: string) {
+  const module = await import("../../src/version/tool-versions-file");
+  return module.getPythonVersionFromToolVersions(filePath);
+}
 
 describe("getUvVersionFromToolVersions", () => {
   beforeEach(() => {
+    jest.resetModules();
     jest.clearAllMocks();
   });
 
-  it("should return undefined for non-.tool-versions files", () => {
+  it("should return undefined for non-.tool-versions files", async () => {
-    const result = getUvVersionFromToolVersions("package.json");
+    const result = await getVersionFromToolVersions("package.json");
     expect(result).toBeUndefined();
-    expect(mockedFs.readFileSync).not.toHaveBeenCalled();
+    expect(mockReadFileSync).not.toHaveBeenCalled();
   });
 
-  it("should return version for valid uv entry", () => {
+  it("should return version for valid uv entry", async () => {
     const fileContent = "python 3.11.0\nuv 0.1.0\nnodejs 18.0.0";
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    mockReadFileSync.mockReturnValue(fileContent);
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBe("0.1.0");
-    expect(mockedFs.readFileSync).toHaveBeenCalledWith(
+    expect(mockReadFileSync).toHaveBeenCalledWith(".tool-versions", "utf8");
-      ".tool-versions",
-      "utf8",
-    );
   });
 
-  it("should return version for uv entry with v prefix", () => {
+  it("should return version for uv entry with v prefix", async () => {
     const fileContent = "uv v0.2.0";
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    mockReadFileSync.mockReturnValue(fileContent);
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBe("0.2.0");
   });
 
-  it("should handle whitespace around uv entry", () => {
+  it("should handle whitespace around uv entry", async () => {
     const fileContent = "  uv   0.3.0  ";
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    mockReadFileSync.mockReturnValue(fileContent);
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBe("0.3.0");
   });
 
-  it("should skip commented lines", () => {
+  it("should skip comments", async () => {
-    const fileContent = "# uv 0.1.0\npython 3.11.0\nuv 0.2.0";
+    const fileContent = "# uv 0.1.0\npython 3.11.0\nuv 0.2.0 # inline comment";
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    mockReadFileSync.mockReturnValue(fileContent);
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBe("0.2.0");
   });
 
-  it("should return first matching uv version", () => {
+  it("should return first matching uv version", async () => {
     const fileContent = "uv 0.1.0\npython 3.11.0\nuv 0.2.0";
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    mockReadFileSync.mockReturnValue(fileContent);
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBe("0.1.0");
   });
 
-  it("should return undefined when no uv entry found", () => {
+  it("should return undefined when no uv entry found", async () => {
     const fileContent = "python 3.11.0\nnodejs 18.0.0";
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    mockReadFileSync.mockReturnValue(fileContent);
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBeUndefined();
   });
 
-  it("should return undefined for empty file", () => {
+  it("should return undefined for empty file", async () => {
-    mockedFs.readFileSync.mockReturnValue("");
+    mockReadFileSync.mockReturnValue("");
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBeUndefined();
   });
 
-  it("should warn and return undefined for ref syntax", () => {
+  it("should warn and return undefined for ref syntax", async () => {
     const fileContent = "uv ref:main";
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    mockReadFileSync.mockReturnValue(fileContent);
 
-    const result = getUvVersionFromToolVersions(".tool-versions");
+    const result = await getVersionFromToolVersions(".tool-versions");
 
     expect(result).toBeUndefined();
-    expect(mockedCore.warning).toHaveBeenCalledWith(
+    expect(mockWarning).toHaveBeenCalledWith(
       "The ref syntax of .tool-versions is not supported. Please use a released version instead.",
     );
   });
 
-  it("should handle file path with .tool-versions extension", () => {
+  it.each(["/my/python/exploit", "my/exploited/uv", "C:\\exploited\\uv"])(
-    const fileContent = "uv 0.1.0";
+    "should warn and return undefined for path %s",
-    mockedFs.readFileSync.mockReturnValue(fileContent);
+    async (version) => {
+      mockReadFileSync.mockReturnValue(`uv ${version}`);
 
-    const result = getUvVersionFromToolVersions("path/to/.tool-versions");
+      const result = await getVersionFromToolVersions(".tool-versions");
+
+      expect(result).toBeUndefined();
+      expect(mockWarning).toHaveBeenCalledWith(
+        `The uv version ${version} in .tool-versions is not supported. Paths are not allowed.`,
+      );
+    },
+  );
+
+  it("should handle file path with .tool-versions extension", async () => {
+    const fileContent = "uv 0.1.0";
+    mockReadFileSync.mockReturnValue(fileContent);
+
+    const result = await getVersionFromToolVersions("path/to/.tool-versions");
 
     expect(result).toBe("0.1.0");
-    expect(mockedFs.readFileSync).toHaveBeenCalledWith(
+    expect(mockReadFileSync).toHaveBeenCalledWith(
       "path/to/.tool-versions",
       "utf8",
     );
   });
 });
+
+describe("getPythonVersionFromToolVersions", () => {
+  beforeEach(() => {
+    jest.resetModules();
+    jest.clearAllMocks();
+  });
+
+  it("should return version for a valid Python entry", async () => {
+    mockReadFileSync.mockReturnValue(
+      "nodejs 24.0.0\r\npython v3.13.1t # use free-threaded Python\r\nuv 0.12.3",
+    );
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBe("3.13.1t");
+  });
+
+  it("should return the first matching Python version", async () => {
+    mockReadFileSync.mockReturnValue("python 3.12\npython 3.13");
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBe("3.12");
+  });
+
+  it("should return undefined when no Python entry is found", async () => {
+    mockReadFileSync.mockReturnValue("uv 0.12.3\nnodejs 24.0.0");
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBeUndefined();
+  });
+
+  it("should warn and return undefined for multiple Python versions", async () => {
+    mockReadFileSync.mockReturnValue("python 3.13 3.12 system");
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBeUndefined();
+    expect(mockWarning).toHaveBeenCalledWith(
+      "Multiple Python versions in .tool-versions are not supported. The Python entry will be ignored.",
+    );
+  });
+
+  it.each([
+    "ref:main",
+    "path:~/src/python",
+    "system",
+    "/my/python/exploit",
+    "my/exploited/python",
+    "C:\\exploited\\python",
+  ])("should warn and return undefined for %s", async (version) => {
+    mockReadFileSync.mockReturnValue(`python ${version}`);
+
+    const result = await getPythonVersionFromToolVersions(".tool-versions");
+
+    expect(result).toBeUndefined();
+    expect(mockWarning).toHaveBeenCalledWith(
+      `The Python version ${version} in .tool-versions is not supported. The Python entry will be ignored.`,
+    );
+  });
+
+  it("should return undefined for non-.tool-versions files", async () => {
+    const result = await getPythonVersionFromToolVersions(".python-version");
+
+    expect(result).toBeUndefined();
+    expect(mockReadFileSync).not.toHaveBeenCalled();
+  });
+});

__tests__/version/uv-lock-file.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "@jest/globals";
+import { getUvVersionFromUvLockContent } from "../../src/version/uv-lock-file";
+
+const UV_LOCK = `version = 1
+requires-python = ">=3.12"
+
+[[package]]
+name = "anyio"
+version = "4.6.0"
+source = { registry = "https://pypi.org/simple" }
+
+[[package]]
+name = "uv"
+version = "0.8.17"
+source = { registry = "https://pypi.org/simple" }
+`;
+
+describe("getUvVersionFromUvLockContent", () => {
+  it("returns the exact uv version locked in uv.lock", () => {
+    expect(getUvVersionFromUvLockContent(UV_LOCK)).toBe("0.8.17");
+  });
+
+  it("returns undefined when uv is not a locked package", () => {
+    const content = `version = 1
+
+[[package]]
+name = "anyio"
+version = "4.6.0"
+`;
+    expect(getUvVersionFromUvLockContent(content)).toBeUndefined();
+  });
+
+  it("returns undefined when there are no packages", () => {
+    expect(getUvVersionFromUvLockContent("version = 1\n")).toBeUndefined();
+  });
+});

__tests__/version/version-request-resolver.test.ts

@@ -0,0 +1,143 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "@jest/globals";
+import { resolveVersionRequest } from "../../src/version/version-request-resolver";
+
+const tempDirs: string[] = [];
+
+function createTempProject(files: Record<string, string> = {}): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "setup-uv-version-test-"));
+  tempDirs.push(dir);
+
+  for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path.join(dir, relativePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content);
+  }
+
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { force: true, recursive: true });
+  }
+});
+
+describe("resolveVersionRequest", () => {
+  it("prefers explicit input over version-file and workspace config", () => {
+    const workingDirectory = createTempProject({
+      ".tool-versions": "uv 0.4.0\n",
+      "pyproject.toml": `[tool.uv]\nrequired-version = "==0.5.14"\n`,
+      "uv.toml": `required-version = "==0.5.15"\n`,
+    });
+
+    const request = resolveVersionRequest({
+      version: "==0.6.0",
+      versionFile: path.join(workingDirectory, ".tool-versions"),
+      workingDirectory,
+    });
+
+    expect(request).toEqual({
+      source: "input",
+      specifier: "0.6.0",
+    });
+  });
+
+  it("uses .tool-versions when it is passed via version-file", () => {
+    const workingDirectory = createTempProject({
+      ".tool-versions": "uv 0.5.15\n",
+    });
+
+    const request = resolveVersionRequest({
+      versionFile: path.join(workingDirectory, ".tool-versions"),
+      workingDirectory,
+    });
+
+    expect(request).toEqual({
+      format: ".tool-versions",
+      source: "version-file",
+      sourcePath: path.join(workingDirectory, ".tool-versions"),
+      specifier: "0.5.15",
+    });
+  });
+
+  it("uses the exact uv version locked in uv.lock when it is passed via version-file", () => {
+    const workingDirectory = createTempProject({
+      "uv.lock": `version = 1\n\n[[package]]\nname = "uv"\nversion = "0.8.17"\nsource = { registry = "https://pypi.org/simple" }\n`,
+    });
+
+    const request = resolveVersionRequest({
+      versionFile: path.join(workingDirectory, "uv.lock"),
+      workingDirectory,
+    });
+
+    expect(request).toEqual({
+      format: "uv.lock",
+      source: "version-file",
+      sourcePath: path.join(workingDirectory, "uv.lock"),
+      specifier: "0.8.17",
+    });
+  });
+
+  it("uses requirements.txt when it is passed via version-file", () => {
+    const workingDirectory = createTempProject({
+      "requirements.txt": "uv==0.6.17\nuvicorn==0.35.0\n",
+    });
+
+    const request = resolveVersionRequest({
+      versionFile: path.join(workingDirectory, "requirements.txt"),
+      workingDirectory,
+    });
+
+    expect(request).toEqual({
+      format: "requirements",
+      source: "version-file",
+      sourcePath: path.join(workingDirectory, "requirements.txt"),
+      specifier: "0.6.17",
+    });
+  });
+
+  it("prefers uv.toml over pyproject.toml during workspace discovery", () => {
+    const workingDirectory = createTempProject({
+      "pyproject.toml": `[tool.uv]\nrequired-version = "==0.5.14"\n`,
+      "uv.toml": `required-version = "==0.5.15"\n`,
+    });
+
+    const request = resolveVersionRequest({ workingDirectory });
+
+    expect(request).toEqual({
+      format: "uv.toml",
+      source: "uv.toml",
+      sourcePath: path.join(workingDirectory, "uv.toml"),
+      specifier: "0.5.15",
+    });
+  });
+
+  it("falls back to latest when no version source is found", () => {
+    const workingDirectory = createTempProject({});
+
+    const request = resolveVersionRequest({ workingDirectory });
+
+    expect(request).toEqual({
+      source: "default",
+      specifier: "latest",
+    });
+  });
+
+  it("throws when version-file does not resolve a version", () => {
+    const workingDirectory = createTempProject({
+      "requirements.txt": "uvicorn==0.35.0\n",
+    });
+
+    expect(() =>
+      resolveVersionRequest({
+        versionFile: path.join(workingDirectory, "requirements.txt"),
+        workingDirectory,
+      }),
+    ).toThrow(
+      `Could not determine uv version from file: ${path.join(workingDirectory, "requirements.txt")}`,
+    );
+  });
+});

__tests__/workflows/workflow-run.yml

@@ -0,0 +1,42 @@
+name: "test workflow_run caching"
+
+on: # zizmor: ignore[dangerous-triggers] this workflow is a test fixture executed by act only
+  workflow_run:
+    workflows:
+      - test
+    types:
+      - completed
+
+permissions:
+  contents: read
+
+jobs:
+  test-cache-disabled:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Setup uv with automatic caching
+        id: setup-uv
+        uses: ./
+      - name: Verify automatic caching is disabled
+        env:
+          CACHE_KEY: ${{ steps.setup-uv.outputs.cache-key }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" != "workflow_run" ]; then
+            echo "Expected workflow_run event, got: $GITHUB_EVENT_NAME"
+            exit 1
+          fi
+          if [ "$RUNNER_ENVIRONMENT" != "github-hosted" ]; then
+            echo "Expected a simulated GitHub-hosted runner, got: $RUNNER_ENVIRONMENT"
+            exit 1
+          fi
+          if [ -n "$CACHE_KEY" ]; then
+            echo "Cache key should not be set for a workflow_run event: $CACHE_KEY"
+            exit 1
+          fi
+          if [ -n "$UV_CACHE_DIR" ]; then
+            echo "UV_CACHE_DIR should not be set for a workflow_run event: $UV_CACHE_DIR"
+            exit 1
+          fi

action-types.yml

@@ -0,0 +1,89 @@
+# See https://github.com/typesafegithub/github-actions-typing
+
+inputs:
+  version:
+    type: string
+  version-file:
+    type: string
+  python-version:
+    type: string
+  activate-environment:
+    type: boolean
+  venv-path:
+    type: string
+  no-project:
+    type: boolean
+  working-directory:
+    type: string
+  checksum:
+    type: string
+  github-token:
+    type: string
+  enable-cache:
+    type: enum
+    allowed-values:
+      - "true"
+      - "false"
+      - auto
+  cache-dependency-glob:
+    type: list
+    separator: "\n"
+    list-item:
+      type: string
+  restore-cache:
+    type: boolean
+  save-cache:
+    type: enum
+    allowed-values:
+      - "true"
+      - "false"
+      - auto
+  cache-suffix:
+    type: string
+  cache-local-path:
+    type: string
+  prune-cache:
+    type: boolean
+  cache-python:
+    type: boolean
+  ignore-nothing-to-cache:
+    type: boolean
+  ignore-empty-workdir:
+    type: boolean
+  tool-dir:
+    type: string
+  tool-bin-dir:
+    type: string
+  manifest-file:
+    type: string
+  download-from-astral-mirror:
+    type: boolean
+  add-problem-matchers:
+    type: boolean
+  quiet:
+    type: boolean
+  resolution-strategy:
+    type: enum
+    allowed-values:
+      - highest
+      - lowest
+
+outputs:
+  uv-version:
+    type: string
+  uv-path:
+    type: string
+  uvx-path:
+    type: string
+  cache-hit:
+    type: boolean
+  cache-key:
+    type: string
+  venv:
+    type: string
+  python-version:
+    type: string
+  python-runtime-id:
+    type: string
+  python-cache-hit:
+    type: boolean

action.yml

@@ -4,17 +4,23 @@ description:
 author: "astral-sh"
 inputs:
   version:
-    description: "The version of uv to install e.g., `0.5.0` Defaults to the version in pyproject.toml or 'latest'."
+    description: "The version of uv to install, e.g., `0.5.0`, `latest`, or `latest-known`. Defaults to the version in pyproject.toml or `latest`."
     default: ""
   version-file:
-    description: "Path to a file containing the version of uv to install. Defaults to searching for uv.toml and if not found pyproject.toml."
+    description: "Path to a file containing the version of uv to install, e.g., uv.toml, pyproject.toml, .tool-versions, requirements.txt or uv.lock. A selected .tool-versions file can also provide the Python version. Defaults to searching for uv.toml and if not found pyproject.toml."
     default: ""
   python-version:
-    description: "The version of Python to set UV_PYTHON to"
+    description: "The version of Python to set UV_PYTHON to. Overrides the Python version from .tool-versions."
     required: false
   activate-environment:
     description: "Use uv venv to activate a venv ready to be used by later steps. "
     default: "false"
+  venv-path:
+    description: "Custom path for the virtual environment when using activate-environment. Defaults to '.venv' in the working directory."
+    default: ""
+  no-project:
+    description: "Pass --no-project when creating the venv with activate-environment."
+    default: "false"
   working-directory:
     description: "The directory to execute all commands in and look for files such as pyproject.toml"
     default: ${{ github.workspace }}
@@ -23,15 +29,15 @@ inputs:
     required: false
   github-token:
     description:
-      "Used to increase the rate limit when retrieving versions and downloading uv."
+      "Used when downloading uv from GitHub releases."
     required: false
     default: ${{ github.token }}
   enable-cache:
-    description: "Enable uploading of the uv cache"
+    description: "Enable the GitHub Actions cache for uv. 'auto' enables caching on GitHub-hosted runners except for release, tag push, pull_request_target, and workflow_run events."
     default: "auto"
   cache-dependency-glob:
     description:
-      "Glob pattern to match files relative to the repository root to control
+      "Glob pattern to match files relative to the working directory to control
       the cache."
     default: |
       **/*requirements*.txt
@@ -45,8 +51,8 @@ inputs:
     description: "Whether to restore the cache if found."
     default: "true"
   save-cache:
-    description: "Whether to save the cache after the run."
+    description: "Whether to save the cache after the run. 'auto' disables saving for merge_group events."
-    default: "true"
+    default: "auto"
   cache-suffix:
     description: "Suffix for the cache key"
     required: false
@@ -55,7 +61,7 @@ inputs:
     default: ""
   prune-cache:
     description: "Prune cache before saving."
-    default: "true"
+    default: "false"
   cache-python:
     description: "Upload managed Python installations to the Github Actions cache."
     default: "false"
@@ -72,11 +78,20 @@ inputs:
     description: "Custom path to set UV_TOOL_BIN_DIR to."
     required: false
   manifest-file:
-    description: "URL to the manifest file containing available versions and download URLs."
+    description: "URL to a custom manifest file in the astral-sh/versions format."
     required: false
+  download-from-astral-mirror:
+    description: "Download uv from the Astral mirror instead of directly from GitHub Releases."
+    default: "true"
   add-problem-matchers:
     description: "Add problem matchers."
     default: "true"
+  quiet:
+    description: "Suppress info-level log output. Only warnings and errors are shown."
+    default: "false"
+  resolution-strategy:
+    description: "Resolution strategy to use when resolving version ranges. 'highest' uses the latest compatible version, 'lowest' uses the oldest compatible version."
+    default: "highest"
 outputs:
   uv-version:
     description: "The installed uv version. Useful when using latest."
@@ -86,12 +101,20 @@ outputs:
     description: "The path to the installed uvx binary."
   cache-hit:
     description: "A boolean value to indicate a cache entry was found"
+  cache-key:
+    description: "The cache key used for storing/restoring the cache"
   venv:
     description: "Path to the activated venv if activate-environment is true"
+  python-version:
+    description: "The Python version that was set."
+  python-runtime-id:
+    description: "An opaque identifier reported by uv for the activated venv's Python runtime. Empty when activate-environment is false."
+  python-cache-hit:
+    description: "A boolean value to indicate the Python cache entry was found"
 runs:
   using: "node24"
-  main: "dist/setup/index.js"
+  main: "dist/setup/index.cjs"
-  post: "dist/save-cache/index.js"
+  post: "dist/save-cache/index.cjs"
   post-if: success()
 branding:
   icon: "package"

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.9/schema.json",
   "assist": {
     "actions": {
       "source": {
@@ -18,7 +18,8 @@
       "!**/node_modules",
       "!**/package*.json",
       "!**/known-checksums.*"
-    ]
+    ],
+    "maxSize": 2097152
   },
   "formatter": {
     "enabled": true,
@@ -33,7 +34,7 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "preset": "recommended"
     }
   },
   "vcs": {

docs/advanced-version-configuration.md

@@ -0,0 +1,109 @@
+# Advanced Version Configuration
+
+This document covers advanced options for configuring which version of uv to install.
+
+## Install the latest version
+
+```yaml
+- name: Install the latest version of uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: "latest"
+```
+
+## Install the latest version with a checksum verified by this action
+
+Use `latest-known` to install the newest uv version whose checksums were bundled with the version of setup-uv used by your workflow. Version resolution is performed locally without fetching the latest release, so updating setup-uv also updates the version selected by `latest-known`.
+
+When `manifest-file` is set, `latest-known` still selects a version from setup-uv's bundled checksum table, but the artifact and checksum come from the custom manifest.
+
+```yaml
+- name: Install the latest version of uv known to setup-uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: "latest-known"
+```
+
+## Install a specific version
+
+```yaml
+- name: Install a specific version of uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: "0.4.4"
+```
+
+## Install a version by supplying a semver range or pep440 specifier
+
+You can specify a [semver range](https://github.com/npm/node-semver?tab=readme-ov-file#ranges)
+or [pep440 specifier](https://peps.python.org/pep-0440/#version-specifiers)
+to install the latest version that satisfies the range.
+
+```yaml
+- name: Install a semver range of uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: ">=0.4.0"
+```
+
+```yaml
+- name: Pinning a minor version of uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: "0.4.x"
+```
+
+```yaml
+- name: Install a pep440-specifier-satisfying version of uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: ">=0.4.25,<0.5"
+```
+
+## Resolution strategy
+
+By default, when resolving version ranges, setup-uv will install the highest compatible version.
+You can change this behavior using the `resolution-strategy` input:
+
+```yaml
+- name: Install the lowest compatible version of uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: ">=0.4.0"
+    resolution-strategy: "lowest"
+```
+
+The supported resolution strategies are:
+- `highest` (default): Install the latest version that satisfies the constraints
+- `lowest`: Install the oldest version that satisfies the constraints
+
+This can be useful for testing compatibility with older versions of uv, similar to uv's own `--resolution-strategy` option.
+
+## Install a version defined in a requirements or config file
+
+You can use the `version-file` input to specify a file that contains the version of uv to install.
+This can either be a `pyproject.toml` or `uv.toml` file which defines a `required-version` or
+uv defined as a dependency in `pyproject.toml` or `requirements.txt`.
+
+[asdf](https://asdf-vm.com/) `.tool-versions` is also supported for selecting uv. If neither
+`python-version` nor `UV_PYTHON` is set, the `python` entry from the selected file is also exported
+as `UV_PYTHON`. Only a single Python version is supported; multiple fallback versions and the asdf
+`ref:`, `path:`, and `system` forms are ignored with a warning.
+
+```yaml
+- name: Install uv based on the version defined in pyproject.toml
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version-file: "pyproject.toml"
+```
+
+If uv is locked as a dependency in your `uv.lock`, you can point `version-file` at the
+lockfile to install the exact pinned version. This keeps CI runs deterministic and avoids
+silently picking up a newer uv until the lockfile is updated.
+
+```yaml
+- name: Install uv based on the version locked in uv.lock
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version-file: "uv.lock"
+```

docs/caching.md

@@ -0,0 +1,234 @@
+# Caching
+
+This document covers all caching-related configuration options for setup-uv.
+
+## Cache key
+
+The cache key is automatically generated based on:
+
+- **Architecture**: CPU architecture (e.g., `x86_64`, `aarch64`)
+- **Platform**: OS platform type (e.g., `unknown-linux-gnu`, `unknown-linux-musl`, `apple-darwin`,
+  `pc-windows-msvc`)
+- **OS version**: OS name and version (e.g., `ubuntu-22.04`, `macos-14`, `windows-2022`)
+- **Python version**: The Python version in use
+- **Cache options**: Whether pruning and Python caching are enabled
+- **Dependency hash**: Hash of files matching `cache-dependency-glob`
+- **Suffix**: Optional `cache-suffix` if provided
+
+Including the OS version ensures that caches are not shared between different OS versions,
+preventing binary incompatibility issues when runner images change.
+
+The computed cache key is available as the `cache-key` output:
+
+```yaml
+- name: Setup uv
+  id: setup-uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+- name: Print cache key
+  run: echo "Cache key: ${{ steps.setup-uv.outputs.cache-key }}"
+```
+
+## Enable caching
+
+> [!NOTE]
+> The entire uv cache is uploaded to the GitHub Actions cache by default. To reduce the cache size,
+> see [Enable cache pruning](#enable-cache-pruning).
+
+If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be uploaded to
+the GitHub Actions cache. This can speed up runs that reuse the cache by several minutes.
+With the default `enable-cache: auto`, caching is enabled on GitHub-hosted runners except for
+`release`, tag push, `pull_request_target`, and `workflow_run` events. Caching is disabled for these
+events to prevent insecure or release-sensitive jobs from restoring potentially poisoned caches.
+Set `enable-cache: true` to explicitly enable caching for any event.
+
+> [!TIP]
+>
+> On self-hosted runners this is usually not needed since the cache generated by uv on the runner's
+> filesystem is not removed after a run. For more details see [Local cache path](#local-cache-path).
+
+You can optionally define a custom cache key suffix.
+
+```yaml
+- name: Enable caching and define a custom cache key suffix
+  id: setup-uv
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    cache-suffix: "optional-suffix"
+```
+
+When the cache was successfully restored, the output `cache-hit` will be set to `true` and you can
+use it in subsequent steps. For example, to use the cache in the above case:
+
+```yaml
+- name: Do something if the cache was restored
+  if: steps.setup-uv.outputs.cache-hit == 'true'
+  run: echo "Cache was restored"
+```
+
+## Cache dependency glob
+
+If you want to control when the GitHub Actions cache is invalidated, specify a glob pattern with the
+`cache-dependency-glob` input. The GitHub Actions cache will be invalidated if any file matching the glob pattern
+changes. If you use relative paths, they are relative to the working directory.
+
+> [!NOTE]
+>
+> You can look up supported patterns [here](https://github.com/actions/toolkit/tree/main/packages/glob#patterns)
+>
+> The default is
+> ```yaml
+> cache-dependency-glob: |
+>   **/*requirements*.txt
+>   **/*requirements*.in
+>   **/*constraints*.txt
+>   **/*constraints*.in
+>   **/pyproject.toml
+>   **/uv.lock
+>   **/*.py.lock
+> ```
+
+```yaml
+- name: Define a cache dependency glob
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    cache-dependency-glob: "**/pyproject.toml"
+```
+
+```yaml
+- name: Define a list of cache dependency globs
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    cache-dependency-glob: |
+      **/requirements*.txt
+      **/pyproject.toml
+```
+
+```yaml
+- name: Define an absolute cache dependency glob
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    cache-dependency-glob: "/tmp/my-folder/requirements*.txt"
+```
+
+```yaml
+- name: Never invalidate the cache
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    cache-dependency-glob: ""
+```
+
+## Restore cache
+
+Restoring an existing cache can be enabled or disabled with the `restore-cache` input.
+By default, the cache will be restored.
+
+```yaml
+- name: Don't restore an existing cache
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    restore-cache: false
+```
+
+## Save cache
+
+You can control saving the cache after the run with the `save-cache` input.
+This can be useful to save cache storage when you know you will not use the cache of the run again.
+By default, `save-cache: auto` saves the cache except for `merge_group` events, where caches created
+for temporary merge queue refs are unlikely to be reused. Cache restoration remains enabled for
+these events. Set `save-cache: true` to save the cache for all events.
+
+```yaml
+- name: Don't save the cache after the run
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    save-cache: false
+```
+
+## Local cache path
+
+If caching is enabled, this action controls where uv stores its cache on the runner's filesystem
+by setting `UV_CACHE_DIR`.
+
+It defaults to `setup-uv-cache` in the `TMP` dir, `D:\a\_temp\setup-uv-cache` on Windows and
+`/tmp/setup-uv-cache` on Linux/macOS. You can change the default by specifying the path with the
+`cache-local-path` input.
+
+> [!NOTE]
+> If the environment variable `UV_CACHE_DIR` is already set this action will not override it.
+> If you configured [cache-dir](https://docs.astral.sh/uv/reference/settings/#cache-dir) in your
+> config file then it is also respected and this action will not set `UV_CACHE_DIR`.
+
+> [!NOTE]
+> If caching is disabled, you can still use `cache-local-path` so this action sets `UV_CACHE_DIR`
+> to your desired path.
+
+```yaml
+- name: Define a custom uv cache path
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    cache-local-path: "/path/to/cache"
+```
+
+## Enable cache pruning
+
+By default, the entire uv cache is persisted across runs. On GitHub-hosted runners, it's typically
+faster to prune the cache before saving it, removing pre-built wheels, but retaining any wheels that
+were built from source. The pre-built wheels are then re-downloaded from the registry on each run.
+See the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration)
+for more information.
+
+If you want to prune the cache before saving it, enable cache pruning with the `prune-cache` input.
+
+```yaml
+- name: Prune the cache before saving it
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    prune-cache: true
+```
+
+## Cache Python installs
+
+By default, the Python install dir (`uv python dir` / `UV_PYTHON_INSTALL_DIR`) is not cached,
+for the same reason that pruning the dependency cache can improve performance on GitHub-hosted
+runners.
+If you want to cache Python installs along with your dependencies, set the `cache-python` input to `true`.
+
+Note that this only caches Python versions that uv actually installs into `UV_PYTHON_INSTALL_DIR`
+(i.e. managed Python installs). If uv uses a system Python, there may be nothing to cache.
+To force managed Python installs, set `UV_PYTHON_PREFERENCE=only-managed`.
+
+```yaml
+- name: Cache Python installs
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    cache-python: true
+```
+
+## Ignore nothing to cache
+
+By default, the action will fail if caching is enabled but there is nothing to upload (the uv cache directory does not exist) with an error like
+
+```console
+Error: Cache path /home/runner/.cache/uv does not exist on disk. This likely indicates that there are no dependencies to cache. Consider disabling the cache input if it is not needed.
+```
+
+If you want to ignore this, set the `ignore-nothing-to-cache` input to `true`.
+
+```yaml
+- name: Ignore nothing to cache
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    enable-cache: true
+    ignore-nothing-to-cache: true
+```

docs/customization.md

@@ -0,0 +1,65 @@
+# Customization
+
+This document covers advanced customization options including checksum validation, custom manifests, and problem matchers.
+
+## Validate checksum
+
+Downloaded executables are automatically verified using checksums bundled with this action or,
+for newer, not yet bundled versions, the checksum from [`astral-sh/versions`](https://github.com/astral-sh/versions).
+You can specify a checksum to override those values. The sha256 hashes can also be found on the
+[releases page](https://github.com/astral-sh/uv/releases) of the uv repo.
+
+```yaml
+- name: Install a specific version and validate the checksum
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    version: "0.3.1"
+    checksum: "e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"
+```
+
+## Manifest file
+
+By default, setup-uv reads version metadata from
+[`astral-sh/versions`](https://github.com/astral-sh/versions).
+
+The `manifest-file` input lets you override that source with your own URL, for example to test
+custom uv builds or alternate download locations.
+
+### Format
+
+The manifest file must use the same format as `astral-sh/versions`: one JSON object per line, where each object represents a version and its artifacts. The versions must be sorted in descending order. For example:
+
+```json
+{"version":"0.10.7","artifacts":[{"platform":"x86_64-unknown-linux-gnu","variant":"default","url":"https://example.com/uv-x86_64-unknown-linux-gnu.tar.gz","archive_format":"tar.gz","sha256":"..."}]}
+{"version":"0.10.6","artifacts":[{"platform":"x86_64-unknown-linux-gnu","variant":"default","url":"https://example.com/uv-x86_64-unknown-linux-gnu.tar.gz","archive_format":"tar.gz","sha256":"..."}]}
+```
+
+setup-uv currently only supports `default` as the `variant`.
+
+The `archive_format` field is currently ignored.
+
+```yaml
+- name: Use a custom manifest file
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    manifest-file: "https://example.com/my-custom-manifest.ndjson"
+```
+
+> [!NOTE]
+> When you use a custom manifest file and do not set the `version` input, setup-uv installs the
+> latest version from that custom manifest.
+
+## Add problem matchers
+
+This action automatically adds
+[problem matchers](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)
+for python errors.
+
+You can disable this by setting the `add-problem-matchers` input to `false`.
+
+```yaml
+- name: Install the latest version of uv without problem matchers
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    add-problem-matchers: false
+```

docs/environment-and-tools.md

@@ -0,0 +1,173 @@
+# Environment and Tools
+
+This document covers environment activation, tool directory configuration, and authentication options.
+
+## Activate environment
+
+You can set `activate-environment` to `true` to automatically activate a venv.
+This allows directly using it in later steps:
+
+```yaml
+- name: Install the latest version of uv and activate the environment
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    activate-environment: true
+- run: uv pip install pip
+```
+
+By default, the venv is created at `.venv` inside the `working-directory`.
+
+With `activate-environment: true`, the `python-runtime-id` output identifies the
+venv's Python runtime as reported by uv. This is an opaque identifier that users of the action
+can use as a cache key if necessary; users should not assume anything about
+the stability or structure of the identifier itself.
+
+For example, you can combine it with the platform and dependency information relevant to
+your cache with `id: setup-uv` on the setup step:
+
+```yaml
+key: build-${{ runner.os }}-${{ runner.arch }}-${{ steps.setup-uv.outputs.python-runtime-id }}-${{ hashFiles('uv.lock') }}
+```
+
+You can customize the venv location with `venv-path`, for example to place it in the runner temp directory:
+
+```yaml
+- uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    activate-environment: true
+    venv-path: ${{ runner.temp }}/custom-venv
+```
+
+> [!WARNING]
+>
+> Activating the environment adds your dependencies to the `PATH`, which could break some workflows.
+> For example, if you have a dependency which requires uv, e.g., `hatch`, activating the
+> environment will shadow the `uv` binary installed by this action and may result in a different uv
+> version being used.
+>
+> We do not recommend using this setting for most use-cases. Instead, use `uv run` to execute
+> commands in the environment.
+
+## GitHub authentication token
+
+By default, this action resolves available uv versions from
+[`astral-sh/versions`](https://github.com/astral-sh/versions), then downloads uv artifacts from
+GitHub Releases.
+
+You can provide a token via `github-token` to authenticate those downloads. By default, the
+`GITHUB_TOKEN` secret is used, which is automatically provided by GitHub Actions.
+
+If the default
+[permissions for the GitHub token](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)
+are not sufficient, you can provide a custom GitHub token with the necessary permissions.
+
+```yaml
+- name: Install the latest version of uv with a custom GitHub token
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
+```
+
+## UV_TOOL_DIR
+
+On Windows `UV_TOOL_DIR` is set to `uv-tool-dir` in the `TMP` dir (e.g. `D:\a\_temp\uv-tool-dir`).
+On GitHub hosted runners this is on the much faster `D:` drive.
+
+On all other platforms the tool environments are placed in the
+[default location](https://docs.astral.sh/uv/concepts/tools/#tools-directory).
+
+If you want to change this behaviour (especially on self-hosted runners) you can use the `tool-dir`
+input:
+
+```yaml
+- name: Install the latest version of uv with a custom tool dir
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    tool-dir: "/path/to/tool/dir"
+```
+
+## UV_TOOL_BIN_DIR
+
+On Windows `UV_TOOL_BIN_DIR` is set to `uv-tool-bin-dir` in the `TMP` dir (e.g.
+`D:\a\_temp\uv-tool-bin-dir`). On GitHub hosted runners this is on the much faster `D:` drive. This
+path is also automatically added to the PATH.
+
+On all other platforms the tool binaries get installed to the
+[default location](https://docs.astral.sh/uv/concepts/tools/#the-bin-directory).
+
+If you want to change this behaviour (especially on self-hosted runners) you can use the
+`tool-bin-dir` input:
+
+```yaml
+- name: Install the latest version of uv with a custom tool bin dir
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    tool-bin-dir: "/path/to/tool-bin/dir"
+```
+
+## Tilde Expansion
+
+This action supports expanding the `~` character to the user's home directory for the following inputs:
+
+- `version-file`
+- `cache-local-path`
+- `tool-dir`
+- `tool-bin-dir`
+- `cache-dependency-glob`
+
+```yaml
+- name: Expand the tilde character
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    cache-local-path: "~/path/to/cache"
+    tool-dir: "~/path/to/tool/dir"
+    tool-bin-dir: "~/path/to/tool-bin/dir"
+    cache-dependency-glob: "~/my-cache-buster"
+```
+
+## Ignore empty workdir
+
+By default, the action will warn if the workdir is empty, because this is usually the case when
+`actions/checkout` is configured to run after `setup-uv`, which is not supported.
+
+If you want to ignore this, set the `ignore-empty-workdir` input to `true`.
+
+```yaml
+- name: Ignore empty workdir
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    ignore-empty-workdir: true
+```
+
+## Environment Variables
+
+This action sets several environment variables that influence uv's behavior and can be used by subsequent steps:
+
+- `UV_PYTHON`: Set when `python-version` is specified or the selected `.tool-versions` file contains a supported `python` entry. Controls which Python version uv uses.
+- `UV_CACHE_DIR`: Set when caching is enabled (unless already configured in uv config files). Controls where uv stores its cache.
+- `UV_TOOL_DIR`: Set when `tool-dir` input is specified. Controls where uv installs tool environments.
+- `UV_TOOL_BIN_DIR`: Set when `tool-bin-dir` input is specified. Controls where uv installs tool binaries.
+- `UV_PYTHON_INSTALL_DIR`: Always set. Controls where uv installs Python versions.
+- `VIRTUAL_ENV`: Set when `activate-environment` is true. Points to the activated virtual environment.
+
+**Environment variables that affect the action behavior:**
+
+- `UV_NO_MODIFY_PATH`: If set, prevents the action from modifying PATH. Cannot be used with `activate-environment`.
+- `UV_CACHE_DIR`: If already set, the action will respect it instead of setting its own cache directory.
+- `UV_PYTHON`: If already set and `python-version` is not specified, the action will respect it instead of using the `python` entry from `.tool-versions`.
+
+```yaml
+- name: Example using environment variables
+  uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+  with:
+    python-version: "3.12"
+    tool-dir: "/custom/tool/dir"
+    enable-cache: true
+
+- name: Check environment variables
+  run: |
+    echo "UV_PYTHON: $UV_PYTHON"
+    echo "UV_CACHE_DIR: $UV_CACHE_DIR"
+    echo "UV_TOOL_DIR: $UV_TOOL_DIR"
+    echo "UV_PYTHON_INSTALL_DIR: $UV_PYTHON_INSTALL_DIR"
+```

docs/threat-model.md

@@ -0,0 +1,81 @@
+# setup-uv Repository Threat Model
+
+## Overview
+
+`setup-uv` is a GitHub Action that installs or reuses `uv`, modifies `PATH` and the environment for later steps, may execute a discovered Python interpreter, may create or clear a virtual environment, and may restore or save caches. It may use `github-token` to authenticate GitHub downloads; it requires no OIDC credential or additional workflow secret.
+
+The consumer runtime is the selected ref's committed action metadata, bundles, and runner-interpreted companion files; source alone is not evidence of shipped behavior. Privileged automation that generates, updates, or publishes those artifacts is also in scope.
+
+The assets are job credentials; integrity of installed executables, interpreter, environment, checkout, runner, artifacts, and caches; isolation between jobs sharing caches or persistent runners; integrity of published action refs; and workflow compute/storage availability.
+
+Material failures are unauthorized executable selection, credential disclosure, premature execution of lower-authority content, filesystem escape or destructive path use, cross-authority cache/runner persistence, and unauthorized publication.
+
+## Threat Model, Trust Boundaries, and Assumptions
+
+### Authority and trust boundaries
+
+| Actor or input | Trust decision |
+|---|---|
+| Maintainers, repository/configuration administrators, and GitHub infrastructure | Trusted roots for source, bundles, workflows, refs, rulesets, environments, runner protocol, hosted isolation, and cache service. A lower-authority path into these roots is in scope; their compromise alone is not a repository bug. |
+| Consumer workflow authors and runner operators | Control the action ref, trigger, runner, permissions, secrets, proxy, environment, inputs, paths, globs, and custom sources. These are trusted choices unless derived from lower-authority event data. Selecting a custom manifest delegates metadata and executable authority; selecting a path authorizes normal operations on it and intended referents. |
+| Selected checkout, project authors, and pull-request contributors | The consumer delegates project/version files, interpreter discovery state, virtual environments, symlinks, cache inputs, and code execution within `setup-uv`'s process environment. Checkout-controlled behavior is trusted unless it overrides an explicit workflow choice or crosses an independent cache, runner, remote, or publication boundary. |
+| Remote metadata and artifacts | Default official endpoints, TLS roots, and an operator proxy are trusted mutable authorities. A custom manifest authorizes its URLs and hashes; a hash supplied by that same authority detects corruption, not malice. |
+| Cache and runner-state producers/consumers | Same-principal state is trusted by default. Integrity attacks require a lower-authority producer and higher-authority consumer. Confidentiality can flow the opposite way because lower-authority refs may read eligible higher-authority caches. Shared self-hosted state creates a boundary only when principals and authority differ. |
+| GitHub-managed automation | Dependency, coding-agent, and review workflows may exist outside the committed tree. Treat them as external principals and obtain their effective trigger, actor, token, environment, ref, and write/secret authority from live evidence. |
+
+### Assumptions
+
+- Running the selected `uv` and checkout-selected Python interpreters is intended. Project execution is out of scope unless it bypasses an explicit workflow choice or crosses an independent cache, runner, remote, or publication boundary.
+- Mutable official manifests, ranges, `latest`, and unprotected refs are not attacker control. A protected ref or independent checksum matters only if the selected bundle actually enforces it.
+- Same-user changes to paths, environment, proxies, or tool/cache state are not separate attacks. Demonstrate a cross-principal or lower-to-higher boundary.
+- Content merged through a trust path that can also merge executable code is not a lower-authority source; require a narrower writer or post-review mutation path.
+- Running `setup-uv` on an untrusted checkout with higher authority is a consumer trust decision; checkout-selected code may inherit the action environment.
+- Authorized paths include expected symlink/junction referents. Absolute paths and paths outside the workspace are supported; an escape requires independent control crossing an unauthorized boundary.
+- Hosted runners are assumed ephemeral and isolated. Persistence or hostile co-tenancy on self-hosted runners must be demonstrated.
+- Branch/tag rules, environments, token defaults, cache visibility, fork policy, dynamic workflows, and runner allocation are external state. Re-query required approvals/checks, bypass actors, tag movement, deployment reviewers/principals, release targets, and effective permissions for each attack path.
+- Web-application classes such as sessions, CSRF, XSS, SQL injection, and tenant isolation are not applicable.
+
+### Security invariants
+
+1. **Published runtime:** review `action.yml`, committed `dist/*.cjs`, and runner-interpreted shipped files; source-only fixes do not protect consumers.
+2. **Executable identity:** precedence is workflow version, version file, project configuration, then `latest`. Manifest authority, platform, variant, URL, checksum, mirror fallback, extraction, and cache placement must bind the intended artifact. A tool-cache hit bypasses download validation and depends on cache provenance.
+3. **Credential recipients:** tokens and URL credentials may reach only workflow-authorized origins, redirects, paths, and logs. Metadata authority does not imply token-recipient authority.
+4. **Executable boundaries:** checkout-selected interpreters are authorized by default. Explicit workflow selections must win, and independent cache, runner, or remote state must not substitute executables or gain additional authority.
+5. **Paths and action channels:** path/environment changes, virtual-environment clearing, outputs, state, and problem matchers must affect only authorized targets and keep untrusted values as data.
+6. **Cache boundaries:** keys, scope, restore paths, and executable content must prevent lower-to-higher poisoning; cache contents and post-action path re-resolution must prevent higher-to-lower disclosure, destructive pruning, or persistence.
+7. **Workflow and release authority:** unreviewed code or mutable tooling must not acquire write, secret, OIDC, artifact, deployment, tag, or publication authority. Only the intended reviewed bundles and commit may be released.
+8. **Availability:** independently controlled manifests, archives, globs, traversal, and caches must stay within the accepted one-job resource-failure model.
+
+### Finding gate
+
+Before reporting, identify the attacker and victim principals; exact controlled input; scanned action and checkout refs; runtime reachability in committed bundles; effective token, secrets/OIDC, environment gates, cache scope, and runner persistence; applicable defaults and opt-ins; validation performed or skipped; declared trust roots; baseline versus incremental capability; and concrete impact. Reproduce platform-specific behavior and distinguish the scanned ref from other versions.
+
+A report must demonstrate independent attacker control, a violated guarantee, committed-runtime reachability, incremental capability, and practical impact; otherwise it is not a security finding and should not be reported as one.
+
+## Attack Surface, Mitigations, and Attacker Stories
+
+| Surface | Security-relevant behavior and controls | Reportable attacker story |
+|---|---|---|
+| Published action and build/release supply chain | Consumers execute committed bundles and embedded dependencies. Verify source/bundle alignment, lockfile integrity, dependency-install policy, reproducible/generated-diff checks, immutable action pins, branch enforcement, and publication target checks. | A lower-authority contributor or dependency changes shipped code, or release automation publishes a different commit, by bypassing an effective review, branch, or release control. |
+| Version, manifest, proxy, and network selection | Project files may select an official version by documented precedence. Custom manifests may select URLs, hashes, variants, and platforms and may reach arbitrary network locations. Parsing should reject malformed, ambiguous, unsupported, or incorrectly typed records; verify HTTPS, time/size bounds, proxy behavior, and selected-ref defaults. | Lower-authority event/project data violates a promised fixed version, escapes the selected manifest, probes runner-only services, causes material resource use, selects attacker bytes, or redirects later credentials. Operator selection of a custom authority is not itself a finding. |
+| Artifact URL, token, checksum, extraction, and tool cache | Mirror fallback must preserve identity and checksum policy. Origin gating should restrict tokens; redirect handling should strip authorization across unauthorized hosts and reject downgrade. Verify checksum precedence and reject missing/empty hashes when policy requires validation. Independent hashes must precede extraction. Native helpers come from `PATH`; tool-cache hits skip network/hash validation. | An attacker receives a usable token outside delegated authority, bypasses an independent pin, exploits archive/link traversal, substitutes the cached executable, or poisons shared tool state later executed with higher authority. Same-authority manifest hashes and same-user cache changes do not establish the boundary. |
+| Interpreter, PATH, virtual environment, and action channels | Checkout-selected interpreters, virtual environments, paths, symlinks, and helpers are delegated project authority. Explicit workflow choices must bind; the action also changes later-step paths/environment, emits state/outputs, invokes native helpers, and consumes cache/runner state. | Independent cache, runner, or remote content substitutes an executable; an explicit workflow choice is bypassed; or action channels cross an authority boundary. Same-checkout interpreter, path, and helper effects are not findings. |
+| GitHub uv/Python caches and post action | Cache keys should partition platform, interpreter, dependency, and policy state and restore without unsafe fallback. Determine cache defaults, visibility, and the exact hit/miss path from the selected ref and GitHub policy; an exact hit may suppress post save/prune. Post processing re-reads inputs/config/environment and may save re-resolved uv or Python paths. | A lower producer supplies executable content to a higher consumer; a higher producer exposes private data to a lower cache reader; or a later successful step retargets a cache miss toward sensitive files, destructive pruning, or cross-job persistence. Existing equal-authority code with the same secrets often gains no new confidentiality. |
+| CI, updater, dynamic automation, and release workflows | PR workflows intentionally execute contributor code. Verify effective permissions, fork behavior, credential persistence, mutable tooling, security-upload authority, and whether checks are required. Updaters convert remote data into source under write authority. Distinguish ruleset-required deployment from human review present only in a workflow DAG. | Unreviewed code gains write/secret/OIDC/artifact authority; remote metadata becomes executable generated source; a dynamic workflow has unexpected authority; or an actor satisfies a deployment/tag rule without the intended review and publishes a malicious ref. |
+| Availability and logging | Manifests, version enumeration, archives, globs, hashing, caches, and remote strings can consume resources or influence logs. Verify size/count/expansion bounds, timeouts, retries, top-level error handling, and that parsing never executes data. | Independently controlled input causes reliable material workflow cost, disk/memory exhaustion, or meaningful log/output manipulation. A bounded one-job failure or operator-selected broad input is usually Low or correctness. |
+| Lower-priority classes | Shell injection is constrained where child execution uses argv, but workflow shell blocks still require quoting review. Prototype pollution requires a dangerous merge/sink. Secret-shaped strings require proof of a genuine usable secret. Documentation drift, range surprises, malformed trusted config, and test-only code normally lack a security boundary. | Report only when a concrete lower-authority value reaches an execution, credential, persistent-state, publication, or material-availability sink. |
+
+## Severity Calibration (Critical, High, Medium, Low)
+
+Severity follows the complete attack graph and incremental capability, not the presence of words such as token, checksum, cache, manifest, archive, Python, PATH, release, or OIDC.
+
+| Severity | Threshold | Representative examples |
+|---|---|---|
+| **Critical** | A low-prerequisite remote/lower-authority attacker compromises default distribution or installation across many consumers, publishes trusted malicious action artifacts, or gains broad credentials/runner control under safe defaults without first compromising a declared trust root. | Bypass an effective hash/origin control to distribute an automatically executed malicious binary at scale; reach publication authority to ship malicious bundles or move trusted refs without required approval; exploit default-accepted archive content for host overwrite or cross-job execution across hosted runners. |
+| **High** | A demonstrated lower-authority input crosses an execution, confidentiality, integrity, or persistence boundary in a privileged job and gains substantial capability. | Independent shared-state interpreter substitution in a write/OIDC release job; shared cache poisoning later executed with secrets; high-value cache disclosure to an untrusted ref; usable write-token disclosure; independent-pin bypass; archive/cache escape into sensitive state. |
+| **Medium** | A real but constrained crossing causes limited credential/filesystem impact, reliable remote denial of service, scoped persistence, or premature execution in a realistic uncommon configuration. | Limited executable substitution from independent cache/runner state in a read-only job; same-repository cache confusion or disclosure; reliable hosted-runner exhaustion; disclosure of a usable read-only private token; output manipulation without publication or high-value credentials. |
+| **Low** | A genuine weak boundary causes narrow disclosure, log/annotation spoofing, defense-in-depth weakness, exotic cache aliasing without a privileged consumer, or limited waste. | Confusing logs with no execution effect; bounded job failure; limited overwrite of nonexecuted cache data; disclosure of a path/URL without private data or follow-on capability. |
+
+Trust-root compromise may have Critical impact but is not a repository Critical without a lower-authority path into that root or an independent control that should have survived. High requires exact trigger, refs, effective authority, sink, and committed runtime; it cannot rely only on a trusted operator choosing malicious inputs, same-user state changes, or code already intentionally executed with equal authority. A separate privileged consumer, broad secret, persistent trusted state, publication path, or cross-repository boundary can raise Medium to High.
+
+Normally non-reportable without additional evidence: expected mutability of ranges, `latest`, official/custom sources, or unprotected refs; documented project version selection; checkout-selected interpreters, paths, virtual environments, symlinks, and helpers; deliberate operator selection of manifests, proxies, checksums, or paths; same-principal cache/path changes; requested `uv` or dependency execution; trusted-runner `PATH` lookup; test/developer-only code without a shipped or privileged-workflow path; behavior fixed in the scanned ref; and correctness/compatibility/documentation issues without incremental confidentiality, integrity, persistence, or availability impact.

jest.config.js

@@ -1,9 +0,0 @@
-module.exports = {
-  clearMocks: true,
-  moduleFileExtensions: ["js", "ts"],
-  testMatch: ["**/*.test.ts"],
-  transform: {
-    "^.+\\.ts$": "ts-jest",
-  },
-  verbose: true,
-};

jest.config.mjs

@@ -0,0 +1,14 @@
+import { createDefaultEsmPreset } from "ts-jest";
+
+const esmPreset = createDefaultEsmPreset({
+  tsconfig: "./tsconfig.json",
+});
+
+export default {
+  ...esmPreset,
+  clearMocks: true,
+  moduleFileExtensions: ["js", "mjs", "ts"],
+  testEnvironment: "node",
+  testMatch: ["**/*.test.ts"],
+  verbose: true,
+};

package.json

@@ -2,47 +2,62 @@
   "name": "setup-uv",
   "version": "1.0.0",
   "private": true,
+  "type": "module",
   "description": "Set up your GitHub Actions workflow with a specific version of uv",
-  "main": "dist/index.js",
+  "main": "dist/setup/index.cjs",
+  "engines": {
+    "npm": ">=11.10.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=11.10.0",
+      "onFail": "error"
+    }
+  },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc --noEmit",
     "check": "biome check --write",
-    "package": "ncc build -o dist/setup src/setup-uv.ts && ncc build -o dist/save-cache src/save-cache.ts && ncc build -o dist/update-known-versions src/update-known-versions.ts",
+    "package": "node scripts/build-dist.mjs",
-    "test": "jest",
+    "test:unit": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
+    "test": "npm run build && npm run test:unit",
     "act": "act pull_request -W .github/workflows/test.yml --container-architecture linux/amd64 -s GITHUB_TOKEN=\"$(gh auth token)\"",
-    "update-known-versions": "RUNNER_TEMP=known_versions node dist/update-known-versions/index.js src/download/checksum/known-versions.ts \"$(gh auth token)\"",
+    "update-known-checksums": "RUNNER_TEMP=known_versions node dist/update-known-checksums/index.cjs src/download/checksum/known-checksums.json",
-    "all": "npm run build && npm run check && npm run package && npm test"
+    "all": "npm run build && npm run check && npm run package && npm run test:unit"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/astral-sh/setup-uv.git"
   },
-  "keywords": ["actions", "python", "setup", "uv"],
+  "keywords": [
+    "actions",
+    "python",
+    "setup",
+    "uv"
+  ],
   "author": "@eifinger",
   "license": "MIT",
   "dependencies": {
-    "@actions/cache": "^4.0.5",
+    "@actions/cache": "^6.2.0",
-    "@actions/core": "^1.11.1",
+    "@actions/core": "^3.0.0",
-    "@actions/exec": "^1.1.1",
+    "@actions/exec": "^3.0.0",
-    "@actions/glob": "^0.5.0",
+    "@actions/glob": "^0.7.0",
-    "@actions/io": "^1.1.3",
+    "@actions/io": "^3.0.2",
-    "@actions/tool-cache": "^2.0.2",
+    "@actions/tool-cache": "^4.0.0",
-    "@octokit/core": "^7.0.5",
+    "@renovatebot/pep440": "^5.0.0",
-    "@octokit/plugin-paginate-rest": "^13.1.1",
+    "smol-toml": "^1.8.0",
-    "@octokit/plugin-rest-endpoint-methods": "^16.1.0",
+    "undici": "^8.10.0"
-    "@renovatebot/pep440": "^4.2.1",
-    "smol-toml": "^1.4.2",
-    "undici": "^7.16.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.2.4",
+    "@biomejs/biome": "^2.5.9",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^24.7.0",
+    "@types/node": "^26.2.0",
-    "@types/semver": "^7.7.1",
+    "@types/semver": "^7.8.0",
-    "@vercel/ncc": "^0.38.4",
+    "@vercel/ncc": "^0.45.0",
-    "jest": "^30.1.3",
+    "esbuild": "^0.28.2",
-    "js-yaml": "^4.1.0",
+    "jest": "^30.4.2",
-    "ts-jest": "^29.4.4",
+    "js-yaml": "^5.3.0",
-    "typescript": "^5.9.2"
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
   }
 }

scripts/build-dist.mjs

@@ -0,0 +1,33 @@
+import { rm } from "node:fs/promises";
+import { build } from "esbuild";
+
+const builds = [
+  {
+    entryPoints: ["src/setup-uv.ts"],
+    outfile: "dist/setup/index.cjs",
+    staleOutfiles: ["dist/setup/index.mjs"],
+  },
+  {
+    entryPoints: ["src/save-cache.ts"],
+    outfile: "dist/save-cache/index.cjs",
+    staleOutfiles: ["dist/save-cache/index.mjs"],
+  },
+  {
+    entryPoints: ["src/update-known-checksums.ts"],
+    outfile: "dist/update-known-checksums/index.cjs",
+    staleOutfiles: ["dist/update-known-checksums/index.mjs"],
+  },
+];
+
+for (const { staleOutfiles, ...options } of builds) {
+  await Promise.all(
+    staleOutfiles.map((outfile) => rm(outfile, { force: true })),
+  );
+  await build({
+    bundle: true,
+    format: "cjs",
+    platform: "node",
+    target: "node24",
+    ...options,
+  });
+}

src/cache/restore-cache.ts

@@ -1,121 +1,123 @@
 import * as cache from "@actions/cache";
 import * as core from "@actions/core";
-import * as exec from "@actions/exec";
 import { hashFiles } from "../hash/hash-files";
-import {
+import type { SetupInputs } from "../utils/inputs";
-  cacheDependencyGlob,
+import * as log from "../utils/logging";
-  cacheLocalPath,
+import { getArch, getOSNameVersion, getPlatform } from "../utils/platforms";
-  cachePython,
-  cacheSuffix,
-  pruneCache,
-  pythonDir,
-  pythonVersion as pythonVersionInput,
-  restoreCache as shouldRestoreCache,
-  workingDirectory,
-} from "../utils/inputs";
-import { getArch, getPlatform } from "../utils/platforms";
 
 export const STATE_CACHE_KEY = "cache-key";
 export const STATE_CACHE_MATCHED_KEY = "cache-matched-key";
-const CACHE_VERSION = "1";
+export const STATE_PYTHON_CACHE_MATCHED_KEY = "python-cache-matched-key";
 
-export async function restoreCache(): Promise<void> {
+const CACHE_VERSION = "2";
-  const cacheKey = await computeKeys();
+
+export async function restoreCache(
+  inputs: SetupInputs,
+  pythonVersion?: string,
+): Promise<void> {
+  const cacheKey = await computeKeys(inputs, pythonVersion);
   core.saveState(STATE_CACHE_KEY, cacheKey);
+  core.setOutput("cache-key", cacheKey);
 
-  if (!shouldRestoreCache) {
+  if (!inputs.restoreCache) {
-    core.info("restore-cache is false. Skipping restore cache step.");
+    log.info("restore-cache is false. Skipping restore cache step.");
+    core.setOutput("python-cache-hit", false);
     return;
   }
 
-  let matchedKey: string | undefined;
+  if (inputs.cacheLocalPath === undefined) {
-  core.info(
+    throw new Error(
-    `Trying to restore uv cache from GitHub Actions cache with key: ${cacheKey}`,
+      "cache-local-path is not set. Cannot restore cache without a valid cache path.",
     );
-  const cachePaths = [cacheLocalPath];
-  if (cachePython) {
-    cachePaths.push(pythonDir);
-  }
-  try {
-    matchedKey = await cache.restoreCache(cachePaths, cacheKey);
-  } catch (err) {
-    const message = (err as Error).message;
-    core.warning(message);
-    core.setOutput("cache-hit", false);
-    return;
   }
 
-  handleMatchResult(matchedKey, cacheKey);
+  await restoreCacheFromKey(
+    cacheKey,
+    inputs.cacheLocalPath.path,
+    STATE_CACHE_MATCHED_KEY,
+    "cache-hit",
+  );
+
+  if (inputs.cachePython) {
+    await restoreCacheFromKey(
+      `${cacheKey}-python`,
+      inputs.pythonDir,
+      STATE_PYTHON_CACHE_MATCHED_KEY,
+      "python-cache-hit",
+    );
+  } else {
+    core.setOutput("python-cache-hit", false);
+  }
 }
 
-async function computeKeys(): Promise<string> {
+async function restoreCacheFromKey(
-  let cacheDependencyPathHash = "-";
+  cacheKey: string,
-  if (cacheDependencyGlob !== "") {
+  cachePath: string,
-    core.info(
+  stateKey: string,
-      `Searching files using cache dependency glob: ${cacheDependencyGlob.split("\n").join(",")}`,
+  outputKey: string,
+): Promise<void> {
+  log.info(
+    `Trying to restore cache from GitHub Actions cache with key: ${cacheKey}`,
+  );
+  let matchedKey: string | undefined;
+  try {
+    matchedKey = await cache.restoreCache([cachePath], cacheKey);
+  } catch (err) {
+    const message = (err as Error).message;
+    log.warning(message);
+    core.setOutput(outputKey, false);
+    return;
+  }
+
+  handleMatchResult(matchedKey, cacheKey, stateKey, outputKey);
+}
+
+async function computeKeys(
+  inputs: SetupInputs,
+  pythonVersion?: string,
+): Promise<string> {
+  let cacheDependencyPathHash = "-";
+  if (inputs.cacheDependencyGlob !== "") {
+    log.info(
+      `Searching files using cache dependency glob: ${inputs.cacheDependencyGlob.split("\n").join(",")}`,
+    );
+    cacheDependencyPathHash += await hashFiles(
+      inputs.cacheDependencyGlob,
+      true,
     );
-    cacheDependencyPathHash += await hashFiles(cacheDependencyGlob, true);
     if (cacheDependencyPathHash === "-") {
-      core.warning(
+      log.warning(
-        `No file matched to [${cacheDependencyGlob.split("\n").join(",")}]. The cache will never get invalidated. Make sure you have checked out the target repository and configured the cache-dependency-glob input correctly.`,
+        `No file matched to [${inputs.cacheDependencyGlob.split("\n").join(",")}]. The cache will never get invalidated. Make sure you have checked out the target repository and configured the cache-dependency-glob input correctly.`,
       );
     }
   }
   if (cacheDependencyPathHash === "-") {
     cacheDependencyPathHash = "-no-dependency-glob";
   }
-  const suffix = cacheSuffix ? `-${cacheSuffix}` : "";
+  const suffix = inputs.cacheSuffix
-  const pythonVersion = await getPythonVersion();
+    ? `-${encodeURIComponent(inputs.cacheSuffix)}`
+    : "";
+  const version = encodeURIComponent(pythonVersion ?? "unknown");
   const platform = await getPlatform();
-  const pruned = pruneCache ? "-pruned" : "";
+  const osNameVersion = getOSNameVersion();
-  const python = cachePython ? "-py" : "";
+  const pruned = inputs.pruneCache ? "-pruned" : "";
-  return `setup-uv-${CACHE_VERSION}-${getArch()}-${platform}-${pythonVersion}${pruned}${python}${cacheDependencyPathHash}${suffix}`;
+  const python = inputs.cachePython ? "-py" : "";
-}
+  return `setup-uv-${CACHE_VERSION}-${getArch()}-${platform}-${osNameVersion}-${version}${pruned}${python}${cacheDependencyPathHash}${suffix}`;
-
-async function getPythonVersion(): Promise<string> {
-  if (pythonVersionInput !== "") {
-    return pythonVersionInput;
-  }
-
-  let output = "";
-  const options: exec.ExecOptions = {
-    listeners: {
-      stdout: (data: Buffer) => {
-        output += data.toString();
-      },
-    },
-    silent: !core.isDebug(),
-  };
-
-  try {
-    const execArgs = ["python", "find", "--directory", workingDirectory];
-    await exec.exec("uv", execArgs, options);
-    const pythonPath = output.trim();
-
-    output = "";
-    await exec.exec(pythonPath, ["--version"], options);
-    // output is like "Python 3.8.10"
-    return output.split(" ")[1].trim();
-  } catch (error) {
-    const err = error as Error;
-    core.debug(`Failed to get python version from uv. Error: ${err.message}`);
-    return "unknown";
-  }
 }
 
 function handleMatchResult(
   matchedKey: string | undefined,
   primaryKey: string,
+  stateKey: string,
+  outputKey: string,
 ): void {
   if (!matchedKey) {
-    core.info(`No GitHub Actions cache found for key: ${primaryKey}`);
+    log.info(`No GitHub Actions cache found for key: ${primaryKey}`);
-    core.setOutput("cache-hit", false);
+    core.setOutput(outputKey, false);
     return;
   }
 
-  core.saveState(STATE_CACHE_MATCHED_KEY, matchedKey);
+  core.saveState(stateKey, matchedKey);
-  core.info(
+  log.info(`cache restored from GitHub Actions cache with key: ${matchedKey}`);
-    `uv cache restored from GitHub Actions cache with key: ${matchedKey}`,
+  core.setOutput(outputKey, true);
-  );
-  core.setOutput("cache-hit", true);
 }

src/download/checksum/checksum.ts

@@ -6,33 +6,46 @@ import type { Architecture, Platform } from "../../utils/platforms";
 import { KNOWN_CHECKSUMS } from "./known-checksums";
 
 export async function validateChecksum(
-  checkSum: string | undefined,
+  checksum: string | undefined,
   downloadPath: string,
   arch: Architecture,
   platform: Platform,
   version: string,
+  manifestChecksum?: string,
 ): Promise<void> {
-  let isValid: boolean | undefined;
-  if (checkSum !== undefined && checkSum !== "") {
-    isValid = await validateFileCheckSum(downloadPath, checkSum);
-  } else {
-    core.debug("Checksum not provided. Checking known checksums.");
   const key = `${arch}-${platform}-${version}`;
-    if (key in KNOWN_CHECKSUMS) {
+  const hasProvidedChecksum = checksum !== undefined && checksum !== "";
-      const knownChecksum = KNOWN_CHECKSUMS[`${arch}-${platform}-${version}`];
+  const knownChecksum = KNOWN_CHECKSUMS[key];
-      core.debug(`Checking checksum for ${arch}-${platform}-${version}.`);
+  const hasManifestChecksum =
-      isValid = await validateFileCheckSum(downloadPath, knownChecksum);
+    manifestChecksum !== undefined && manifestChecksum !== "";
-    } else {
+  const checksumToUse = hasProvidedChecksum
-      core.debug(`No known checksum found for ${key}.`);
+    ? checksum
+    : (knownChecksum ?? (hasManifestChecksum ? manifestChecksum : undefined));
+
+  if (checksumToUse === undefined) {
+    if (manifestChecksum !== undefined) {
+      throw new Error(`No checksum found for ${key} in manifest.`);
     }
+    core.debug(`No checksum found for ${key}.`);
+    return;
   }
 
-  if (isValid === false) {
+  const checksumSource = hasProvidedChecksum
-    throw new Error(`Checksum for ${downloadPath} did not match ${checkSum}.`);
+    ? "provided checksum"
+    : knownChecksum !== undefined
+      ? `KNOWN_CHECKSUMS entry for ${key}`
+      : "manifest checksum";
+
+  core.debug(`Validating checksum using ${checksumSource}.`);
+  const isValid = await validateFileCheckSum(downloadPath, checksumToUse);
+
+  if (!isValid) {
+    throw new Error(
+      `Checksum for ${downloadPath} did not match ${checksumToUse}.`,
+    );
   }
-  if (isValid === true) {
+
   core.debug(`Checksum for ${downloadPath} is valid.`);
-  }
 }
 
 async function validateFileCheckSum(

src/download/checksum/known-version.ts

@@ -0,0 +1,23 @@
+import * as semver from "semver";
+import { KNOWN_CHECKSUMS } from "./known-checksums";
+
+const VERSION_IN_CHECKSUM_KEY_PATTERN =
+  /-(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)$/;
+
+export function getLatestKnownVersion(): string {
+  const versions = new Set<string>();
+
+  for (const key of Object.keys(KNOWN_CHECKSUMS)) {
+    const version = key.match(VERSION_IN_CHECKSUM_KEY_PATTERN)?.[1];
+    if (version !== undefined) {
+      versions.add(version);
+    }
+  }
+
+  const latestVersion = [...versions].sort(semver.rcompare)[0];
+  if (!latestVersion) {
+    throw new Error("Could not determine latest known version from checksums.");
+  }
+
+  return latestVersion;
+}

src/download/checksum/update-known-checksums.ts

@@ -1,59 +1,25 @@
 import { promises as fs } from "node:fs";
-import * as tc from "@actions/tool-cache";
+
-import { KNOWN_CHECKSUMS } from "./known-checksums";
+export interface ChecksumEntry {
+  key: string;
+  checksum: string;
+}
+
 export async function updateChecksums(
   filePath: string,
-  downloadUrls: string[],
+  checksumEntries: ChecksumEntry[],
 ): Promise<void> {
-  await fs.rm(filePath);
+  const deduplicatedEntries = new Map<string, string>();
-  await fs.appendFile(
+
-    filePath,
+  for (const entry of checksumEntries) {
-    "// AUTOGENERATED_DO_NOT_EDIT\nexport const KNOWN_CHECKSUMS: { [key: string]: string } = {\n",
+    if (deduplicatedEntries.has(entry.key)) {
-  );
-  let firstLine = true;
-  for (const downloadUrl of downloadUrls) {
-    const key = getKey(downloadUrl);
-    if (key === undefined) {
       continue;
     }
-    const checksum = await getOrDownloadChecksum(key, downloadUrl);
-    if (!firstLine) {
-      await fs.appendFile(filePath, ",\n");
-    }
-    await fs.appendFile(filePath, `  "${key}":\n    "${checksum}"`);
-    firstLine = false;
-  }
-  await fs.appendFile(filePath, ",\n};\n");
-}
 
-function getKey(downloadUrl: string): string | undefined {
+    deduplicatedEntries.set(entry.key, entry.checksum);
-  // https://github.com/astral-sh/uv/releases/download/0.3.2/uv-aarch64-apple-darwin.tar.gz.sha256
-  const parts = downloadUrl.split("/");
-  const fileName = parts[parts.length - 1];
-  if (fileName.startsWith("source")) {
-    return undefined;
   }
-  const name = fileName.split(".")[0].split("uv-")[1];
-  const version = parts[parts.length - 2];
-  return `${name}-${version}`;
-}
 
-async function getOrDownloadChecksum(
+  const content = `${JSON.stringify(Object.fromEntries(deduplicatedEntries), null, 2)}\n`;
-  key: string,
-  downloadUrl: string,
-): Promise<string> {
-  let checksum = "";
-  if (key in KNOWN_CHECKSUMS) {
-    checksum = KNOWN_CHECKSUMS[key];
-  } else {
-    const content = await downloadAssetContent(downloadUrl);
-    checksum = content.split(" ")[0].trim();
-  }
-  return checksum;
-}
 
-async function downloadAssetContent(downloadUrl: string): Promise<string> {
+  await fs.writeFile(filePath, content);
-  const downloadPath = await tc.downloadTool(downloadUrl);
-  const content = await fs.readFile(downloadPath, "utf8");
-  return content;
 }

src/download/download-version.ts

@@ -2,19 +2,18 @@ import { promises as fs } from "node:fs";
 import * as path from "node:path";
 import * as core from "@actions/core";
 import * as tc from "@actions/tool-cache";
-import type { Endpoints } from "@octokit/types";
+import {
-import * as pep440 from "@renovatebot/pep440";
+  ASTRAL_MIRROR_PREFIX,
-import { OWNER, REPO, TOOL_CACHE_NAME } from "../utils/constants";
+  GITHUB_RELEASES_PREFIX,
-import { Octokit } from "../utils/octokit";
+  TOOL_CACHE_NAME,
+  VERSIONS_MANIFEST_URL,
+} from "../utils/constants";
+import * as log from "../utils/logging";
 import type { Architecture, Platform } from "../utils/platforms";
 import { validateChecksum } from "./checksum/checksum";
-import {
+import { getArtifact } from "./manifest";
-  getDownloadUrl,
-  getLatestKnownVersion as getLatestVersionInManifest,
-} from "./version-manifest";
 
-type Release =
+export { resolveVersion } from "../version/resolve";
-  Endpoints["GET /repos/{owner}/{repo}/releases"]["response"]["data"][number];
 
 export function tryGetFromToolCache(
   arch: Architecture,
@@ -31,236 +30,172 @@ export function tryGetFromToolCache(
   return { installedPath, version: resolvedVersion };
 }
 
-export async function downloadVersionFromGithub(
+export async function downloadVersion(
   platform: Platform,
   arch: Architecture,
   version: string,
-  checkSum: string | undefined,
+  checksum: string | undefined,
   githubToken: string,
+  manifestUrl?: string,
+  downloadFromAstralMirror = true,
 ): Promise<{ version: string; cachedToolDir: string }> {
-  const artifact = `uv-${arch}-${platform}`;
+  const artifact = await getArtifact(version, arch, platform, manifestUrl);
-  const extension = getExtension(platform);
-  const downloadUrl = `https://github.com/${OWNER}/${REPO}/releases/download/${version}/${artifact}${extension}`;
-  return await downloadVersion(
-    downloadUrl,
-    artifact,
-    platform,
-    arch,
-    version,
-    checkSum,
-    githubToken,
-  );
-}
 
-export async function downloadVersionFromManifest(
+  if (!artifact) {
-  manifestUrl: string | undefined,
+    throw new Error(
-  platform: Platform,
+      getMissingArtifactMessage(version, arch, platform, manifestUrl),
-  arch: Architecture,
-  version: string,
-  checkSum: string | undefined,
-  githubToken: string,
-): Promise<{ version: string; cachedToolDir: string }> {
-  const downloadUrl = await getDownloadUrl(
-    manifestUrl,
-    version,
-    arch,
-    platform,
-  );
-  if (!downloadUrl) {
-    core.info(
-      `manifest-file does not contain version ${version}, arch ${arch}, platform ${platform}. Falling back to GitHub releases.`,
-    );
-    return await downloadVersionFromGithub(
-      platform,
-      arch,
-      version,
-      checkSum,
-      githubToken,
     );
   }
-  return await downloadVersion(
+
+  // Custom manifests are explicitly selected by the user, so their checksum
+  // takes precedence over the built-in table. For the default manifest, pass
+  // its checksum as a fallback after user input and KNOWN_CHECKSUMS.
+  const resolvedChecksum =
+    manifestUrl === undefined
+      ? checksum
+      : resolveChecksum(checksum, artifact.checksum);
+  const manifestChecksum = artifact.checksum;
+
+  const mirrorUrl = downloadFromAstralMirror
+    ? rewriteToMirror(artifact.downloadUrl)
+    : undefined;
+  const downloadUrl = mirrorUrl ?? artifact.downloadUrl;
+
+  try {
+    return await downloadArtifact(
       downloadUrl,
       `uv-${arch}-${platform}`,
       platform,
       arch,
       version,
-    checkSum,
+      resolvedChecksum,
-    githubToken,
+      manifestChecksum,
+      githubTokenForUrl(downloadUrl, githubToken),
     );
+  } catch (err) {
+    if (mirrorUrl === undefined) {
+      throw err;
+    }
+
+    log.warning(
+      `Failed to download from mirror, falling back to GitHub Releases: ${(err as Error).message}`,
+    );
+
+    return await downloadArtifact(
+      artifact.downloadUrl,
+      `uv-${arch}-${platform}`,
+      platform,
+      arch,
+      version,
+      resolvedChecksum,
+      manifestChecksum,
+      githubTokenForUrl(artifact.downloadUrl, githubToken),
+    );
+  }
 }
 
-async function downloadVersion(
+/**
+ * Rewrite a GitHub Releases URL to the Astral mirror.
+ * Returns `undefined` if the URL does not match the expected GitHub prefix.
+ */
+export function rewriteToMirror(url: string): string | undefined {
+  if (!url.startsWith(GITHUB_RELEASES_PREFIX)) {
+    return undefined;
+  }
+
+  return ASTRAL_MIRROR_PREFIX + url.slice(GITHUB_RELEASES_PREFIX.length);
+}
+
+function githubTokenForUrl(
+  downloadUrl: string,
+  githubToken: string,
+): string | undefined {
+  try {
+    return new URL(downloadUrl).origin === "https://github.com"
+      ? githubToken
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function downloadArtifact(
   downloadUrl: string,
   artifactName: string,
   platform: Platform,
   arch: Architecture,
   version: string,
-  checkSum: string | undefined,
+  checksum: string | undefined,
-  githubToken: string,
+  manifestChecksum: string | undefined,
+  githubToken: string | undefined,
 ): Promise<{ version: string; cachedToolDir: string }> {
-  core.info(`Downloading uv from "${downloadUrl}" ...`);
+  log.info(`Downloading uv from "${downloadUrl}" ...`);
   const downloadPath = await tc.downloadTool(
     downloadUrl,
     undefined,
     githubToken,
   );
-  await validateChecksum(checkSum, downloadPath, arch, platform, version);
+  await validateChecksum(
+    checksum,
+    downloadPath,
+    arch,
+    platform,
+    version,
+    manifestChecksum,
+  );
 
   let uvDir: string;
-  const extension = getExtension(platform);
   if (platform === "pc-windows-msvc") {
+    // On windows extracting the zip does not create an intermediate directory.
+    try {
+      // Try tar first as it's much faster, but only bsdtar supports zip files,
+      // so this may fail if another tar, like gnu tar, ends up being used.
+      uvDir = await tc.extractTar(downloadPath, undefined, "x");
+    } catch (err) {
+      log.info(
+        `Extracting with tar failed, falling back to zip extraction: ${(err as Error).message}`,
+      );
+      const extension = getExtension(platform);
       const fullPathWithExtension = `${downloadPath}${extension}`;
       await fs.copyFile(downloadPath, fullPathWithExtension);
       uvDir = await tc.extractZip(fullPathWithExtension);
-    // On windows extracting the zip does not create an intermediate directory
+    }
   } else {
     const extractedDir = await tc.extractTar(downloadPath);
     uvDir = path.join(extractedDir, artifactName);
   }
+
   const cachedToolDir = await tc.cacheDir(
     uvDir,
     TOOL_CACHE_NAME,
     version,
     arch,
   );
-  return { cachedToolDir, version: version };
+  return { cachedToolDir, version };
+}
+
+function getMissingArtifactMessage(
+  version: string,
+  arch: Architecture,
+  platform: Platform,
+  manifestUrl?: string,
+): string {
+  if (manifestUrl === undefined) {
+    return `Could not find artifact for version ${version}, arch ${arch}, platform ${platform} in ${VERSIONS_MANIFEST_URL} .`;
+  }
+
+  return `manifest-file does not contain version ${version}, arch ${arch}, platform ${platform}.`;
+}
+
+function resolveChecksum(
+  checksum: string | undefined,
+  manifestChecksum: string,
+): string {
+  return checksum !== undefined && checksum !== ""
+    ? checksum
+    : manifestChecksum;
 }
 
 function getExtension(platform: Platform): string {
   return platform === "pc-windows-msvc" ? ".zip" : ".tar.gz";
 }
-
-export async function resolveVersion(
-  versionInput: string,
-  manifestFile: string | undefined,
-  githubToken: string,
-): Promise<string> {
-  core.debug(`Resolving version: ${versionInput}`);
-  let version: string;
-  const isSimpleMinimumVersionSpecifier =
-    versionInput.includes(">") && !versionInput.includes(",");
-  if (isSimpleMinimumVersionSpecifier) {
-    core.info("Found minimum version specifier, using latest version");
-  }
-  if (manifestFile) {
-    version =
-      versionInput === "latest" || isSimpleMinimumVersionSpecifier
-        ? await getLatestVersionInManifest(manifestFile)
-        : versionInput;
-  } else {
-    version =
-      versionInput === "latest" || isSimpleMinimumVersionSpecifier
-        ? await getLatestVersion(githubToken)
-        : versionInput;
-  }
-  if (tc.isExplicitVersion(version)) {
-    core.debug(`Version ${version} is an explicit version.`);
-    if (isSimpleMinimumVersionSpecifier) {
-      if (!pep440.satisfies(version, versionInput)) {
-        throw new Error(`No version found for ${versionInput}`);
-      }
-    }
-    return version;
-  }
-  const availableVersions = await getAvailableVersions(githubToken);
-  core.debug(`Available versions: ${availableVersions}`);
-  const resolvedVersion = maxSatisfying(availableVersions, version);
-  if (resolvedVersion === undefined) {
-    throw new Error(`No version found for ${version}`);
-  }
-  return resolvedVersion;
-}
-
-async function getAvailableVersions(githubToken: string): Promise<string[]> {
-  core.info("Getting available versions from GitHub API...");
-  try {
-    const octokit = new Octokit({
-      auth: githubToken,
-    });
-    return await getReleaseTagNames(octokit);
-  } catch (err) {
-    if ((err as Error).message.includes("Bad credentials")) {
-      core.info(
-        "No (valid) GitHub token provided. Falling back to anonymous. Requests might be rate limited.",
-      );
-      const octokit = new Octokit();
-      return await getReleaseTagNames(octokit);
-    }
-    throw err;
-  }
-}
-
-async function getReleaseTagNames(octokit: Octokit): Promise<string[]> {
-  const response: Release[] = await octokit.paginate(
-    octokit.rest.repos.listReleases,
-    {
-      owner: OWNER,
-      repo: REPO,
-    },
-  );
-  const releaseTagNames = response.map((release) => release.tag_name);
-  if (releaseTagNames.length === 0) {
-    throw Error(
-      "Github API request failed while getting releases. Check the GitHub status page for outages. Try again later.",
-    );
-  }
-  return releaseTagNames;
-}
-
-async function getLatestVersion(githubToken: string) {
-  core.info("Getting latest version from GitHub API...");
-  const octokit = new Octokit({
-    auth: githubToken,
-  });
-
-  let latestRelease: { tag_name: string } | undefined;
-  try {
-    latestRelease = await getLatestRelease(octokit);
-  } catch (err) {
-    if ((err as Error).message.includes("Bad credentials")) {
-      core.info(
-        "No (valid) GitHub token provided. Falling back to anonymous. Requests might be rate limited.",
-      );
-      const octokit = new Octokit();
-      latestRelease = await getLatestRelease(octokit);
-    } else {
-      core.error(
-        "Github API request failed while getting latest release. Check the GitHub status page for outages. Try again later.",
-      );
-      throw err;
-    }
-  }
-
-  if (!latestRelease) {
-    throw new Error("Could not determine latest release.");
-  }
-  core.debug(`Latest version: ${latestRelease.tag_name}`);
-  return latestRelease.tag_name;
-}
-
-async function getLatestRelease(octokit: Octokit) {
-  const { data: latestRelease } = await octokit.rest.repos.getLatestRelease({
-    owner: OWNER,
-    repo: REPO,
-  });
-  return latestRelease;
-}
-
-function maxSatisfying(
-  versions: string[],
-  version: string,
-): string | undefined {
-  const maxSemver = tc.evaluateVersions(versions, version);
-  if (maxSemver !== "") {
-    core.debug(`Found a version that satisfies the semver range: ${maxSemver}`);
-    return maxSemver;
-  }
-  const maxPep440 = pep440.maxSatisfying(versions, version);
-  if (maxPep440 !== null) {
-    core.debug(
-      `Found a version that satisfies the pep440 specifier: ${maxPep440}`,
-    );
-    return maxPep440;
-  }
-  return undefined;
-}

src/download/manifest.ts

@@ -0,0 +1,338 @@
+import { createInterface } from "node:readline";
+import { Readable } from "node:stream";
+import * as core from "@actions/core";
+import { VERSIONS_MANIFEST_URL } from "../utils/constants";
+import { fetch } from "../utils/fetch";
+import * as log from "../utils/logging";
+import { selectDefaultVariant } from "./variant-selection";
+
+export interface ManifestArtifact {
+  platform: string;
+  variant?: string;
+  url: string;
+  archive_format: string;
+  sha256: string;
+}
+
+export interface ManifestVersion {
+  version: string;
+  artifacts: ManifestArtifact[];
+}
+
+export interface ArtifactResult {
+  archiveFormat: string;
+  checksum: string;
+  downloadUrl: string;
+}
+
+interface CachedManifest {
+  complete: boolean;
+  versions: ManifestVersion[];
+}
+
+const cachedManifestData = new Map<string, CachedManifest>();
+export const MANIFEST_FETCH_ATTEMPTS = 3;
+
+export async function fetchManifest(
+  manifestUrl: string = VERSIONS_MANIFEST_URL,
+): Promise<ManifestVersion[]> {
+  const cachedManifest = cachedManifestData.get(manifestUrl);
+  if (cachedManifest?.complete === true) {
+    core.debug(`Using cached manifest data from ${manifestUrl}`);
+    return cachedManifest.versions;
+  }
+
+  const response = await fetchManifestResponse(manifestUrl);
+  const body = await response.text();
+  const versions = parseManifest(body, manifestUrl);
+  cachedManifestData.set(manifestUrl, { complete: true, versions });
+  return versions;
+}
+
+export function parseManifest(
+  data: string,
+  sourceDescription: string,
+): ManifestVersion[] {
+  const trimmed = data.trim();
+  if (trimmed === "") {
+    throw new Error(`Manifest at ${sourceDescription} is empty.`);
+  }
+
+  rejectLegacyManifest(trimmed, sourceDescription);
+
+  const versions: ManifestVersion[] = [];
+
+  for (const [index, line] of data.split("\n").entries()) {
+    const record = line.trim();
+    if (record === "") {
+      continue;
+    }
+
+    versions.push(parseManifestRecord(record, sourceDescription, index + 1));
+  }
+
+  if (versions.length === 0) {
+    throw new Error(`No manifest data found in ${sourceDescription}.`);
+  }
+
+  return versions;
+}
+
+export async function getLatestVersion(
+  manifestUrl: string = VERSIONS_MANIFEST_URL,
+): Promise<string> {
+  const latestVersion =
+    manifestUrl === VERSIONS_MANIFEST_URL
+      ? (await findManifestVersion(() => true))?.version
+      : (await fetchManifest(manifestUrl))[0]?.version;
+
+  if (latestVersion === undefined) {
+    throw new Error("No versions found in manifest data");
+  }
+
+  core.debug(`Latest version from manifest: ${latestVersion}`);
+  return latestVersion;
+}
+
+// The default manifest is guaranteed to be ordered newest-first:
+// https://github.com/astral-sh/versions#format
+export async function getFirstMatchingVersion(
+  predicate: (version: string) => boolean,
+): Promise<string | undefined> {
+  return (
+    await findManifestVersion((versionData) => predicate(versionData.version))
+  )?.version;
+}
+
+export async function getAllVersions(
+  manifestUrl: string = VERSIONS_MANIFEST_URL,
+): Promise<string[]> {
+  log.info(
+    `Getting available versions from ${manifestSource(manifestUrl)} ...`,
+  );
+  const versions = await fetchManifest(manifestUrl);
+  return versions.map((versionData) => versionData.version);
+}
+
+export async function getArtifact(
+  version: string,
+  arch: string,
+  platform: string,
+  manifestUrl: string = VERSIONS_MANIFEST_URL,
+): Promise<ArtifactResult | undefined> {
+  const versionData =
+    manifestUrl === VERSIONS_MANIFEST_URL
+      ? await findManifestVersion((candidate) => candidate.version === version)
+      : (await fetchManifest(manifestUrl)).find(
+          (candidate) => candidate.version === version,
+        );
+  if (!versionData) {
+    core.debug(`Version ${version} not found in manifest ${manifestUrl}`);
+    return undefined;
+  }
+
+  const targetPlatform = `${arch}-${platform}`;
+  const matchingArtifacts = versionData.artifacts.filter(
+    (candidate) => candidate.platform === targetPlatform,
+  );
+
+  if (matchingArtifacts.length === 0) {
+    core.debug(
+      `Artifact for ${targetPlatform} not found in version ${version}. Available platforms: ${versionData.artifacts
+        .map((candidate) => candidate.platform)
+        .join(", ")}`,
+    );
+    return undefined;
+  }
+
+  const artifact = selectDefaultVariant(
+    matchingArtifacts,
+    `Multiple artifacts found for ${targetPlatform} in version ${version}`,
+  );
+
+  return {
+    archiveFormat: artifact.archive_format,
+    checksum: artifact.sha256,
+    downloadUrl: artifact.url,
+  };
+}
+
+export function clearManifestCache(manifestUrl?: string): void {
+  if (manifestUrl === undefined) {
+    cachedManifestData.clear();
+    return;
+  }
+
+  cachedManifestData.delete(manifestUrl);
+}
+
+async function fetchManifestResponse(manifestUrl: string) {
+  let response: Awaited<ReturnType<typeof fetch>> | undefined;
+  for (let attempt = 1; attempt <= MANIFEST_FETCH_ATTEMPTS; attempt++) {
+    log.info(`Fetching manifest data from ${manifestUrl} ...`);
+    try {
+      response = await fetch(manifestUrl, {});
+      break;
+    } catch (error) {
+      if (attempt >= MANIFEST_FETCH_ATTEMPTS) {
+        throw error;
+      }
+      const delayMs = 1_000 * 2 ** (attempt - 1);
+      log.info(`Manifest fetch failed; retrying in ${delayMs}ms ...`);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
+  if (response === undefined) {
+    throw new Error("Manifest fetch attempts exhausted.");
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch manifest data: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return response;
+}
+
+async function findManifestVersion(
+  predicate: (versionData: ManifestVersion) => boolean,
+): Promise<ManifestVersion | undefined> {
+  const cachedManifest = cachedManifestData.get(VERSIONS_MANIFEST_URL);
+  const cachedVersion = cachedManifest?.versions.find(predicate);
+  if (cachedVersion !== undefined || cachedManifest?.complete === true) {
+    return cachedVersion;
+  }
+
+  const response = await fetchManifestResponse(VERSIONS_MANIFEST_URL);
+  if (response.body === null) {
+    const versions = parseManifest(
+      await response.text(),
+      VERSIONS_MANIFEST_URL,
+    );
+    cachedManifestData.set(VERSIONS_MANIFEST_URL, {
+      complete: true,
+      versions,
+    });
+    return versions.find(predicate);
+  }
+
+  const input = Readable.fromWeb(response.body);
+  const lines = createInterface({ crlfDelay: Number.POSITIVE_INFINITY, input });
+  const versions: ManifestVersion[] = [];
+  let complete = false;
+  let lineNumber = 0;
+  let matchedVersion: ManifestVersion | undefined;
+
+  try {
+    for await (const line of lines) {
+      lineNumber += 1;
+      const record = line.trim();
+      if (record === "") {
+        continue;
+      }
+
+      if (versions.length === 0) {
+        rejectLegacyManifest(record, VERSIONS_MANIFEST_URL);
+      }
+
+      const versionData = parseManifestRecord(
+        record,
+        VERSIONS_MANIFEST_URL,
+        lineNumber,
+      );
+      versions.push(versionData);
+      if (predicate(versionData)) {
+        matchedVersion = versionData;
+        break;
+      }
+    }
+
+    complete = matchedVersion === undefined;
+  } finally {
+    lines.close();
+    if (!complete) {
+      input.destroy();
+    }
+  }
+
+  if (versions.length === 0) {
+    throw new Error(`Manifest at ${VERSIONS_MANIFEST_URL} is empty.`);
+  }
+
+  cachedManifestData.set(VERSIONS_MANIFEST_URL, { complete, versions });
+  return matchedVersion;
+}
+
+function manifestSource(manifestUrl: string): string {
+  if (manifestUrl === VERSIONS_MANIFEST_URL) {
+    return VERSIONS_MANIFEST_URL;
+  }
+
+  return `manifest-file ${manifestUrl}`;
+}
+
+function parseManifestRecord(
+  record: string,
+  sourceDescription: string,
+  lineNumber: number,
+): ManifestVersion {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(record);
+  } catch (error) {
+    throw new Error(
+      `Failed to parse manifest data from ${sourceDescription} at line ${lineNumber}: ${(error as Error).message}`,
+    );
+  }
+
+  if (!isManifestVersion(parsed)) {
+    throw new Error(
+      `Invalid manifest record in ${sourceDescription} at line ${lineNumber}.`,
+    );
+  }
+
+  return parsed;
+}
+
+function rejectLegacyManifest(data: string, sourceDescription: string): void {
+  if (data.startsWith("[")) {
+    throw new Error(
+      `Legacy JSON array manifests are no longer supported in ${sourceDescription}. Use the astral-sh/versions manifest format instead.`,
+    );
+  }
+}
+
+function isManifestVersion(value: unknown): value is ManifestVersion {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  if (typeof value.version !== "string" || !Array.isArray(value.artifacts)) {
+    return false;
+  }
+
+  return value.artifacts.every(isManifestArtifact);
+}
+
+function isManifestArtifact(value: unknown): value is ManifestArtifact {
+  if (!isRecord(value)) {
+    return false;
+  }
+
+  const variantIsValid =
+    typeof value.variant === "string" || value.variant === undefined;
+
+  return (
+    typeof value.archive_format === "string" &&
+    typeof value.platform === "string" &&
+    typeof value.sha256 === "string" &&
+    typeof value.url === "string" &&
+    variantIsValid
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

src/download/variant-selection.ts

@@ -0,0 +1,39 @@
+interface VariantAwareEntry {
+  variant?: string;
+}
+
+export function selectDefaultVariant<T extends VariantAwareEntry>(
+  entries: T[],
+  duplicateEntryDescription: string,
+): T {
+  const firstEntry = entries[0];
+  if (firstEntry === undefined) {
+    throw new Error("selectDefaultVariant requires at least one candidate.");
+  }
+
+  if (entries.length === 1) {
+    return firstEntry;
+  }
+
+  const defaultEntries = entries.filter((entry) =>
+    isDefaultVariant(entry.variant),
+  );
+  if (defaultEntries.length === 1) {
+    return defaultEntries[0];
+  }
+
+  throw new Error(
+    `${duplicateEntryDescription} with variants ${formatVariants(entries)}. setup-uv currently requires a single default variant for duplicate platform entries.`,
+  );
+}
+
+function isDefaultVariant(variant: string | undefined): boolean {
+  return variant === undefined || variant === "default";
+}
+
+function formatVariants<T extends VariantAwareEntry>(entries: T[]): string {
+  return entries
+    .map((entry) => entry.variant ?? "default")
+    .sort((left, right) => left.localeCompare(right))
+    .join(", ");
+}

src/download/version-manifest.ts

@@ -1,91 +0,0 @@
-import { promises as fs } from "node:fs";
-import { join } from "node:path";
-import * as core from "@actions/core";
-import * as semver from "semver";
-import { fetch } from "../utils/fetch";
-
-const localManifestFile = join(__dirname, "..", "..", "version-manifest.json");
-
-interface ManifestEntry {
-  version: string;
-  artifactName: string;
-  arch: string;
-  platform: string;
-  downloadUrl: string;
-}
-
-export async function getLatestKnownVersion(
-  manifestUrl: string | undefined,
-): Promise<string> {
-  const manifestEntries = await getManifestEntries(manifestUrl);
-  return manifestEntries.reduce((a, b) =>
-    semver.gt(a.version, b.version) ? a : b,
-  ).version;
-}
-
-export async function getDownloadUrl(
-  manifestUrl: string | undefined,
-  version: string,
-  arch: string,
-  platform: string,
-): Promise<string | undefined> {
-  const manifestEntries = await getManifestEntries(manifestUrl);
-  const entry = manifestEntries.find(
-    (entry) =>
-      entry.version === version &&
-      entry.arch === arch &&
-      entry.platform === platform,
-  );
-  return entry ? entry.downloadUrl : undefined;
-}
-
-async function getManifestEntries(
-  manifestUrl: string | undefined,
-): Promise<ManifestEntry[]> {
-  let data: string;
-  if (manifestUrl !== undefined) {
-    core.info(`Fetching manifest-file from: ${manifestUrl}`);
-    const response = await fetch(manifestUrl, {});
-    if (!response.ok) {
-      throw new Error(
-        `Failed to fetch manifest-file: ${response.status} ${response.statusText}`,
-      );
-    }
-    data = await response.text();
-  } else {
-    core.info("manifest-file not provided, reading from local file.");
-    const fileContent = await fs.readFile(localManifestFile);
-    data = fileContent.toString();
-  }
-
-  return JSON.parse(data);
-}
-
-export async function updateVersionManifest(
-  manifestUrl: string,
-  downloadUrls: string[],
-): Promise<void> {
-  const manifest: ManifestEntry[] = [];
-
-  for (const downloadUrl of downloadUrls) {
-    const urlParts = downloadUrl.split("/");
-    const version = urlParts[urlParts.length - 2];
-    const artifactName = urlParts[urlParts.length - 1];
-    if (!artifactName.startsWith("uv-")) {
-      continue;
-    }
-    if (artifactName.startsWith("uv-installer")) {
-      continue;
-    }
-    const artifactParts = artifactName.split(".")[0].split("-");
-    manifest.push({
-      arch: artifactParts[1],
-      artifactName: artifactName,
-      downloadUrl: downloadUrl,
-      platform: artifactName.split(`uv-${artifactParts[1]}-`)[1].split(".")[0],
-      version: version,
-    });
-  }
-  core.debug(`Updating manifest-file: ${JSON.stringify(manifest)}`);
-  await fs.writeFile(manifestUrl, JSON.stringify(manifest));
-}

src/hash/hash-files.ts

@@ -2,8 +2,8 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as stream from "node:stream";
 import * as util from "node:util";
-import * as core from "@actions/core";
 import { create } from "@actions/glob";
+import * as log from "../utils/logging";
 
 /**
  * Hashes files matching the given glob pattern.
@@ -19,7 +19,7 @@ export async function hashFiles(
 ): Promise<string> {
   const globber = await create(pattern);
   let hasMatch = false;
-  const writeDelegate = verbose ? core.info : core.debug;
+  const writeDelegate = verbose ? log.info : log.debug;
   const result = crypto.createHash("sha256");
   let count = 0;
   for await (const file of globber.globGenerator()) {

src/save-cache.ts

@@ -6,26 +6,44 @@ import * as pep440 from "@renovatebot/pep440";
 import {
   STATE_CACHE_KEY,
   STATE_CACHE_MATCHED_KEY,
+  STATE_PYTHON_CACHE_MATCHED_KEY,
 } from "./cache/restore-cache";
 import { STATE_UV_PATH, STATE_UV_VERSION } from "./utils/constants";
-import {
+import { loadInputs, type SetupInputs } from "./utils/inputs";
-  cacheLocalPath,
+import * as log from "./utils/logging";
-  cachePython,
+
-  enableCache,
+function formatUnexpectedFailure(error: unknown): string {
-  ignoreNothingToCache,
+  if (error instanceof Error) {
-  pythonDir,
+    return error.stack ?? error.message;
-  pruneCache as shouldPruneCache,
+  }
-  saveCache as shouldSaveCache,
+  return String(error);
-} from "./utils/inputs";
+}
+
+function failUnexpectedly(event: string, error: unknown): never {
+  core.setFailed(`${event}: ${formatUnexpectedFailure(error)}`);
+  process.exit(1);
+}
+
+process.on("uncaughtException", (error) => {
+  failUnexpectedly("Uncaught exception", error);
+});
+
+process.on("unhandledRejection", (reason) => {
+  failUnexpectedly("Unhandled promise rejection", reason);
+});
 
 export async function run(): Promise<void> {
   try {
-    if (enableCache) {
+    const inputs = loadInputs();
-      if (shouldSaveCache) {
+    if (inputs.enableCache) {
-        await saveCache();
+      if (inputs.saveCache) {
+        await saveCache(inputs);
       } else {
-        core.info("save-cache is false. Skipping save cache step.");
+        log.info("save-cache is false. Skipping save cache step.");
       }
+      // https://github.com/nodejs/node/issues/56645#issuecomment-3924958861
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
       // node will stay alive if any promises are not resolved,
       // which is a possibility if HTTP requests are dangling
       // due to retries or timeouts. We know that if we got here
@@ -39,66 +57,58 @@ export async function run(): Promise<void> {
   }
 }
 
-async function saveCache(): Promise<void> {
+async function saveCache(inputs: SetupInputs): Promise<void> {
   const cacheKey = core.getState(STATE_CACHE_KEY);
   const matchedKey = core.getState(STATE_CACHE_MATCHED_KEY);
 
   if (!cacheKey) {
-    core.warning("Error retrieving cache key from state.");
+    log.warning("Error retrieving cache key from state.");
     return;
   }
   if (matchedKey === cacheKey) {
-    core.info(`Cache hit occurred on key ${cacheKey}, not saving cache.`);
+    log.info(`Cache hit occurred on key ${cacheKey}, not saving cache.`);
-    return;
+  } else {
-  }
+    if (inputs.pruneCache) {
-
-  if (shouldPruneCache) {
       await pruneCache();
     }
 
-  let actualCachePath = cacheLocalPath;
+    const actualCachePath = getUvCachePath(inputs);
-  if (process.env.UV_CACHE_DIR && process.env.UV_CACHE_DIR !== cacheLocalPath) {
+    if (!fs.existsSync(actualCachePath)) {
-    core.warning(
+      if (inputs.ignoreNothingToCache) {
-      `The environment variable UV_CACHE_DIR has been changed to "${process.env.UV_CACHE_DIR}", by an action or step running after astral-sh/setup-uv. This can lead to unexpected behavior. If you expected this to happen set the cache-local-path input to "${process.env.UV_CACHE_DIR}" instead of "${cacheLocalPath}".`,
+        log.info(
+          "No cacheable uv cache paths were found. Ignoring because ignore-nothing-to-cache is enabled.",
         );
-    actualCachePath = process.env.UV_CACHE_DIR;
+      } else {
-  }
-
-  core.info(`Saving cache path: ${actualCachePath}`);
-  if (!fs.existsSync(actualCachePath) && !ignoreNothingToCache) {
         throw new Error(
           `Cache path ${actualCachePath} does not exist on disk. This likely indicates that there are no dependencies to cache. Consider disabling the cache input if it is not needed.`,
         );
       }
-
-  const cachePaths = [actualCachePath];
-  if (cachePython) {
-    core.info(`Including Python cache path: ${pythonDir}`);
-    if (!fs.existsSync(pythonDir) && !ignoreNothingToCache) {
-      throw new Error(
-        `Python cache path ${pythonDir} does not exist on disk. This likely indicates that there are no dependencies to cache. Consider disabling the cache input if it is not needed.`,
-      );
-    }
-    cachePaths.push(pythonDir);
-  }
-
-  core.info(`Final cache paths: ${cachePaths.join(", ")}`);
-  try {
-    await cache.saveCache(cachePaths, cacheKey);
-    core.info(`cache saved with the key: ${cacheKey}`);
-  } catch (e) {
-    if (
-      e instanceof Error &&
-      e.message ===
-        "Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved."
-    ) {
-      core.info(
-        "No cacheable paths were found. Ignoring because ignore-nothing-to-save is enabled.",
-      );
     } else {
-      throw e;
+      await saveCacheToKey(
+        cacheKey,
+        actualCachePath,
+        STATE_CACHE_MATCHED_KEY,
+        "uv cache",
+      );
     }
   }
+
+  if (inputs.cachePython) {
+    if (!fs.existsSync(inputs.pythonDir)) {
+      log.warning(
+        `Python cache path ${inputs.pythonDir} does not exist on disk. Skipping Python cache save because no managed Python installation was found. If you want uv to install managed Python instead of using a system interpreter, set UV_PYTHON_PREFERENCE=only-managed.`,
+      );
+      return;
+    }
+
+    const pythonCacheKey = `${cacheKey}-python`;
+    await saveCacheToKey(
+      pythonCacheKey,
+      inputs.pythonDir,
+      STATE_PYTHON_CACHE_MATCHED_KEY,
+      "Python cache",
+    );
+  }
 }
 
 async function pruneCache(): Promise<void> {
@@ -112,9 +122,45 @@ async function pruneCache(): Promise<void> {
     execArgs.push("--force");
   }
 
-  core.info("Pruning cache...");
+  log.info("Pruning cache...");
   const uvPath = core.getState(STATE_UV_PATH);
   await exec.exec(uvPath, execArgs, options);
 }
 
+function getUvCachePath(inputs: SetupInputs): string {
+  if (inputs.cacheLocalPath === undefined) {
+    throw new Error(
+      "cache-local-path is not set. Cannot save cache without a valid cache path.",
+    );
+  }
+  if (
+    process.env.UV_CACHE_DIR &&
+    process.env.UV_CACHE_DIR !== inputs.cacheLocalPath.path
+  ) {
+    log.warning(
+      `The environment variable UV_CACHE_DIR has been changed to "${process.env.UV_CACHE_DIR}", by an action or step running after astral-sh/setup-uv. This can lead to unexpected behavior. If you expected this to happen set the cache-local-path input to "${process.env.UV_CACHE_DIR}" instead of "${inputs.cacheLocalPath.path}".`,
+    );
+    return process.env.UV_CACHE_DIR;
+  }
+  return inputs.cacheLocalPath.path;
+}
+
+async function saveCacheToKey(
+  cacheKey: string,
+  cachePath: string,
+  stateKey: string,
+  cacheName: string,
+): Promise<void> {
+  const matchedKey = core.getState(stateKey);
+
+  if (matchedKey === cacheKey) {
+    log.info(`${cacheName} hit occurred on key ${cacheKey}, not saving cache.`);
+    return;
+  }
+
+  log.info(`Including ${cacheName} path: ${cachePath}`);
+  await cache.saveCache([cachePath], cacheKey);
+  log.info(`${cacheName} saved with key: ${cacheKey}`);
+}
+
 run();

src/setup-uv.ts

@@ -4,81 +4,125 @@ import * as core from "@actions/core";
 import * as exec from "@actions/exec";
 import { restoreCache } from "./cache/restore-cache";
 import {
-  downloadVersionFromManifest,
+  downloadVersion,
-  resolveVersion,
   tryGetFromToolCache,
 } from "./download/download-version";
-import { getConfigValueFromTomlFile } from "./utils/config-file";
 import { STATE_UV_PATH, STATE_UV_VERSION } from "./utils/constants";
-import {
+import { CacheLocalSource, loadInputs, type SetupInputs } from "./utils/inputs";
-  activateEnvironment as activateEnvironmentInput,
+import * as log from "./utils/logging";
-  addProblemMatchers,
-  cacheLocalPath,
-  checkSum,
-  enableCache,
-  githubToken,
-  ignoreEmptyWorkdir,
-  manifestFile,
-  pythonDir,
-  pythonVersion,
-  toolBinDir,
-  toolDir,
-  versionFile as versionFileInput,
-  version as versionInput,
-  workingDirectory,
-} from "./utils/inputs";
 import {
   type Architecture,
   getArch,
   getPlatform,
   type Platform,
 } from "./utils/platforms";
-import { getUvVersionFromFile } from "./version/resolve";
+import { getPythonRuntimeId } from "./utils/python-runtime";
+import { resolveUvVersion } from "./version/resolve";
+
+const sourceDir = __dirname;
+
+function formatUnexpectedFailure(error: unknown): string {
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+  return String(error);
+}
+
+function failUnexpectedly(event: string, error: unknown): never {
+  core.setFailed(`${event}: ${formatUnexpectedFailure(error)}`);
+  process.exit(1);
+}
+
+process.on("uncaughtException", (error) => {
+  failUnexpectedly("Uncaught exception", error);
+});
+
+process.on("unhandledRejection", (reason) => {
+  failUnexpectedly("Unhandled promise rejection", reason);
+});
+
+async function getPythonVersion(inputs: SetupInputs): Promise<string> {
+  if (inputs.pythonVersion !== "") {
+    return inputs.pythonVersion;
+  }
+
+  let output = "";
+  const options: exec.ExecOptions = {
+    listeners: {
+      stdout: (data: Buffer) => {
+        output += data.toString();
+      },
+    },
+    silent: !core.isDebug(),
+  };
+
+  try {
+    const execArgs = ["python", "find", "--directory", inputs.workingDirectory];
+    await exec.exec("uv", execArgs, options);
+    const pythonPath = output.trim();
+
+    output = "";
+    await exec.exec(pythonPath, ["--version"], options);
+    // output is like "Python 3.8.10"
+    return output.split(" ")[1].trim();
+  } catch (error) {
+    const err = error as Error;
+    core.debug(`Failed to get python version from uv. Error: ${err.message}`);
+    return "unknown";
+  }
+}
 
 async function run(): Promise<void> {
-  detectEmptyWorkdir();
+  try {
+    const inputs = loadInputs();
+    detectEmptyWorkdir(inputs);
     const platform = await getPlatform();
     const arch = getArch();
 
-  try {
     if (platform === undefined) {
       throw new Error(`Unsupported platform: ${process.platform}`);
     }
     if (arch === undefined) {
       throw new Error(`Unsupported architecture: ${process.arch}`);
     }
-    const setupResult = await setupUv(platform, arch, checkSum, githubToken);
+    const setupResult = await setupUv(inputs, platform, arch);
 
-    addToolBinToPath();
+    addToolBinToPath(inputs);
     addUvToPathAndOutput(setupResult.uvDir);
-    setToolDir();
+    setToolDir(inputs);
-    addPythonDirToPath();
+    addPythonDirToPath(inputs);
-    setupPython();
+    setupPython(inputs);
-    await activateEnvironment();
+    await activateEnvironment(inputs);
-    addMatchers();
+    addMatchers(inputs);
-    setCacheDir();
+    setCacheDir(inputs);
 
     core.setOutput("uv-version", setupResult.version);
     core.saveState(STATE_UV_VERSION, setupResult.version);
-    core.info(`Successfully installed uv version ${setupResult.version}`);
+    log.info(`Successfully installed uv version ${setupResult.version}`);
 
-    if (enableCache) {
+    const detectedPythonVersion = await getPythonVersion(inputs);
-      await restoreCache();
+    core.setOutput("python-version", detectedPythonVersion);
+    core.setOutput("python-runtime-id", await getPythonRuntimeId(inputs));
+
+    if (inputs.enableCache) {
+      await restoreCache(inputs, detectedPythonVersion);
     }
+    // https://github.com/nodejs/node/issues/56645#issuecomment-3924958861
+    await new Promise((resolve) => setTimeout(resolve, 100));
     process.exit(0);
   } catch (err) {
     core.setFailed((err as Error).message);
   }
 }
 
-function detectEmptyWorkdir(): void {
+function detectEmptyWorkdir(inputs: SetupInputs): void {
-  if (fs.readdirSync(".").length === 0) {
+  if (fs.readdirSync(inputs.workingDirectory).length === 0) {
-    if (ignoreEmptyWorkdir) {
+    if (inputs.ignoreEmptyWorkdir) {
-      core.info(
+      log.info(
         "Empty workdir detected. Ignoring because ignore-empty-workdir is enabled",
       );
     } else {
-      core.warning(
+      log.warning(
         "Empty workdir detected. This may cause unexpected behavior. You can enable ignore-empty-workdir to mute this warning.",
       );
     }
@@ -86,174 +130,156 @@ function detectEmptyWorkdir(): void {
 }
 
 async function setupUv(
+  inputs: SetupInputs,
   platform: Platform,
   arch: Architecture,
-  checkSum: string | undefined,
-  githubToken: string,
 ): Promise<{ uvDir: string; version: string }> {
-  const resolvedVersion = await determineVersion(manifestFile);
+  const resolvedVersion = await resolveUvVersion({
+    manifestFile: inputs.manifestFile,
+    resolutionStrategy: inputs.resolutionStrategy,
+    version: inputs.version,
+    versionFile: inputs.versionFile,
+    workingDirectory: inputs.workingDirectory,
+  });
   const toolCacheResult = tryGetFromToolCache(arch, resolvedVersion);
   if (toolCacheResult.installedPath) {
-    core.info(`Found uv in tool-cache for ${toolCacheResult.version}`);
+    log.info(`Found uv in tool-cache for ${toolCacheResult.version}`);
     return {
       uvDir: toolCacheResult.installedPath,
       version: toolCacheResult.version,
     };
   }
 
-  const downloadVersionResult = await downloadVersionFromManifest(
+  const downloadResult = await downloadVersion(
-    manifestFile,
     platform,
     arch,
     resolvedVersion,
-    checkSum,
+    inputs.checksum,
-    githubToken,
+    inputs.githubToken,
+    inputs.manifestFile,
+    inputs.downloadFromAstralMirror,
   );
 
   return {
-    uvDir: downloadVersionResult.cachedToolDir,
+    uvDir: downloadResult.cachedToolDir,
-    version: downloadVersionResult.version,
+    version: downloadResult.version,
   };
 }
 
-async function determineVersion(
-  manifestFile: string | undefined,
-): Promise<string> {
-  if (versionInput !== "") {
-    return await resolveVersion(versionInput, manifestFile, githubToken);
-  }
-  if (versionFileInput !== "") {
-    const versionFromFile = getUvVersionFromFile(versionFileInput);
-    if (versionFromFile === undefined) {
-      throw new Error(
-        `Could not determine uv version from file: ${versionFileInput}`,
-      );
-    }
-    return await resolveVersion(versionFromFile, manifestFile, githubToken);
-  }
-  const versionFromUvToml = getUvVersionFromFile(
-    `${workingDirectory}${path.sep}uv.toml`,
-  );
-  const versionFromPyproject = getUvVersionFromFile(
-    `${workingDirectory}${path.sep}pyproject.toml`,
-  );
-  if (versionFromUvToml === undefined && versionFromPyproject === undefined) {
-    core.info(
-      "Could not determine uv version from uv.toml or pyproject.toml. Falling back to latest.",
-    );
-  }
-  return await resolveVersion(
-    versionFromUvToml || versionFromPyproject || "latest",
-    manifestFile,
-    githubToken,
-  );
-}
-
 function addUvToPathAndOutput(cachedPath: string): void {
   core.setOutput("uv-path", `${cachedPath}${path.sep}uv`);
   core.saveState(STATE_UV_PATH, `${cachedPath}${path.sep}uv`);
   core.setOutput("uvx-path", `${cachedPath}${path.sep}uvx`);
   if (process.env.UV_NO_MODIFY_PATH !== undefined) {
-    core.info("UV_NO_MODIFY_PATH is set, not modifying PATH");
+    log.info("UV_NO_MODIFY_PATH is set, not modifying PATH");
   } else {
     core.addPath(cachedPath);
-    core.info(`Added ${cachedPath} to the path`);
+    log.info(`Added ${cachedPath} to the path`);
   }
 }
 
-function addToolBinToPath(): void {
+function addToolBinToPath(inputs: SetupInputs): void {
-  if (toolBinDir !== undefined) {
+  if (inputs.toolBinDir !== undefined) {
-    core.exportVariable("UV_TOOL_BIN_DIR", toolBinDir);
+    core.exportVariable("UV_TOOL_BIN_DIR", inputs.toolBinDir);
-    core.info(`Set UV_TOOL_BIN_DIR to ${toolBinDir}`);
+    log.info(`Set UV_TOOL_BIN_DIR to ${inputs.toolBinDir}`);
     if (process.env.UV_NO_MODIFY_PATH !== undefined) {
-      core.info(`UV_NO_MODIFY_PATH is set, not adding ${toolBinDir} to path`);
+      log.info(
+        `UV_NO_MODIFY_PATH is set, not adding ${inputs.toolBinDir} to path`,
+      );
     } else {
-      core.addPath(toolBinDir);
+      core.addPath(inputs.toolBinDir);
-      core.info(`Added ${toolBinDir} to the path`);
+      log.info(`Added ${inputs.toolBinDir} to the path`);
     }
   } else {
     if (process.env.UV_NO_MODIFY_PATH !== undefined) {
-      core.info("UV_NO_MODIFY_PATH is set, not adding user local bin to path");
+      log.info("UV_NO_MODIFY_PATH is set, not adding user local bin to path");
       return;
     }
     if (process.env.XDG_BIN_HOME !== undefined) {
       core.addPath(process.env.XDG_BIN_HOME);
-      core.info(`Added ${process.env.XDG_BIN_HOME} to the path`);
+      log.info(`Added ${process.env.XDG_BIN_HOME} to the path`);
     } else if (process.env.XDG_DATA_HOME !== undefined) {
       core.addPath(`${process.env.XDG_DATA_HOME}/../bin`);
-      core.info(`Added ${process.env.XDG_DATA_HOME}/../bin to the path`);
+      log.info(`Added ${process.env.XDG_DATA_HOME}/../bin to the path`);
     } else {
       core.addPath(`${process.env.HOME}/.local/bin`);
-      core.info(`Added ${process.env.HOME}/.local/bin to the path`);
+      log.info(`Added ${process.env.HOME}/.local/bin to the path`);
     }
   }
 }
 
-function setToolDir(): void {
+function setToolDir(inputs: SetupInputs): void {
-  if (toolDir !== undefined) {
+  if (inputs.toolDir !== undefined) {
-    core.exportVariable("UV_TOOL_DIR", toolDir);
+    core.exportVariable("UV_TOOL_DIR", inputs.toolDir);
-    core.info(`Set UV_TOOL_DIR to ${toolDir}`);
+    log.info(`Set UV_TOOL_DIR to ${inputs.toolDir}`);
   }
 }
 
-function addPythonDirToPath(): void {
+function addPythonDirToPath(inputs: SetupInputs): void {
-  core.exportVariable("UV_PYTHON_INSTALL_DIR", pythonDir);
+  core.exportVariable("UV_PYTHON_INSTALL_DIR", inputs.pythonDir);
-  core.info(`Set UV_PYTHON_INSTALL_DIR to ${pythonDir}`);
+  log.info(`Set UV_PYTHON_INSTALL_DIR to ${inputs.pythonDir}`);
   if (process.env.UV_NO_MODIFY_PATH !== undefined) {
-    core.info("UV_NO_MODIFY_PATH is set, not adding python dir to path");
+    log.info("UV_NO_MODIFY_PATH is set, not adding python dir to path");
   } else {
-    core.addPath(pythonDir);
+    core.addPath(inputs.pythonDir);
-    core.info(`Added ${pythonDir} to the path`);
+    log.info(`Added ${inputs.pythonDir} to the path`);
   }
 }
 
-function setupPython(): void {
+function setupPython(inputs: SetupInputs): void {
-  if (pythonVersion !== "") {
+  if (inputs.pythonVersion !== "") {
-    core.exportVariable("UV_PYTHON", pythonVersion);
+    core.exportVariable("UV_PYTHON", inputs.pythonVersion);
-    core.info(`Set UV_PYTHON to ${pythonVersion}`);
+    log.info(`Set UV_PYTHON to ${inputs.pythonVersion}`);
   }
 }
 
-async function activateEnvironment(): Promise<void> {
+async function activateEnvironment(inputs: SetupInputs): Promise<void> {
-  if (activateEnvironmentInput) {
+  if (inputs.activateEnvironment) {
     if (process.env.UV_NO_MODIFY_PATH !== undefined) {
       throw new Error(
         "UV_NO_MODIFY_PATH and activate-environment cannot be used together.",
       );
     }
-    const execArgs = ["venv", ".venv", "--directory", workingDirectory];
 
-    core.info("Activating python venv...");
+    log.info(`Creating and activating python venv at ${inputs.venvPath}...`);
-    await exec.exec("uv", execArgs);
+    const venvArgs = [
+      "venv",
+      inputs.venvPath,
+      "--directory",
+      inputs.workingDirectory,
+      "--clear",
+    ];
+    if (inputs.noProject) {
+      venvArgs.push("--no-project");
+    }
+    await exec.exec("uv", venvArgs);
 
-    const venvPath = path.resolve(`${workingDirectory}${path.sep}.venv`);
+    let venvBinPath = `${inputs.venvPath}${path.sep}bin`;
-    let venvBinPath = `${venvPath}${path.sep}bin`;
     if (process.platform === "win32") {
-      venvBinPath = `${venvPath}${path.sep}Scripts`;
+      venvBinPath = `${inputs.venvPath}${path.sep}Scripts`;
     }
     core.addPath(path.resolve(venvBinPath));
-    core.exportVariable("VIRTUAL_ENV", venvPath);
+    core.exportVariable("VIRTUAL_ENV", inputs.venvPath);
-    core.setOutput("venv", venvPath);
+    core.setOutput("venv", inputs.venvPath);
   }
 }
 
-function setCacheDir(): void {
+function setCacheDir(inputs: SetupInputs): void {
-  if (enableCache) {
+  if (inputs.cacheLocalPath !== undefined) {
-    const cacheDirFromConfig = getConfigValueFromTomlFile("", "cache-dir");
+    if (inputs.cacheLocalPath.source === CacheLocalSource.Config) {
-    if (cacheDirFromConfig !== undefined) {
+      log.info(
-      core.info(
         "Using cache-dir from uv config file, not modifying UV_CACHE_DIR",
       );
       return;
     }
-    core.exportVariable("UV_CACHE_DIR", cacheLocalPath);
+    core.exportVariable("UV_CACHE_DIR", inputs.cacheLocalPath.path);
-    core.info(`Set UV_CACHE_DIR to ${cacheLocalPath}`);
+    log.info(`Set UV_CACHE_DIR to ${inputs.cacheLocalPath.path}`);
   }
 }
 
-function addMatchers(): void {
+function addMatchers(inputs: SetupInputs): void {
-  if (addProblemMatchers) {
+  if (inputs.addProblemMatchers) {
-    const matchersPath = path.join(__dirname, `..${path.sep}..`, ".github");
+    const matchersPath = path.join(sourceDir, "..", "..", ".github");
     core.info(`##[add-matcher]${path.join(matchersPath, "python.json")}`);
   }
 }

src/update-known-checksums.ts

@@ -0,0 +1,57 @@
+import * as core from "@actions/core";
+import * as semver from "semver";
+import { getLatestKnownVersion } from "./download/checksum/known-version";
+import {
+  type ChecksumEntry,
+  updateChecksums,
+} from "./download/checksum/update-known-checksums";
+import {
+  fetchManifest,
+  getLatestVersion,
+  type ManifestVersion,
+} from "./download/manifest";
+import * as log from "./utils/logging";
+
+async function run(): Promise<void> {
+  const checksumFilePath = process.argv.slice(2)[0];
+  if (!checksumFilePath) {
+    throw new Error(
+      "Missing checksum file path. Usage: node dist/update-known-checksums/index.cjs <checksum-file-path>",
+    );
+  }
+
+  const latestVersion = await getLatestVersion();
+  const latestKnownVersion = getLatestKnownVersion();
+
+  if (semver.lte(latestVersion, latestKnownVersion)) {
+    log.info(
+      `Latest release (${latestVersion}) is not newer than the latest known version (${latestKnownVersion}). Skipping update.`,
+    );
+    return;
+  }
+
+  const versions = await fetchManifest();
+  const checksumEntries = extractChecksumsFromManifest(versions);
+  await updateChecksums(checksumFilePath, checksumEntries);
+
+  core.setOutput("latest-version", latestVersion);
+}
+
+function extractChecksumsFromManifest(
+  versions: ManifestVersion[],
+): ChecksumEntry[] {
+  const checksums: ChecksumEntry[] = [];
+
+  for (const version of versions) {
+    for (const artifact of version.artifacts) {
+      checksums.push({
+        checksum: artifact.sha256,
+        key: `${artifact.platform}-${version.version}`,
+      });
+    }
+  }
+
+  return checksums;
+}
+
+run();

src/update-known-versions.ts

@@ -1,63 +0,0 @@
-import * as core from "@actions/core";
-import type { Endpoints } from "@octokit/types";
-import * as semver from "semver";
-import { updateChecksums } from "./download/checksum/update-known-checksums";
-import {
-  getLatestKnownVersion,
-  updateVersionManifest,
-} from "./download/version-manifest";
-import { OWNER, REPO } from "./utils/constants";
-import { Octokit } from "./utils/octokit";
-
-type Release =
-  Endpoints["GET /repos/{owner}/{repo}/releases"]["response"]["data"][number];
-
-async function run(): Promise<void> {
-  const checksumFilePath = process.argv.slice(2)[0];
-  const versionsManifestFile = process.argv.slice(2)[1];
-  const githubToken = process.argv.slice(2)[2];
-
-  const octokit = new Octokit({
-    auth: githubToken,
-  });
-
-  const { data: latestRelease } = await octokit.rest.repos.getLatestRelease({
-    owner: OWNER,
-    repo: REPO,
-  });
-
-  const latestKnownVersion = await getLatestKnownVersion(undefined);
-
-  if (semver.lte(latestRelease.tag_name, latestKnownVersion)) {
-    core.info(
-      `Latest release (${latestRelease.tag_name}) is not newer than the latest known version (${latestKnownVersion}). Skipping update.`,
-    );
-    return;
-  }
-
-  const releases: Release[] = await octokit.paginate(
-    octokit.rest.repos.listReleases,
-    {
-      owner: OWNER,
-      repo: REPO,
-    },
-  );
-  const checksumDownloadUrls: string[] = releases.flatMap((release) =>
-    release.assets
-      .filter((asset) => asset.name.endsWith(".sha256"))
-      .map((asset) => asset.browser_download_url),
-  );
-  await updateChecksums(checksumFilePath, checksumDownloadUrls);
-
-  const artifactDownloadUrls: string[] = releases.flatMap((release) =>
-    release.assets
-      .filter((asset) => !asset.name.endsWith(".sha256"))
-      .map((asset) => asset.browser_download_url),
-  );
-
-  await updateVersionManifest(versionsManifestFile, artifactDownloadUrls);
-
-  core.setOutput("latest-version", latestRelease.tag_name);
-}
-
-run();

src/utils/config-file.ts

@@ -8,7 +8,19 @@ export function getConfigValueFromTomlFile(
   if (!fs.existsSync(filePath) || !filePath.endsWith(".toml")) {
     return undefined;
   }
+
   const fileContent = fs.readFileSync(filePath, "utf-8");
+  return getConfigValueFromTomlContent(filePath, fileContent, key);
+}
+
+export function getConfigValueFromTomlContent(
+  filePath: string,
+  fileContent: string,
+  key: string,
+): string | undefined {
+  if (!filePath.endsWith(".toml")) {
+    return undefined;
+  }
 
   if (filePath.endsWith("pyproject.toml")) {
     const tomlContent = toml.parse(fileContent) as {
@@ -16,6 +28,7 @@ export function getConfigValueFromTomlFile(
     };
     return tomlContent?.tool?.uv?.[key];
   }
+
   const tomlContent = toml.parse(fileContent) as Record<
     string,
     string | undefined

src/utils/constants.ts

@@ -1,5 +1,13 @@
-export const REPO = "uv";
-export const OWNER = "astral-sh";
 export const TOOL_CACHE_NAME = "uv";
 export const STATE_UV_PATH = "uv-path";
 export const STATE_UV_VERSION = "uv-version";
+export const VERSIONS_MANIFEST_URL =
+  "https://raw.githubusercontent.com/astral-sh/versions/main/v1/uv.ndjson";
+
+/** GitHub Releases URL prefix for uv artifacts. */
+export const GITHUB_RELEASES_PREFIX =
+  "https://github.com/astral-sh/uv/releases/download/";
+
+/** Astral mirror URL prefix that fronts GitHub Releases for uv artifacts. */
+export const ASTRAL_MIRROR_PREFIX =
+  "https://releases.astral.sh/github/uv/releases/download/";

src/utils/fetch.ts

@@ -1,21 +1,20 @@
-import { ProxyAgent, type RequestInit, fetch as undiciFetch } from "undici";
+import {
+  EnvHttpProxyAgent,
+  type RequestInit,
+  fetch as undiciFetch,
+} from "undici";
 
-export function getProxyAgent() {
+export const fetch = async (url: string, opts: RequestInit) => {
-  const httpProxy = process.env.HTTP_PROXY || process.env.http_proxy;
+  // Merge timeout signal with any existing signal from opts
-  if (httpProxy) {
+  const timeoutSignal = AbortSignal.timeout(5_000);
-    return new ProxyAgent(httpProxy);
+  const existingSignal = opts.signal;
-  }
+  const mergedSignal = existingSignal
+    ? AbortSignal.any([timeoutSignal, existingSignal])
+    : timeoutSignal;
 
-  const httpsProxy = process.env.HTTPS_PROXY || process.env.https_proxy;
+  return await undiciFetch(url, {
-  if (httpsProxy) {
+    dispatcher: new EnvHttpProxyAgent(),
-    return new ProxyAgent(httpsProxy);
-  }
-
-  return undefined;
-}
-
-export const fetch = async (url: string, opts: RequestInit) =>
-  await undiciFetch(url, {
-    dispatcher: getProxyAgent(),
     ...opts,
+    signal: mergedSignal,
   });
+};

src/utils/inputs.ts

@@ -1,55 +1,211 @@
+import fs from "node:fs";
 import path from "node:path";
 import * as core from "@actions/core";
+import { getPythonVersionFromToolVersions } from "../version/tool-versions-file";
 import { getConfigValueFromTomlFile } from "./config-file";
+import * as log from "./logging";
 
-export const workingDirectory = core.getInput("working-directory");
+export enum CacheLocalSource {
-export const version = core.getInput("version");
+  Input,
-export const versionFile = getVersionFile();
+  Config,
-export const pythonVersion = core.getInput("python-version");
+  Env,
-export const activateEnvironment = core.getBooleanInput("activate-environment");
+  Default,
-export const checkSum = core.getInput("checksum");
+}
-export const enableCache = getEnableCache();
+
-export const restoreCache = core.getInput("restore-cache") === "true";
+export interface CacheLocalPath {
-export const saveCache = core.getInput("save-cache") === "true";
+  path: string;
-export const cacheSuffix = core.getInput("cache-suffix") || "";
+  source: CacheLocalSource;
-export const cacheLocalPath = getCacheLocalPath();
+}
-export const cacheDependencyGlob = getCacheDependencyGlob();
+
-export const pruneCache = core.getInput("prune-cache") === "true";
+export type ResolutionStrategy = "highest" | "lowest";
-export const cachePython = core.getInput("cache-python") === "true";
+
-export const ignoreNothingToCache =
+export interface SetupInputs {
+  workingDirectory: string;
+  version: string;
+  versionFile: string;
+  pythonVersion: string;
+  activateEnvironment: boolean;
+  noProject: boolean;
+  venvPath: string;
+  checksum: string;
+  enableCache: boolean;
+  restoreCache: boolean;
+  saveCache: boolean;
+  cacheSuffix: string;
+  cacheLocalPath?: CacheLocalPath;
+  cacheDependencyGlob: string;
+  pruneCache: boolean;
+  cachePython: boolean;
+  ignoreNothingToCache: boolean;
+  ignoreEmptyWorkdir: boolean;
+  toolBinDir?: string;
+  toolDir?: string;
+  pythonDir: string;
+  githubToken: string;
+  manifestFile?: string;
+  downloadFromAstralMirror: boolean;
+  addProblemMatchers: boolean;
+  quiet: boolean;
+  resolutionStrategy: ResolutionStrategy;
+}
+
+export function loadInputs(): SetupInputs {
+  const workingDirectory = core.getInput("working-directory");
+  const version = core.getInput("version");
+  const versionFile = getVersionFile(workingDirectory);
+  const pythonVersion = getPythonVersion(versionFile);
+  const activateEnvironment = core.getBooleanInput("activate-environment");
+  const noProject = core.getBooleanInput("no-project");
+  const venvPath = getVenvPath(workingDirectory, activateEnvironment);
+  const checksum = core.getInput("checksum");
+  const enableCache = getEnableCache();
+  const restoreCache = core.getInput("restore-cache") === "true";
+  const saveCache = getSaveCache();
+  const cacheSuffix = core.getInput("cache-suffix") || "";
+  const cacheLocalPath = getCacheLocalPath(
+    workingDirectory,
+    versionFile,
+    enableCache,
+  );
+  const cacheDependencyGlob = getCacheDependencyGlob(workingDirectory);
+  const pruneCache = core.getInput("prune-cache") === "true";
+  const cachePython = core.getInput("cache-python") === "true";
+  const ignoreNothingToCache =
     core.getInput("ignore-nothing-to-cache") === "true";
-export const ignoreEmptyWorkdir =
+  const ignoreEmptyWorkdir = core.getInput("ignore-empty-workdir") === "true";
-  core.getInput("ignore-empty-workdir") === "true";
+  const toolBinDir = getToolBinDir(workingDirectory);
-export const toolBinDir = getToolBinDir();
+  const toolDir = getToolDir(workingDirectory);
-export const toolDir = getToolDir();
+  const pythonDir = getUvPythonDir();
-export const pythonDir = getUvPythonDir();
+  const githubToken = core.getInput("github-token");
-export const githubToken = core.getInput("github-token");
+  const manifestFile = getManifestFile();
-export const manifestFile = getManifestFile();
+  const downloadFromAstralMirror =
-export const addProblemMatchers =
+    core.getInput("download-from-astral-mirror") === "true";
-  core.getInput("add-problem-matchers") === "true";
+  const addProblemMatchers = core.getInput("add-problem-matchers") === "true";
+  const quiet = core.getInput("quiet") === "true";
+  const resolutionStrategy = getResolutionStrategy();
 
-function getVersionFile(): string {
+  return {
+    activateEnvironment,
+    addProblemMatchers,
+    cacheDependencyGlob,
+    cacheLocalPath,
+    cachePython,
+    cacheSuffix,
+    checksum,
+    downloadFromAstralMirror,
+    enableCache,
+    githubToken,
+    ignoreEmptyWorkdir,
+    ignoreNothingToCache,
+    manifestFile,
+    noProject,
+    pruneCache,
+    pythonDir,
+    pythonVersion,
+    quiet,
+    resolutionStrategy,
+    restoreCache,
+    saveCache,
+    toolBinDir,
+    toolDir,
+    venvPath,
+    version,
+    versionFile,
+    workingDirectory,
+  };
+}
+
+function getVersionFile(workingDirectory: string): string {
   const versionFileInput = core.getInput("version-file");
   if (versionFileInput !== "") {
     const tildeExpanded = expandTilde(versionFileInput);
-    return resolveRelativePath(tildeExpanded);
+    return resolveRelativePath(workingDirectory, tildeExpanded);
   }
   return versionFileInput;
 }
 
+function getPythonVersion(versionFile: string): string {
+  const pythonVersionInput = core.getInput("python-version");
+  if (pythonVersionInput !== "") {
+    return pythonVersionInput;
+  }
+  if (process.env.UV_PYTHON !== undefined && process.env.UV_PYTHON !== "") {
+    return "";
+  }
+  if (versionFile === "" || !fs.existsSync(versionFile)) {
+    return "";
+  }
+
+  try {
+    return getPythonVersionFromToolVersions(versionFile) ?? "";
+  } catch (err) {
+    log.warning(
+      `Error while parsing Python version from ${versionFile}: ${(err as Error).message}`,
+    );
+    return "";
+  }
+}
+
+function getVenvPath(
+  workingDirectory: string,
+  activateEnvironment: boolean,
+): string {
+  const venvPathInput = core.getInput("venv-path");
+  if (venvPathInput !== "") {
+    if (!activateEnvironment) {
+      log.warning("venv-path is only used when activate-environment is true");
+    }
+    const tildeExpanded = expandTilde(venvPathInput);
+    return normalizePath(resolveRelativePath(workingDirectory, tildeExpanded));
+  }
+  return normalizePath(resolveRelativePath(workingDirectory, ".venv"));
+}
+
 function getEnableCache(): boolean {
   const enableCacheInput = core.getInput("enable-cache");
   if (enableCacheInput === "auto") {
-    return process.env.RUNNER_ENVIRONMENT === "github-hosted";
+    if (process.env.RUNNER_ENVIRONMENT !== "github-hosted") {
+      return false;
+    }
+
+    const eventName = process.env.GITHUB_EVENT_NAME;
+    const isTagPush =
+      eventName === "push" && process.env.GITHUB_REF?.startsWith("refs/tags/");
+    if (isTagPush) {
+      log.info("Caching is disabled for tag pushes");
+      return false;
+    }
+    if (
+      eventName === "pull_request_target" ||
+      eventName === "workflow_run" ||
+      eventName === "release"
+    ) {
+      log.info(`Caching is disabled for the ${eventName} event`);
+      return false;
+    }
+
+    return true;
   }
   return enableCacheInput === "true";
 }
 
-function getToolBinDir(): string | undefined {
+function getSaveCache(): boolean {
+  const saveCacheInput = core.getInput("save-cache");
+  if (saveCacheInput === "auto") {
+    if (process.env.GITHUB_EVENT_NAME === "merge_group") {
+      log.info("Cache saving is disabled for the merge_group event");
+      return false;
+    }
+    return true;
+  }
+  return saveCacheInput === "true";
+}
+
+function getToolBinDir(workingDirectory: string): string | undefined {
   const toolBinDirInput = core.getInput("tool-bin-dir");
   if (toolBinDirInput !== "") {
     const tildeExpanded = expandTilde(toolBinDirInput);
-    return resolveRelativePath(tildeExpanded);
+    return resolveRelativePath(workingDirectory, tildeExpanded);
   }
   if (process.platform === "win32") {
     if (process.env.RUNNER_TEMP !== undefined) {
@@ -62,11 +218,11 @@ function getToolBinDir(): string | undefined {
   return undefined;
 }
 
-function getToolDir(): string | undefined {
+function getToolDir(workingDirectory: string): string | undefined {
   const toolDirInput = core.getInput("tool-dir");
   if (toolDirInput !== "") {
     const tildeExpanded = expandTilde(toolDirInput);
-    return resolveRelativePath(tildeExpanded);
+    return resolveRelativePath(workingDirectory, tildeExpanded);
   }
   if (process.platform === "win32") {
     if (process.env.RUNNER_TEMP !== undefined) {
@@ -79,46 +235,70 @@ function getToolDir(): string | undefined {
   return undefined;
 }
 
-function getCacheLocalPath(): string {
+function getCacheLocalPath(
+  workingDirectory: string,
+  versionFile: string,
+  enableCache: boolean,
+): CacheLocalPath | undefined {
   const cacheLocalPathInput = core.getInput("cache-local-path");
   if (cacheLocalPathInput !== "") {
     const tildeExpanded = expandTilde(cacheLocalPathInput);
-    return resolveRelativePath(tildeExpanded);
+    return {
+      path: resolveRelativePath(workingDirectory, tildeExpanded),
+      source: CacheLocalSource.Input,
+    };
   }
-  const cacheDirFromConfig = getCacheDirFromConfig();
+  const cacheDirFromConfig = getCacheDirFromConfig(
+    workingDirectory,
+    versionFile,
+  );
   if (cacheDirFromConfig !== undefined) {
-    return cacheDirFromConfig;
+    return { path: cacheDirFromConfig, source: CacheLocalSource.Config };
   }
   if (process.env.UV_CACHE_DIR !== undefined) {
-    core.info(`UV_CACHE_DIR is already set to ${process.env.UV_CACHE_DIR}`);
+    log.info(`UV_CACHE_DIR is already set to ${process.env.UV_CACHE_DIR}`);
-    return process.env.UV_CACHE_DIR;
+    return { path: process.env.UV_CACHE_DIR, source: CacheLocalSource.Env };
   }
+  if (enableCache) {
     if (process.env.RUNNER_ENVIRONMENT === "github-hosted") {
       if (process.env.RUNNER_TEMP !== undefined) {
-      return `${process.env.RUNNER_TEMP}${path.sep}setup-uv-cache`;
+        return {
+          path: `${process.env.RUNNER_TEMP}${path.sep}setup-uv-cache`,
+          source: CacheLocalSource.Default,
+        };
       }
       throw Error(
         "Could not determine UV_CACHE_DIR. Please make sure RUNNER_TEMP is set or provide the cache-local-path input",
       );
     }
     if (process.platform === "win32") {
-    return `${process.env.APPDATA}${path.sep}uv${path.sep}cache`;
+      return {
+        path: `${process.env.APPDATA}${path.sep}uv${path.sep}cache`,
+        source: CacheLocalSource.Default,
+      };
+    }
+    return {
+      path: `${process.env.HOME}${path.sep}.cache${path.sep}uv`,
+      source: CacheLocalSource.Default,
+    };
   }
-  return `${process.env.HOME}${path.sep}.cache${path.sep}uv`;
 }
 
-function getCacheDirFromConfig(): string | undefined {
+function getCacheDirFromConfig(
+  workingDirectory: string,
+  versionFile: string,
+): string | undefined {
   for (const filePath of [versionFile, "uv.toml", "pyproject.toml"]) {
-    const resolvedPath = resolveRelativePath(filePath);
+    const resolvedPath = resolveRelativePath(workingDirectory, filePath);
     try {
       const cacheDir = getConfigValueFromTomlFile(resolvedPath, "cache-dir");
       if (cacheDir !== undefined) {
-        core.info(`Found cache-dir in ${resolvedPath}: ${cacheDir}`);
+        log.info(`Found cache-dir in ${resolvedPath}: ${cacheDir}`);
         return cacheDir;
       }
     } catch (err) {
       const message = (err as Error).message;
-      core.warning(`Error while parsing ${filePath}: ${message}`);
+      log.warning(`Error while parsing ${filePath}: ${message}`);
       return undefined;
     }
   }
@@ -127,7 +307,7 @@ function getCacheDirFromConfig(): string | undefined {
 
 export function getUvPythonDir(): string {
   if (process.env.UV_PYTHON_INSTALL_DIR !== undefined) {
-    core.info(
+    log.info(
       `UV_PYTHON_INSTALL_DIR is already set to ${process.env.UV_PYTHON_INSTALL_DIR}`,
     );
     return process.env.UV_PYTHON_INSTALL_DIR;
@@ -135,9 +315,8 @@ export function getUvPythonDir(): string {
   if (process.env.RUNNER_ENVIRONMENT !== "github-hosted") {
     if (process.platform === "win32") {
       return `${process.env.APPDATA}${path.sep}uv${path.sep}python`;
-    } else {
-      return `${process.env.HOME}${path.sep}.local${path.sep}share${path.sep}uv${path.sep}python`;
     }
+    return `${process.env.HOME}${path.sep}.local${path.sep}share${path.sep}uv${path.sep}python`;
   }
   if (process.env.RUNNER_TEMP !== undefined) {
     return `${process.env.RUNNER_TEMP}${path.sep}uv-python-dir`;
@@ -147,14 +326,14 @@ export function getUvPythonDir(): string {
   );
 }
 
-function getCacheDependencyGlob(): string {
+function getCacheDependencyGlob(workingDirectory: string): string {
   const cacheDependencyGlobInput = core.getInput("cache-dependency-glob");
   if (cacheDependencyGlobInput !== "") {
     return cacheDependencyGlobInput
       .split("\n")
       .map((part) => part.trim())
       .map((part) => expandTilde(part))
-      .map((part) => resolveRelativePath(part))
+      .map((part) => resolveRelativePath(workingDirectory, part))
       .join("\n");
   }
   return cacheDependencyGlobInput;
@@ -167,7 +346,23 @@ function expandTilde(input: string): string {
   return input;
 }
 
-function resolveRelativePath(inputPath: string): string {
+function normalizePath(inputPath: string): string {
+  const normalized = path.normalize(inputPath);
+  const root = path.parse(normalized).root;
+
+  // Remove any trailing path separators, except when the whole path is the root.
+  let trimmed = normalized;
+  while (trimmed.length > root.length && trimmed.endsWith(path.sep)) {
+    trimmed = trimmed.slice(0, -1);
+  }
+
+  return trimmed;
+}
+
+function resolveRelativePath(
+  workingDirectory: string,
+  inputPath: string,
+): string {
   const hasNegation = inputPath.startsWith("!");
   const pathWithoutNegation = hasNegation ? inputPath.substring(1) : inputPath;
 
@@ -186,3 +381,16 @@ function getManifestFile(): string | undefined {
   }
   return undefined;
 }
+
+function getResolutionStrategy(): ResolutionStrategy {
+  const resolutionStrategyInput = core.getInput("resolution-strategy");
+  if (resolutionStrategyInput === "lowest") {
+    return "lowest";
+  }
+  if (resolutionStrategyInput === "highest" || resolutionStrategyInput === "") {
+    return "highest";
+  }
+  throw new Error(
+    `Invalid resolution-strategy: ${resolutionStrategyInput}. Must be 'highest' or 'lowest'.`,
+  );
+}

src/utils/logging.ts

@@ -0,0 +1,21 @@
+import * as core from "@actions/core";
+
+let quiet: boolean | undefined;
+
+function isQuiet(): boolean {
+  if (quiet === undefined) {
+    quiet =
+      typeof core.getInput === "function" && core.getInput("quiet") === "true";
+  }
+  return quiet;
+}
+
+export function info(msg: string): void {
+  if (!isQuiet()) {
+    core.info(msg);
+  }
+}
+
+export const warning = core.warning;
+export const error = core.error;
+export const debug = core.debug;

src/utils/octokit.ts

@@ -1,34 +0,0 @@
-import type { OctokitOptions } from "@octokit/core";
-import { Octokit as Core } from "@octokit/core";
-import {
-  type PaginateInterface,
-  paginateRest,
-} from "@octokit/plugin-paginate-rest";
-import { legacyRestEndpointMethods } from "@octokit/plugin-rest-endpoint-methods";
-import { fetch as customFetch } from "./fetch";
-
-export type { RestEndpointMethodTypes } from "@octokit/plugin-rest-endpoint-methods";
-
-const DEFAULTS = {
-  baseUrl: "https://api.github.com",
-  userAgent: "setup-uv",
-};
-
-const OctokitWithPlugins = Core.plugin(paginateRest, legacyRestEndpointMethods);
-
-export const Octokit = OctokitWithPlugins.defaults(function buildDefaults(
-  options: OctokitOptions,
-): OctokitOptions {
-  return {
-    ...DEFAULTS,
-    ...options,
-    request: {
-      fetch: customFetch,
-      ...options.request,
-    },
-  };
-});
-
-export type Octokit = InstanceType<typeof OctokitWithPlugins> & {
-  paginate: PaginateInterface;
-};

src/utils/platforms.ts

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import os from "node:os";
 import * as core from "@actions/core";
 import * as exec from "@actions/exec";
 export type Platform =
@@ -11,6 +13,7 @@ export type Architecture =
   | "x86_64"
   | "aarch64"
   | "s390x"
+  | "riscv64gc"
   | "powerpc64le";
 
 export function getArch(): Architecture | undefined {
@@ -19,6 +22,7 @@ export function getArch(): Architecture | undefined {
     arm64: "aarch64",
     ia32: "i686",
     ppc64: "powerpc64le",
+    riscv64: "riscv64gc",
     s390x: "s390x",
     x64: "x86_64",
   };
@@ -74,3 +78,93 @@ async function isMuslOs(): Promise<boolean> {
     return false;
   }
 }
+
+/**
+ * Returns OS name and version for cache key differentiation.
+ * Examples: "ubuntu-22.04", "macos-14", "windows-2022"
+ * Throws if OS detection fails.
+ */
+export function getOSNameVersion(): string {
+  const platform = process.platform;
+
+  if (platform === "linux") {
+    return getLinuxOSNameVersion();
+  }
+  if (platform === "darwin") {
+    return getMacOSNameVersion();
+  }
+  if (platform === "win32") {
+    return getWindowsNameVersion();
+  }
+
+  throw new Error(`Unsupported platform: ${platform}`);
+}
+
+function getLinuxOSNameVersion(): string {
+  const files = ["/etc/os-release", "/usr/lib/os-release"];
+  let idWithoutVersion: string | undefined;
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, "utf8");
+      const id = parseOsReleaseValue(content, "ID");
+      const versionId = parseOsReleaseValue(content, "VERSION_ID");
+      // Fallback for rolling releases (debian:unstable/testing, arch, etc.)
+      // that don't have VERSION_ID but have VERSION_CODENAME or BUILD_ID
+      const versionCodename = parseOsReleaseValue(content, "VERSION_CODENAME");
+      const buildId = parseOsReleaseValue(content, "BUILD_ID");
+
+      if (id && versionId) {
+        return `${id}-${versionId}`;
+      }
+      if (id && versionCodename) {
+        return `${id}-${versionCodename}`;
+      }
+      if (id && buildId) {
+        return `${id}-${buildId}`;
+      }
+      // Remember the ID but keep looking: the next file might still
+      // provide a version field
+      if (id && idWithoutVersion === undefined) {
+        idWithoutVersion = id;
+      }
+    } catch {
+      // Try next file
+    }
+  }
+
+  // Fallback for rolling releases (e.g. void) that have no version
+  // field at all
+  if (idWithoutVersion) {
+    return idWithoutVersion;
+  }
+
+  throw new Error(
+    "Failed to determine Linux distribution. " +
+      "Could not read /etc/os-release or /usr/lib/os-release",
+  );
+}
+
+function parseOsReleaseValue(content: string, key: string): string | undefined {
+  const regex = new RegExp(`^${key}=["']?([^"'\\n]*)["']?$`, "m");
+  const match = content.match(regex);
+  return match?.[1];
+}
+
+function getMacOSNameVersion(): string {
+  const darwinVersion = Number.parseInt(os.release().split(".")[0], 10);
+  if (Number.isNaN(darwinVersion)) {
+    throw new Error(`Failed to parse macOS version from: ${os.release()}`);
+  }
+  const macosVersion = darwinVersion - 9;
+  return `macos-${macosVersion}`;
+}
+
+function getWindowsNameVersion(): string {
+  const version = os.version();
+  const match = version.match(/Windows(?: Server)? (\d+)/);
+  if (!match) {
+    throw new Error(`Failed to parse Windows version from: ${version}`);
+  }
+  return `windows-${match[1]}`;
+}

src/utils/python-runtime.ts

@@ -0,0 +1,43 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { SetupInputs } from "./inputs";
+
+const execFileAsync = promisify(execFile);
+
+export async function getPythonRuntimeId(inputs: SetupInputs): Promise<string> {
+  if (!inputs.activateEnvironment) {
+    return "";
+  }
+
+  try {
+    // The venv path restricts results to this invocation's runtime, even if
+    // earlier setup-uv calls installed other Python versions in the same job.
+    const { stdout } = await execFileAsync(
+      "uv",
+      [
+        "python",
+        "list",
+        inputs.venvPath,
+        "--only-installed",
+        "--output-format",
+        "json",
+      ],
+      { encoding: "utf8" },
+    );
+    const pythons = JSON.parse(stdout);
+    if (
+      !Array.isArray(pythons) ||
+      pythons.length !== 1 ||
+      typeof pythons[0]?.key !== "string" ||
+      pythons[0].key === ""
+    ) {
+      throw new Error("Expected one installed Python with a runtime key");
+    }
+    return pythons[0].key;
+  } catch (error) {
+    throw new Error(
+      `Failed to identify the activated environment's Python runtime: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+}

src/version/file-parser.ts

@@ -0,0 +1,107 @@
+import fs from "node:fs";
+import { getConfigValueFromTomlContent } from "../utils/config-file";
+import * as log from "../utils/logging";
+import {
+  getUvVersionFromParsedPyproject,
+  getUvVersionFromRequirementsText,
+  parsePyprojectContent,
+} from "./requirements-file";
+import { normalizeVersionSpecifier } from "./specifier";
+import { getUvVersionFromToolVersions } from "./tool-versions-file";
+import type { ParsedVersionFile, VersionFileFormat } from "./types";
+import { getUvVersionFromUvLock } from "./uv-lock-file";
+
+interface VersionFileParser {
+  format: VersionFileFormat;
+  parse(filePath: string): string | undefined;
+  supports(filePath: string): boolean;
+}
+
+const VERSION_FILE_PARSERS: VersionFileParser[] = [
+  {
+    format: ".tool-versions",
+    parse: (filePath) => getUvVersionFromToolVersions(filePath),
+    supports: (filePath) => filePath.endsWith(".tool-versions"),
+  },
+  {
+    format: "uv.toml",
+    parse: (filePath) => {
+      const fileContent = fs.readFileSync(filePath, "utf-8");
+      return getConfigValueFromTomlContent(
+        filePath,
+        fileContent,
+        "required-version",
+      );
+    },
+    supports: (filePath) => filePath.endsWith("uv.toml"),
+  },
+  {
+    format: "pyproject.toml",
+    parse: (filePath) => {
+      const fileContent = fs.readFileSync(filePath, "utf-8");
+      const pyproject = parsePyprojectContent(fileContent);
+      const requiredVersion = pyproject.tool?.uv?.["required-version"];
+
+      if (requiredVersion !== undefined) {
+        return requiredVersion;
+      }
+
+      return getUvVersionFromParsedPyproject(pyproject);
+    },
+    supports: (filePath) => filePath.endsWith("pyproject.toml"),
+  },
+  {
+    format: "uv.lock",
+    parse: (filePath) => getUvVersionFromUvLock(filePath),
+    supports: (filePath) => filePath.endsWith("uv.lock"),
+  },
+  {
+    format: "requirements",
+    parse: (filePath) => {
+      const fileContent = fs.readFileSync(filePath, "utf-8");
+      return getUvVersionFromRequirementsText(fileContent);
+    },
+    supports: (filePath) => filePath.endsWith(".txt"),
+  },
+];
+
+export function getParsedVersionFile(
+  filePath: string,
+): ParsedVersionFile | undefined {
+  log.info(`Trying to find version for uv in: ${filePath}`);
+
+  if (!fs.existsSync(filePath)) {
+    log.info(`Could not find file: ${filePath}`);
+    return undefined;
+  }
+
+  const parser = getVersionFileParser(filePath);
+  if (parser === undefined) {
+    return undefined;
+  }
+
+  try {
+    const specifier = parser.parse(filePath);
+    if (specifier === undefined) {
+      return undefined;
+    }
+
+    const normalizedSpecifier = normalizeVersionSpecifier(specifier);
+    log.info(`Found version for uv in ${filePath}: ${normalizedSpecifier}`);
+    return {
+      format: parser.format,
+      specifier: normalizedSpecifier,
+    };
+  } catch (error) {
+    log.warning(`Error while parsing ${filePath}: ${(error as Error).message}`);
+    return undefined;
+  }
+}
+
+export function getUvVersionFromFile(filePath: string): string | undefined {
+  return getParsedVersionFile(filePath)?.specifier;
+}
+
+function getVersionFileParser(filePath: string): VersionFileParser | undefined {
+  return VERSION_FILE_PARSERS.find((parser) => parser.supports(filePath));
+}

src/version/requirements-file.ts

@@ -5,31 +5,23 @@ export function getUvVersionFromRequirementsFile(
   filePath: string,
 ): string | undefined {
   const fileContent = fs.readFileSync(filePath, "utf-8");
+
   if (filePath.endsWith(".txt")) {
-    return getUvVersionFromAllDependencies(fileContent.split("\n"));
+    return getUvVersionFromRequirementsText(fileContent);
   }
-  const dependencies = parsePyprojectDependencies(fileContent);
+
-  return getUvVersionFromAllDependencies(dependencies);
+  return getUvVersionFromPyprojectContent(fileContent);
 }
-function getUvVersionFromAllDependencies(
+
-  allDependencies: string[],
+export function getUvVersionFromRequirementsText(
+  fileContent: string,
 ): string | undefined {
-  return allDependencies
+  return getUvVersionFromAllDependencies(fileContent.split("\n"));
-    .find((dep: string) => dep.match(/^uv[=<>~!]/))
-    ?.match(/^uv([=<>~!]+\S*)/)?.[1]
-    .trim();
 }
 
-interface Pyproject {
+export function getUvVersionFromParsedPyproject(
-  project?: {
+  pyproject: Pyproject,
-    dependencies?: string[];
+): string | undefined {
-    "optional-dependencies"?: Record<string, string[]>;
-  };
-  "dependency-groups"?: Record<string, Array<string | object>>;
-}
-
-function parsePyprojectDependencies(pyprojectContent: string): string[] {
-  const pyproject: Pyproject = toml.parse(pyprojectContent);
   const dependencies: string[] = pyproject?.project?.dependencies || [];
   const optionalDependencies: string[] = Object.values(
     pyproject?.project?.["optional-dependencies"] || {},
@@ -39,5 +31,43 @@ function parsePyprojectDependencies(pyprojectContent: string): string[] {
   )
     .flat()
     .filter((item: string | object) => typeof item === "string");
-  return dependencies.concat(optionalDependencies, devDependencies);
+
+  return getUvVersionFromAllDependencies(
+    dependencies.concat(optionalDependencies, devDependencies),
+  );
+}
+
+export function getUvVersionFromPyprojectContent(
+  pyprojectContent: string,
+): string | undefined {
+  const pyproject = parsePyprojectContent(pyprojectContent);
+  return getUvVersionFromParsedPyproject(pyproject);
+}
+
+export interface Pyproject {
+  project?: {
+    dependencies?: string[];
+    "optional-dependencies"?: Record<string, string[]>;
+  };
+  "dependency-groups"?: Record<string, Array<string | object>>;
+  tool?: {
+    uv?: Record<string, string | undefined>;
+  };
+}
+
+export function parsePyprojectContent(pyprojectContent: string): Pyproject {
+  return toml.parse(pyprojectContent) as Pyproject;
+}
+
+function getUvVersionFromAllDependencies(
+  allDependencies: string[],
+): string | undefined {
+  return allDependencies
+    .map(getUvVersionFromDependency)
+    .find((version): version is string => version !== undefined);
+}
+
+function getUvVersionFromDependency(dependency: string): string | undefined {
+  const dependencyWithoutMarker = dependency.split(";", 1)[0]?.trim();
+  return dependencyWithoutMarker?.match(/^uv([=<>~!]+\S*)/)?.[1].trim();
 }

src/version/resolve.ts

@@ -1,34 +1,236 @@
-import fs from "node:fs";
 import * as core from "@actions/core";
-import { getConfigValueFromTomlFile } from "../utils/config-file";
+import * as tc from "@actions/tool-cache";
-import { getUvVersionFromRequirementsFile } from "./requirements-file";
+import * as pep440 from "@renovatebot/pep440";
-import { getUvVersionFromToolVersions } from "./tool-versions-file";
+import * as semver from "semver";
+import { getLatestKnownVersion } from "../download/checksum/known-version";
+import {
+  getAllVersions,
+  getFirstMatchingVersion,
+  getLatestVersion,
+} from "../download/manifest";
+import { VERSIONS_MANIFEST_URL } from "../utils/constants";
+import type { ResolutionStrategy } from "../utils/inputs";
+import * as log from "../utils/logging";
+import {
+  type ParsedVersionSpecifier,
+  parseVersionSpecifier,
+} from "./specifier";
+import type { ResolveUvVersionOptions } from "./types";
+import { resolveVersionRequest } from "./version-request-resolver";
 
-export function getUvVersionFromFile(filePath: string): string | undefined {
+interface ConcreteVersionResolutionContext {
-  core.info(`Trying to find version for uv in: ${filePath}`);
+  manifestUrl?: string;
-  if (!fs.existsSync(filePath)) {
+  parsedSpecifier: ParsedVersionSpecifier;
-    core.info(`Could not find file: ${filePath}`);
+  resolutionStrategy: ResolutionStrategy;
-    return undefined;
+}
-  }
+
-  let uvVersion: string | undefined;
+interface ConcreteVersionResolver {
-  try {
+  resolve(
-    uvVersion = getUvVersionFromToolVersions(filePath);
+    context: ConcreteVersionResolutionContext,
-    if (uvVersion === undefined) {
+  ): Promise<string | undefined>;
-      uvVersion = getConfigValueFromTomlFile(filePath, "required-version");
+}
-    }
+
-    if (uvVersion === undefined) {
+class ExactVersionResolver implements ConcreteVersionResolver {
-      uvVersion = getUvVersionFromRequirementsFile(filePath);
+  async resolve(
-    }
+    context: ConcreteVersionResolutionContext,
-  } catch (err) {
+  ): Promise<string | undefined> {
-    const message = (err as Error).message;
+    if (context.parsedSpecifier.kind !== "exact") {
-    core.warning(`Error while parsing ${filePath}: ${message}`);
+      return undefined;
-    return undefined;
+    }
-  }
+
-  if (uvVersion?.startsWith("==")) {
+    core.debug(
-    uvVersion = uvVersion.slice(2);
+      `Version ${context.parsedSpecifier.normalized} is an explicit version.`,
-  }
+    );
-  if (uvVersion !== undefined) {
+    return context.parsedSpecifier.normalized;
-    core.info(`Found version for uv in ${filePath}: ${uvVersion}`);
+  }
-  }
+}
-  return uvVersion;
+
+class LatestVersionResolver implements ConcreteVersionResolver {
+  async resolve(
+    context: ConcreteVersionResolutionContext,
+  ): Promise<string | undefined> {
+    const shouldUseLatestVersion =
+      context.parsedSpecifier.kind === "latest" ||
+      (context.parsedSpecifier.kind === "range" &&
+        context.parsedSpecifier.isSimpleMinimumVersionSpecifier &&
+        context.resolutionStrategy === "highest");
+
+    if (!shouldUseLatestVersion) {
+      return undefined;
+    }
+
+    if (
+      context.parsedSpecifier.kind === "range" &&
+      context.parsedSpecifier.isSimpleMinimumVersionSpecifier
+    ) {
+      log.info("Found minimum version specifier, using latest version");
+    }
+
+    const latestVersion = await getLatestVersion(context.manifestUrl);
+
+    if (
+      context.parsedSpecifier.kind === "range" &&
+      context.parsedSpecifier.isSimpleMinimumVersionSpecifier &&
+      !pep440.satisfies(latestVersion, context.parsedSpecifier.raw)
+    ) {
+      throw new Error(`No version found for ${context.parsedSpecifier.raw}`);
+    }
+
+    return latestVersion;
+  }
+}
+
+class RangeVersionResolver implements ConcreteVersionResolver {
+  async resolve(
+    context: ConcreteVersionResolutionContext,
+  ): Promise<string | undefined> {
+    if (context.parsedSpecifier.kind !== "range") {
+      return undefined;
+    }
+
+    let resolvedVersion: string | undefined;
+    if (
+      context.resolutionStrategy === "highest" &&
+      (context.manifestUrl === undefined ||
+        context.manifestUrl === VERSIONS_MANIFEST_URL)
+    ) {
+      resolvedVersion = await findHighestSatisfyingVersion(
+        context.parsedSpecifier.normalized,
+      );
+    } else {
+      const availableVersions = await getAllVersions(context.manifestUrl);
+      core.debug(`Available versions: ${availableVersions}`);
+      resolvedVersion =
+        context.resolutionStrategy === "lowest"
+          ? minSatisfying(availableVersions, context.parsedSpecifier.normalized)
+          : maxSatisfying(
+              availableVersions,
+              context.parsedSpecifier.normalized,
+            );
+    }
+
+    if (resolvedVersion === undefined) {
+      throw new Error(`No version found for ${context.parsedSpecifier.raw}`);
+    }
+
+    return resolvedVersion;
+  }
+}
+
+const CONCRETE_VERSION_RESOLVERS: ConcreteVersionResolver[] = [
+  new ExactVersionResolver(),
+  new LatestVersionResolver(),
+  new RangeVersionResolver(),
+];
+
+export async function resolveUvVersion(
+  options: ResolveUvVersionOptions,
+): Promise<string> {
+  const request = resolveVersionRequest(options);
+  const resolutionStrategy = options.resolutionStrategy ?? "highest";
+  const version = await resolveVersion(
+    request.specifier,
+    options.manifestFile,
+    resolutionStrategy,
+  );
+
+  return version;
+}
+
+export async function resolveVersion(
+  versionInput: string,
+  manifestUrl: string | undefined,
+  resolutionStrategy: ResolutionStrategy = "highest",
+): Promise<string> {
+  core.debug(`Resolving version: ${versionInput}`);
+
+  if (versionInput.trim() === "latest-known") {
+    return getLatestKnownVersion();
+  }
+
+  const context: ConcreteVersionResolutionContext = {
+    manifestUrl,
+    parsedSpecifier: parseVersionSpecifier(versionInput),
+    resolutionStrategy,
+  };
+
+  for (const resolver of CONCRETE_VERSION_RESOLVERS) {
+    const version = await resolver.resolve(context);
+    if (version !== undefined) {
+      return version;
+    }
+  }
+
+  throw new Error(`No version found for ${versionInput}`);
+}
+
+async function findHighestSatisfyingVersion(
+  versionSpecifier: string,
+): Promise<string | undefined> {
+  // This fast path assumes uv releases are semver-monotonic: newer manifest
+  // entries always have higher versions, with no lower-version backports.
+  const semverRange = semver.validRange(versionSpecifier);
+  if (semverRange !== null) {
+    const semverMatch = await getFirstMatchingVersion((version) =>
+      semver.satisfies(version, semverRange),
+    );
+    if (semverMatch !== undefined) {
+      core.debug(
+        `Found a version that satisfies the semver range: ${semverMatch}`,
+      );
+      return semverMatch;
+    }
+  }
+
+  const pep440Match = await getFirstMatchingVersion((version) =>
+    pep440.satisfies(version, versionSpecifier),
+  );
+  if (pep440Match !== undefined) {
+    core.debug(
+      `Found a version that satisfies the pep440 specifier: ${pep440Match}`,
+    );
+  }
+  return pep440Match;
+}
+
+function maxSatisfying(
+  versions: string[],
+  version: string,
+): string | undefined {
+  const maxSemver = tc.evaluateVersions(versions, version);
+  if (maxSemver !== "") {
+    core.debug(`Found a version that satisfies the semver range: ${maxSemver}`);
+    return maxSemver;
+  }
+
+  const maxPep440 = pep440.maxSatisfying(versions, version);
+  if (maxPep440 !== null) {
+    core.debug(
+      `Found a version that satisfies the pep440 specifier: ${maxPep440}`,
+    );
+    return maxPep440;
+  }
+
+  return undefined;
+}
+
+function minSatisfying(
+  versions: string[],
+  version: string,
+): string | undefined {
+  const minSemver = semver.minSatisfying(versions, version);
+  if (minSemver !== null) {
+    core.debug(`Found a version that satisfies the semver range: ${minSemver}`);
+    return minSemver;
+  }
+
+  const minPep440 = pep440.minSatisfying(versions, version);
+  if (minPep440 !== null) {
+    core.debug(
+      `Found a version that satisfies the pep440 specifier: ${minPep440}`,
+    );
+    return minPep440;
+  }
+
+  return undefined;
 }

src/version/specifier.ts

@@ -0,0 +1,59 @@
+import * as tc from "@actions/tool-cache";
+
+export type ParsedVersionSpecifier =
+  | {
+      kind: "exact";
+      normalized: string;
+      raw: string;
+    }
+  | {
+      kind: "latest";
+      normalized: "latest";
+      raw: string;
+    }
+  | {
+      isSimpleMinimumVersionSpecifier: boolean;
+      kind: "range";
+      normalized: string;
+      raw: string;
+    };
+
+export function normalizeVersionSpecifier(specifier: string): string {
+  const trimmedSpecifier = specifier.trim();
+
+  if (trimmedSpecifier.startsWith("==")) {
+    return trimmedSpecifier.slice(2);
+  }
+
+  return trimmedSpecifier;
+}
+
+export function parseVersionSpecifier(
+  specifier: string,
+): ParsedVersionSpecifier {
+  const raw = specifier.trim();
+  const normalized = normalizeVersionSpecifier(raw);
+
+  if (normalized === "latest") {
+    return {
+      kind: "latest",
+      normalized: "latest",
+      raw,
+    };
+  }
+
+  if (tc.isExplicitVersion(normalized)) {
+    return {
+      kind: "exact",
+      normalized,
+      raw,
+    };
+  }
+
+  return {
+    isSimpleMinimumVersionSpecifier: raw.includes(">") && !raw.includes(","),
+    kind: "range",
+    normalized,
+    raw,
+  };
+}

src/version/tool-versions-file.ts

@@ -4,28 +4,83 @@ import * as core from "@actions/core";
 export function getUvVersionFromToolVersions(
   filePath: string,
 ): string | undefined {
-  if (!filePath.endsWith(".tool-versions")) {
+  const versions = getToolVersions(filePath, "uv");
+  if (versions === undefined || versions.length !== 1) {
     return undefined;
   }
-  const fileContents = fs.readFileSync(filePath, "utf8");
-  const lines = fileContents.split("\n");
 
-  for (const line of lines) {
+  const version = stripVersionPrefix(versions[0]);
-    // Skip commented lines
+  if (isPath(version)) {
-    if (line.trim().startsWith("#")) {
+    core.warning(
-      continue;
+      `The uv version ${versions[0]} in .tool-versions is not supported. Paths are not allowed.`,
+    );
+    return undefined;
   }
-    const match = line.match(/^\s*uv\s*v?\s*(?<version>[^\s]+)\s*$/);
+  if (version.startsWith("ref")) {
-    if (match) {
-      const matchedVersion = match.groups?.version.trim();
-      if (matchedVersion?.startsWith("ref")) {
     core.warning(
       "The ref syntax of .tool-versions is not supported. Please use a released version instead.",
     );
     return undefined;
   }
-      return matchedVersion;
+  return version;
+}
+
+export function getPythonVersionFromToolVersions(
+  filePath: string,
+): string | undefined {
+  const versions = getToolVersions(filePath, "python");
+  if (versions === undefined || versions.length === 0) {
+    return undefined;
+  }
+  if (versions.length > 1) {
+    core.warning(
+      "Multiple Python versions in .tool-versions are not supported. The Python entry will be ignored.",
+    );
+    return undefined;
+  }
+
+  const version = stripVersionPrefix(versions[0]);
+  if (
+    version === "system" ||
+    version.startsWith("ref:") ||
+    version.startsWith("path:") ||
+    isPath(version)
+  ) {
+    core.warning(
+      `The Python version ${versions[0]} in .tool-versions is not supported. The Python entry will be ignored.`,
+    );
+    return undefined;
+  }
+  return version;
+}
+
+function getToolVersions(
+  filePath: string,
+  toolName: string,
+): string[] | undefined {
+  if (!filePath.endsWith(".tool-versions")) {
+    return undefined;
+  }
+  const fileContents = fs.readFileSync(filePath, "utf8");
+
+  for (const line of fileContents.split("\n")) {
+    const content = line.split("#", 1)[0].trim();
+    if (content === "") {
+      continue;
+    }
+
+    const [tool, ...versions] = content.split(/\s+/);
+    if (tool === toolName) {
+      return versions;
     }
   }
   return undefined;
 }
+
+function stripVersionPrefix(version: string): string {
+  return version.startsWith("v") ? version.slice(1) : version;
+}
+
+function isPath(version: string): boolean {
+  return version.includes("/") || version.includes("\\");
+}

src/version/types.ts

@@ -0,0 +1,35 @@
+import type { ResolutionStrategy } from "../utils/inputs";
+
+export type VersionSource =
+  | "input"
+  | "version-file"
+  | "uv.toml"
+  | "pyproject.toml"
+  | "default";
+
+export type VersionFileFormat =
+  | ".tool-versions"
+  | "pyproject.toml"
+  | "requirements"
+  | "uv.lock"
+  | "uv.toml";
+
+export interface ParsedVersionFile {
+  format: VersionFileFormat;
+  specifier: string;
+}
+
+export interface ResolveUvVersionOptions {
+  manifestFile?: string;
+  resolutionStrategy?: ResolutionStrategy;
+  version?: string;
+  versionFile?: string;
+  workingDirectory: string;
+}
+
+export interface VersionRequest {
+  format?: VersionFileFormat;
+  source: VersionSource;
+  sourcePath?: string;
+  specifier: string;
+}

src/version/uv-lock-file.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+import * as toml from "smol-toml";
+
+interface UvLockPackage {
+  name?: string;
+  version?: string;
+}
+
+interface UvLock {
+  package?: UvLockPackage[];
+}
+
+export function getUvVersionFromUvLock(filePath: string): string | undefined {
+  const fileContent = fs.readFileSync(filePath, "utf-8");
+  return getUvVersionFromUvLockContent(fileContent);
+}
+
+export function getUvVersionFromUvLockContent(
+  fileContent: string,
+): string | undefined {
+  const parsed = toml.parse(fileContent) as UvLock;
+  const uvPackage = parsed.package?.find((pkg) => pkg.name === "uv");
+  return uvPackage?.version;
+}

src/version/version-request-resolver.ts

@@ -0,0 +1,158 @@
+import * as path from "node:path";
+import * as log from "../utils/logging";
+import { getParsedVersionFile } from "./file-parser";
+import { normalizeVersionSpecifier } from "./specifier";
+import type {
+  ParsedVersionFile,
+  ResolveUvVersionOptions,
+  VersionRequest,
+} from "./types";
+
+export interface VersionRequestResolver {
+  resolve(context: VersionRequestContext): VersionRequest | undefined;
+}
+
+export class VersionRequestContext {
+  readonly version: string | undefined;
+  readonly versionFile: string | undefined;
+  readonly workingDirectory: string;
+
+  private readonly parsedFiles = new Map<
+    string,
+    ParsedVersionFile | undefined
+  >();
+
+  constructor(
+    version: string | undefined,
+    versionFile: string | undefined,
+    workingDirectory: string,
+  ) {
+    this.version = version;
+    this.versionFile = versionFile;
+    this.workingDirectory = workingDirectory;
+  }
+
+  getVersionFile(filePath: string): ParsedVersionFile | undefined {
+    const cachedResult = this.parsedFiles.get(filePath);
+    if (cachedResult !== undefined || this.parsedFiles.has(filePath)) {
+      return cachedResult;
+    }
+
+    const result = getParsedVersionFile(filePath);
+    this.parsedFiles.set(filePath, result);
+    return result;
+  }
+
+  getWorkspaceCandidates(): Array<{
+    source: "pyproject.toml" | "uv.toml";
+    sourcePath: string;
+  }> {
+    return [
+      {
+        source: "uv.toml",
+        sourcePath: path.join(this.workingDirectory, "uv.toml"),
+      },
+      {
+        source: "pyproject.toml",
+        sourcePath: path.join(this.workingDirectory, "pyproject.toml"),
+      },
+    ];
+  }
+}
+
+export class ExplicitInputVersionResolver implements VersionRequestResolver {
+  resolve(context: VersionRequestContext): VersionRequest | undefined {
+    if (context.version === undefined) {
+      return undefined;
+    }
+
+    return {
+      source: "input",
+      specifier: normalizeVersionSpecifier(context.version),
+    };
+  }
+}
+
+export class VersionFileVersionResolver implements VersionRequestResolver {
+  resolve(context: VersionRequestContext): VersionRequest | undefined {
+    if (context.versionFile === undefined) {
+      return undefined;
+    }
+
+    const versionFile = context.getVersionFile(context.versionFile);
+    if (versionFile === undefined) {
+      throw new Error(
+        `Could not determine uv version from file: ${context.versionFile}`,
+      );
+    }
+
+    return {
+      format: versionFile.format,
+      source: "version-file",
+      sourcePath: context.versionFile,
+      specifier: versionFile.specifier,
+    };
+  }
+}
+
+export class WorkspaceVersionResolver implements VersionRequestResolver {
+  resolve(context: VersionRequestContext): VersionRequest | undefined {
+    for (const candidate of context.getWorkspaceCandidates()) {
+      const versionFile = context.getVersionFile(candidate.sourcePath);
+      if (versionFile === undefined) {
+        continue;
+      }
+
+      return {
+        format: versionFile.format,
+        source: candidate.source,
+        sourcePath: candidate.sourcePath,
+        specifier: versionFile.specifier,
+      };
+    }
+
+    log.info(
+      "Could not determine uv version from uv.toml or pyproject.toml. Falling back to latest.",
+    );
+    return undefined;
+  }
+}
+
+export class LatestVersionResolver implements VersionRequestResolver {
+  resolve(): VersionRequest {
+    return {
+      source: "default",
+      specifier: "latest",
+    };
+  }
+}
+
+const VERSION_REQUEST_RESOLVERS: VersionRequestResolver[] = [
+  new ExplicitInputVersionResolver(),
+  new VersionFileVersionResolver(),
+  new WorkspaceVersionResolver(),
+  new LatestVersionResolver(),
+];
+
+export function resolveVersionRequest(
+  options: ResolveUvVersionOptions,
+): VersionRequest {
+  const context = new VersionRequestContext(
+    emptyToUndefined(options.version),
+    emptyToUndefined(options.versionFile),
+    options.workingDirectory,
+  );
+
+  for (const resolver of VERSION_REQUEST_RESOLVERS) {
+    const request = resolver.resolve(context);
+    if (request !== undefined) {
+      return request;
+    }
+  }
+
+  throw new Error("Could not resolve a requested uv version.");
+}
+
+function emptyToUndefined(value: string | undefined): string | undefined {
+  return value === undefined || value === "" ? undefined : value;
+}

tsconfig.json

@@ -1,12 +1,13 @@
 {
   "compilerOptions": {
-    "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */,
+    "esModuleInterop": true,
-    "module": "nodenext" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', or 'ESNext'. */,
+    "isolatedModules": true,
-    "noImplicitAny": true /* Raise error on expressions and declarations with an implied 'any' type. */,
+    "module": "esnext",
-    "outDir": "./lib" /* Redirect output structure to the directory. */,
+    "moduleResolution": "bundler",
-    "rootDir": "./src" /* Specify the root directory of input files. Use to control the output directory structure with --outDir. */,
+    "noImplicitAny": true,
-    "strict": true /* Enable all strict type-checking options. */,
+    "resolveJsonModule": true,
-    "target": "ES2024" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019' or 'ESNEXT'. */
+    "strict": true,
+    "target": "ES2022"
   },
-  "exclude": ["node_modules", "**/*.test.ts"]
+  "include": ["src/**/*.ts"]
 }