# 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.