/configure:package-management

Check and configure modern package managers for optimal development experience.

Context

This command validates package manager configuration and migrates to modern tools.

Modern package manager preferences:

• Python: uv (replaces pip, poetry, pipenv, pyenv) – 10-100x faster
• JavaScript/TypeScript: bun (alternative to npm/yarn/pnpm) – significantly faster
• Rust: cargo (standard, no alternatives needed)
• Go: go mod (standard, no alternatives needed)

Version Checking

CRITICAL: Before configuring package managers, verify latest versions:

1. uv: Check docs.astral.sh/uv or GitHub releases
2. bun: Check bun.sh or GitHub releases
3. npm: Check npm docs for latest version
4. Rust/cargo: Check Rust releases

Use WebSearch or WebFetch to verify current versions before configuring package managers.

Workflow

Phase 1: Language Detection

Detect project languages and current package managers:

Phase 2: Current State Analysis

For each detected language, check configuration:

Python (uv):

• uv installed and on PATH
• pyproject.toml exists with [project] section
• uv.lock exists (lock file)
• Virtual environment in .venv/
• Python version pinned in pyproject.toml
• Dependency groups configured (dev, test, docs)
• Build system specified (hatchling, setuptools, etc.)

JavaScript/TypeScript (bun):

• bun installed and on PATH
• package.json exists
• bun.lockb exists (lock file)
• node_modules/ exists
• Scripts defined (dev, build, test, lint)
• Type definitions configured (TypeScript)
• Workspaces configured (if monorepo)

Phase 3: Compliance Report

Package Management Configuration Report
=======================================
Project: [name]
Languages: Python, TypeScript

Python:
  Package manager           uv 0.5.x                   [✅ MODERN | ⚠️ LEGACY pip]
  pyproject.toml            exists                     [✅ EXISTS | ❌ MISSING]
  Lock file                 uv.lock                    [✅ EXISTS | ⚠️ OUTDATED | ❌ MISSING]
  Virtual environment       .venv/                     [✅ EXISTS | ❌ MISSING]
  Python version            3.12                       [✅ PINNED | ⚠️ NOT PINNED]
  Dependency groups         dev, test, docs            [✅ CONFIGURED | ⚠️ MINIMAL]
  Build backend             hatchling                  [✅ CONFIGURED | ⚠️ MISSING]

JavaScript/TypeScript:
  Package manager           bun 1.1.x                  [✅ MODERN | ⚠️ npm | ⚠️ yarn]
  package.json              exists                     [✅ EXISTS | ❌ MISSING]
  Lock file                 bun.lockb                  [✅ EXISTS | ❌ MISSING]
  Scripts                   dev, build, test, lint     [✅ COMPLETE | ⚠️ INCOMPLETE]
  Type definitions          tsconfig.json              [✅ CONFIGURED | ⚠️ MISSING]
  Engine constraints        package.json engines       [✅ PINNED | ⚠️ NOT PINNED]

Overall: [X issues found]

Recommendations:
  - Migrate from pip to uv for faster installs
  - Add uv.lock to version control
  - Configure dependency groups in pyproject.toml
  - Migrate from npm to bun for better performance

Phase 4: Configuration (if –fix or user confirms)

Python with uv

Install uv:

# Via mise (recommended)
mise use uv@latest

# Or via curl
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via homebrew
brew install uv

Initialize project:

# New project
uv init my-project
cd my-project

# Existing project with requirements.txt
uv init
uv add -r requirements.txt
rm requirements.txt

# Existing project with poetry
uv init
# Copy dependencies from pyproject.toml [tool.poetry.dependencies]
# Then: uv add <deps>

Create pyproject.toml:

[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
readme = "README.md"
requires-python = ">=3.12"
license = { text = "MIT" }
authors = [
    { name = "Your Name", email = "you@example.com" }
]
dependencies = [
    # Production dependencies
]

[project.optional-dependencies]
dev = [
    "ruff>=0.8.0",
    "basedpyright>=1.22.0",
]
test = [
    "pytest>=8.0",
    "pytest-cov>=6.0",
    "pytest-asyncio>=0.24",
]
docs = [
    "mkdocs>=1.6",
    "mkdocs-material>=9.5",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    # Dev dependencies installed with `uv sync`
    "ruff>=0.8.0",
    "basedpyright>=1.22.0",
    "pytest>=8.0",
]

[tool.hatch.build.targets.wheel]
packages = ["src/my_project"]

Common uv commands:

# Install dependencies
uv sync

# Add production dependency
uv add httpx

# Add dev dependency
uv add --group dev pytest

# Run script
uv run python script.py
uv run pytest

# Create virtual environment
uv venv

# Pin Python version
uv python pin 3.12

# Update dependencies
uv lock --upgrade
uv sync

Add to .gitignore:

# Python
.venv/
__pycache__/
*.pyc
.pytest_cache/
.ruff_cache/
dist/
*.egg-info/

JavaScript/TypeScript with bun

Install bun:

# Via mise (recommended)
mise use bun@latest

# Or via curl
curl -fsSL https://bun.sh/install | bash

# Or via homebrew
brew install bun

Initialize project:

# New project
bun init

# Existing project - migrate from npm
rm -rf node_modules package-lock.json
bun install

# Existing project - migrate from yarn
rm -rf node_modules yarn.lock
bun install

# Existing project - migrate from pnpm
rm -rf node_modules pnpm-lock.yaml
bun install

Create/update package.json:

{
  "name": "my-project",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "bun run --watch src/index.ts",
    "build": "bun build src/index.ts --outdir dist",
    "test": "bun test",
    "lint": "biome check .",
    "lint:fix": "biome check --write .",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {},
  "devDependencies": {
    "@biomejs/biome": "^1.9.0",
    "@types/bun": "latest",
    "typescript": "^5.7.0"
  },
  "engines": {
    "bun": ">=1.1.0"
  }
}

TypeScript configuration (tsconfig.json):

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "types": ["bun-types"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Common bun commands:

# Install dependencies
bun install

# Add dependency
bun add zod

# Add dev dependency
bun add --dev @types/node

# Run script
bun run dev
bun run build

# Run TypeScript directly
bun src/index.ts

# Run tests
bun test

# Update dependencies
bun update

Add to .gitignore:

# JavaScript/TypeScript
node_modules/
dist/
.turbo/
*.tsbuildinfo

Phase 5: Migration Guides

pip/poetry → uv Migration

Step 1: Install uv

mise use uv@latest

Step 2: Initialize uv project

uv init

Step 3: Migrate dependencies

From requirements.txt:

uv add -r requirements.txt
rm requirements.txt

From poetry (pyproject.toml):

# Extract dependencies from [tool.poetry.dependencies]
# Add them with uv add
uv add httpx fastapi pydantic
uv add --group dev pytest ruff

Step 4: Remove old files

rm -f requirements.txt requirements-dev.txt
rm -f Pipfile Pipfile.lock
rm -f poetry.lock
# Update pyproject.toml to remove [tool.poetry] section

Step 5: Update CI/CD

# GitHub Actions
- name: Install uv
  uses: astral-sh/setup-uv@v4

- name: Install dependencies
  run: uv sync

- name: Run tests
  run: uv run pytest

npm/yarn/pnpm → bun Migration

Step 1: Install bun

mise use bun@latest

Step 2: Remove old lock files

rm -rf node_modules
rm -f package-lock.json yarn.lock pnpm-lock.yaml

Step 3: Install with bun

bun install

Step 4: Update scripts Replace npm/yarn/pnpm scripts with bun equivalents:

{
  "scripts": {
    "dev": "bun run --watch src/index.ts",
    "build": "bun build src/index.ts --outdir dist",
    "test": "bun test"
  }
}

Step 5: Update CI/CD

# GitHub Actions
- name: Setup Bun
  uses: oven-sh/setup-bun@v2

- name: Install dependencies
  run: bun install

- name: Run tests
  run: bun test

Phase 6: CI/CD Integration

GitHub Actions – uv:

- name: Install uv
  uses: astral-sh/setup-uv@v4
  with:
    enable-cache: true

- name: Set up Python
  run: uv python install

- name: Install dependencies
  run: uv sync --all-extras

- name: Run tests
  run: uv run pytest

GitHub Actions – bun:

- name: Setup Bun
  uses: oven-sh/setup-bun@v2
  with:
    bun-version: latest

- name: Install dependencies
  run: bun install --frozen-lockfile

- name: Run tests
  run: bun test

Phase 7: Standards Tracking

Update .project-standards.yaml:

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  package_management: "2025.1"
  python_package_manager: "uv"
  javascript_package_manager: "bun"
  lock_files_committed: true

Phase 8: Final Report

Package Management Configuration Complete
==========================================

Python:
  ✅ uv installed (0.5.x)
  ✅ pyproject.toml configured
  ✅ uv.lock created
  ✅ Dependency groups: dev, test, docs
  ✅ Python 3.12 pinned

JavaScript/TypeScript:
  ✅ bun installed (1.1.x)
  ✅ package.json updated
  ✅ bun.lockb created
  ✅ Scripts configured

Migration:
  ✅ poetry.lock removed
  ✅ package-lock.json removed
  ✅ CI/CD workflows updated

Next Steps:
  1. Verify dependencies install correctly:
     uv sync && bun install

  2. Run tests to ensure nothing broke:
     uv run pytest && bun test

  3. Commit lock files:
     git add uv.lock bun.lockb

Documentation: docs/PACKAGE_MANAGEMENT.md

Flags

Examples

# Check compliance and offer migrations
/configure:package-management

# Check only, no modifications
/configure:package-management --check-only

# Auto-migrate Python to uv
/configure:package-management --fix --manager uv

# Auto-migrate JavaScript to bun
/configure:package-management --fix --manager bun

Error Handling

• Multiple Python managers detected: Warn about conflict, suggest single source of truth
• Missing package manager: Offer to install via mise
• Invalid pyproject.toml: Report parse error, offer template
• Lock file conflicts: Warn about multiple lock files, suggest cleanup
• Workspace/monorepo: Detect and configure workspace settings

See Also

• /configure:linting – Configure linting tools (ruff, biome)
• /configure:formatting – Configure formatters
• /deps:install – Universal dependency installer
• /configure:all – Run all compliance checks
• uv documentation: https://docs.astral.sh/uv
• bun documentation: https://bun.sh/docs