@ai-dossier/worktree-pool 0.1.0 → 0.2.0
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 +122 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# @ai-dossier/worktree-pool
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@ai-dossier/worktree-pool)
|
|
4
|
+
[](https://www.npmjs.com/package/@ai-dossier/worktree-pool)
|
|
5
|
+
[](https://github.com/imboard-ai/ai-dossier/blob/main/LICENSE)
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g @ai-dossier/worktree-pool
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Or use directly with npx:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx @ai-dossier/worktree-pool status
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Requires Node.js >= 20.0.0.
|
|
22
|
+
|
|
23
|
+
## Commands
|
|
24
|
+
|
|
25
|
+
| Command | Description |
|
|
26
|
+
|---------|-------------|
|
|
27
|
+
| `worktree-pool status` | Show pool inventory (warm/assigned/stale counts) |
|
|
28
|
+
| `worktree-pool replenish [--count N]` | Pre-warm spares up to target count |
|
|
29
|
+
| `worktree-pool claim --issue N --branch B` | Claim a warm worktree, print path |
|
|
30
|
+
| `worktree-pool return --path P` | Return worktree to pool for reuse |
|
|
31
|
+
| `worktree-pool refresh` | Fetch origin + rebuild in all warm worktrees |
|
|
32
|
+
| `worktree-pool gc` | Remove stale/orphaned/excess worktrees |
|
|
33
|
+
| `worktree-pool init` | Configure pool directory for this project |
|
|
34
|
+
|
|
35
|
+
## Quick Start
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# Initialize pool in your repo
|
|
39
|
+
worktree-pool init
|
|
40
|
+
|
|
41
|
+
# Pre-warm 3 worktrees
|
|
42
|
+
worktree-pool replenish --count 3
|
|
43
|
+
|
|
44
|
+
# Check pool status
|
|
45
|
+
worktree-pool status
|
|
46
|
+
|
|
47
|
+
# Claim a worktree for an issue (~2 seconds)
|
|
48
|
+
WORKTREE_PATH=$(worktree-pool claim --issue 42 --branch feature/42-add-dashboard)
|
|
49
|
+
cd "$WORKTREE_PATH"
|
|
50
|
+
|
|
51
|
+
# Return worktree to pool when done
|
|
52
|
+
worktree-pool return --path "$WORKTREE_PATH"
|
|
53
|
+
|
|
54
|
+
# Clean up stale worktrees
|
|
55
|
+
worktree-pool gc
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## How It Works
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
replenish claim return
|
|
62
|
+
| | |
|
|
63
|
+
v v v
|
|
64
|
+
origin/main ──> [warm worktree] ──> [assigned] ──> [recycled/warm]
|
|
65
|
+
npm install rename to reset to
|
|
66
|
+
+ build feature branch temp branch
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
1. **Replenish** creates worktrees from `origin/main` on temp branches, runs `npm install` and builds
|
|
70
|
+
2. **Claim** renames a warm worktree, switches to your feature branch — instant setup (~2s)
|
|
71
|
+
3. **Return** recycles the worktree back to pool on a fresh temp branch
|
|
72
|
+
4. **GC** removes stale entries (>72h) and reconciles disk state vs pool state
|
|
73
|
+
|
|
74
|
+
### Pool State
|
|
75
|
+
|
|
76
|
+
Pool state is stored in `worktrees/.pool-state.json` (automatically gitignored). Each worktree transitions through:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
creating -> warming -> warm -> assigned -> recycling -> warm
|
|
80
|
+
-> destroying
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Concurrent access is protected by atomic `mkdir`-based file locking.
|
|
84
|
+
|
|
85
|
+
## Configuration
|
|
86
|
+
|
|
87
|
+
Default pool settings (configurable via `.pool-state.json`):
|
|
88
|
+
|
|
89
|
+
| Setting | Default | Description |
|
|
90
|
+
|---------|---------|-------------|
|
|
91
|
+
| `target_spares` | 5 | Number of warm spares to maintain |
|
|
92
|
+
| `max_pool_size` | 10 | Maximum total worktrees in pool |
|
|
93
|
+
| `stale_after_hours` | 72 | Hours before a warm worktree is considered stale |
|
|
94
|
+
|
|
95
|
+
## Integration
|
|
96
|
+
|
|
97
|
+
Works with [ai-dossier](https://github.com/imboard-ai/ai-dossier) workflows:
|
|
98
|
+
|
|
99
|
+
- `setup-issue-workflow` v1.6.0+ auto-claims from pool when available
|
|
100
|
+
- `full-cycle-issue` v2.5.0+ returns worktrees to pool after merge
|
|
101
|
+
- `batch-issues.sh --pool` pre-warms before spawning agents
|
|
102
|
+
|
|
103
|
+
### Batch Example
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
# Pre-warm pool, then spawn agents for issues 100-105
|
|
107
|
+
./scripts/batch-issues.sh --pool 100..105
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Development
|
|
111
|
+
|
|
112
|
+
Part of the [ai-dossier](https://github.com/imboard-ai/ai-dossier) monorepo.
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npm run build -w packages/worktree-pool # build
|
|
116
|
+
npm run test -w packages/worktree-pool # test
|
|
117
|
+
make build-pool # build via Makefile
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## License
|
|
121
|
+
|
|
122
|
+
[AGPL-3.0](https://github.com/imboard-ai/ai-dossier/blob/main/LICENSE)
|