# Working On Worker

> Cloudflare Worker development conventions for Savecraft. Use when working on files in worker/, including the push API, SourceHub/UserHub Durable Objects, WebSocket protocol, D1 schemas, route handling, or Worker tests. Triggers on TypeScript Worker code, Miniflare, Vitest, Durable Objects, wrangler, or Worker deployment.

- Skill: `joshsymonds/working-on-worker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add joshsymonds/working-on-worker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshsymonds/working-on-worker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: joshsymonds (https://skillmd.com/u/joshsymonds)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/joshsymonds/working-on-worker

---


# Working on the Worker

Read `docs/worker.md` for the full architecture reference.

## Verification

```bash
just test-worker   # Vitest + Miniflare
```

## TypeScript Rules

**Type safety:**
- Never use `any` — use `unknown` if type is truly unknown.
- Never use `@ts-ignore` or `@ts-expect-error` — fix the type issue properly.
- Strict mode enabled. Avoid type assertions except after type guards.
- Never use `!` non-null assertion without a preceding check.

**State & data:**
- Discriminated unions for state machines and message types. Never use boolean flags for multiple states.
- Exhaustive checking with `never` type in switch defaults.
- Use `readonly` for properties unless mutation is needed. Never mutate parameters.

**Null handling:**
- Always handle null/undefined explicitly.
- Use optional chaining (`?.`) and nullish coalescing (`??`).

**Error handling:**
- Custom error classes for different error types. Never throw strings — always `Error` objects.
- Never ignore Promise rejections.

**eslint-enforced (CI will fail):**
- `T[]` not `Array<T>` — eslint `array-type` rule.
- `toSorted((a, b) => a.localeCompare(b))` not `sort()` — eslint unicorn/sonarjs rules.
- Max function complexity: 15. Split into helper functions to stay under.

**Never do:**
- Use `any`, `var`, `==`, `@ts-ignore`, bare `!` assertions.
- Mutate function parameters.
- Skip runtime validation for external data (API responses, user input).

## MCP Handler

The MCP server is a **hand-rolled JSON-RPC 2.0 handler**. Do NOT use `@modelcontextprotocol/sdk` — it depends on ajv/express/hono which are CJS and incompatible with the workerd runtime.

- Handler: `src/mcp/handler.ts` (protocol routing)
- Tools: `src/mcp/tools.ts` (pure tool functions)
- The `agents` npm package (v0.6.0) replaces the deprecated `@cloudflare/agents`.

See `docs/mcp.md` for the full tool contracts and OAuth architecture.

## Test Infrastructure

**Sharded parallelism:** `just test-worker` runs 4 vitest shards in parallel (`worker/scripts/test-sharded.mjs`), each with its own Miniflare instance. This sidesteps Miniflare's `isolatedStorage` WAL bug while giving true file-level parallelism. `npm test` still works for single-shard runs.

**Within each shard** (`vitest.config.ts`): `singleWorker: true` + `isolatedStorage: false` + `fileParallelism: false` — files run serially sharing one Miniflare instance per shard.

**Test lifecycle:**

- `setup.ts`: Creates tables (migrations) + one-time cleanup at suite start.
- `helpers.ts`: `cleanAll()` batch-deletes all D1 tables (FK-safe order) + R2 objects.
- **Every `describe` block** must have `beforeEach(cleanAll)` — NOT at module level. Module-level `beforeEach` leaks to all test files in singleWorker mode.
- **Always consume DO fetch responses** (call `.json()` or `.text()`) — unconsumed responses leave SQLite WAL files that break `isolatedStorage` if ever re-enabled.

**DO gotcha:** `DurableObject.ctx.id.toString()` returns a hex hash, NOT the original `idFromName()` string. Pass the real `userUuid` via `X-User-UUID` header if you need it inside the DO.

**Test tokens:** `getOAuthToken(userUuid)` in `test/helpers.ts` uses `getOAuthApi()` to mint real library tokens via KV without Clerk. No dev-mode code in production.

**IDE noise:** `ProvidedEnv` TS errors in tests are IDE-only; runtime works fine via Miniflare.

## Key Paths

```
worker/src/index.ts          # Routes, request handling, OAuthProvider wrapper
worker/src/hub.ts            # SourceHub Durable Object (per-source, daemon WebSocket + state)
worker/src/user-hub.ts       # UserHub Durable Object (per-user, UI WebSocket + aggregation)
worker/src/auth.ts           # Session/daemon auth (stub mode + Clerk mode)
worker/src/oauth.ts          # OAuth endpoint config, OAUTH_ENDPOINTS constant
worker/src/mcp/handler.ts    # JSON-RPC 2.0 protocol handler
worker/src/mcp/tools.ts      # Pure MCP tool functions
worker/test/helpers.ts       # cleanAll(), getOAuthToken(), test utilities
worker/test/setup.ts         # Table creation, one-time cleanup
worker/vitest.config.ts      # Per-shard config (singleWorker + isolatedStorage)
worker/scripts/test-sharded.mjs # Parallel shard runner (4 vitest processes)
worker/wrangler.toml         # Bindings, D1, R2, KV, DO
```