@ruaruababa/vibe-kit 1.0.0

package/skills/uv-package-manager/resources/implementation-playbook.md

@@ -0,0 +1,830 @@
+# UV Package Manager Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+# UV Package Manager
+
+Comprehensive guide to using uv, an extremely fast Python package installer and resolver written in Rust, for modern Python project management and dependency workflows.
+
+## When to Use This Skill
+
+- Setting up new Python projects quickly
+- Managing Python dependencies faster than pip
+- Creating and managing virtual environments
+- Installing Python interpreters
+- Resolving dependency conflicts efficiently
+- Migrating from pip/pip-tools/poetry
+- Speeding up CI/CD pipelines
+- Managing monorepo Python projects
+- Working with lockfiles for reproducible builds
+- Optimizing Docker builds with Python dependencies
+
+## Core Concepts
+
+### 1. What is uv?
+- **Ultra-fast package installer**: 10-100x faster than pip
+- **Written in Rust**: Leverages Rust's performance
+- **Drop-in pip replacement**: Compatible with pip workflows
+- **Virtual environment manager**: Create and manage venvs
+- **Python installer**: Download and manage Python versions
+- **Resolver**: Advanced dependency resolution
+- **Lockfile support**: Reproducible installations
+
+### 2. Key Features
+- Blazing fast installation speeds
+- Disk space efficient with global cache
+- Compatible with pip, pip-tools, poetry
+- Comprehensive dependency resolution
+- Cross-platform support (Linux, macOS, Windows)
+- No Python required for installation
+- Built-in virtual environment support
+
+### 3. UV vs Traditional Tools
+- **vs pip**: 10-100x faster, better resolver
+- **vs pip-tools**: Faster, simpler, better UX
+- **vs poetry**: Faster, less opinionated, lighter
+- **vs conda**: Faster, Python-focused
+
+## Installation
+
+### Quick Install
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows (PowerShell)
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Using pip (if you already have Python)
+pip install uv
+
+# Using Homebrew (macOS)
+brew install uv
+
+# Using cargo (if you have Rust)
+cargo install --git https://github.com/astral-sh/uv uv
+```
+
+### Verify Installation
+
+```bash
+uv --version
+# uv 0.x.x
+```
+
+## Quick Start
+
+### Create a New Project
+
+```bash
+# Create new project with virtual environment
+uv init my-project
+cd my-project
+
+# Or create in current directory
+uv init .
+
+# Initialize creates:
+# - .python-version (Python version)
+# - pyproject.toml (project config)
+# - README.md
+# - .gitignore
+```
+
+### Install Dependencies
+
+```bash
+# Install packages (creates venv if needed)
+uv add requests pandas
+
+# Install dev dependencies
+uv add --dev pytest black ruff
+
+# Install from requirements.txt
+uv pip install -r requirements.txt
+
+# Install from pyproject.toml
+uv sync
+```
+
+## Virtual Environment Management
+
+### Pattern 1: Creating Virtual Environments
+
+```bash
+# Create virtual environment with uv
+uv venv
+
+# Create with specific Python version
+uv venv --python 3.12
+
+# Create with custom name
+uv venv my-env
+
+# Create with system site packages
+uv venv --system-site-packages
+
+# Specify location
+uv venv /path/to/venv
+```
+
+### Pattern 2: Activating Virtual Environments
+
+```bash
+# Linux/macOS
+source .venv/bin/activate
+
+# Windows (Command Prompt)
+.venv\Scripts\activate.bat
+
+# Windows (PowerShell)
+.venv\Scripts\Activate.ps1
+
+# Or use uv run (no activation needed)
+uv run python script.py
+uv run pytest
+```
+
+### Pattern 3: Using uv run
+
+```bash
+# Run Python script (auto-activates venv)
+uv run python app.py
+
+# Run installed CLI tool
+uv run black .
+uv run pytest
+
+# Run with specific Python version
+uv run --python 3.11 python script.py
+
+# Pass arguments
+uv run python script.py --arg value
+```
+
+## Package Management
+
+### Pattern 4: Adding Dependencies
+
+```bash
+# Add package (adds to pyproject.toml)
+uv add requests
+
+# Add with version constraint
+uv add "django>=4.0,<5.0"
+
+# Add multiple packages
+uv add numpy pandas matplotlib
+
+# Add dev dependency
+uv add --dev pytest pytest-cov
+
+# Add optional dependency group
+uv add --optional docs sphinx
+
+# Add from git
+uv add git+https://github.com/user/repo.git
+
+# Add from git with specific ref
+uv add git+https://github.com/user/repo.git@v1.0.0
+
+# Add from local path
+uv add ./local-package
+
+# Add editable local package
+uv add -e ./local-package
+```
+
+### Pattern 5: Removing Dependencies
+
+```bash
+# Remove package
+uv remove requests
+
+# Remove dev dependency
+uv remove --dev pytest
+
+# Remove multiple packages
+uv remove numpy pandas matplotlib
+```
+
+### Pattern 6: Upgrading Dependencies
+
+```bash
+# Upgrade specific package
+uv add --upgrade requests
+
+# Upgrade all packages
+uv sync --upgrade
+
+# Upgrade package to latest
+uv add --upgrade requests
+
+# Show what would be upgraded
+uv tree --outdated
+```
+
+### Pattern 7: Locking Dependencies
+
+```bash
+# Generate uv.lock file
+uv lock
+
+# Update lock file
+uv lock --upgrade
+
+# Lock without installing
+uv lock --no-install
+
+# Lock specific package
+uv lock --upgrade-package requests
+```
+
+## Python Version Management
+
+### Pattern 8: Installing Python Versions
+
+```bash
+# Install Python version
+uv python install 3.12
+
+# Install multiple versions
+uv python install 3.11 3.12 3.13
+
+# Install latest version
+uv python install
+
+# List installed versions
+uv python list
+
+# Find available versions
+uv python list --all-versions
+```
+
+### Pattern 9: Setting Python Version
+
+```bash
+# Set Python version for project
+uv python pin 3.12
+
+# This creates/updates .python-version file
+
+# Use specific Python version for command
+uv --python 3.11 run python script.py
+
+# Create venv with specific version
+uv venv --python 3.12
+```
+
+## Project Configuration
+
+### Pattern 10: pyproject.toml with uv
+
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+description = "My awesome project"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.31.0",
+    "pydantic>=2.0.0",
+    "click>=8.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+]
+docs = [
+    "sphinx>=7.0.0",
+    "sphinx-rtd-theme>=1.3.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+dev-dependencies = [
+    # Additional dev dependencies managed by uv
+]
+
+[tool.uv.sources]
+# Custom package sources
+my-package = { git = "https://github.com/user/repo.git" }
+```
+
+### Pattern 11: Using uv with Existing Projects
+
+```bash
+# Migrate from requirements.txt
+uv add -r requirements.txt
+
+# Migrate from poetry
+# Already have pyproject.toml, just use:
+uv sync
+
+# Export to requirements.txt
+uv pip freeze > requirements.txt
+
+# Export with hashes
+uv pip freeze --require-hashes > requirements.txt
+```
+
+## Advanced Workflows
+
+### Pattern 12: Monorepo Support
+
+```bash
+# Project structure
+# monorepo/
+#   packages/
+#     package-a/
+#       pyproject.toml
+#     package-b/
+#       pyproject.toml
+#   pyproject.toml (root)
+
+# Root pyproject.toml
+[tool.uv.workspace]
+members = ["packages/*"]
+
+# Install all workspace packages
+uv sync
+
+# Add workspace dependency
+uv add --path ./packages/package-a
+```
+
+### Pattern 13: CI/CD Integration
+
+```yaml
+# .github/workflows/test.yml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Run linting
+        run: |
+          uv run ruff check .
+          uv run black --check .
+```
+
+### Pattern 14: Docker Integration
+
+```dockerfile
+# Dockerfile
+FROM python:3.12-slim
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Set working directory
+WORKDIR /app
+
+# Copy dependency files
+COPY pyproject.toml uv.lock ./
+
+# Install dependencies
+RUN uv sync --frozen --no-dev
+
+# Copy application code
+COPY . .
+
+# Run application
+CMD ["uv", "run", "python", "app.py"]
+```
+
+**Optimized multi-stage build:**
+
+```dockerfile
+# Multi-stage Dockerfile
+FROM python:3.12-slim AS builder
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Install dependencies to venv
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-editable
+
+# Runtime stage
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Copy venv from builder
+COPY --from=builder /app/.venv .venv
+COPY . .
+
+# Use venv
+ENV PATH="/app/.venv/bin:$PATH"
+
+CMD ["python", "app.py"]
+```
+
+### Pattern 15: Lockfile Workflows
+
+```bash
+# Create lockfile (uv.lock)
+uv lock
+
+# Install from lockfile (exact versions)
+uv sync --frozen
+
+# Update lockfile without installing
+uv lock --no-install
+
+# Upgrade specific package in lock
+uv lock --upgrade-package requests
+
+# Check if lockfile is up to date
+uv lock --check
+
+# Export lockfile to requirements.txt
+uv export --format requirements-txt > requirements.txt
+
+# Export with hashes for security
+uv export --format requirements-txt --hash > requirements.txt
+```
+
+## Performance Optimization
+
+### Pattern 16: Using Global Cache
+
+```bash
+# UV automatically uses global cache at:
+# Linux: ~/.cache/uv
+# macOS: ~/Library/Caches/uv
+# Windows: %LOCALAPPDATA%\uv\cache
+
+# Clear cache
+uv cache clean
+
+# Check cache size
+uv cache dir
+```
+
+### Pattern 17: Parallel Installation
+
+```bash
+# UV installs packages in parallel by default
+
+# Control parallelism
+uv pip install --jobs 4 package1 package2
+
+# No parallel (sequential)
+uv pip install --jobs 1 package
+```
+
+### Pattern 18: Offline Mode
+
+```bash
+# Install from cache only (no network)
+uv pip install --offline package
+
+# Sync from lockfile offline
+uv sync --frozen --offline
+```
+
+## Comparison with Other Tools
+
+### uv vs pip
+
+```bash
+# pip
+python -m venv .venv
+source .venv/bin/activate
+pip install requests pandas numpy
+# ~30 seconds
+
+# uv
+uv venv
+uv add requests pandas numpy
+# ~2 seconds (10-15x faster)
+```
+
+### uv vs poetry
+
+```bash
+# poetry
+poetry init
+poetry add requests pandas
+poetry install
+# ~20 seconds
+
+# uv
+uv init
+uv add requests pandas
+uv sync
+# ~3 seconds (6-7x faster)
+```
+
+### uv vs pip-tools
+
+```bash
+# pip-tools
+pip-compile requirements.in
+pip-sync requirements.txt
+# ~15 seconds
+
+# uv
+uv lock
+uv sync --frozen
+# ~2 seconds (7-8x faster)
+```
+
+## Common Workflows
+
+### Pattern 19: Starting a New Project
+
+```bash
+# Complete workflow
+uv init my-project
+cd my-project
+
+# Set Python version
+uv python pin 3.12
+
+# Add dependencies
+uv add fastapi uvicorn pydantic
+
+# Add dev dependencies
+uv add --dev pytest black ruff mypy
+
+# Create structure
+mkdir -p src/my_project tests
+
+# Run tests
+uv run pytest
+
+# Format code
+uv run black .
+uv run ruff check .
+```
+
+### Pattern 20: Maintaining Existing Project
+
+```bash
+# Clone repository
+git clone https://github.com/user/project.git
+cd project
+
+# Install dependencies (creates venv automatically)
+uv sync
+
+# Install with dev dependencies
+uv sync --all-extras
+
+# Update dependencies
+uv lock --upgrade
+
+# Run application
+uv run python app.py
+
+# Run tests
+uv run pytest
+
+# Add new dependency
+uv add new-package
+
+# Commit updated files
+git add pyproject.toml uv.lock
+git commit -m "Add new-package dependency"
+```
+
+## Tool Integration
+
+### Pattern 21: Pre-commit Hooks
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: uv-lock
+        name: uv lock
+        entry: uv lock
+        language: system
+        pass_filenames: false
+
+      - id: ruff
+        name: ruff
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+
+      - id: black
+        name: black
+        entry: uv run black
+        language: system
+        types: [python]
+```
+
+### Pattern 22: VS Code Integration
+
+```json
+// .vscode/settings.json
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.terminal.activateEnvironment": true,
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": ["-v"],
+  "python.linting.enabled": true,
+  "python.formatting.provider": "black",
+  "[python]": {
+    "editor.defaultFormatter": "ms-python.black-formatter",
+    "editor.formatOnSave": true
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+```bash
+# Issue: uv not found
+# Solution: Add to PATH or reinstall
+echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
+
+# Issue: Wrong Python version
+# Solution: Pin version explicitly
+uv python pin 3.12
+uv venv --python 3.12
+
+# Issue: Dependency conflict
+# Solution: Check resolution
+uv lock --verbose
+
+# Issue: Cache issues
+# Solution: Clear cache
+uv cache clean
+
+# Issue: Lockfile out of sync
+# Solution: Regenerate
+uv lock --upgrade
+```
+
+## Best Practices
+
+### Project Setup
+
+1. **Always use lockfiles** for reproducibility
+2. **Pin Python version** with .python-version
+3. **Separate dev dependencies** from production
+4. **Use uv run** instead of activating venv
+5. **Commit uv.lock** to version control
+6. **Use --frozen in CI** for consistent builds
+7. **Leverage global cache** for speed
+8. **Use workspace** for monorepos
+9. **Export requirements.txt** for compatibility
+10. **Keep uv updated** for latest features
+
+### Performance Tips
+
+```bash
+# Use frozen installs in CI
+uv sync --frozen
+
+# Use offline mode when possible
+uv sync --offline
+
+# Parallel operations (automatic)
+# uv does this by default
+
+# Reuse cache across environments
+# uv shares cache globally
+
+# Use lockfiles to skip resolution
+uv sync --frozen  # skips resolution
+```
+
+## Migration Guide
+
+### From pip + requirements.txt
+
+```bash
+# Before
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# After
+uv venv
+uv pip install -r requirements.txt
+# Or better:
+uv init
+uv add -r requirements.txt
+```
+
+### From Poetry
+
+```bash
+# Before
+poetry install
+poetry add requests
+
+# After
+uv sync
+uv add requests
+
+# Keep existing pyproject.toml
+# uv reads [project] and [tool.poetry] sections
+```
+
+### From pip-tools
+
+```bash
+# Before
+pip-compile requirements.in
+pip-sync requirements.txt
+
+# After
+uv lock
+uv sync --frozen
+```
+
+## Command Reference
+
+### Essential Commands
+
+```bash
+# Project management
+uv init [PATH]              # Initialize project
+uv add PACKAGE              # Add dependency
+uv remove PACKAGE           # Remove dependency
+uv sync                     # Install dependencies
+uv lock                     # Create/update lockfile
+
+# Virtual environments
+uv venv [PATH]              # Create venv
+uv run COMMAND              # Run in venv
+
+# Python management
+uv python install VERSION   # Install Python
+uv python list              # List installed Pythons
+uv python pin VERSION       # Pin Python version
+
+# Package installation (pip-compatible)
+uv pip install PACKAGE      # Install package
+uv pip uninstall PACKAGE    # Uninstall package
+uv pip freeze               # List installed
+uv pip list                 # List packages
+
+# Utility
+uv cache clean              # Clear cache
+uv cache dir                # Show cache location
+uv --version                # Show version
+```
+
+## Resources
+
+- **Official documentation**: https://docs.astral.sh/uv/
+- **GitHub repository**: https://github.com/astral-sh/uv
+- **Astral blog**: https://astral.sh/blog
+- **Migration guides**: https://docs.astral.sh/uv/guides/
+- **Comparison with other tools**: https://docs.astral.sh/uv/pip/compatibility/
+
+## Best Practices Summary
+
+1. **Use uv for all new projects** - Start with `uv init`
+2. **Commit lockfiles** - Ensure reproducible builds
+3. **Pin Python versions** - Use .python-version
+4. **Use uv run** - Avoid manual venv activation
+5. **Leverage caching** - Let uv manage global cache
+6. **Use --frozen in CI** - Exact reproduction
+7. **Keep uv updated** - Fast-moving project
+8. **Use workspaces** - For monorepo projects
+9. **Export for compatibility** - Generate requirements.txt when needed
+10. **Read the docs** - uv is feature-rich and evolving