@aku11i/phantom 0.2.0 → 0.4.0

package/README.ja.md

@@ -0,0 +1,300 @@
+# 👻 Phantom
+
+<div align="center">
+
+**Git worktreeを使った並行開発のためのパワフルなCLIツール**
+
+[![npm version](https://img.shields.io/npm/v/@aku11i/phantom.svg)](https://www.npmjs.com/package/@aku11i/phantom)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/@aku11i/phantom.svg)](https://nodejs.org)
+
+[インストール](#-インストール) • [基本的な使い方](#-基本的な使い方) • [なぜPhantom？](#-なぜphantom) • [ドキュメント](#-ドキュメント)
+
+</div>
+
+## ✨ 概要
+
+Phantomは、Git worktreeの管理を劇的にシンプルにするCLIツールです。複数の機能開発、バグ修正、PRレビューを並行して進める現代の開発ワークフローに最適化されています。
+
+### 主な特徴
+
+- 🚀 **シンプルなWorktree管理** - 直感的なコマンドでGit worktreeを作成・管理
+- 🔄 **シームレスなコンテキスト切り替え** - stashやcommitせずに異なる作業間を瞬時に移動
+- 🤖 **AI対応** - 複数のAIコーディングエージェントを並行実行するのに最適
+- 🎯 **ブランチとWorktreeの同期** - 各worktreeに対応するブランチを自動作成
+- 🐚 **インタラクティブシェル** - SSH風のworktreeナビゲーション体験
+- ⚡ **ゼロ設定** - 賢明なデフォルト設定ですぐに使用可能
+
+## 🤔 なぜPhantom？
+
+現代の開発ワークフローでは、複数の機能を同時に作業することが一般的になっています。Git worktreeは素晴らしい機能ですが、パスとブランチを個別に指定する必要があり、少し面倒です。
+
+### Git worktreeを使う際の問題点
+
+素のGit worktreeを使う場合、worktreeのパス、ブランチ名、ベースブランチなどを毎回指定する必要があります。また、作業を切り替える際はディレクトリを移動する必要があり、複数の作業を頻繁に切り替える場合は少し手間がかかります。
+
+### Phantomの解決策
+
+```bash
+# 従来の方法
+git worktree add -b feature ../project-feature origin/main
+cd ../project-feature
+
+# Phantomを使用
+phantom create feature --shell
+```
+
+Phantomは、worktreeとブランチの作成を1つのコマンドにまとめ、作業スペース間の移動や操作を簡単にします。
+
+## 🚀 基本的な使い方
+
+```bash
+# Phantomをインストール
+npm install -g @aku11i/phantom
+
+# 新しいworktreeを作成
+phantom create feature-awesome
+
+# worktreeにジャンプ
+phantom shell feature-awesome
+
+# または直接コマンドを実行
+phantom exec feature-awesome npm install
+phantom exec feature-awesome npm test
+
+# すべてのworktreeをリスト表示
+phantom list
+
+# 完了したらクリーンアップ
+phantom delete feature-awesome
+```
+
+## 📦 インストール
+
+### npmを使用（推奨）
+```bash
+npm install -g @aku11i/phantom
+```
+
+### pnpmを使用
+```bash
+pnpm add -g @aku11i/phantom
+```
+
+### yarnを使用
+```bash
+yarn global add @aku11i/phantom
+```
+
+### ソースからビルド
+```bash
+git clone https://github.com/aku11i/phantom.git
+cd phantom
+pnpm install
+pnpm build
+npm link
+```
+
+## 📖 ドキュメント
+
+### コマンド概要
+
+#### Worktree管理
+
+```bash
+# 対応するブランチを持つ新しいworktreeを作成
+phantom create <name>
+
+# すべてのworktreeとその現在のステータスをリスト表示
+phantom list
+
+# worktreeへの絶対パスを取得
+phantom where <name>
+
+# worktreeとそのブランチを削除
+phantom delete <name>
+phantom delete <name> --force  # コミットされていない変更がある場合の強制削除
+```
+
+#### Worktreeでの作業
+
+```bash
+# worktreeのコンテキストで任意のコマンドを実行
+phantom exec <name> <command> [args...]
+
+# 例:
+phantom exec feature-auth npm install
+phantom exec feature-auth npm run test
+phantom exec feature-auth git status
+
+# worktreeでインタラクティブシェルセッションを開く
+phantom shell <name>
+```
+
+### 環境変数
+
+`phantom shell`でインタラクティブシェルを開いた際、以下の環境変数が設定されます：
+
+- `PHANTOM` - phantom shellから起動されたすべてのプロセスに"1"がセットされる
+- `PHANTOM_NAME` - 現在のworktreeの名前
+- `PHANTOM_PATH` - worktreeディレクトリへの絶対パス
+
+## 💡 ユースケース
+
+Phantomは単なるworktreeラッパーではなく、開発生産性を劇的に向上させるツールです。以下に実際の使用例を紹介します。
+
+### tmuxとの統合
+
+tmuxとPhantomを組み合わせることで、驚くほど効率的なワークフローを実現できます：
+
+```bash
+# 新しいtmuxウィンドウを開いて、同時にworktreeを作成
+tmux new-window 'phantom create new-feature --shell'
+```
+
+このたった1行のコマンドで：
+1. `new-feature`用の新しいGit worktreeを作成 ✨
+2. 新しいtmuxウィンドウを開く 🪟
+3. 新しいworktreeでインタラクティブシェルを起動 🚀
+
+複数の機能を並行して開発する際に、各機能を独立したtmuxウィンドウで管理できます。
+
+### VS Codeとの統合
+
+```bash
+# worktreeを作成してすぐにVS Codeで開く
+phantom create feature-auth
+phantom exec feature-auth code .
+```
+
+### 並行開発ワークフロー
+
+```bash
+# 機能開発中にバグレポートが来た場合
+phantom create hotfix-critical  # バグ修正用のworktreeを作成
+phantom shell hotfix-critical   # すぐに作業開始
+
+# 修正後、元の機能開発に戻る
+exit  # hotfixシェルを終了
+phantom shell feature-awesome  # 機能開発を続行
+```
+
+## 🔄 Phantom vs Git Worktree
+
+| 機能 | Git Worktree | Phantom |
+|---------|--------------|---------|
+| worktree + ブランチの作成 | `git worktree add -b feature ../project-feature` | `phantom create feature` |
+| worktreeのリスト表示 | `git worktree list` | `phantom list` |
+| worktreeへの移動 | `cd ../project-feature` | `phantom shell feature` |
+| worktreeでコマンド実行 | `cd ../project-feature && npm test` | `phantom exec feature npm test` |
+| worktreeの削除 | `git worktree remove ../project-feature` | `phantom delete feature` |
+
+## 🛠️ 開発
+
+```bash
+# クローンとセットアップ
+git clone https://github.com/aku11i/phantom.git
+cd phantom
+pnpm install
+
+# テストの実行
+pnpm test
+
+# 型チェック
+pnpm type-check
+
+# リンティング
+pnpm lint
+
+# すべてのチェックを実行
+pnpm ready
+```
+
+## 🚀 リリースプロセス
+
+Phantomの新しいバージョンをリリースするには：
+
+1. **mainブランチにいて最新の状態であることを確認**
+   ```bash
+   git checkout main
+   git pull
+   ```
+
+2. **すべてのチェックを実行**
+   ```bash
+   pnpm ready
+   ```
+
+3. **バージョンを上げる**
+   ```bash
+   # パッチリリース（バグ修正）の場合
+   npm version patch
+
+   # マイナーリリース（新機能）の場合
+   npm version minor
+
+   # メジャーリリース（破壊的変更）の場合
+   npm version major
+   ```
+
+4. **バージョンコミットとタグをプッシュ**
+   ```bash
+   git push && git push --tags
+   ```
+
+5. **npmに公開**
+   ```bash
+   pnpm publish
+   ```
+
+6. **GitHubリリースを作成**
+   ```bash
+   # 自動生成されたノートでリリースを作成
+   gh release create v<version> \
+     --title "Phantom v<version>" \
+     --generate-notes \
+     --target main
+
+   # v0.1.3の例:
+   gh release create v0.1.3 \
+     --title "Phantom v0.1.3" \
+     --generate-notes \
+     --target main
+   ```
+
+ビルドプロセスは`prepublishOnly`スクリプトによって自動的に処理され、以下を行います：
+- すべてのテストとチェックを実行
+- esbuildを使用してTypeScriptソースをJavaScriptにビルド
+- `dist/`ディレクトリにバンドルされた実行可能ファイルを作成
+
+**注意**: `dist/`ディレクトリはgit-ignoreされており、公開プロセス中にのみ作成されます。
+
+## 🤝 コントリビューション
+
+コントリビューションは歓迎します！プルリクエストを自由に送信してください。大きな変更については、まず変更したい内容について議論するためにissueを開いてください。
+
+以下を必ず行ってください：
+- 適切にテストを更新する
+- 既存のコードスタイルに従う
+- 提出前に`pnpm ready`を実行する
+
+## 📄 ライセンス
+
+このプロジェクトはMITライセンスの下でライセンスされています - 詳細は[LICENSE](LICENSE)ファイルをご覧ください。
+
+## 🙏 謝辞
+
+- より良い並行開発ワークフローの必要性に触発されて
+- AI支援開発時代のために構築
+- すべてのコントリビューターに特別な感謝を
+
+## 🤝 コントリビューター
+
+- [@aku11i](https://github.com/aku11i) - プロジェクトの作成者およびメンテナー
+- [Claude (Anthropic)](https://claude.ai) - コードベースの大部分を実装したAIペアプログラマー
+
+---
+
+<div align="center">
+<a href="https://github.com/aku11i">aku11i</a>と<a href="https://claude.ai">Claude</a>により👻で作成
+</div>

package/README.md

@@ -8,11 +8,15 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/node/v/@aku11i/phantom.svg)](https://nodejs.org)
 
-[Installation](#-installation) • [Quick Start](#-quick-start) • [Why Phantom?](#-why-phantom) • [Documentation](#-documentation)
+[Installation](#-installation) • [Basic Usage](#-basic-usage) • [Why Phantom?](#-why-phantom) • [Documentation](#-documentation) • [日本語](./README.ja.md)
 
 </div>
 
-## ✨ Key Features
+## ✨ Overview
+
+Phantom is a CLI tool that dramatically simplifies Git worktree management. It's optimized for modern development workflows where you need to work on multiple features, bug fixes, and PR reviews in parallel.
+
+### Key Features
 
 - 🚀 **Simplified Worktree Management** - Create and manage Git worktrees with intuitive commands
 - 🔄 **Seamless Context Switching** - Jump between different features without stashing or committing
@@ -23,41 +27,46 @@
 
 ## 🤔 Why Phantom?
 
-Modern development workflows often require working on multiple features simultaneously. Whether you're running AI coding agents in parallel, reviewing PRs while developing, or simply multitasking across features, managing multiple Git worktrees can be cumbersome.
+Modern development workflows often require working on multiple features simultaneously. While Git worktree is a powerful feature, it requires specifying paths and branches separately, which can be cumbersome.
+
+### The Manual Process
+
+When using Git worktree directly, you need to specify the worktree path, branch name, and base branch each time. Additionally, switching between tasks requires navigating directories, which can be a bit tedious when frequently switching between multiple parallel tasks.
 
-**The Problem:**
-- Git worktree commands are verbose and complex
-- Managing branches and worktrees separately is error-prone
-- Switching contexts requires multiple commands
-- Running parallel AI agents on the same codebase is challenging
+### The Phantom Solution
+
+```bash
+# Traditional approach
+git worktree add -b feature ../project-feature origin/main
+cd ../project-feature
+
+# With Phantom
+phantom create feature --shell
+```
 
-**The Phantom Solution:**
-- One command to create both worktree and branch: `phantom garden create feature-x`
-- Instant context switching: `phantom shell feature-x`
-- Execute commands without changing directories: `phantom exec feature-x npm test`
-- Perfect for "parallel vibe coding" with multiple AI agents
+Phantom combines worktree and branch creation into a single command, making it easy to switch between and work in different workspaces.
 
-## 🚀 Quick Start
+## 🚀 Basic Usage
 
 ```bash
 # Install Phantom
 npm install -g @aku11i/phantom
 
-# Create a new development space (garden)
-phantom garden create feature-awesome
+# Create a new worktree
+phantom create feature-awesome
 
-# Jump into the new space
+# Jump into the worktree
 phantom shell feature-awesome
 
 # Or execute commands directly
 phantom exec feature-awesome npm install
 phantom exec feature-awesome npm test
 
-# List all your gardens
-phantom garden list
+# List all your worktrees
+phantom list
 
 # Clean up when done
-phantom garden delete feature-awesome
+phantom delete feature-awesome
 ```
 
 ## 📦 Installation
@@ -88,62 +97,97 @@ npm link
 
 ## 📖 Documentation
 
-### Core Concepts
-
-**Gardens** 🌳 - Git worktrees managed by Phantom. Each garden is an isolated workspace for a specific branch or feature.
-
-**Phantoms** 👻 - Processes or agents that work within gardens.
-
 ### Commands Overview
 
-#### Gardens Management
+#### Worktree Management
 
 ```bash
-# Create a new garden with a matching branch
-phantom garden create <name>
+# Create a new worktree with a matching branch
+phantom create <name>
 
-# List all gardens with their current status
-phantom garden list
+# List all worktrees with their current status
+phantom list
 
-# Get the absolute path to a garden
-phantom garden where <name>
+# Get the absolute path to a worktree
+phantom where <name>
 
-# Delete a garden and its branch
-phantom garden delete <name>
-phantom garden delete <name> --force  # Force delete with uncommitted changes
+# Delete a worktree and its branch
+phantom delete <name>
+phantom delete <name> --force  # Force delete with uncommitted changes
 ```
 
-#### Working with Gardens
+#### Working with Worktrees
 
 ```bash
-# Execute any command in a garden's context
-phantom exec <garden> <command> [args...]
+# Execute any command in a worktree's context
+phantom exec <name> <command> [args...]
 
 # Examples:
 phantom exec feature-auth npm install
 phantom exec feature-auth npm run test
 phantom exec feature-auth git status
 
-# Open an interactive shell session in a garden
-phantom shell <garden>
+# Open an interactive shell session in a worktree
+phantom shell <name>
 ```
 
 ### Environment Variables
 
-When working within a Phantom context, these environment variables are available:
+When opening an interactive shell with `phantom shell`, these environment variables are set:
+
+- `PHANTOM` - Set to "1" for all processes spawned from phantom shell
+- `PHANTOM_NAME` - Name of the current worktree
+- `PHANTOM_PATH` - Absolute path to the worktree directory
+
+## 💡 Use Cases
+
+Phantom is more than just a worktree wrapper - it's a productivity multiplier. Here are some real-world examples:
+
+### tmux Integration
+
+Combine tmux with Phantom for an incredibly efficient workflow:
 
-- `PHANTOM_GARDEN` - Name of the current garden
-- `PHANTOM_GARDEN_PATH` - Absolute path to the garden directory
+```bash
+# Open a new tmux window and create a worktree in one command
+tmux new-window 'phantom create new-feature --shell'
+```
+
+This single line:
+1. Creates a new Git worktree for `new-feature` ✨
+2. Opens a new tmux window 🪟
+3. Starts an interactive shell in the new worktree 🚀
+
+When developing multiple features in parallel, you can manage each feature in its own tmux window.
+
+### VS Code Integration
+
+```bash
+# Create a worktree and immediately open it in VS Code
+phantom create feature-auth
+phantom exec feature-auth code .
+```
+
+### Parallel Development Workflow
+
+```bash
+# When a bug report comes in during feature development
+phantom create hotfix-critical  # Create worktree for the fix
+phantom shell hotfix-critical   # Start working immediately
+
+# After fixing, return to your feature
+exit  # Exit the hotfix shell
+phantom shell feature-awesome  # Continue feature development
+```
 
 ## 🔄 Phantom vs Git Worktree
 
 | Feature | Git Worktree | Phantom |
 |---------|--------------|---------|
-| Create worktree + branch | `git worktree add -b feature ../project-feature` | `phantom garden create feature` |
-| List worktrees | `git worktree list` | `phantom garden list` |
+| Create worktree + branch | `git worktree add -b feature ../project-feature` | `phantom create feature` |
+| List worktrees | `git worktree list` | `phantom list` |
 | Navigate to worktree | `cd ../project-feature` | `phantom shell feature` |
 | Run command in worktree | `cd ../project-feature && npm test` | `phantom exec feature npm test` |
-| Remove worktree | `git worktree remove ../project-feature` | `phantom garden delete feature` |
+| Remove worktree | `git worktree remove ../project-feature` | `phantom delete feature` |
 
 ## 🛠️ Development
 
@@ -185,10 +229,10 @@ To release a new version of Phantom:
    ```bash
    # For patch releases (bug fixes)
    npm version patch
-   
+
    # For minor releases (new features)
    npm version minor
-   
+
    # For major releases (breaking changes)
    npm version major
    ```
@@ -210,7 +254,7 @@ To release a new version of Phantom:
      --title "Phantom v<version>" \
      --generate-notes \
      --target main
-   
+
    # Example for v0.1.3:
    gh release create v0.1.3 \
      --title "Phantom v0.1.3" \