vde-worktree 0.0.1 → 0.0.2

package/README.ja.md

@@ -0,0 +1,343 @@
+# vde-worktree
+
+`vde-worktree` は、人間とコーディングエージェントの両方を想定した、安全な Git worktree 管理 CLI です。
+
+利用できるコマンド名:
+- `vde-worktree`
+- `vw`（エイリアス）
+
+英語版ドキュメント: `README.md`
+
+## このツールで解決すること
+
+- worktree をリポジトリ配下 `.worktree/` に統一配置
+- `switch` を冪等にして、同じ指示を繰り返しても破綻しにくくする
+- `del` / `gone` の破壊操作に安全ガードを入れる
+- Agent 向けに安定した JSON 出力を提供
+- hooks ベースで運用を拡張しやすくする
+
+## 動作要件
+
+- Node.js 22+
+- pnpm 10+
+- `fzf`（`cd` に必須）
+- `gh`（PR merged 判定に任意）
+
+## インストール / ビルド
+
+```bash
+pnpm install
+pnpm run build
+```
+
+開発時の検証:
+
+```bash
+pnpm run ci
+```
+
+## クイックスタート
+
+```bash
+vw init
+vw switch feature/foo
+cd "$(vw cd)"
+```
+
+## 管理ディレクトリ
+
+`vw init` 実行後に次を管理します:
+
+- `.worktree/`（worktree 実体）
+- `.vde/worktree/hooks/`
+- `.vde/worktree/logs/`
+- `.vde/worktree/locks/`
+- `.vde/worktree/state/`
+
+また `.git/info/exclude` に管理対象エントリを冪等で追記します。
+
+## 全体ルール
+
+- 多くの書き込み系コマンドは `init` 実行済みが前提
+- 書き込み時は内部の repo lock で排他制御
+- `--json` 指定時、stdout は単一 JSON オブジェクトのみ
+- ログや警告は stderr に出力
+- 非TTYで unsafe 操作を行う場合は `--allow-unsafe` が必要
+
+## グローバルオプション
+
+- `--json`: 機械可読の単一 JSON 出力
+- `--verbose`: 詳細ログ
+- `--no-hooks`: 今回のみ hook 無効化（`--allow-unsafe` 必須）
+- `--allow-unsafe`: unsafe 操作の明示同意
+- `--hook-timeout-ms <ms>`: hook timeout 上書き
+- `--lock-timeout-ms <ms>`: repo lock timeout 上書き
+
+## コマンド詳細
+
+### `init`
+
+```bash
+vw init
+```
+
+機能:
+- `.worktree/` と `.vde/worktree/*` を作成
+- `.git/info/exclude` に管理エントリ追加
+- デフォルト hook テンプレートを作成
+
+### `list`
+
+```bash
+vw list
+vw list --json
+```
+
+機能:
+- Git の porcelain 情報から worktree 一覧を取得
+- branch/path/dirty/lock/merged/upstream を表示
+
+### `status`
+
+```bash
+vw status
+vw status feature/foo
+vw status --json
+```
+
+機能:
+- 対象 worktree 1件の状態を表示
+- branch 指定なしなら現在 `cwd` から該当 worktree を解決
+
+### `path`
+
+```bash
+vw path feature/foo
+vw path feature/foo --json
+```
+
+機能:
+- 指定 branch の絶対 worktree path を返す
+
+### `new`
+
+```bash
+vw new
+vw new feature/foo
+```
+
+機能:
+- 新しい branch + worktree を `.worktree/` に作成
+- branch 省略時は `wip-xxxxxx` を自動生成
+
+### `switch`
+
+```bash
+vw switch feature/foo
+```
+
+機能:
+- 指定 branch の worktree があれば再利用、なければ作成
+- 冪等な branch 入口コマンド
+
+### `mv`
+
+```bash
+vw mv feature/new-name
+```
+
+機能:
+- 現在の非primary worktree の branch 名と path をリネーム
+- detached HEAD では実行不可
+
+### `del`
+
+```bash
+vw del
+vw del feature/foo
+vw del feature/foo --force-unmerged --allow-unpushed --allow-unsafe
+```
+
+機能:
+- worktree と branch を安全に削除
+- デフォルトで dirty / locked / unmerged(unknown含む) / unpushed(unknown含む) を拒否
+
+主な解除フラグ:
+- `--force-dirty`
+- `--allow-unpushed`
+- `--force-unmerged`
+- `--force-locked`
+- `--force`（上記を一括有効）
+
+### `gone`
+
+```bash
+vw gone
+vw gone --apply
+vw gone --json
+```
+
+機能:
+- 一括クリーンアップ候補の抽出/削除
+- デフォルトは dry-run
+- `--apply` で削除実行
+
+### `get`
+
+```bash
+vw get origin/feature/foo
+```
+
+機能:
+- remote branch を fetch
+- ローカル追跡 branch がなければ作成
+- worktree を作成/再利用
+
+### `extract`
+
+```bash
+vw extract --current
+vw extract --current --stash
+```
+
+機能:
+- primary worktree の現在 branch を `.worktree/` 側へ切り出し
+- primary を base branch に戻す
+- dirty 状態で切り出す場合は `--stash` を使用
+
+現状の制約:
+- 実装は primary worktree の抽出フローが中心
+
+### `use`
+
+```bash
+vw use feature/foo
+vw use feature/foo --allow-agent --allow-unsafe
+```
+
+機能:
+- primary worktree を指定 branch に checkout
+- primary context を固定したい用途向け
+
+安全条件:
+- primary が dirty なら拒否
+- 非TTYでは `--allow-agent` と `--allow-unsafe` の両方が必要
+
+### `exec`
+
+```bash
+vw exec feature/foo -- pnpm test
+vw exec feature/foo --json -- pnpm test
+```
+
+機能:
+- 指定 branch の worktree を `cwd` にしてコマンド実行
+- shell 展開は使わず引数配列で実行
+
+終了コード:
+- 子プロセス成功: `0`
+- 子プロセス失敗: `21`（JSON では `CHILD_PROCESS_FAILED`）
+
+### `invoke`
+
+```bash
+vw invoke post-switch
+vw invoke pre-new -- --arg1 --arg2
+```
+
+機能:
+- `pre-*` / `post-*` hook を手動実行
+- hook デバッグ用
+
+### `copy`
+
+```bash
+vw copy .envrc .claude/settings.local.json
+```
+
+機能:
+- repo 相対パスのファイル/ディレクトリを target worktree にコピー
+- 主に hook 内で `WT_WORKTREE_PATH` と合わせて使う想定
+
+### `link`
+
+```bash
+vw link .envrc
+vw link .envrc --no-fallback
+```
+
+機能:
+- target worktree 側に symlink を作成
+- Windows では `--no-fallback` がない場合、copy にフォールバック可
+
+### `lock` / `unlock`
+
+```bash
+vw lock feature/foo --owner codex --reason "agent in progress"
+vw unlock feature/foo --owner codex
+vw unlock feature/foo --force
+```
+
+機能:
+- `lock`: `.vde/worktree/locks/` に lock 情報を保存
+- `unlock`: lock を解除（owner 不一致時は `--force` 必須）
+
+### `cd`
+
+```bash
+cd "$(vw cd)"
+```
+
+機能:
+- `fzf` で worktree を対話選択
+- 選択した絶対 path を stdout に出力
+
+## merged 判定（ローカル + PR）
+
+各 worktree で次を評価します:
+
+- `merged.byAncestry`: ローカル履歴判定（`git merge-base --is-ancestor`）
+- `merged.byPR`: GitHub PR merged 判定（`gh`）
+- `merged.overall`: 最終判定
+
+`overall` ポリシー:
+
+- `byPR === true` -> `overall = true`
+- `byPR === false` -> `overall = false`
+- `byPR === null` -> `byAncestry` にフォールバック
+
+`byPR` が `null` になる例:
+- `gh` 未導入
+- `gh auth` 未設定
+- API 失敗
+- `git config vde-worktree.enableGh false`
+
+## JSON 契約
+
+`--json` 指定時、stdout は常に単一 JSON オブジェクトです。
+
+共通成功フィールド:
+- `schemaVersion`
+- `command`
+- `status`
+- `repoRoot`
+
+エラー時:
+- `status: "error"`
+- `code`
+- `message`
+- `details`
+
+## 設定キー（git config）
+
+- `vde-worktree.baseBranch`
+- `vde-worktree.baseRemote`
+- `vde-worktree.enableGh`
+- `vde-worktree.hooksEnabled`
+- `vde-worktree.hookTimeoutMs`
+- `vde-worktree.lockTimeoutMs`
+- `vde-worktree.staleLockTTLSeconds`
+
+## 現在のスコープ
+
+- Ink ベースの `tui` は未実装

package/README.md

@@ -1,45 +1,341 @@
 # vde-worktree
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+`vde-worktree` is a safe Git worktree manager designed for both humans and coding agents.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+It installs two command names:
+- `vde-worktree`
+- `vw` (alias)
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+Japanese documentation: [README.ja.md](./README.ja.md)
 
-## Purpose
+## Goals
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `vde-worktree`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+- Keep all worktrees in one repo-local location: `.worktree/`
+- Provide idempotent branch-to-worktree operations
+- Prevent accidental destructive actions by default
+- Expose stable JSON output for automation
+- Support hook-driven customization
 
-## What is OIDC Trusted Publishing?
+## Requirements
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+- Node.js 22+
+- pnpm 10+
+- `fzf` (required for `cd`)
+- `gh` (optional, for PR-based merge status)
 
-## Setup Instructions
+## Install / Build
 
-To properly configure OIDC trusted publishing for this package:
+```bash
+pnpm install
+pnpm run build
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+Validate locally:
 
-## DO NOT USE THIS PACKAGE
+```bash
+pnpm run ci
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+## Quick Start
 
-## More Information
+```bash
+vw init
+vw switch feature/foo
+cd "$(vw cd)"
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+## Managed Directories
 
----
+After `vw init`, the tool manages:
 
-**Maintained for OIDC setup purposes only**
+- `.worktree/` (worktree roots)
+- `.vde/worktree/hooks/`
+- `.vde/worktree/logs/`
+- `.vde/worktree/locks/`
+- `.vde/worktree/state/`
+
+`init` updates `.git/info/exclude` idempotently.
+
+## Global Behavior
+
+- Most write commands require prior `init`.
+- Write commands are protected by an internal repository lock.
+- `--json` prints exactly one JSON object to stdout.
+- Logs and warnings are written to stderr.
+- Non-TTY unsafe overrides require `--allow-unsafe`.
+
+## Global Options
+
+- `--json`: machine-readable single-object output
+- `--verbose`: verbose logging
+- `--no-hooks`: disable hooks for this run (requires `--allow-unsafe`)
+- `--allow-unsafe`: explicit unsafe override
+- `--hook-timeout-ms <ms>`: hook timeout override
+- `--lock-timeout-ms <ms>`: repository lock timeout override
+
+## Command Guide
+
+### `init`
+
+```bash
+vw init
+```
+
+What it does:
+- Creates `.worktree/` and `.vde/worktree/*`
+- Appends managed entries to `.git/info/exclude`
+- Creates default hook templates
+
+### `list`
+
+```bash
+vw list
+vw list --json
+```
+
+What it does:
+- Lists all worktrees from Git porcelain output
+- Includes metadata such as branch, path, dirty, lock, merged, and upstream status
+
+### `status`
+
+```bash
+vw status
+vw status feature/foo
+vw status --json
+```
+
+What it does:
+- Shows one worktree state
+- Without branch argument, resolves current worktree from current `cwd`
+
+### `path`
+
+```bash
+vw path feature/foo
+vw path feature/foo --json
+```
+
+What it does:
+- Resolves and returns the absolute worktree path for the target branch
+
+### `new`
+
+```bash
+vw new
+vw new feature/foo
+```
+
+What it does:
+- Creates a new branch + worktree under `.worktree/`
+- Without argument, generates `wip-xxxxxx`
+
+### `switch`
+
+```bash
+vw switch feature/foo
+```
+
+What it does:
+- Idempotent branch entrypoint
+- Reuses existing worktree if present, otherwise creates one
+
+### `mv`
+
+```bash
+vw mv feature/new-name
+```
+
+What it does:
+- Renames current non-primary worktree branch and moves its directory
+- Requires branch checkout (not detached HEAD)
+
+### `del`
+
+```bash
+vw del
+vw del feature/foo
+vw del feature/foo --force-unmerged --allow-unpushed --allow-unsafe
+```
+
+What it does:
+- Removes worktree and branch safely
+- By default, rejects dirty, locked, unmerged/unknown, or unpushed/unknown states
+
+Useful force flags:
+- `--force-dirty`
+- `--allow-unpushed`
+- `--force-unmerged`
+- `--force-locked`
+- `--force` (enables all force flags)
+
+### `gone`
+
+```bash
+vw gone
+vw gone --apply
+vw gone --json
+```
+
+What it does:
+- Bulk cleanup candidate finder/remover
+- Default mode is dry-run
+- `--apply` actually deletes eligible branches/worktrees
+
+### `get`
+
+```bash
+vw get origin/feature/foo
+```
+
+What it does:
+- Fetches remote branch
+- Creates tracking local branch when missing
+- Creates/reuses local worktree
+
+### `extract`
+
+```bash
+vw extract --current
+vw extract --current --stash
+```
+
+What it does:
+- Extracts current primary worktree branch into `.worktree/`
+- Switches primary worktree back to base branch
+- `--stash` allows extraction when primary is dirty
+
+Current limitation:
+- Implementation currently supports primary worktree extraction flow.
+
+### `use`
+
+```bash
+vw use feature/foo
+vw use feature/foo --allow-agent --allow-unsafe
+```
+
+What it does:
+- Checks out the target branch in the primary worktree
+- Intended for human workflows where primary context must be fixed
+
+Safety:
+- Rejects dirty primary worktree
+- In non-TTY mode, requires `--allow-agent` and `--allow-unsafe`
+
+### `exec`
+
+```bash
+vw exec feature/foo -- pnpm test
+vw exec feature/foo --json -- pnpm test
+```
+
+What it does:
+- Executes command inside the target branch worktree path
+- Does not use shell expansion
+
+Exit behavior:
+- Child success => `0`
+- Child failure => `21` (`CHILD_PROCESS_FAILED` in JSON mode)
+
+### `invoke`
+
+```bash
+vw invoke post-switch
+vw invoke pre-new -- --arg1 --arg2
+```
+
+What it does:
+- Manually invokes `pre-*` / `post-*` hook scripts
+- Useful for debugging hook behavior
+
+### `copy`
+
+```bash
+vw copy .envrc .claude/settings.local.json
+```
+
+What it does:
+- Copies repo-relative files/dirs from repo root into target worktree
+- Primarily intended for hook usage with `WT_WORKTREE_PATH`
+
+### `link`
+
+```bash
+vw link .envrc
+vw link .envrc --no-fallback
+```
+
+What it does:
+- Creates symlink in target worktree pointing to repo-root file
+- On Windows, can fallback to copy unless `--no-fallback`
+
+### `lock` / `unlock`
+
+```bash
+vw lock feature/foo --owner codex --reason "agent in progress"
+vw unlock feature/foo --owner codex
+vw unlock feature/foo --force
+```
+
+What they do:
+- `lock` writes lock metadata under `.vde/worktree/locks/`
+- `unlock` clears lock, enforcing owner match unless `--force`
+
+### `cd`
+
+```bash
+cd "$(vw cd)"
+```
+
+What it does:
+- Interactive worktree picker via `fzf`
+- Prints selected absolute path to stdout
+
+## Merge Status (Local + PR)
+
+Each worktree reports:
+
+- `merged.byAncestry`: local ancestry check (`git merge-base --is-ancestor <branch> <baseBranch>`)
+- `merged.byPR`: PR-based merged check via GitHub CLI
+- `merged.overall`: final decision
+
+Overall policy:
+
+- `byPR === true` => `overall = true`
+- `byPR === false` => `overall = false`
+- `byPR === null` => fallback to `byAncestry`
+
+`byPR` becomes `null` when PR lookup is unavailable (for example: `gh` missing, auth missing, API error, or `vde-worktree.enableGh=false`).
+
+## JSON Contract
+
+With `--json`, stdout always emits exactly one JSON object.
+
+Common success fields:
+- `schemaVersion`
+- `command`
+- `status`
+- `repoRoot`
+
+Error shape:
+- `status: "error"`
+- `code`
+- `message`
+- `details`
+
+## Configuration Keys
+
+Configured via `git config`:
+
+- `vde-worktree.baseBranch`
+- `vde-worktree.baseRemote`
+- `vde-worktree.enableGh`
+- `vde-worktree.hooksEnabled`
+- `vde-worktree.hookTimeoutMs`
+- `vde-worktree.lockTimeoutMs`
+- `vde-worktree.staleLockTTLSeconds`
+
+## Current Scope
+
+- Ink-based `tui` is not implemented yet.