dan/skills

dan 61cce7e380 refactor: extract helpers and add developer docs

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

2026-01-11 15:34:15 -08:00

3.1 KiB

Raw Blame History

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

# 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

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

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:

nimble install tiny_sqlite cligen

Deployment

The worker binary needs libsqlite3.so at runtime. Options:

System sqlite: Ensure sqlite is installed system-wide
LD_LIBRARY_PATH: Point to sqlite library location
Static linking: Compile with -d:staticSqlite (requires sqlite source)

Copy binary to PATH:

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.

3.1 KiB Raw Blame History