Development Setup

Step-by-step instructions to get the pair monorepo running locally.

Prerequisites

Clone and install

git clone https://github.com/foomakers/pair.git
cd pair
pnpm install

pnpm install also sets up Husky git hooks automatically.

Running the dev server

Use pnpm --filter to run commands in a specific package:

# Documentation site
pnpm --filter @pair/website dev
 
# CLI tool
pnpm --filter @pair/pair-cli dev

Running tests

Tests use Vitest, orchestrated by Turborepo:

# All tests across the monorepo
pnpm test
 
# Single package
pnpm --filter @pair/pair-cli test
pnpm --filter @pair/content-ops test
 
# Single test by name
pnpm vitest run -t "test name"
 
# With coverage
pnpm test:coverage
 
# Playwright E2E tests (builds + starts Next.js)
pnpm --filter @pair/website e2e
 
# CLI smoke tests (e2e release process)
pnpm smoke-tests

Testing conventions

• In-memory test doubles over mocks (e.g., InMemoryFileSystemService instead of mocking fs).
• 1:1 mapping between source modules and test files.
• TDD discipline: RED (failing test) → GREEN (minimal implementation) → REFACTOR.

Quality gate

Before committing, always run:

pnpm quality-gate

This runs (in order): ts:check, test, lint, prettier:fix, mdlint:fix, hygiene:check, docs:staleness.

Gate registry

Git hooks (Husky)

Husky is configured to run checks automatically:

• Pre-commit — Linting and formatting checks.
• Pre-push — Tests run before pushing.

Troubleshooting hooks

Common commands

pnpm install              # Install all dependencies
pnpm quality-gate         # Full quality check
pnpm build                # Build all packages
pnpm test                 # Run all tests
pnpm lint                 # Lint all packages
pnpm lint:fix             # Auto-fix linting issues
pnpm ts:check             # Type-check all TypeScript
pnpm prettier:check       # Check formatting
pnpm prettier:fix         # Auto-format code
pnpm clean                # Clean build artifacts and caches

Dependency management

Shared dependency versions are managed via the pnpm catalog in pnpm-workspace.yaml:

pnpm sync-deps            # Update all dependencies recursively
pnpm deps:outdated        # Show outdated packages
pnpm catalog:update       # Update pnpm catalog
pnpm catalog:check        # Show catalog contents

When adding a new shared dependency, add it to the catalog first.

Changesets

We use @changesets/cli for version management. When your change affects a published package, create a changeset:

pnpm exec changeset add

Select the affected package(s) and bump type (patch/minor/major). Commit the .changeset/*.md file with your PR.

See the Release Process for the full workflow.

Platform notes

• macOS / Linux — Fully supported. All commands work as documented.
• Windows — Use WSL2 or Git Bash. Native Windows may have issues with symlinks (skills distribution falls back to copy mode).