2e4ef7035a
- Split Validation Checklist into verifiable docs vs deferred implementation checks (AGENTS.md) - Correct README example output to match actual `git worktree list` format - Add pi platform version requirement (`pi >= 0.5.0`) to Requirements section - Add Testing Strategy section with unit, integration, and manual verification procedures (DESIGN.md) - Document annotated `git worktree list` raw output format with parsing rules (DOMAIN.md) - Add permission fail condition for `create` tool in Tool Behaviors table
88 lines
4 KiB
Markdown
88 lines
4 KiB
Markdown
# DESIGN.md — Architecture & Design Decisions
|
|
|
|
## Overview
|
|
|
|
A pi extension that manages git worktrees through tool commands and an interactive `/worktree` command, with tight session integration.
|
|
|
|
## v1 Scope
|
|
|
|
- Four tools: `git_worktree_create`, `git_worktree_list`, `git_worktree_switch`, `git_worktree_remove`
|
|
- One command: `/worktree` (interactive picker)
|
|
- Session hooks: branch display update + offer new session after switch
|
|
- **Out of scope**: auto-worktree creation, smart defaults, persistent state
|
|
|
|
## Architecture
|
|
|
|
```
|
|
pi-worktree.ts
|
|
├── Tools
|
|
│ ├── git_worktree_create(path, branch?, create_branch?)
|
|
│ ├── git_worktree_list()
|
|
│ ├── git_worktree_switch(target)
|
|
│ └── git_worktree_remove(path)
|
|
├── Command: /worktree (interactive picker)
|
|
└── Session hooks
|
|
├── Update pi's git branch display on switch
|
|
└── Offer new session creation after switch
|
|
```
|
|
|
|
## Key Design Decisions
|
|
|
|
### Stateless Tools, Ephemeral Memory
|
|
Tools are stateless; only in-memory mapping of worktree→session during a process lifetime for back-switching. Lost on restart.
|
|
|
|
### Fail Fast, No Auto-Correction
|
|
Refuse dangerous operations (existing path, current branch, uncommitted changes) with clear messages and suggested fixes. Never silently auto-correct.
|
|
|
|
### Session Integration Depth (v1)
|
|
Update branch display + offer new session creation. No automatic worktree creation per branch — keeps complexity down and avoids assumptions about workflow.
|
|
|
|
## Tool Behaviors
|
|
|
|
| Tool | Key Behavior | Fail Conditions |
|
|
|------|-------------|-----------------|
|
|
| `create` | `git worktree add <path> [branch]`, `-b` for new branches | Path exists, branch is current, no write permission at target path (check with `fs.access()` before invoking git) |
|
|
| `list` | Parses `git worktree list` output into structured data | No git repo present |
|
|
| `switch` | Changes cwd to target worktree path | Already there, uncommitted changes in source |
|
|
| `remove` | `git worktree remove <path>` | Target is main repo, uncommitted changes |
|
|
|
|
## Edge Cases
|
|
|
|
1. **Nested worktrees**: Not supported by git — surface native error
|
|
2. **Detached HEAD**: Use path for identification instead of branch name
|
|
3. **Untracked files on removal**: Suggest removing/moving them first
|
|
4. **Same-branch worktrees**: Let git handle it, surface the error
|
|
|
|
## Testing Strategy
|
|
|
|
### Unit Tests — Parsing (`git_worktree_list`)
|
|
- Parse valid `git worktree list` output into structured data with correct `branch`, `path`, and `isCurrent`
|
|
- Handle detached HEAD entries (no branch name → use path for identification)
|
|
- Handle bare repos (HEAD line without branch brackets)
|
|
- Reject non-git-repo directories
|
|
|
|
### Unit Tests — Validation (`git_worktree_create`)
|
|
- Refuse when target path already exists (suggest `--force` or alternative path)
|
|
- Refuse when attempting to create a worktree on the current branch in the main repo
|
|
- Surface permission errors with actionable guidance (e.g., "cannot write to /root/ — try ~/worktrees/")
|
|
|
|
### Integration Tests — Each Tool
|
|
| Test | Procedure |
|
|
|------|-----------|
|
|
| `create` | Create worktree → verify `git worktree list` shows it → remove it |
|
|
| `list` | Run against repo with 0, 1, and N worktrees → assert structured output shape |
|
|
| `switch` | Switch to existing worktree → verify cwd updated → switch back → verify original state restored |
|
|
| `remove` | Remove a linked worktree → verify it's gone from list; refuse if uncommitted changes exist |
|
|
|
|
### Manual Verification — `/worktree` Command UX
|
|
- Run `/worktree` in a repo with multiple worktrees
|
|
- Confirm picker shows branch names (not just paths)
|
|
- Switch to a worktree → confirm branch display updates
|
|
- Return to main repo → confirm session back-switching works
|
|
|
|
## Rollout Phases
|
|
|
|
1. Core tools (create, list, switch, remove) with error handling + unit tests
|
|
2. `/worktree` interactive command with picker + back-switching + integration tests
|
|
3. Session integration hooks (branch display, new session offer)
|
|
4. Polish: edge cases, README, manual verification pass
|