@aku11i/phantom 0.8.1 → 1.0.0

package/README.ja.md

@@ -2,426 +2,184 @@
 
 <div align="center">
 
-**Git worktreeを使った並行開発のためのパワフルなCLIツール**
+**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)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/aku11i/phantom)
 
-[インストール](#-インストール) • [基本的な使い方](#-基本的な使い方) • [なぜPhantom？](#-なぜphantom) • [ドキュメント](#-ドキュメント)
+[English](./README.md) • [インストール](#-インストール) • [なぜPhantom？](#-なぜphantom) • [基本的な使い方](#-基本的な使い方) • [ドキュメント](#-ドキュメント)
 
 </div>
 
-## ✨ 概要
+## ✨ Phantomとは？
 
-Phantomは、Git worktreeの管理を劇的にシンプルにするCLIツールです。複数の機能開発、バグ修正、PRレビューを並行して進める現代の開発ワークフローに最適化されています。
+PhantomはGit worktreeをシンプルかつパワフルに操り、開発生産性を飛躍的に向上させるCLIツールです。複数のタスクを独立した作業環境で同時進行し、真のマルチタスク開発を実現します。AIエージェントを用いた並行開発に対応した次世代の並行開発ツールです。
 
-### 主な特徴
+### 主な機能
 
 - 🚀 **シンプルなWorktree管理** - 直感的なコマンドでGit worktreeを作成・管理
-- 🔄 **シームレスなコンテキスト切り替え** - stashやcommitせずに異なる作業間を瞬時に移動
-- 🤖 **AI対応** - 複数のAIコーディングエージェントを並行実行するのに最適
-- 🎯 **ブランチとWorktreeの同期** - 各worktreeに対応するブランチを自動作成
-- 🐚 **インタラクティブシェル** - SSH風のworktreeナビゲーション体験
-- ⚡ **ゼロ設定** - 賢明なデフォルト設定ですぐに使用可能
-- 📦 **ゼロ依存** - 外部依存関係がなく軽量で高速
+- 🔄 **真のマルチタスク** - ブランチ毎に作業ディレクトリを作成し、複数のタスクを同時進行
+- 🎯 **どこからでもコマンド実行** - `phantom exec <worktree> <command>`でワークツリーに対してコマンドを実行可能
+- 🪟 **組み込みtmux統合** - ワークツリーを新しいペインやウィンドウで開きます
+- 🔍 **fzfによるインタラクティブな選択** - worktreeの選択に組み込みのfzfオプションを使用できます
+- 🎮 **シェル補完** - FishとZshの完全な自動補完サポート
+- ⚡ **ゼロ依存** - 高速で軽量
 
-## 🤔 なぜPhantom？
-
-現代の開発ワークフローでは、複数の機能を同時に作業することが一般的になっています。Git worktreeは素晴らしい機能ですが、パスとブランチを個別に指定する必要があり、少し面倒です。
-
-### Git worktreeを使う際の問題点
-
-素のGit worktreeを使う場合、worktreeのパス、ブランチ名、ベースブランチなどを毎回指定する必要があります。また、作業を切り替える際はディレクトリを移動する必要があり、複数の作業を頻繁に切り替える場合は少し手間がかかります。
+## 🚀 インストール
 
-### Phantomの解決策
+### Homebrewを使用（推奨）
 
 ```bash
-# 従来の方法
-git worktree add -b feature ../project-feature origin/main
-cd ../project-feature
-
-# Phantomを使用
-phantom create feature --shell
+brew install aku11i/tap/phantom
 ```
 
-Phantomは、worktreeとブランチの作成を1つのコマンドにまとめ、作業スペース間の移動や操作を簡単にします。
-
-## 🚀 基本的な使い方
+#### npmを使用
 
 ```bash
-# Phantomをインストール
 npm install -g @aku11i/phantom
+```
 
-# 新しいworktreeを作成
-phantom create feature-awesome
-
-# 既存のブランチにアタッチ
-phantom attach existing-branch
-
-# worktreeにジャンプ
-phantom shell feature-awesome
+## 🤔 なぜPhantom？
 
-# または直接コマンドを実行
-phantom exec feature-awesome npm install
-phantom exec feature-awesome npm test
+Git worktreeは強力ですが、パスとブランチの手動管理が必要です。また、複数のワークツリーを移動するのも大変です。Phantomはこの問題を解消します：
 
-# すべてのworktreeをリスト表示
-phantom list
+```bash
+# Phantomなし
+git worktree add -b feature-awesome ../project-feature-awesome origin/main
+cd ../project-feature-awesome
 
-# 完了したらクリーンアップ
-phantom delete feature-awesome
+# Phantomあり
+phantom create feature-awesome --shell
 ```
 
-## 📦 インストール
+### Phantomの仕組み
 
-### npmを使用（推奨）
-```bash
-npm install -g @aku11i/phantom
-```
-
-### pnpmを使用
-```bash
-pnpm add -g @aku11i/phantom
-```
+`phantom create feature-awesome`を実行すると、`.git/phantom/worktrees/`に`feature-awesome`という名前の新しいGit worktreeが作成されます。
+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
+your-project/    # Gitリポジトリ
+├── .git/
+│   └── phantom/
+│       └── worktrees/        # Phantomが管理するディレクトリ
+│           ├── feature-awesome/  # ブランチ名 = worktree名
+│           ├── bugfix-login/     # 別のworktree
+│           └── hotfix-critical/  # さらに別のworktree
+└── ...
 ```
 
-## 📖 ドキュメント
+このルールにより、worktreeの場所を覚える必要がなくなり、ブランチ名だけで簡単にワークツリーの操作ができます。
 
-### コマンド概要
+### ✈️ 快適な開発体験を実現する機能
 
-#### Worktree管理
+Phantomはコマンドラインツールとしての完璧な機能を備えています。開発者はまるでファーストクラスに乗っているような信頼と安心を感じます。
 
-```bash
-# 対応するブランチを持つ新しいworktreeを作成
-phantom create <name>
-phantom create <name> --shell  # 作成してインタラクティブシェルに入る
-phantom create <name> --exec <command>  # 作成してコマンドを実行
-phantom create <name> --tmux  # 作成して新しいtmuxウィンドウで開く
-phantom create <name> --tmux-vertical  # 作成してtmuxペインを縦に分割
-phantom create <name> --tmux-v  # --tmux-verticalの短縮形
-phantom create <name> --tmux-horizontal  # 作成してtmuxペインを横に分割
-phantom create <name> --tmux-h  # --tmux-horizontalの短縮形
-
-# worktreeを作成し、特定のファイルをコピー
-phantom create <name> --copy-file ".env" --copy-file ".env.local"
-
-# 既存のブランチにworktreeとしてアタッチ
-phantom attach <branch-name>
-phantom attach <branch-name> --shell  # アタッチしてインタラクティブシェルに入る
-phantom attach <branch-name> --exec <command>  # アタッチしてコマンドを実行
-
-# すべてのworktreeとその現在のステータスをリスト表示
-phantom list
+#### シェル補完
 
-# worktreeへの絶対パスを取得
-phantom where <name>
+Phantomはfishとzshの完全なシェル補完をサポートしています。タブキーでコマンドやworktree名を補完できます。
 
-# worktreeとそのブランチを削除
-phantom delete <name>
-phantom delete <name> --force  # コミットされていない変更がある場合の強制削除
-```
+#### tmux統合
 
-#### Worktreeでの作業
+ワークツリーを作成する際にtmuxを使用して新しいウィンドウやペインで開くことができます。これにより、複数の作業環境を同時に管理できます。
 
 ```bash
-# worktreeのコンテキストで任意のコマンドを実行
-phantom exec <name> <command> [args...]
+# 新しいウィンドウでworktreeを作成して開く
+phantom create feature-x --tmux
+# ペインを分割して作成
+phantom create feature-y --tmux-vertical
+phantom create feature-z --tmux-horizontal
 
-# 例:
-phantom exec feature-auth npm install
-phantom exec feature-auth npm run test
-phantom exec feature-auth git status
+# 既存のworktreeをtmuxで開く
+phantom shell feature-x --tmux
+phantom shell feature-y --tmux-v
 
-# worktreeでインタラクティブシェルセッションを開く
-phantom shell <name>
+# 結果: 複数のworktreeが同時に表示され、それぞれで独立した作業が可能
 ```
 
-### 環境変数
+#### エディタ統合
 
-`phantom shell`でインタラクティブシェルを開いた際、以下の環境変数が設定されます：
+PhantomはVS CodeやCursorなどのエディタでも快適に使用できます。エディタを指定してワークツリーを開くことができます。
 
-- `PHANTOM` - phantom shellから起動されたすべてのプロセスに"1"がセットされる
-- `PHANTOM_NAME` - 現在のworktreeの名前
-- `PHANTOM_PATH` - worktreeディレクトリへの絶対パス
+```bash
+# VS Codeで開く
+phantom create feature --exec "code ."
 
-## 💡 ユースケース
+# または既存のworktreeを開く
+phantom exec feature code .
 
-Phantomは単なるworktreeラッパーではなく、開発生産性を劇的に向上させるツールです。以下に実際の使用例を紹介します。
+# Cursorで開く
+phantom create feature --exec "cursor ."
+phantom exec feature cursor .
+```
 
-### tmuxとの統合
+#### fzf統合
 
-tmuxとPhantomを組み合わせることで、驚くほど効率的なワークフローを実現できます：
+fzfを使用したインタラクティブな検索で素早くworktreeを選択できます。
 
 ```bash
-# 新しいtmuxウィンドウを開いて、同時にworktreeを作成
-tmux new-window 'phantom create --shell new-feature'
-```
+# fzfでworktreeを選択してシェルを開く
+phantom shell --fzf
 
-このたった1行のコマンドで：
-1. `new-feature`用の新しいGit worktreeを作成 ✨
-2. 新しいtmuxウィンドウを開く 🪟
-3. 新しいworktreeでインタラクティブシェルを起動 🚀
+# fzfでworktreeを選択して削除
+phantom delete --fzf
+```
 
-複数の機能を並行して開発する際に、各機能を独立したtmuxウィンドウで管理できます。
+## 🔍 基本的な使い方
 
-### VS Codeとの統合
+### 新しいワークツリーの作成
 
 ```bash
-# worktreeを作成してすぐにVS Codeで開く
-phantom create --exec "code ." new-feature
-phantom create --exec "cursor ." new-feature # Cursorでも動作します！
+phantom create feature-awesome
 
-# 既存のブランチにアタッチしてVS Codeで開く
-phantom attach --exec "code ." feature/existing-branch
+phantom list
 ```
 
-### 並行開発ワークフロー
+### worktreeで新しいシェルを起動
 
 ```bash
-# 機能開発中にバグレポートが来た場合
-phantom create hotfix-critical  # バグ修正用のworktreeを作成
-phantom shell hotfix-critical   # すぐに作業開始
+phantom shell feature-awesome
 
-# 修正後、元の機能開発に戻る
-exit  # hotfixシェルを終了
-phantom shell feature-awesome  # 機能開発を続行
-```
+# 開発作業を開始
 
-## 🔄 Phantom vs Git Worktree
-
-| 機能 | Git Worktree | Phantom |
-|---------|--------------|---------|
-| worktree + ブランチの作成 | `git worktree add -b feature ../project-feature` | `phantom create feature` |
-| 既存のブランチにアタッチ | `git worktree add ../project-feature feature` | `phantom attach 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` |
-
-## ⚙️ 設定
-
-Phantomはリポジトリルートの`phantom.config.json`ファイルによる設定をサポートします。これにより、新しいworktreeを作成する際に自動的にコピーされるファイルの定義や、実行されるコマンドを設定できます。
-
-### 設定ファイル
-
-リポジトリルートに`phantom.config.json`ファイルを作成します：
-
-```json
-{
-  "postCreate": {
-    "copyFiles": [
-      ".env",
-      ".env.local",
-      "config/local.json"
-    ],
-    "commands": [
-      "pnpm install",
-      "pnpm build"
-    ]
-  }
-}
+# 作業が終わったらシェルを終了
+exit
 ```
 
-### ファイルコピー機能
-
-新しいworktreeを作成する際、Phantomは現在のworktreeから新しいworktreeへ指定されたファイルを自動的にコピーできます。これは以下のような場合に特に便利です：
-
-- 環境設定ファイル（`.env`、`.env.local`）
-- ローカル開発設定
-- gitignoreされているシークレットファイル
-
-ファイルのコピーは2つの方法で指定できます：
-
-1. **コマンドラインオプションを使用：**
-   ```bash
-   phantom create feature --copy-file ".env" --copy-file ".env.local" --copy-file "config/local.json"
-   ```
-
-2. **設定ファイルを使用：**
-   `phantom.config.json`で一度設定すれば、すべての新しいworktreeに適用されます。
-
-3. **両方を使用：**
-   設定ファイルとコマンドラインオプションの両方で指定されたファイルはマージされます（重複は削除されます）。
-
-> **注意：** 現在、globパターンはサポートされていません。ファイルはリポジトリルートからの相対パスで正確に指定する必要があります。
+### 任意のworktreeでコマンドを実行
 
-### 作成後コマンド
-
-Phantomは新しいworktreeを作成した後に自動的にコマンドを実行できます。これは以下のような場合に便利です：
-
-- 依存関係のインストール（`pnpm install`、`npm install`、`yarn install`）
-- プロジェクトのビルド
-- 開発環境のセットアップ
-- データベースマイグレーションの実行
-- プロジェクト固有のその他のセットアップタスク
-
-コマンドは設定ファイルで指定された順序で実行されます。コマンドが失敗した場合、作成プロセスは停止し、エラーが報告されます。
-
-使用例：
-```json
-{
-  "postCreate": {
-    "commands": [
-      "pnpm install",           // 依存関係をインストール
-      "pnpm db:migrate",        // データベースマイグレーションを実行
-      "cp .env.example .env",   // テンプレートから環境ファイルを作成
-      "pnpm build"              // プロジェクトをビルド
-    ]
-  }
-}
+```bash
+phantom exec feature-awesome {実行したいコマンド}
+# 例: phantom exec feature-awesome npm run build
 ```
 
-## 🛠️ 開発
+### 完了したらクリーンアップ
 
 ```bash
-# クローンとセットアップ
-git clone https://github.com/aku11i/phantom.git
-cd phantom
-pnpm install
+phantom delete feature-awesome
+```
 
-# テストの実行
-pnpm test
 
-# 特定のテストファイルを実行
-pnpm test:file src/core/worktree/create.test.js
+## 📚 ドキュメント
 
-# 型チェック
-pnpm typecheck
+- **[はじめに](./docs/getting-started.md)** - 一般的なワークフローとヒント
+- **[コマンドリファレンス](./docs/commands.md)** - すべてのコマンドとオプション
+- **[設定](./docs/configuration.md)** - 自動ファイルコピーと作成後コマンドの設定
 
-# リンティング
-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
-   ```
-
-7. **リリースノートを分かりやすく更新**
-   - 自動生成されたリリースノートを`gh release view v<version>`でレビュー
-   - 重要な詳細についてはPRの説明を`gh pr view <number>`で確認
-   - リリースノートをよりユーザーフレンドリーに更新：
-     - 変更をカテゴリー別にグループ化（機能、バグ修正、改善）
-     - 新機能には使用例を追加
-     - 変更の影響を平易な言葉で説明
-     - セキュリティ修正と破壊的変更を強調
-   
-   ```bash
-   # リリースノートを編集
-   gh release edit v<version> --notes "$(cat <<'EOF'
-   ## 🚀 v<version> の新機能
-   
-   ### ✨ 新機能
-   - 使用例付きの機能説明
-   
-   ### 🐛 バグ修正
-   - 修正内容の明確な説明
-   
-   ### 🛠️ 改善
-   - パフォーマンス、セキュリティ、その他の改善
-   
-   EOF
-   )"
-   ```
-
-ビルドプロセスは`prepublishOnly`スクリプトによって自動的に処理され、以下を行います：
-- すべてのテストとチェックを実行
-- esbuildを使用してTypeScriptソースをJavaScriptにビルド
-- `dist/`ディレクトリにバンドルされた実行可能ファイルを作成
-
-**注意**: `dist/`ディレクトリはgit-ignoreされており、公開プロセス中にのみ作成されます。
-
-## 🤝 コントリビューション
-
-コントリビューションは歓迎します！プルリクエストを自由に送信してください。大きな変更については、まず変更したい内容について議論するためにissueを開いてください。
-
-以下を必ず行ってください：
-- 適切にテストを更新する
-- 既存のコードスタイルに従う
-- 提出前に`pnpm ready`を実行する
+コントリビュートは歓迎します！[コントリビューションガイド](./CONTRIBUTING.md)をご覧ください：
+- 開発環境のセットアップ
+- コードスタイルガイドライン
+- テスト要件
+- プルリクエストプロセス
 
 ## 📄 ライセンス
 
-このプロジェクトはMITライセンスの下でライセンスされています - 詳細は[LICENSE](LICENSE)ファイルをご覧ください。
+MIT License - [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>
+👻 [@aku11i](https://github.com/aku11i)と[Claude](https://claude.ai)によって作られました