setup-uv/.github/copilot-instructions.md

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 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

npm install

Timing: ~20-30 seconds
Note: Always run this first after cloning or when package.json changes

2. Build TypeScript

npm run build

Timing: ~5-10 seconds
Purpose: Compiles TypeScript source to JavaScript in lib/ directory

3. Lint and Format Code

npm run check

Timing: ~2-5 seconds
Tool: Biome (replaces ESLint/Prettier)
Auto-fixes: Formatting, import organization, basic linting issues

4. Package for Distribution

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

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)

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.