Development Workflow

Full guide: docs/development.md

Quick Command Reference

npm run build          # tsc --build (all packages via project references)
npm run lint           # eslint "packages/**/*.ts"
npm run format         # prettier
npm run test           # vitest run (unit tests, excludes *.e2e.test.ts)
npm run test:e2e       # vitest e2e (CDK synth E2E tests)
npm run skills:sync    # sync shared skills into Claude/Codex mirrors
npm run skills:check   # verify shared skill mirrors are in sync

# Single test file
npx vitest run packages/gateway/__tests__/handlers/ws-connect.test.ts

# Single test by name
npx vitest run -t "should verify JWT"

Package Structure (6 packages)

packages/
├── shared/      # Types + constants (TABLE_NAMES, BRIDGE_PORT, key prefixes)
├── cdk/         # CDK stacks (lib/stacks/)
├── gateway/     # 7 Lambda handlers (ws-connect/message/disconnect, telegram-webhook, api-handler, watchdog, prewarm)
├── container/   # Fargate container (Bridge server + OpenClaw JSON-RPC client)
├── lambda-agent/ # Lambda agent (Phase 2 — OpenClaw embedded in Lambda)
└── web/         # React SPA (Vite, amazon-cognito-identity-js for auth)

Git Hooks (husky)

Hook	Checks
pre-commit	npm run build + npm run lint + unit tests
pre-push	E2E tests (CDK synth verification)

TDD Rules

• Tests first for all packages except web
• Write test → watch it fail → implement → watch it pass
• Unit tests: packages/<pkg>/__tests__/
• E2E tests: packages/<pkg>/__tests__/*.e2e.test.ts

Import Path Rule

TypeScript uses NodeNext module resolution. All imports must use .js extension:

// Correct
import { TABLE_NAMES } from "@serverless-openclaw/shared/constants.js";
import { routeMessage } from "../services/message.js";

// Wrong — omitting .js will fail at runtime
import { TABLE_NAMES } from "@serverless-openclaw/shared/constants";

Coding Conventions

• DI pattern: Inject send function (same pattern as container package)
• AWS SDK send binding: ddb.send.bind(ddb) as (cmd: any) => Promise<any> cast needed
• vi.mock hoisting: Use vi.hoisted() when referencing variables in module-level mocks
• npm workspaces: Use "*" for local dependencies ("workspace:*" is pnpm-only)
• TypeScript: ES2022, Node16 module resolution, strict, composite builds