@ai-dossier/worktree-pool 0.1.1 → 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 +55 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# @ai-dossier/worktree-pool
|
|
2
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
|
+
|
|
3
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.
|
|
4
8
|
|
|
5
9
|
## Install
|
|
@@ -14,6 +18,8 @@ Or use directly with npx:
|
|
|
14
18
|
npx @ai-dossier/worktree-pool status
|
|
15
19
|
```
|
|
16
20
|
|
|
21
|
+
Requires Node.js >= 20.0.0.
|
|
22
|
+
|
|
17
23
|
## Commands
|
|
18
24
|
|
|
19
25
|
| Command | Description |
|
|
@@ -51,11 +57,41 @@ worktree-pool gc
|
|
|
51
57
|
|
|
52
58
|
## How It Works
|
|
53
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
|
+
|
|
54
69
|
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
|
|
70
|
+
2. **Claim** renames a warm worktree, switches to your feature branch — instant setup (~2s)
|
|
56
71
|
3. **Return** recycles the worktree back to pool on a fresh temp branch
|
|
57
72
|
4. **GC** removes stale entries (>72h) and reconciles disk state vs pool state
|
|
58
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
|
+
|
|
59
95
|
## Integration
|
|
60
96
|
|
|
61
97
|
Works with [ai-dossier](https://github.com/imboard-ai/ai-dossier) workflows:
|
|
@@ -64,6 +100,23 @@ Works with [ai-dossier](https://github.com/imboard-ai/ai-dossier) workflows:
|
|
|
64
100
|
- `full-cycle-issue` v2.5.0+ returns worktrees to pool after merge
|
|
65
101
|
- `batch-issues.sh --pool` pre-warms before spawning agents
|
|
66
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
|
+
|
|
67
120
|
## License
|
|
68
121
|
|
|
69
|
-
AGPL-3.0-
|
|
122
|
+
[AGPL-3.0](https://github.com/imboard-ai/ai-dossier/blob/main/LICENSE)
|