Contributing to Poltergeist

September 4, 2026 · View on GitHub

Thank you for your interest in contributing to Poltergeist! This guide covers both Node.js CLI and macOS app development.

🚀 Getting Started

Prerequisites

Node.js 24+ and pnpm 11 for CLI development
Xcode 15+ with Command Line Tools for macOS app development
Watchman installed (brew install watchman)
SwiftLint and swift-format for Swift code quality (brew install swiftlint swift-format)

Development Setup

# Clone the repository
git clone https://github.com/steipete/poltergeist.git
cd poltergeist

# Install CLI dependencies
pnpm install

# Build CLI
pnpm run build

# Verify setup
pnpm test

For macOS app development:

# Navigate to macOS app
cd apps/mac

# Open in Xcode
open Poltergeist.xcodeproj

# Or build from command line
xcodebuild -project Poltergeist.xcodeproj -scheme Poltergeist build

📝 Development Guidelines

Code Style & Quality

We prioritize code quality and proper refactoring over speed. All contributions must meet these standards:

Node.js/TypeScript Standards

Type Safety First: Use proper TypeScript types, never any or workarounds
Modern JavaScript: ES2022+ features, async/await over promises
Functional Style: Prefer immutable operations and pure functions
Error Handling: Comprehensive error handling with proper typing

Swift Standards

Swift 6: Strict concurrency checking enabled
Modern Swift: Use latest language features and best practices
Memory Safety: Proper @MainActor usage and concurrency annotations
Architecture: Clean separation of concerns with proper abstractions

Code Quality Checks

Before submitting any PR, ensure all quality checks pass:

CLI/Node.js Checks

pnpm run build         # TypeScript compilation
pnpm test              # Test suite
pnpm run lint          # Oxfmt formatting and Oxlint linting
pnpm run typecheck     # Type validation
pnpm run format:check  # Code formatting

macOS App Checks

cd apps/mac
./scripts/lint.sh      # SwiftLint validation
./scripts/format.sh    # swift-format fixes
xcodebuild -project Poltergeist.xcodeproj -scheme Poltergeist build

No Quick Fixes Policy

We follow a "No Quick Fixes" policy:

❌ No ignoring of linting errors or warnings
❌ No @ts-ignore or similar workarounds
❌ No // swiftlint:disable unless absolutely necessary
❌ No band-aid solutions that don't address root causes
✅ Proper refactoring and type-safe solutions
✅ Clean code that removes unused imports and dead code
✅ Quality over speed in implementation

🏗️ Architecture Overview

CLI Architecture (Node.js/TypeScript)

src/
├── cli.ts              # Command line interface entry point
├── builders/           # Target-specific build implementations
│   ├── base-builder.ts # Abstract base class for all builders
│   ├── executable-builder.ts
│   ├── app-bundle-builder.ts
│   └── index.ts
├── utils/              # Utility modules
│   ├── filesystem.ts   # File system operations
│   ├── process-manager.ts
│   └── config-manager.ts
├── poltergeist.ts      # Core application logic
├── state.ts            # State management system
├── build-queue.ts      # Smart build queue management
├── priority-engine.ts  # Intelligent priority scoring
└── watchman.ts         # Watchman file watching integration

Key principles:

Builder Pattern: Each target type has a dedicated builder
State Management: Unified state system with atomic operations
Queue Management: Intelligent build scheduling and deduplication
Watchman Integration: Efficient file watching with smart exclusions

macOS App Architecture (Swift)

Poltergeist/
├── PoltergeistApp.swift       # App entry point
├── Models/                    # Data models
│   ├── Project.swift         # Project and target state models
│   └── Preferences.swift     # User preferences
├── Services/                  # Business logic services
│   ├── ProjectMonitor.swift  # Core monitoring service
│   ├── NotificationManager.swift
│   ├── FileWatcher.swift
│   └── IconLoader.swift
├── Features/                  # UI components
│   ├── StatusBarController.swift
│   ├── StatusBarMenuView.swift
│   └── SettingsView.swift
└── Utils/                     # Utility extensions
    ├── NSMenuItem+Extensions.swift
    └── VisualEffectView.swift

Key principles:

MVVM Architecture: Clear separation of UI and business logic
SwiftUI + AppKit: Modern UI with legacy integration where needed
Actor-based Concurrency: Proper @MainActor usage for UI updates
Service-Oriented: Core functionality in dedicated service classes

🔄 Development Workflow

1. Branch Strategy

main: Production-ready code only
feature/: New features (feature/smart-notifications)
fix/: Bug fixes (fix/build-queue-deadlock)
refactor/: Code improvements (refactor/state-management)

2. Commit Message Format

type: Brief description (50 chars max)

Detailed explanation of what and why, not how.
Reference issues: Fixes #123, Closes #456

Breaking changes should be clearly noted.

Types: feat, fix, refactor, test, docs, ci, chore

3. Pull Request Process

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes
- Follow code style guidelines
- Add/update tests for new functionality
- Update documentation as needed

Quality Checks

# CLI checks
pnpm run build && pnpm test --run && pnpm run lint && pnpm run typecheck

# macOS app checks (if applicable)
cd apps/mac && ./scripts/lint.sh && ./scripts/format.sh

Commit and Push

git add .
git commit -m "feat: Add intelligent build prioritization"
git push origin feature/your-feature-name

Create Pull Request
- Clear title and description
- Reference related issues
- Include testing instructions
- Screenshots for UI changes

🧪 Testing Guidelines

CLI Testing

Unit Tests: Test individual functions and classes
Integration Tests: Test component interactions
E2E Tests: Test complete workflows
Performance Tests: Ensure scalability

# Run specific test files
pnpm test --run priority-engine.test.ts

# Run with coverage
pnpm run test:coverage

# Watch mode for development
pnpm test --watch

macOS App Testing

Unit Tests: Test business logic and models
UI Tests: Test user interface interactions
Integration Tests: Test CLI/app communication

cd apps/mac
xcodebuild test -project Poltergeist.xcodeproj -scheme Poltergeist

Test Requirements

New Features: Must include comprehensive tests
Bug Fixes: Must include regression tests
Coverage: Maintain >80% test coverage
Performance: No degradation in existing benchmarks

📚 Documentation Standards

Code Documentation

TypeScript: JSDoc comments for public APIs
Swift: Swift documentation comments for public interfaces
README Updates: Keep installation and usage instructions current
Changelog: Document all user-facing changes

Documentation Requirements

New Features: Update README with usage examples
API Changes: Update API documentation
Configuration: Document new config options
Breaking Changes: Migration guides required

🔍 Debugging & Troubleshooting

CLI Debugging

# Enable debug logging
POLTERGEIST_LOG_LEVEL=debug poltergeist haunt

# Verbose output
poltergeist haunt --verbose

# Check state files
ls -la /tmp/poltergeist/
cat /tmp/poltergeist/your-project-hash-target.state

macOS App Debugging

# Console logs
log stream --predicate 'subsystem BEGINSWITH "com.poltergeist"'

# Xcode debugging
# Set breakpoints and use Xcode's debugger
# Enable scheme debugging options for detailed output