Technology Stack

This document details the languages, frameworks, tools, and technologies used in Phantom.

Core Technologies

Language & Runtime

TypeScript

Source: package.json#L48

• Version: 5.8.0-dev (using native preview features)
• Target: ES2023
• Module System: ES Modules (ESM)
• Type Checking: Strict mode enabled

Key TypeScript features used:

• Strict null checks
• Type inference
• Union types for Result pattern
• Module augmentation for testing

Node.js

Source: package.json#L36

• Minimum Version: v22.0.0
• Features Used:
  • Native ES modules
  • Built-in test runner
  • Native module mocking
  • Child process management

Zero Runtime Dependencies

Source: package.json#L50

Phantom has no runtime dependencies, which provides:

• Faster installation
• Smaller package size
• Better security posture
• Simplified deployment

Build Tools

esbuild

Source: build.ts

• Purpose: Fast JavaScript/TypeScript bundler
• Version: 0.24.2
• Usage: Building the CLI executable

Build configuration:

{
  bundle: true,
  minify: false,  // Keep readable for debugging
  platform: "node",
  target: "node22",
  format: "esm",
  sourcemap: true
}

TypeScript Native Preview

Source: package.json#L46

• Package: @typescript/native-preview
• Purpose: Access to experimental TypeScript features
• Benefits: Latest language features and performance improvements

Code Quality Tools

Biome

Source: biome.json

• Version: 1.9.4
• Purpose: Fast formatter and linter
• Replaces: ESLint + Prettier

Configuration highlights:

{
  "formatter": {
    "indentStyle": "tab",
    "lineWidth": 100,
    "quoteStyle": "double"
  },
  "linter": {
    "rules": {
      "recommended": true,
      "noPrototypeBuiltins": "off",
      "noUselessElse": "off"
    }
  }
}

Benefits over traditional tools:

• 10-20x faster than ESLint
• Single tool for formatting and linting
• Written in Rust for performance
• Excellent TypeScript support

Package Management

pnpm

Source: package.json#L37

• Version: 10.8.1 or higher
• Purpose: Fast, disk space efficient package manager

Benefits:

• Efficient dependency storage
• Strict dependency resolution
• Faster installations
• Better monorepo support

Development Dependencies

Type Definitions

Source: package.json#L45

• @types/node: v22.10.2
  • Node.js API type definitions
  • Enables TypeScript IntelliSense

Testing Tools

Built-in Node.js test runner:

• No external test framework
• Native module mocking
• Built-in assertions
• Parallel test execution

Version Control & Collaboration

Git

• Version: 2.5.0+ (for worktree support)
• Usage: Core functionality relies on Git CLI
• Features Used:
  • Worktree management
  • Branch operations
  • Repository information

GitHub

• Issue Tracking: GitHub Issues
• Code Review: GitHub Pull Requests
• CI/CD: GitHub Actions
• Package Registry: npm via GitHub

CI/CD Pipeline

GitHub Actions

Source: .github/workflows/

Workflow configuration:

• Node.js Versions: v22, v24
• Operating Systems: Linux, macOS, Windows
• Quality Checks:
  • Linting (Biome)
  • Type checking (TypeScript)
  • Unit tests (Node.js test runner)

Architecture Patterns

Functional Programming

• Result type for error handling
• Pure functions where possible
• Immutable data structures
• Function composition

Object-Oriented Design

• SOLID principles
• Single responsibility per module
• Dependency injection patterns
• Interface segregation

Design Patterns Used

1. Result Pattern: Explicit error handling
2. Builder Pattern: Command construction
3. Strategy Pattern: Command handlers
4. Facade Pattern: Git operations wrapper

File System Structure

Module Organization

src/
├── bin/              # Entry points (ESM)
├── cli/              # CLI layer
│   ├── handlers/     # Command implementations
│   └── output.ts     # Output formatting
└── core/             # Business logic
    ├── worktree/     # Worktree operations
    ├── git/          # Git abstractions
    ├── process/      # Process management
    └── types/        # Type definitions

Build Output

dist/
├── phantom.js        # Main executable
└── phantom.js.map    # Source maps

Performance Characteristics

Startup Performance

• Cold Start: ~50ms
• Factors:
  • Zero dependencies
  • Bundled executable
  • Minimal initialization

Memory Usage

• Base Memory: ~30MB
• Scalability: Linear with worktree count
• No Background Processes: Zero idle memory

Build Performance

• Full Build: <1 second (esbuild)
• Type Check: ~2 seconds
• Test Suite: ~1 second

Security Considerations

Input Validation

• Command argument sanitization
• Path traversal prevention
• Shell injection protection

Process Isolation

• Controlled environment variables
• Explicit shell invocation
• No eval or dynamic execution

Dependency Security

• Zero runtime dependencies = minimal attack surface
• Development dependencies regularly updated
• npm audit on CI pipeline

Platform Support

Operating Systems

• macOS: Full support
• Linux: Full support
• Windows: Full support (with Git Bash)

Shell Support

• bash: Primary support
• zsh: Full compatibility
• fish: Full compatibility
• PowerShell: Basic compatibility

Future Technology Considerations

Potential Additions

1. Configuration Management

   • TOML/YAML for config files
   • Environment variable support

2. Plugin System

   • Dynamic module loading
   • API for extensions

3. Performance Monitoring

   • OpenTelemetry integration
   • Metrics collection

4. Additional Language Support

   • Rust for performance-critical parts
   • WebAssembly for plugins

Technology Principles

1. Minimize Dependencies: Every dependency is a liability
2. Performance First: Choose fast tools
3. Developer Experience: Excellent tooling
4. Type Safety: Leverage TypeScript fully
5. Modern Standards: Use latest stable features

Comparison with Alternatives

vs. Git Worktree Directly

Feature	Git Worktree	Phantom
Learning Curve	Steep	Gentle
Commands	Complex	Simple
Naming	Paths	Names
Integration	Manual	Automated

vs. Git Clone

Aspect	Git Clone	Phantom
Disk Usage	High	Low
Setup Time	Slow	Fast
Shared History	No	Yes
Context Switch	Manual	Instant

Summary

Phantom's technology stack is carefully chosen to provide:

1. Performance: Fast execution and minimal overhead
2. Reliability: Type safety and comprehensive testing
3. Simplicity: Zero runtime dependencies
4. Developer Experience: Modern tooling and practices
5. Maintainability: Clean architecture and code quality

The combination of TypeScript, Node.js, and modern build tools creates a robust, performant CLI tool that enhances Git workflow productivity.