JA Getting Started Architecture Overview - aku11i/phantom GitHub Wiki

アーキテクチャ概要

English | 日本語

このドキュメントでは、Phantomのシステムアーキテクチャと設計原則の概要を説明します。

システムアーキテクチャ

graph TB
    subgraph "ユーザーインターフェース"
        CLI[CLIコマンド]
    end
    
    subgraph "CLIレイヤー"
        Handlers[コマンドハンドラー]
        Output[出力フォーマッター]
        Errors[エラーハンドラー]
    end
    
    subgraph "コアビジネスロジック"
        Worktree[Worktree操作]
        Git[Git操作]
        Process[プロセス実行]
        Paths[パス管理]
        Types[型システム]
    end
    
    subgraph "外部システム"
        FS[ファイルシステム]
        GitCLI[Git CLI]
        Shell[システムシェル]
    end
    
    CLI --> Handlers
    Handlers --> Output
    Handlers --> Errors
    Handlers --> Worktree
    Handlers --> Process
    
    Worktree --> Git
    Worktree --> Paths
    Worktree --> Types
    
    Process --> Types
    
    Git --> GitCLI
    Paths --> FS
    Process --> Shell
Loading

設計原則

1. レイヤードアーキテクチャ

ソース: CLAUDE.md#L26-L31

アーキテクチャはクリーンなレイヤード アプローチに従います：

  • CLIレイヤー: ユーザーインタラクション、コマンド解析、出力フォーマットを処理
  • コアレイヤー: CLIフレームワークに依存しないビジネスロジックを含む
  • 外部レイヤー: システムリソース（Git、ファイルシステム、シェル）とのインターフェース

2. 関心の分離

各モジュールには、明確に定義された単一の責任があります：

  • コマンドハンドラー: 操作のオーケストレーション、ビジネスロジックなし
  • コアモジュール: ビジネスロジック、CLI依存関係なし
  • Git操作: 集約されたGitコマンド実行
  • プロセス実行: 統一されたプロセス生成と管理

3. 関数型エラーハンドリング

ソース: src/core/types/result.ts

明示的なエラーハンドリングのためにResult<T, E>型パターンを使用：

type Result<T, E = Error> = 
  | { ok: true; value: T }
  | { ok: false; error: E }

これにより以下が可能になります：

  • 明示的なエラー状態
  • 型安全なエラーハンドリング
  • 予期されるエラーに対する例外なし
  • 構成可能なエラーハンドリング

コンポーネント概要

CLIコンポーネント

src/cli/に配置：

  • handlers/: コマンド実装

    • 各コマンドには独自のハンドラーファイル
    • ハンドラーはコア操作をオーケストレート
    • 最小限のビジネスロジック

  • output.ts: 集約されたコンソール出力

    • 一貫したフォーマット
    • リスト用のテーブルレンダリング
    • エラーメッセージのフォーマット

  • errors.ts: CLIエラーハンドリング

    • 終了コード管理
    • ユーザーフレンドリーなエラーメッセージ

コアコンポーネント

src/core/に配置：

Worktreeモジュール（worktree/）

Git worktree操作を管理：

  • create.ts: 新しいworktreeを作成
  • delete.ts: worktreeを削除
  • list.ts: 既存のworktreeをリスト表示
  • where.ts: worktreeパスを特定
  • validate.ts: worktree名と状態を検証

Gitモジュール（git/）

ソース: src/core/git/

Git操作を集約：

  • executor.ts: メインGitコマンドエグゼキューター
  • libs/: 特定のGit操作ラッパー
    • add-worktree.ts: Worktree作成
    • get-current-branch.ts: ブランチ検出
    • get-git-root.ts: リポジトリルート検索

Processモジュール（process/）

外部プロセス実行を処理：

  • spawn.ts: コアプロセス生成ロジック
  • exec.ts: worktree内でのコマンド実行
  • shell.ts: インタラクティブシェルセッション

サポートモジュール

  • paths.ts: 集約されたパス管理
  • version.ts: バージョン情報
  • types/: 共有型定義

データフロー

コマンド実行フロー

sequenceDiagram
    participant User
    participant CLI
    participant Handler
    participant Core
    participant Git
    participant FS
    
    User->>CLI: phantom create feature
    CLI->>Handler: ParsedCommand
    Handler->>Core: validateWorktreeName()
    Core-->>Handler: Result<void>
    
    Handler->>Core: createWorktree()
    Core->>Git: getBranch()
    Git-->>Core: currentBranch
    
    Core->>Git: addWorktree()
    Git->>FS: git worktree add
    FS-->>Git: success
    
    Git-->>Core: Result<WorktreeInfo>
    Core-->>Handler: Result<WorktreeInfo>
    Handler->>CLI: Format output
    CLI->>User: Success message
Loading

エラーハンドリングフロー

graph LR
    A[操作] --> B{成功？}
    B -->|はい| C[Result.okを返す]
    B -->|いいえ| D[エラーを作成]
    D --> E[Result.errorを返す]
    E --> F[ハンドラーが結果をチェック]
    F --> G[エラーメッセージをフォーマット]
    G --> H[コードで終了]
Loading

主要なアーキテクチャ決定

1. ランタイム依存関係ゼロ

ソース: package.json#L50

  • 外部ランタイム依存関係なし
  • より高速なインストールと実行
  • セキュリティ表面積の削減
  • 簡素化されたデプロイメント

2. ESMを使用したTypeScript

  • 全体を通してモダンなESモジュール
  • コンパイル時の型安全性
  • より良いIDEサポート
  • ツリーシェイキング可能

3. ネイティブNode.js機能

  • Node.js組み込みテストランナーを使用
  • テスト用のネイティブモジュールモッキング
  • 組み込みの子プロセス処理
  • 外部テストフレームワークなし

4. Git CLI統合

  • 操作をGit CLIに委譲
  • Gitライブラリ依存関係なし
  • Gitバージョンとの互換性を確保
  • Gitの実戦テスト済みコードを活用

モジュール依存関係

graph TD
    CLI[CLIレイヤー]
    Core[コアレイヤー]
    Git[Git操作]
    Process[プロセスユーティリティ]
    Types[型定義]
    
    CLI --> Core
    CLI --> Types
    Core --> Git
    Core --> Process
    Core --> Types
    Git --> Types
    Process --> Types
    
    style CLI fill:#f9f,stroke:#333,stroke-width:2px
    style Core fill:#9ff,stroke:#333,stroke-width:2px
    style Git fill:#ff9,stroke:#333,stroke-width:2px
Loading

主要なルール：

  • CLIはCoreに依存（逆は決してない）
  • コアモジュールはCLIから独立
  • types/モジュールの共有型
  • 循環依存なし

セキュリティに関する考慮事項

入力検証

  • すべてのユーザー入力を検証
  • Worktree名をサニタイズ
  • パストラバーサル防止
  • コマンドインジェクション保護

プロセス実行

  • コマンドは適切にエスケープ
  • シェル実行は明示的
  • 環境変数は制御
  • evalや動的コード実行なし

パフォーマンス特性

起動時間

  • 最小限の依存関係 = 高速起動
  • ランタイムオーバーヘッドなしの直接実行
  • esbuildで最適化のためバンドル

メモリ使用量

  • 軽量なプロセスフットプリント
  • 永続的なデーモンなし
  • 実行後にガベージコレクション

スケーラビリティ

  • ステートレス操作
  • 多くのworktreeを管理可能
  • 並列操作サポート
  • ほとんどの操作で線形の複雑性

将来のアーキテクチャに関する考慮事項

アーキテクチャは以下をサポートするよう設計されています：

  1. プラグインシステム: モジュラー拡張
  2. 設定: ユーザー設定
  3. リモート操作: ネットワークworktreeサポート
  4. パフォーマンス監視: メトリクス収集
  5. 高度なGit機能: サブモジュール、スパースチェックアウト

関心事のクリーンな分離とモジュラー設計により、大規模なリファクタリングなしでこれらの拡張が可能になります。

⚠️ **GitHub.com Fallback** ⚠️