dev-specialisms:init-local-tooling

What this skill does

# Local Tooling Initialization

Comprehensive setup for linting, formatting, type checking, testing, Git hooks, CI/CD, and publishing across TypeScript, Rust, and Python projects.

## When to Use This Skill

Use this skill when you need to:
- Initialize tooling for a new TypeScript/Rust/Python project
- Set up monorepo with Nx + pnpm workspaces
- Configure Git hooks with lefthook (conventional commits, pre-commit, pre-push)
- Add GitHub Actions for CI/CD
- Set up automated publishing to npm/crates.io/PyPI
- Configure version bumping and changelog generation with Changesets
- Migrate from Husky to lefthook
- Choose between ESLint+Prettier vs Biome for TypeScript

## Quick Start

### TypeScript Project

**Automated setup:**
```bash
./scripts/init_typescript.sh
```

**Choose tooling:**
- **Biome** (recommended) - Fast, all-in-one, modern
- **ESLint + Prettier** - Traditional, highly configurable

**What you get:**
- Linting and formatting
- TypeScript strict mode
- Vitest for testing
- Package.json scripts

→ **See:** [references/typescript.md](references/typescript.md)

### Rust Project

**Manual setup (opinionated configs in assets/):**
```bash
# Tools come with Rust
rustup component add rustfmt clippy

# Optional: Enhanced tooling
brew install cargo-nextest cargo-deny

# Copy configs from assets/configs/rust/
cp assets/configs/rust/rustfmt.toml .
cp assets/configs/rust/clippy.toml .
```

→ **See:** [references/rust.md](references/rust.md)

### Python Project

**Using uv (recommended):**
```bash
# Install uv
brew install uv

# Create project
uv init my-project
cd my-project

# Add dev dependencies
uv add --dev ruff mypy pytest

# Copy config from assets/
cp assets/configs/python/pyproject.toml .
```

→ **See:** [references/python.md](references/python.md)

### Monorepo Setup

**Create Nx + pnpm monorepo:**
```bash
./scripts/init_monorepo.sh
```

Or manually:
```bash
npx create-nx-workspace@latest my-monorepo
# Choose: pnpm + integrated monorepo
```

→ **See:** [references/monorepo.md](references/monorepo.md)

---

## Workflow Decision Tree

### 1. Choose Project Type

**Single Language Project**
→ Use language-specific init script or manual setup
→ See Quick Start above

**Monorepo (Multiple Packages)**
→ Set up Nx + pnpm workspaces
→ See [references/monorepo.md](references/monorepo.md)

### 2. Configure Git Hooks

**Automated setup:**
```bash
./scripts/setup_lefthook.sh
```

This configures:
- **commit-msg** - Conventional commits validation
- **pre-commit** - Format and lint staged files
- **pre-push** - Full validation (lint, type-check, test, build)

→ **See:** [references/git-hooks.md](references/git-hooks.md)

### 3. Set Up CI/CD

**Copy workflow templates:**
```bash
# Basic CI
cp assets/workflows/ci.yml .github/workflows/

# Language-specific workflows available in assets/
```

→ **See:** [references/ci-cd.md](references/ci-cd.md)

### 4. Configure Publishing (Optional)

**For npm packages:**
```bash
./scripts/setup_changesets.sh
```

Then copy publishing workflows from `assets/workflows/`.

→ **See:**
- [references/version-management.md](references/version-management.md)
- [references/publishing.md](references/publishing.md)

---

## Language-Specific Guides

### TypeScript/JavaScript

**Tooling options:**
- **Biome** - Fast, opinionated, all-in-one (recommended for new projects)
- **ESLint + Prettier** - Traditional, highly configurable (recommended for existing projects)

**Testing:**
- **Vitest** - Modern, fast, Vite-based (recommended)
- **Jest** - Established, widely used

**Key decisions:**
- Choose Biome for speed and simplicity
- Choose ESLint+Prettier for existing projects or specific plugins

→ **Full guide:** [references/typescript.md](references/typescript.md)

### Rust

**Built-in tools:**
- `rustfmt` - Code formatting
- `clippy` - Linting
- `cargo test` - Testing

**Enhanced tools:**
- `cargo-nextest` - Faster test runner
- `cargo-deny` - Dependency security
- `cargo-make` - Task runner

→ **Full guide:** [references/rust.md](references/rust.md)

### Python

**Modern stack (recommended):**
- **uv** - Fast package manager
- **ruff** - Fast linting + formatting (replaces black, isort, flake8)
- **mypy** - Type checking
- **pytest** - Testing

→ **Full guide:** [references/python.md](references/python.md)

---

## Git Hooks with lefthook

### Why lefthook?

- **Language-agnostic** - Works across TS, Rust, Python
- **Fast** - Parallel execution, written in Go
- **Simple** - Single YAML config
- **Better than Husky** - Faster, works across languages

### Setup

**Automated:**
```bash
./scripts/setup_lefthook.sh
```

**Manual:**
```bash
brew install lefthook
lefthook install
```

### Configuration Example

**lefthook.yml:**
```yaml
commit-msg:
  commands:
    commitlint:
      run: npx commitlint --edit {1}

pre-commit:
  parallel: true
  commands:
    format:
      glob: "*.{ts,rs,py}"
      run: format-staged-files {staged_files}
      stage_fixed: true

pre-push:
  commands:
    validate:
      run: ./scripts/validate_all.sh
```

→ **Full guide:** [references/git-hooks.md](references/git-hooks.md)

---

## Monorepo Management

### Nx + pnpm Workspaces

**Key principle:** Nx builds on top of pnpm, doesn't replace it.

- **pnpm workspaces** - Dependency management
- **Nx** - Task orchestration, caching, affected commands

### Benefits

- Run tasks only for affected packages
- Intelligent caching
- Parallel execution
- Supports multiple languages

### Common Commands

```bash
# Run target for all packages
nx run-many --target=build --all

# Run only for affected
nx affected --target=test

# Visualize dependencies
nx graph
```

→ **Full guide:** [references/monorepo.md](references/monorepo.md)

---

## Version Management & Publishing

### Changesets Workflow

**Recommended for monorepos and npm packages.**

1. **Add changeset:**
```bash
pnpm changeset
# Select packages, type (major/minor/patch), write summary
```

2. **Version packages:**
```bash
pnpm changeset version
# Updates package.json, generates CHANGELOG.md
```

3. **Publish:**
```bash
pnpm changeset publish
git push --follow-tags
```

### Automated Publishing

Use GitHub Actions to automate releases:

**Copy workflow:**
```bash
cp assets/workflows/publish-changesets.yml .github/workflows/
```

This creates "Version Packages" PR on main when changesets exist.

→ **See:**
- [references/version-management.md](references/version-management.md)
- [references/publishing.md](references/publishing.md)

---

## CI/CD Setup

### Match Local Validation

**Best practice:** Run same checks in CI as local pre-push hook.

**GitHub Actions templates:**
- `ci.yml` - Basic linting, testing, building
- `publish-npm.yml` - Automated npm publishing
- `publish-crates.yml` - Automated crates.io publishing
- `publish-pypi.yml` - Automated PyPI publishing

### Matrix Testing

Test across multiple versions:

```yaml
strategy:
  matrix:
    node-version: [18, 20, 21]
    os: [ubuntu-latest, macos-latest]
```

### Nx Monorepo CI

Use affected commands to only test changed packages:

```bash
nx affected --target=test
nx affected --target=build
```

→ **Full guide:** [references/ci-cd.md](references/ci-cd.md)

---

## Common Tasks

### Initialize TypeScript Project

**Automated:**
```bash
./scripts/init_typescript.sh --biome
# or
./scripts/init_typescript.sh --eslint-prettier
```

**Creates:**
- tsconfig.json (strict mode)
- Linting config (biome.json or eslint.config.js)
- Formatting config (.prettierrc.json if ESLint)
- Testing config (vitest.config.ts)
- Package.json scripts

### Set Up Git Hooks

```bash
./scripts/setup_lefthook.sh
```

**Configures:**
- Conventional commits validation
- Pre-commit: lint/format staged files
- Pre-push: full validation

### Configure Changesets

```bash
./scripts/setup_changesets.sh
```

**Sets up:**
- .changeset/ directory
- Package.json scripts
- Public access configuration

### Full Validation

```bash
./scripts/validate_all.sh
```

**Runs:**
- Format checking
- Li