@laurentenhoor/devclaw 0.1.0

package/docs/TESTING.md

@@ -0,0 +1,339 @@
+# DevClaw Testing Guide
+
+Comprehensive automated testing for DevClaw onboarding and setup.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Run all tests
+npm test
+
+# Run with coverage report
+npm run test:coverage
+
+# Run in watch mode (auto-rerun on changes)
+npm run test:watch
+
+# Run with UI (browser-based test explorer)
+npm run test:ui
+```
+
+## Test Coverage
+
+### Scenario 1: New User (No Prior DevClaw Setup)
+**File:** `tests/setup/new-user.test.ts`
+
+**What's tested:**
+- First-time agent creation with default models
+- Channel binding creation (telegram/whatsapp)
+- Workspace file generation (AGENTS.md, HEARTBEAT.md, projects/, log/)
+- Plugin configuration initialization
+- Error handling: channel not configured
+- Error handling: channel disabled
+
+**Example:**
+```typescript
+// Before: openclaw.json has no DevClaw agents
+{
+  "agents": { "list": [{ "id": "main", ... }] },
+  "bindings": [],
+  "plugins": { "entries": {} }
+}
+
+// After: New orchestrator created
+{
+  "agents": {
+    "list": [
+      { "id": "main", ... },
+      { "id": "my-first-orchestrator", ... }
+    ]
+  },
+  "bindings": [
+    { "agentId": "my-first-orchestrator", "match": { "channel": "telegram" } }
+  ],
+  "plugins": {
+    "entries": {
+      "devclaw": {
+        "config": {
+          "models": {
+            "dev": {
+              "junior": "anthropic/claude-haiku-4-5",
+              "medior": "anthropic/claude-sonnet-4-5",
+              "senior": "anthropic/claude-opus-4-5"
+            },
+            "qa": {
+              "reviewer": "anthropic/claude-sonnet-4-5",
+              "tester": "anthropic/claude-haiku-4-5"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Scenario 2: Existing User (Migration)
+**File:** `tests/setup/existing-user.test.ts`
+
+**What's tested:**
+- Channel conflict detection (existing channel-wide binding)
+- Binding migration from old agent to new agent
+- Custom model preservation during migration
+- Old agent preservation (not deleted)
+- Error handling: migration source doesn't exist
+- Error handling: migration source has no binding
+
+**Example:**
+```typescript
+// Before: Old orchestrator has telegram binding
+{
+  "agents": {
+    "list": [
+      { "id": "main", ... },
+      { "id": "old-orchestrator", ... }
+    ]
+  },
+  "bindings": [
+    { "agentId": "old-orchestrator", "match": { "channel": "telegram" } }
+  ]
+}
+
+// After: Binding migrated to new orchestrator
+{
+  "agents": {
+    "list": [
+      { "id": "main", ... },
+      { "id": "old-orchestrator", ... },
+      { "id": "new-orchestrator", ... }
+    ]
+  },
+  "bindings": [
+    { "agentId": "new-orchestrator", "match": { "channel": "telegram" } }
+  ]
+}
+```
+
+### Scenario 3: Power User (Multiple Agents)
+**File:** `tests/setup/power-user.test.ts`
+
+**What's tested:**
+- No conflicts with group-specific bindings
+- Channel-wide binding creation alongside group bindings
+- Multiple orchestrators coexisting
+- Routing logic (specific bindings win over channel-wide)
+- WhatsApp support
+- Scale testing (12+ orchestrators)
+
+**Example:**
+```typescript
+// Before: Two project orchestrators with group-specific bindings
+{
+  "agents": {
+    "list": [
+      { "id": "project-a-orchestrator", ... },
+      { "id": "project-b-orchestrator", ... }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "project-a-orchestrator",
+      "match": { "channel": "telegram", "peer": { "kind": "group", "id": "-1001234567890" } }
+    },
+    {
+      "agentId": "project-b-orchestrator",
+      "match": { "channel": "telegram", "peer": { "kind": "group", "id": "-1009876543210" } }
+    }
+  ]
+}
+
+// After: Channel-wide orchestrator added (no conflicts)
+{
+  "agents": {
+    "list": [
+      { "id": "project-a-orchestrator", ... },
+      { "id": "project-b-orchestrator", ... },
+      { "id": "global-orchestrator", ... }
+    ]
+  },
+  "bindings": [
+    {
+      "agentId": "project-a-orchestrator",
+      "match": { "channel": "telegram", "peer": { "kind": "group", "id": "-1001234567890" } }
+    },
+    {
+      "agentId": "project-b-orchestrator",
+      "match": { "channel": "telegram", "peer": { "kind": "group", "id": "-1009876543210" } }
+    },
+    {
+      "agentId": "global-orchestrator",
+      "match": { "channel": "telegram" }  // Channel-wide (no peer)
+    }
+  ]
+}
+
+// Routing: Group messages go to specific agents, everything else goes to global
+```
+
+## Test Architecture
+
+### Mock File System
+The tests use an in-memory mock file system (`MockFileSystem`) that simulates:
+- Reading/writing openclaw.json
+- Creating/reading workspace files
+- Tracking command executions (openclaw agents add)
+
+**Why?** Tests run in isolation without touching the real file system, making them:
+- Fast (no I/O)
+- Reliable (no file conflicts)
+- Repeatable (clean state every test)
+
+### Fixtures
+Pre-built configurations for different user types:
+- `createNewUserConfig()` - Empty slate
+- `createCommonUserConfig()` - One orchestrator with binding
+- `createPowerUserConfig()` - Multiple orchestrators with group bindings
+- `createNoChannelConfig()` - Channel not configured
+- `createDisabledChannelConfig()` - Channel disabled
+
+### Assertions
+Reusable assertion helpers that make tests readable:
+```typescript
+assertAgentExists(mockFs, "my-agent", "My Agent");
+assertChannelBinding(mockFs, "my-agent", "telegram");
+assertWorkspaceFilesExist(mockFs, "my-agent");
+assertDevClawConfig(mockFs, { junior: "anthropic/claude-haiku-4-5" });
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+```yaml
+name: Test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+      - run: npm run test:coverage
+      - uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/coverage-final.json
+```
+
+### GitLab CI
+```yaml
+test:
+  image: node:20
+  script:
+    - npm ci
+    - npm test
+    - npm run test:coverage
+  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+```
+
+## Debugging Tests
+
+### Run specific test
+```bash
+npm test -- new-user              # Run all new-user tests
+npm test -- "should create agent" # Run tests matching pattern
+```
+
+### Debug with Node inspector
+```bash
+node --inspect-brk node_modules/.bin/vitest run
+```
+
+Then open Chrome DevTools at `chrome://inspect`
+
+### View coverage report
+```bash
+npm run test:coverage
+open coverage/index.html
+```
+
+## Adding Tests
+
+### 1. Choose the right test file
+- New feature → `tests/setup/new-user.test.ts`
+- Migration feature → `tests/setup/existing-user.test.ts`
+- Multi-agent feature → `tests/setup/power-user.test.ts`
+
+### 2. Write the test
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { MockFileSystem } from "../helpers/mock-fs.js";
+import { createNewUserConfig } from "../helpers/fixtures.js";
+import { assertAgentExists } from "../helpers/assertions.js";
+
+describe("My new feature", () => {
+  let mockFs: MockFileSystem;
+
+  beforeEach(() => {
+    mockFs = new MockFileSystem(createNewUserConfig());
+  });
+
+  it("should do something useful", async () => {
+    // GIVEN: initial state (via fixture)
+    const beforeCount = countAgents(mockFs);
+
+    // WHEN: execute the operation
+    const config = mockFs.getConfig();
+    config.agents.list.push({
+      id: "test-agent",
+      name: "Test Agent",
+      workspace: "/home/test/.openclaw/workspace-test-agent",
+      agentDir: "/home/test/.openclaw/agents/test-agent/agent",
+    });
+    mockFs.setConfig(config);
+
+    // THEN: verify the outcome
+    assertAgentExists(mockFs, "test-agent", "Test Agent");
+    expect(countAgents(mockFs)).toBe(beforeCount + 1);
+  });
+});
+```
+
+### 3. Run your test
+```bash
+npm test -- "should do something useful"
+```
+
+## Best Practices
+
+### ✅ DO
+- Test one thing per test
+- Use descriptive test names ("should create agent with telegram binding")
+- Use fixtures for initial state
+- Use assertion helpers for readability
+- Test error cases
+
+### ❌ DON'T
+- Test implementation details (test behavior, not internals)
+- Share state between tests (use beforeEach)
+- Mock everything (only mock file system and commands)
+- Write brittle tests (avoid hard-coded UUIDs, timestamps)
+
+## Test Metrics
+
+Current coverage:
+- **Lines:** Target 80%+
+- **Functions:** Target 90%+
+- **Branches:** Target 75%+
+
+Run `npm run test:coverage` to see detailed metrics.

package/docs/TOOLS.md

@@ -0,0 +1,361 @@
+# DevClaw — Tools Reference
+
+Complete reference for all 11 tools registered by DevClaw. See [`index.ts`](../index.ts) for registration.
+
+## Worker Lifecycle
+
+### `work_start`
+
+Pick up a task from the issue queue. Handles level assignment, label transition, session creation/reuse, task dispatch, and audit logging — all in one call.
+
+**Source:** [`lib/tools/work-start.ts`](../lib/tools/work-start.ts)
+
+**Context:** Only works in project group chats.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `issueId` | number | No | Issue ID. If omitted, picks next by priority. |
+| `role` | `"dev"` \| `"qa"` | No | Worker role. Auto-detected from issue label if omitted. |
+| `projectGroupId` | string | No | Project group ID. Auto-detected from group context. |
+| `level` | string | No | Developer level (`junior`, `medior`, `senior`, `reviewer`). Auto-detected if omitted. |
+
+**What it does atomically:**
+
+1. Resolves project from `projects.json`
+2. Validates no active worker for this role
+3. Fetches issue from tracker, verifies correct label state
+4. Assigns level (LLM-chosen via `level` param → label detection → keyword heuristic fallback)
+5. Resolves level to model ID via config or defaults
+6. Loads prompt instructions from `projects/roles/<project>/<role>.md`
+7. Looks up existing session for assigned level (session-per-level)
+8. Transitions label (e.g. `To Do` → `Doing`)
+9. Creates session via Gateway RPC if new (`sessions.patch`)
+10. Dispatches task to worker session via CLI (`openclaw gateway call agent`)
+11. Updates `projects.json` state (active, issueId, level, session key)
+12. Writes audit log entries (work_start + model_selection)
+13. Sends notification
+14. Returns announcement text
+
+**Level selection priority:**
+
+1. `level` parameter (LLM-selected) — highest priority
+2. Issue label (e.g. a label named "junior" or "senior")
+3. Keyword heuristic from `model-selector.ts` — fallback
+
+**Execution guards:**
+
+- Rejects if role already has an active worker
+- Respects `roleExecution` (sequential: rejects if other role is active)
+
+**On failure:** Rolls back label transition. No orphaned state.
+
+---
+
+### `work_finish`
+
+Complete a task with a result. Called by workers (DEV/QA sub-agent sessions) directly, or by the orchestrator.
+
+**Source:** [`lib/tools/work-finish.ts`](../lib/tools/work-finish.ts)
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `role` | `"dev"` \| `"qa"` | Yes | Worker role |
+| `result` | string | Yes | Completion result (see table below) |
+| `projectGroupId` | string | Yes | Project group ID |
+| `summary` | string | No | Brief summary for the announcement |
+| `prUrl` | string | No | PR/MR URL (auto-detected if omitted) |
+
+**Valid results by role:**
+
+| Role | Result | Label transition | Side effects |
+|---|---|---|---|
+| DEV | `"done"` | Doing → To Test | git pull, auto-detect PR URL |
+| DEV | `"blocked"` | Doing → To Do | Task returns to queue |
+| QA | `"pass"` | Testing → Done | Issue closed |
+| QA | `"fail"` | Testing → To Improve | Issue reopened |
+| QA | `"refine"` | Testing → Refining | Awaits human decision |
+| QA | `"blocked"` | Testing → To Test | Task returns to QA queue |
+
+**What it does atomically:**
+
+1. Validates role:result combination
+2. Resolves project and active worker
+3. Executes completion via pipeline service (label transition + side effects)
+4. Deactivates worker (sessions map preserved for reuse)
+5. Sends notification
+6. Ticks queue to fill free worker slots
+7. Writes audit log
+
+**Scheduling:** After completion, `work_finish` ticks the queue. The scheduler sees the new label (`To Test` or `To Improve`) and dispatches the next worker if a slot is free.
+
+---
+
+## Task Management
+
+### `task_create`
+
+Create a new issue in the project's issue tracker.
+
+**Source:** [`lib/tools/task-create.ts`](../lib/tools/task-create.ts)
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `projectGroupId` | string | Yes | Project group ID |
+| `title` | string | Yes | Issue title |
+| `description` | string | No | Full issue body (markdown) |
+| `label` | StateLabel | No | State label. Defaults to `"Planning"`. |
+| `assignees` | string[] | No | GitHub/GitLab usernames to assign |
+| `pickup` | boolean | No | If true, immediately pick up for DEV after creation |
+
+**Use cases:**
+
+- Orchestrator creates tasks from chat messages
+- Workers file follow-up bugs discovered during development
+- Breaking down epics into smaller tasks
+
+**Default behavior:** Creates issues in `"Planning"` state. Only use `"To Do"` when the user explicitly requests immediate work.
+
+---
+
+### `task_update`
+
+Change an issue's state label manually without going through the full pickup/complete flow.
+
+**Source:** [`lib/tools/task-update.ts`](../lib/tools/task-update.ts)
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `projectGroupId` | string | Yes | Project group ID |
+| `issueId` | number | Yes | Issue ID to update |
+| `state` | StateLabel | Yes | New state label |
+| `reason` | string | No | Audit log reason for the change |
+
+**Valid states:** `Planning`, `To Do`, `Doing`, `To Test`, `Testing`, `Done`, `To Improve`, `Refining`
+
+**Use cases:**
+
+- Manual state adjustments (e.g. `Planning → To Do` after approval)
+- Failed auto-transitions that need correction
+- Bulk state changes by orchestrator
+
+---
+
+### `task_comment`
+
+Add a comment to an issue for feedback, notes, or discussion.
+
+**Source:** [`lib/tools/task-comment.ts`](../lib/tools/task-comment.ts)
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `projectGroupId` | string | Yes | Project group ID |
+| `issueId` | number | Yes | Issue ID to comment on |
+| `body` | string | Yes | Comment body (markdown) |
+| `authorRole` | `"dev"` \| `"qa"` \| `"orchestrator"` | No | Attribution role prefix |
+
+**Use cases:**
+
+- QA adds review feedback before pass/fail decision
+- DEV posts implementation notes or progress updates
+- Orchestrator adds summary comments
+
+When `authorRole` is provided, the comment is prefixed with a role emoji and attribution label.
+
+---
+
+## Operations
+
+### `status`
+
+Lightweight queue + worker state dashboard.
+
+**Source:** [`lib/tools/status.ts`](../lib/tools/status.ts)
+
+**Context:** Auto-filters to project in group chats. Shows all projects in DMs.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `projectGroupId` | string | No | Filter to specific project. Omit for all. |
+
+**Returns per project:**
+
+- Worker state: active/idle, current issue, level, start time
+- Queue counts: To Do, To Test, To Improve
+- Role execution mode
+
+---
+
+### `health`
+
+Worker health scan with optional auto-fix.
+
+**Source:** [`lib/tools/health.ts`](../lib/tools/health.ts)
+
+**Context:** Auto-filters to project in group chats.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `projectGroupId` | string | No | Filter to specific project. Omit for all. |
+| `fix` | boolean | No | Apply fixes for detected issues. Default: `false` (read-only). |
+| `activeSessions` | string[] | No | Active session IDs for zombie detection. |
+
+**Health checks:**
+
+| Issue | Severity | Detection | Auto-fix |
+|---|---|---|---|
+| Active worker with no session key | Critical | `active=true` but no session in map | Deactivate worker |
+| Active worker whose session is dead | Critical | Session key not in active sessions list | Deactivate worker, revert label |
+| Worker active >2 hours | Warning | `startTime` older than 2h | Deactivate worker, revert label to queue |
+| Inactive worker with lingering issue ID | Warning | `active=false` but `issueId` still set | Clear issueId |
+
+---
+
+### `work_heartbeat`
+
+Manual trigger for heartbeat: health fix + queue dispatch. Same logic as the background heartbeat service, but invoked on demand.
+
+**Source:** [`lib/tools/work-heartbeat.ts`](../lib/tools/work-heartbeat.ts)
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `projectGroupId` | string | No | Target single project. Omit for all. |
+| `dryRun` | boolean | No | Report only, don't dispatch. Default: `false`. |
+| `maxPickups` | number | No | Max worker dispatches per tick. |
+| `activeSessions` | string[] | No | Active session IDs for zombie detection. |
+
+**Two-pass sweep:**
+
+1. **Health pass** — Runs `checkWorkerHealth` per project per role. Auto-fixes zombies, stale workers, orphaned state.
+2. **Tick pass** — Calls `projectTick` per project. Fills free worker slots by priority (To Improve > To Test > To Do).
+
+**Execution guards:**
+
+- `projectExecution: "sequential"` — only one project active at a time
+- `roleExecution: "sequential"` — only one role (DEV or QA) active at a time per project (enforced in `projectTick`)
+
+---
+
+## Setup
+
+### `project_register`
+
+One-time project setup. Creates state labels, scaffolds prompt files, adds project to state.
+
+**Source:** [`lib/tools/project-register.ts`](../lib/tools/project-register.ts)
+
+**Context:** Only works in the Telegram/WhatsApp group being registered.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `projectGroupId` | string | No | Auto-detected from current group if omitted |
+| `name` | string | Yes | Short project name (e.g. `my-webapp`) |
+| `repo` | string | Yes | Path to git repo (e.g. `~/git/my-project`) |
+| `groupName` | string | No | Display name. Defaults to `Project: {name}`. |
+| `baseBranch` | string | Yes | Base branch for development |
+| `deployBranch` | string | No | Deploy branch. Defaults to baseBranch. |
+| `deployUrl` | string | No | Deployment URL |
+| `roleExecution` | `"parallel"` \| `"sequential"` | No | DEV/QA parallelism. Default: `"parallel"`. |
+
+**What it does atomically:**
+
+1. Validates project not already registered
+2. Resolves repo path, auto-detects GitHub/GitLab from git remote
+3. Verifies provider health (CLI installed and authenticated)
+4. Creates all 8 state labels (idempotent — safe to run again)
+5. Adds project entry to `projects.json` with empty worker state
+   - DEV sessions: `{ junior: null, medior: null, senior: null }`
+   - QA sessions: `{ reviewer: null, tester: null }`
+6. Scaffolds prompt files: `projects/roles/<project>/dev.md` and `qa.md`
+7. Writes audit log
+
+---
+
+### `setup`
+
+Agent + workspace initialization.
+
+**Source:** [`lib/tools/setup.ts`](../lib/tools/setup.ts)
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `newAgentName` | string | No | Create a new agent. Omit to configure current workspace. |
+| `channelBinding` | `"telegram"` \| `"whatsapp"` | No | Channel to bind (with `newAgentName` only) |
+| `migrateFrom` | string | No | Agent ID to migrate channel binding from |
+| `models` | object | No | Model overrides per role and level (see [Configuration](CONFIGURATION.md#model-tiers)) |
+| `projectExecution` | `"parallel"` \| `"sequential"` | No | Project execution mode |
+
+**What it does:**
+
+1. Creates a new agent or configures existing workspace
+2. Optionally binds messaging channel (Telegram/WhatsApp)
+3. Optionally migrates channel binding from another agent
+4. Writes workspace files: AGENTS.md, HEARTBEAT.md, `projects/projects.json`
+5. Configures model tiers in `openclaw.json`
+
+---
+
+### `onboard`
+
+Conversational onboarding guide. Returns step-by-step instructions for the agent to walk the user through setup.
+
+**Source:** [`lib/tools/onboard.ts`](../lib/tools/onboard.ts)
+
+**Note:** Call this before `setup` to get step-by-step guidance.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `mode` | `"first-run"` \| `"reconfigure"` | No | Auto-detected from current state |
+
+**Flow:**
+
+1. Call `onboard` — returns QA-style step-by-step instructions
+2. Agent walks user through: agent selection, channel binding, model tiers
+3. Agent calls `setup` with collected answers
+4. User registers projects via `project_register` in group chats
+
+---
+
+## Completion Rules Reference
+
+The pipeline service (`lib/services/pipeline.ts`) defines declarative completion rules:
+
+```
+dev:done    → Doing    → To Test     (git pull, detect PR)
+dev:blocked → Doing    → To Do       (return to queue)
+qa:pass     → Testing  → Done        (close issue)
+qa:fail     → Testing  → To Improve  (reopen issue)
+qa:refine   → Testing  → Refining    (await human decision)
+qa:blocked  → Testing  → To Test     (return to QA queue)
+```
+
+## Issue Priority Order
+
+When the heartbeat or `work_heartbeat` fills free worker slots, issues are prioritized:
+
+1. **To Improve** — QA failures get fixed first (highest priority)
+2. **To Test** — Completed DEV work gets reviewed next
+3. **To Do** — Fresh tasks are picked up last
+
+This ensures the pipeline clears its backlog before starting new work.