61cce7e380
- Add optFromDb generic helper for nullable DbValue conversion - Extract rowToWorkerInfo helper in state.nim (dedup getWorker/getAllWorkers) - Extract loadContextFromPath helper in context.nim (dedup readContext/findContext) - Simplify poll() using optFromDb for optional field extraction - Add developer guide for compiling, testing, and deployment Closes: skills-r3k, skills-luzk, skills-dszn, skills-m0e2 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
116 lines
3.1 KiB
Markdown
116 lines
3.1 KiB
Markdown
# Worker CLI Developer Guide
|
|
|
|
Quick reference for compiling, testing, and deploying the worker CLI.
|
|
|
|
## Prerequisites
|
|
|
|
- Nim 2.2+ (via `nix-shell -p nim`)
|
|
- SQLite library (`libsqlite3.so`)
|
|
- Git
|
|
|
|
## Compiling
|
|
|
|
```bash
|
|
# Standard build
|
|
nix-shell -p nim --run "nim c -d:release --mm:orc src/worker.nim"
|
|
|
|
# Output: src/worker.out
|
|
```
|
|
|
|
Build options in `src/config.nims`:
|
|
- `--mm:orc` - ORC memory management (handles cycles)
|
|
- `--threads:on` - Background heartbeat thread
|
|
- `--opt:size` - Smaller binary
|
|
- `-d:release` - Optimizations
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run test suite (requires sqlite3 in PATH)
|
|
LD_LIBRARY_PATH=/path/to/sqlite/lib \
|
|
PATH=$PATH:/path/to/sqlite/bin \
|
|
src/worker/tests/test-worker.sh
|
|
```
|
|
|
|
On NixOS, find sqlite paths:
|
|
```bash
|
|
find /nix/store -name "libsqlite3.so" | head -1
|
|
find /nix/store -name "sqlite3" -type f | grep bin | head -1
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── worker.nim # CLI dispatch, command implementations
|
|
├── config.nims # Nim build configuration
|
|
├── worker.nimble # Package metadata
|
|
└── worker/
|
|
├── types.nim # Shared types, constants, errors
|
|
├── db.nim # SQLite operations, message bus
|
|
├── state.nim # State machine transitions
|
|
├── git.nim # Worktree operations
|
|
├── context.nim # Worker context file handling
|
|
├── heartbeat.nim # Background heartbeat thread
|
|
├── review.nim # Review-gate integration
|
|
├── utils.nim # Common helpers
|
|
└── tests/
|
|
└── test-worker.sh # Integration test suite
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
Managed via nimble (`src/worker.nimble`):
|
|
- `tiny_sqlite` - SQLite wrapper with RAII
|
|
- `cligen` - CLI generation from proc signatures
|
|
|
|
Install dependencies:
|
|
```bash
|
|
nimble install tiny_sqlite cligen
|
|
```
|
|
|
|
## Deployment
|
|
|
|
The worker binary needs `libsqlite3.so` at runtime. Options:
|
|
|
|
1. **System sqlite**: Ensure sqlite is installed system-wide
|
|
2. **LD_LIBRARY_PATH**: Point to sqlite library location
|
|
3. **Static linking**: Compile with `-d:staticSqlite` (requires sqlite source)
|
|
|
|
Copy binary to PATH:
|
|
```bash
|
|
cp src/worker.out ~/.local/bin/worker
|
|
chmod +x ~/.local/bin/worker
|
|
```
|
|
|
|
## Runtime Files
|
|
|
|
The worker CLI creates these files:
|
|
- `.worker-state/bus.db` - SQLite database (WAL mode)
|
|
- `.review-state/*.json` - Review gate state files
|
|
- `worktrees/<task-id>/` - Git worktrees for workers
|
|
- `worktrees/<task-id>/.worker-ctx.json` - Worker context
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Constant | Meaning |
|
|
|------|----------|---------|
|
|
| 0 | ExitSuccess | Success |
|
|
| 2 | ExitUsageError | Invalid arguments |
|
|
| 3 | ExitInvalidTransition | Invalid state transition |
|
|
| 4 | ExitGitError | Git operation failed |
|
|
| 5 | ExitDbError | Database error |
|
|
| 6 | ExitConflict | Merge/rebase conflict |
|
|
| 7 | ExitNotFound | Worker not found |
|
|
|
|
## Common Issues
|
|
|
|
**"could not load: libsqlite3.so"**
|
|
Set `LD_LIBRARY_PATH` to include sqlite library directory.
|
|
|
|
**Tests show "NOT_FOUND" for state queries**
|
|
Ensure `sqlite3` CLI is in PATH for test helper functions.
|
|
|
|
**"Cannot start: Expected ASSIGNED, got WORKING"**
|
|
Worker already started. Use `worker status` to check state.
|