Skip to content

Contributing

Workbus is one package, packages/workbus, and one template, templates/factory. To work on it: install, run a board, and run the checks below. Verify a claim with a real run, and break the code a test covers once to see the test fail.

Terminal window
npx pnpm@11.23.0 install
cd packages/workbus
npx tsc --noEmit -p . # TS2589 "excessively deep" is known noise
npx vitest run # the workerd suite: the real Ledger, Relay, Mailbox, and Inbox
Test Files 10 passed (10)
Tests 40 passed (40)
Start at 15:21:24
Duration 36.25s (tests 83%, transform 15%, import 2%)
  • Directorypackages/workbus/src
    • Directoryledger/
      • ledger.ts the Ledger: call(), the alarm, rings, dispatch
      • ops.ts op(name, fn, { read }), hooks, Ctx, timers
      • core.ts principals, callers, access, actors, the log, views
      • messages.ts, feed.ts, tasks.ts, grants.ts, schemas.ts, schedules.ts, files.ts, watchers.ts, sync.ts
      • archive.ts sealed segments, cold threads, frozen pages
      • schema.ts the tables
    • Directoryprotocol/ the routes and their zod schemas, per domain; rpc.ts (Cap’n Web), mcp.ts (MCP)
      • …
    • Directorygateway/ routing, auth.ts, held waits, SSE
      • …
    • Directorysync/ GitHub, Slack, Linear, and Notion providers, inbox.ts, courier.ts, docfiles.ts, secrets.ts
      • …
    • binding.ts the Workbus entrypoint and the Board, Tasks, and Claim capabilities
    • relay.ts, mailbox.ts
    • index.ts defineWorkbus
  • Directorypackages/workbus/cli/ the wb CLI and its tests
    • …
  • Directorypackages/workbus/scripts/ the issuer, benchmarks, and archival checks
    • …
  • Directorypackages/workbus/test/ the workerd suite and the external checks
    • …
  • Directorytemplates/factory/
    • …

An operation is a function registered with op(name, fn). It gets a Ctx (the board, the caller, what it may do, and now), runs in one synchronous transaction, and throws a WorkbusError to refuse. A domain that extends messages or reads sets a hooks entry. A route is route({ name, method, path, query | body }) in protocol/, and the Gateway and the Board capability both check inputs against it. The Ledger explains why.

Code is erasable TypeScript only (erasableSyntaxOnly is on): no parameter properties, enums, or namespaces.

Terminal window
cd packages/workbus
node scripts/issuer.mjs key # .issuer.json and .dev.vars, once
npx wrangler dev --port 8787 --ip 127.0.0.1
node scripts/issuer.mjs token jared http://127.0.0.1:8787/b/dev # a person's token, 12 hours

Then use it with the CLI from source:

Terminal window
export WORKBUS_URL=http://127.0.0.1:8787/b/dev WORKBUS_TOKEN=<token>
node cli/workbus.mjs whoami
Check Command What it covers
Types npx tsc --noEmit -p . the package
The workerd suite npx vitest run the Ledger, Relay, Mailbox, and Inbox on real SQLite storage, with the Gateway in front
The CLI WORKBUS_TEST_ORIGIN=http://127.0.0.1:8787 node --test cli/test/ 36 end-to-end tests against a running board
Webhook verification node --test test/sync/providers.node-test.ts each provider’s signatures and mapping
Archival node scripts/archive-check.mjs http://127.0.0.1:8787 every answer the same on a board archived before each request
Slack and Linear test/providers-worker/check.mjs signed requests, each delivery twice, recording stand-ins; setup at its top
The service binding test/binding-client/ narrowing, pinning, forged props, no principal; setup at its top
Cap’n Web node test/capnweb-client.mjs <board url> <token> WebSocket and HTTP batch sessions
The Factory’s GitHub sync templates/factory/test/github-check.mjs issues, comments, and replies, with GitHub’s API stood in

Runs of the first four and the archival check while these docs were written:

$ WORKBUS_TEST_ORIGIN=http://127.0.0.1:8823 node --test cli/test/
ℹ tests 36
ℹ suites 8
ℹ pass 36
ℹ fail 0
$ node --test test/sync/providers.node-test.ts
✔ Slack: the bot's own reaction is the courier's echo, a person's is an event (0.059708ms)
ℹ tests 13
ℹ pass 13
ℹ fail 0
$ node scripts/archive-check.mjs http://127.0.0.1:8823
{
"compared": 317,
"coldReads": 304,
"differences": 0,

The workerd suite gets a fresh issuer key each run and runs with archival off (ARCHIVE: 'off' in vitest.config.ts).

The protocol’s conformance kit checks a board as a black box, over HTTP, with no knowledge of how it’s built. Run its conformance --json with BOARD_URL set to a fresh board’s URL and BOARD_TOKEN to a token for it. The board serves its routes at /b/<name>/openapi.json.

On wrangler dev and on the live deployment it passes 85 and skips 6 as an owner, and passes 86 and skips 5 as a member. A change to behavior that the protocol describes should keep it there.

  • Prove it with a real run. A claim in a doc, a commit, or a status line is backed by a test or a run you can paste.
  • Break it once. A new test fails when you break the code it covers, before you trust it.
  • Keep a write one transaction. An operation never awaits. If it needs something in R2, it faults and runs again (see Archival tiers).
  • Keep provenance server-side. Who wrote something comes from the verified caller, never from a request body.
  • Never commit secrets. .dev.vars and .issuer*.json are gitignored.

AGENTS.md is the same guide for agents working in the repo, and Status is what’s built and how it’s verified.