Modern Toolchain Standard

Modern Toolchain Standard & Package Management Policy

This standard defines the mandatory tooling, package managers, formatters, and test runners across all services and repositories. AI agents and developers must strictly adhere to these specifications to guarantee deterministic, high-performance, and reproducible builds.

1. Node.js & TypeScript Ecosystem

A. Mandatory Package Manager: pnpm

• Strict Rule: Always use pnpm. Never execute npm install, npm add, npm update, yarn, or bun install for dependency management in standard repositories unless explicitly overriding for upstream compatibility.
• Lockfile Enforcement:
  • Only pnpm-lock.yaml is tracked in version control.
  • Committing package-lock.json or yarn.lock is strictly prohibited and flagged as a lint/quality failure.
• Standard Commands:

  # Installing dependencies
  pnpm install
  
  # Adding dependencies
  pnpm add <package-name>
  pnpm add -D <dev-package-name>
  
  # Updating dependencies safely
  pnpm up
  pnpm up --latest
  
  # Running scripts
  pnpm run build
  pnpm run dev
  pnpm run test
  

B. Formatting & Linting: Biome

• Preference: Prefer Biome over legacy ESLint + Prettier combinations where supported.
• Standard Commands:

  pnpm biome check --write .
  pnpm biome lint .
  pnpm biome format --write .
  

C. Unit & Integration Testing: Vitest

• Preference: Prefer Vitest over legacy Jest for ESM-native speed and Vite/Turbopack compatibility.
• Standard Commands:

  pnpm vitest run
  

2. Python Ecosystem

A. Mandatory Package & Environment Manager: uv

• Strict Rule: Always use uv. Never execute bare pip install, python -m venv, poetry, or pip-tools.
• Virtual Environment Management:
  • Virtual environments are managed with uv venv.
  • Commands and scripts are executed inside the environment using uv run.
• Standard Commands:

  # Create virtual environment
  uv venv
  
  # Synchronize dependencies from lockfile
  uv sync
  
  # Add or update dependencies
  uv add <package-name>
  uv add --dev <dev-package-name>
  uv lock --upgrade
  
  # Running test suites and tools
  uv run pytest
  uv run ruff check .
  uv run ruff format .
  uv run mypy .
  

• Lockfile Enforcement:
  • Track uv.lock and pyproject.toml in version control for deterministic multi-platform resolution.

3. Go Ecosystem

• Compiler & Toolchain: Modern Go (Go 1.24+ standard library).
• Code Formatting: Native gofmt enforced on all staged .go files.
• Static Analysis: go vet ./... required before committing.
• Concurrency & Race Detection: Run tests with race instrumentation enabled:

  go test -race -v ./...
  

• Dependency Hygiene: Always run go mod tidy after dependency updates.

4. Pre-Commit Validation Gate Integration

Every repository's pre-commit validation gate (.githooks/pre-commit) must verify:

1. No sensitive credential leaks (.env, private keys, bearer tokens).
2. Appropriate modern package managers are invoked (pnpm for frontend/Node, uv for Python).
3. No foreign lockfiles (package-lock.json in a pnpm project) are committed.