Development Guide

September 4, 2025 · View on GitHub

Quick Start: Run pnpm install to install dependencies, then pnpm dev to start development.

Daily Development Workflow

🚀 Starting Development

# Start development
pnpm dev        # TypeScript watch mode
pnpm test:watch # Test watch mode

🔍 Quick Quality Checks

# Fast check before committing
pnpm quick-check  # typecheck + lint + test

# Full verification (like CI)
pnpm verify       # All quality gates including audit + format

🧪 Testing

# Watch mode (development)
pnpm test:watch

# Single run
pnpm test

# With coverage (80% minimum threshold enforced)
pnpm test:coverage

# Coverage in browser
pnpm coverage:open

📊 Coverage Requirements: This project enforces 80% minimum coverage for lines, branches, functions, and statements. The CI pipeline will fail if coverage drops below this threshold.

🏗️ Building

# Production build
pnpm build

# Watch build (rebuilds on file changes)
pnpm build:watch

Development Tools

📦 Available Scripts

Run pnpm help to see all available scripts, or check these key commands:

Command	Description	What it runs
`pnpm dev`	TypeScript watch mode	`tsc --watch`
`pnpm test`	Run tests once	`vitest run`
`pnpm test:watch`	Test watch mode	`vitest`
`pnpm test:coverage`	Tests with coverage report	`vitest run --coverage` (80% threshold)
`pnpm typecheck`	Type check only	`tsc --noEmit`
`pnpm lint`	Check linting	`eslint .`
`pnpm format`	Check formatting	`prettier --check .`
`pnpm verify`	Full verification (CI equivalent)	audit + typecheck + lint + format + test
`pnpm quick-check`	Fast quality check	typecheck + lint + test
`pnpm ci:local`	Simulate full CI locally	Complete CI pipeline simulation
`pnpm doctor`	Check environment health	Node/pnpm version check

IDE Setup

VS Code (Recommended)

The project includes VS Code configuration in .vscode/:

Auto-formatting on save
ESLint integration with auto-fix
TypeScript strict mode
Vitest integration
Debugging configuration

Recommended Extensions (auto-suggested):

ESLint
Prettier
Vitest Explorer
TypeScript Importer

Debugging

F5 - Debug Node.js app (builds first)
Ctrl+F5 - Debug current test file
Set breakpoints in .ts files (source maps enabled)

Code Quality

Type Safety

This project uses strict TypeScript with additional safety features:

// ✅ Good - explicit types
function processUser(user: User): Promise<UserResult> {
  return validateAndProcess(user);
}

// ❌ Avoid - implicit any
function processUser(user) {
  return user.something;
}

Testing Philosophy

Unit tests (.spec.ts) - Test functions in isolation
Property-based tests (.property.spec.ts) - Test invariants with fast-check

Test Templates Available:

tests/templates/unit-test.template.ts - Standard unit test structure
tests/templates/property-test.template.ts - Property-based test patterns

Documentation & Config Quality

Markdown linting with markdownlint-cli2 ensures consistent documentation
YAML validation with yamllint catches config file issues early
Run pnpm format:fix to automatically fix markdown and YAML formatting issues
Pre-commit hooks enforce these standards automatically

Code Organization

src/
├── index.ts           # Main entry point
├── logger.ts          # Structured logging
├── dev/               # Development utilities (debug, performance)
└── [your-modules]/    # Feature modules

tests/
├── *.spec.ts         # Unit tests
├── *.property.spec.ts # Property-based tests
├── helpers/          # Test utilities
└── templates/        # Test templates to copy

Performance & Debugging

Development Debug Tools

import { PerformanceTimer, timed, trace, devConsole } from './src/dev/debug-utils.js';

// Time operations
const timer = new PerformanceTimer('slow-operation');
await doSomething();
timer.checkpoint('phase-1');
await doSomethingElse();
timer.end();

// Auto-time methods with decorator
class MyService {
  @timed
  async processData(data: unknown[]) {
    // Method automatically timed in development
  }

  @trace
  criticalMethod() {
    // Method calls automatically logged in development
  }
}

// Enhanced console (development only)
devConsole.log(complexObject, 'debug-label');
devConsole.table(arrayData);
devConsole.time('operation', () => expensiveOperation());

Memory Monitoring

import { logMemoryUsage } from './src/dev/debug-utils.js';

// Log current memory usage (development only)
logMemoryUsage('before-operation');
await heavyOperation();
logMemoryUsage('after-operation');

CI/CD Integration

Local CI Simulation

Before pushing, run CI checks locally:

# Full CI simulation (slow, thorough)
pnpm ci:local

# Fast CI simulation (skip security scans)
pnpm ci:local:fast

# Quick commands
pnpm verify       # Full verification
pnpm quick-check  # Fast quality check

Pre-commit Hooks

What Runs on Every Commit

The project uses Husky to enforce quality checks before each commit. The precommit script runs:

Security audit (pnpm audit --audit-level critical) - Checks for critical vulnerabilities
Type check (pnpm typecheck) - Ensures TypeScript types are correct
Linting (pnpm lint) - ESLint checks
Workflow linting (pnpm lint:workflows) - GitHub Actions validation
Markdown linting (pnpm lint:markdown) - Documentation quality
YAML linting (pnpm lint:yaml) - Configuration file validation
Format check (pnpm format) - Prettier formatting verification
Tests (pnpm test) - All test suites must pass

Important: No Bypass Allowed

🔒 Security Feature: This project includes a Claude Code hook that blocks the --no-verify flag. You cannot bypass pre-commit checks with git commit --no-verify. This ensures all commits meet quality standards.

If you encounter issues:

# Fix formatting issues
pnpm format:fix

# Fix linting issues
pnpm lint:fix

# Run full verification to debug
pnpm verify

Troubleshooting

Common Issues

TypeScript errors after pulling changes:

pnpm reset  # Clean + reinstall dependencies

Tests failing randomly:

pnpm test:watch  # Check for shared state between tests

Slow development builds:

# Use incremental builds
pnpm dev  # TypeScript watch mode with incremental compilation

Memory issues during development:

# Monitor memory usage
node --max-old-space-size=4096 ./node_modules/.bin/vitest

Getting Help

Check documentation: All guides are in docs/
Run diagnostics: pnpm doctor
View available commands: Check package.json scripts or this documentation
Check CI logs: Compare local vs CI behavior with pnpm ci:local

Environment Variables

Development

# .env.local (not committed)
NODE_ENV=development
LOG_LEVEL=debug
DEBUG=myapp:*

Testing

NODE_ENV=test
LOG_LEVEL=silent  # Reduce noise in tests

Production

NODE_ENV=production
LOG_LEVEL=info
CORRELATION_ID=request-uuid  # For request tracing

Release Process

Creating a Release

Create a changeset for your changes:
```
pnpm changeset
```
Merge to main - This triggers the release workflow
Automatic release happens if changesets exist:
- Version bumps based on changesets
- CHANGELOG.md generation
- Git tags creation
- GitHub release creation
- Optional: npm publishing (if NPM_TOKEN configured)
- Optional: Docker publishing (if enabled)

Required Secrets for Releases

Secret	Required	Purpose
`RELEASE_TOKEN`	Recommended	GitHub PAT with repo/workflow scopes for protected branches
`NPM_TOKEN`	Optional	Required for npm publishing
`DOCKERHUB_USERNAME`	Optional	Required for Docker Hub publishing
`DOCKERHUB_TOKEN`	Optional	Required for Docker Hub publishing

Repository Variables

Variable	Purpose
`ENABLE_DOCKER_RELEASE`	Set to `true` to enable Docker builds
`ENABLE_DOCS_RELEASE`	Set to `true` to enable documentation deployment

Note: Without RELEASE_TOKEN, the workflow uses GITHUB_TOKEN but may fail on protected branches.

Next Steps

After setting up development:

Read the architecture: docs/architecture/decisions/*.md
Understand the process: docs/PROCESS.md
Set up monitoring: docs/OBSERVABILITY.md
Check troubleshooting: docs/TROUBLESHOOTING.md

Happy coding! 🚀