Development Setup

This guide will help you set up your development environment for contributing to Phantom.

Prerequisites

Required Software

• Node.js v22.0.0 or higher

  • Check version: node --version
  • Install from nodejs.org or use a version manager like nvm

• pnpm v10.8.1 or higher (recommended)

  • Install: npm install -g pnpm
  • Or use corepack: corepack enable pnpm

• Git (with worktree support)

  • Check version: git --version
  • Worktree support requires Git 2.5.0+

Optional Tools

• Visual Studio Code - Recommended IDE with TypeScript support
• GitHub CLI - For easier PR and issue management

Setting Up the Repository

1. Fork and Clone

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/phantom.git
cd phantom

2. Install Dependencies

# Using pnpm (recommended)
pnpm install

# Or using npm
npm install

3. Verify Installation

# Run the CLI from source
pnpm start

# Run tests
pnpm test

# Run all quality checks
pnpm ready

Development Workflow

Available Scripts

Source: package.json#L12-L20

Script	Description	Command
start	Run CLI from source	pnpm start
build	Build the project	pnpm build
test	Run unit tests	pnpm test
lint	Check code quality	pnpm lint
fix	Auto-fix code issues	pnpm fix
typecheck	Check TypeScript types	pnpm typecheck
ready	Run all checks	pnpm ready

Before Committing

Always run the following command to ensure your code meets quality standards:

pnpm ready

This runs:

1. Code formatting and auto-fix (pnpm fix)
2. TypeScript type checking (pnpm typecheck)
3. Unit tests (pnpm test)

IDE Setup

Visual Studio Code

The project includes VS Code configuration. Install recommended extensions:

1. TypeScript - Built-in TypeScript support
2. Biome - For linting and formatting

TypeScript Configuration

Source: tsconfig.json

The project uses:

• TypeScript 5.8+ with native preview features
• ES2023 target with ES modules
• Strict type checking enabled
• Node.js module resolution

Project Structure

phantom/
├── src/                    # Source code
│   ├── bin/               # Entry points
│   ├── cli/               # CLI layer
│   │   ├── handlers/      # Command handlers
│   │   └── output.ts      # Output formatting
│   └── core/              # Business logic
│       ├── worktree/      # Worktree operations
│       ├── git/           # Git operations
│       └── process/       # Process utilities
├── dist/                  # Built output (git-ignored)
├── package.json           # Project configuration
├── tsconfig.json         # TypeScript configuration
├── biome.json           # Code quality configuration
└── build.ts             # Build script

Development Guidelines

Code Style

Source: biome.json

• Formatter: Biome with specific rules
  • Indent style: Tab
  • Quote style: Double quotes
  • Semicolons: Always
• Linter: Recommended rules with some customizations
• No code comments - Write self-documenting code

Architecture Principles

Source: CLAUDE.md#L26-L31

• Single Responsibility: Each module has one clear purpose
• Separation of Concerns: CLI and core logic are separated
• Testability: Core modules are framework-agnostic
• No Duplication: Common operations are centralized

Troubleshooting

Common Issues

1. Node.js Version Error

   • Ensure you have Node.js v22+
   • Use nvm to manage Node versions

2. pnpm Not Found

   • Install globally: npm install -g pnpm
   • Or enable corepack: corepack enable pnpm

3. TypeScript Errors

   • Run pnpm typecheck to see detailed errors
   • Ensure your IDE uses the project's TypeScript version

4. Test Failures

   • Run pnpm test to see failing tests
   • Check that you're using Node.js v22+

Next Steps

• Read the Quick Start Guide to understand basic usage
• Review Architecture Overview to understand the system design
• Check Core Concepts for terminology and concepts

Contributing

1. Create a feature branch
2. Make your changes
3. Run pnpm ready to ensure quality
4. Submit a pull request

All contributions must:

• Be written in English
• Follow existing code patterns
• Include tests for new functionality
• Pass all quality checks