@ai-dossier/worktree-pool 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +69 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# @ai-dossier/worktree-pool
|
|
2
|
+
|
|
3
|
+
Pre-warmed git worktree pool for instant issue setup. Eliminates the ~3-5 minute cold start (git worktree add + npm install + build) by maintaining a pool of ready-to-use worktrees.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install -g @ai-dossier/worktree-pool
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Or use directly with npx:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx @ai-dossier/worktree-pool status
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Commands
|
|
18
|
+
|
|
19
|
+
| Command | Description |
|
|
20
|
+
|---------|-------------|
|
|
21
|
+
| `worktree-pool status` | Show pool inventory (warm/assigned/stale counts) |
|
|
22
|
+
| `worktree-pool replenish [--count N]` | Pre-warm spares up to target count |
|
|
23
|
+
| `worktree-pool claim --issue N --branch B` | Claim a warm worktree, print path |
|
|
24
|
+
| `worktree-pool return --path P` | Return worktree to pool for reuse |
|
|
25
|
+
| `worktree-pool refresh` | Fetch origin + rebuild in all warm worktrees |
|
|
26
|
+
| `worktree-pool gc` | Remove stale/orphaned/excess worktrees |
|
|
27
|
+
| `worktree-pool init` | Configure pool directory for this project |
|
|
28
|
+
|
|
29
|
+
## Quick Start
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# Initialize pool in your repo
|
|
33
|
+
worktree-pool init
|
|
34
|
+
|
|
35
|
+
# Pre-warm 3 worktrees
|
|
36
|
+
worktree-pool replenish --count 3
|
|
37
|
+
|
|
38
|
+
# Check pool status
|
|
39
|
+
worktree-pool status
|
|
40
|
+
|
|
41
|
+
# Claim a worktree for an issue (~2 seconds)
|
|
42
|
+
WORKTREE_PATH=$(worktree-pool claim --issue 42 --branch feature/42-add-dashboard)
|
|
43
|
+
cd "$WORKTREE_PATH"
|
|
44
|
+
|
|
45
|
+
# Return worktree to pool when done
|
|
46
|
+
worktree-pool return --path "$WORKTREE_PATH"
|
|
47
|
+
|
|
48
|
+
# Clean up stale worktrees
|
|
49
|
+
worktree-pool gc
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## How It Works
|
|
53
|
+
|
|
54
|
+
1. **Replenish** creates worktrees from `origin/main` on temp branches, runs `npm install` and builds
|
|
55
|
+
2. **Claim** renames a warm worktree, switches to your feature branch — instant setup
|
|
56
|
+
3. **Return** recycles the worktree back to pool on a fresh temp branch
|
|
57
|
+
4. **GC** removes stale entries (>72h) and reconciles disk state vs pool state
|
|
58
|
+
|
|
59
|
+
## Integration
|
|
60
|
+
|
|
61
|
+
Works with [ai-dossier](https://github.com/imboard-ai/ai-dossier) workflows:
|
|
62
|
+
|
|
63
|
+
- `setup-issue-workflow` v1.6.0+ auto-claims from pool when available
|
|
64
|
+
- `full-cycle-issue` v2.5.0+ returns worktrees to pool after merge
|
|
65
|
+
- `batch-issues.sh --pool` pre-warms before spawning agents
|
|
66
|
+
|
|
67
|
+
## License
|
|
68
|
+
|
|
69
|
+
AGPL-3.0-only
|