@wabot-dev/framework 0.9.80 → 2.0.0-beta.0

package/skills/wabot-persistence/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: wabot-persistence
+description: Use when defining entities, repositories, queries, or per-adapter query extensions in Wabot. Covers Entity / IEntityData, @repository, the @query method-name DSL (find/findOne/count/exists/delete + And/Or + operators), @queryExtension, @memExtension / MemoryRepositoryExtension, @pgExtension / PgRepositoryExtension, and how the active adapter is chosen automatically by the project runner.
+---
+
+# Persistence
+
+Wabot ships a small ORM. You write a domain entity, a `@repository`-decorated class with method-name queries, and (optionally) an adapter-specific extension. The project runner picks the adapter automatically based on `DATABASE_URL`.
+
+## Entity
+
+```typescript
+import { Entity, IEntityData } from '@wabot-dev/framework'
+
+export type IGameStatus = 'backlog' | 'playing' | 'finished' | 'abandoned'
+
+export interface IGameData extends IEntityData {
+  userId: string
+  title: string
+  status: IGameStatus
+  hoursPlayed: number
+  addedAt: number
+}
+
+export class Game extends Entity<IGameData> {}
+```
+
+`IEntityData` adds `id?: string`, `createdAt?: number | null`, `discardedAt?: number | null`. The id/createdAt are filled in by the repository on `create`.
+
+`Entity` exposes:
+- `id` (throws if not yet created)
+- `createdAt: Date`
+- `update(partial)` — merges allowed fields and sets `updatedAt`; rejects writes to id/createdAt/discardedAt
+- `wasCreated()`, `validate()`
+- `lockerKey()` — returns the id, so any `Entity` can be passed to `Locker.withKey(...)`
+
+Date values stored on entity data should be epoch milliseconds (`number`) — the `Mapper` and `Storable` deep-copy convert `Date` to ms automatically.
+
+## Repository
+
+```typescript
+import { CrudRepository, query, queryExtension, repository } from '@wabot-dev/framework'
+import { Game, IGameStatus } from './Game'
+import { IGameRepositoryExtensions } from './IGameRepositoryExtensions'
+
+@repository({ table: 'game', constructor: Game })
+export class GameRepository
+  extends CrudRepository<Game, IGameRepositoryExtensions>
+  implements IGameRepositoryExtensions
+{
+  @query() declare findByUserIdAndStatus: (userId: string, status: IGameStatus) => Promise<Game[]>
+  @query() declare countByUserIdAndStatus: (userId: string, status: IGameStatus) => Promise<number>
+  @queryExtension() declare findLongestInBacklog: (userId: string, limit: number) => Promise<Game[]>
+}
+```
+
+The decorator generates concrete implementations for `CrudRepository`'s methods (`find`, `findOrThrow`, `findByIds`, `findAll`, `create`, `update`, `delete`) and for every `@query()` declare. It also installs a lazy `.extension` accessor backed by the active adapter.
+
+`@repository` applies `@singleton()` for you. Inject `GameRepository` directly anywhere.
+
+## `@query` method-name DSL
+
+`@query()` reads the method name and turns it into a structured query. Supported grammar:
+
+- Prefix: `find`, `findOne`, `count`, `exists`, `delete`.
+- Conditions: PascalCase field names joined by `And` / `Or`.
+- Operators (suffix on the field): `Equals` (default), `Not`, `Like`, `NotLike`, `In`, `NotIn`, `Gt`, `Gte`, `Lt`, `Lte`, `IsNull`, `IsNotNull`.
+- Ordering: append `OrderByField[Asc|Desc]` (chain multiple with `And`).
+- Limit: append `LimitN`.
+
+Examples that work:
+
+```typescript
+@query() declare findByUserId: (userId: string) => Promise<Game[]>
+@query() declare findOneByUserIdAndStatus: (userId: string, status: IGameStatus) => Promise<Game | null>
+@query() declare countByStatusInAndAddedAtGt: (statuses: IGameStatus[], addedAt: number) => Promise<number>
+@query() declare existsByTitleLike: (title: string) => Promise<boolean>
+@query() declare deleteByDiscardedAtIsNotNull: () => Promise<void>
+@query() declare findByUserIdOrderByAddedAtAscLimit10: (userId: string) => Promise<Game[]>
+```
+
+Argument count and order must match the conditions left-to-right. `IsNull`/`IsNotNull` take no argument; `In`/`NotIn` take an array.
+
+If your query cannot be expressed by the DSL (joins, aggregates, JSON paths) use `@queryExtension()` instead — see below.
+
+## Adapter extensions
+
+The runner picks one adapter per process:
+
+- `MemoryRepositoryAdapter` when `DATABASE_URL` is missing or not a `postgres://` URL.
+- `PgJsonRepositoryAdapter` when `DATABASE_URL` is a Postgres URL (data is stored as a JSON blob per row).
+
+For each `@queryExtension()` method you must provide one implementation per adapter you support, in classes decorated with `@memExtension(Repo)` and/or `@pgExtension(Repo)`:
+
+```typescript
+import { memExtension, MemoryRepositoryExtension, pgExtension, PgRepositoryExtension } from '@wabot-dev/framework'
+
+@memExtension(GameRepository)
+export class GameMemoryQueries
+  extends MemoryRepositoryExtension<Game>
+  implements IGameRepositoryExtensions
+{
+  async findLongestInBacklog(userId: string, limit: number) {
+    return [...this.items.values()]
+      .filter((g) => g['data'].userId === userId && g['data'].status === 'backlog')
+      .sort((a, b) => a['data'].addedAt - b['data'].addedAt)
+      .slice(0, limit)
+      .map((g) => this.clone(g))
+  }
+}
+
+@pgExtension(GameRepository)
+export class GamePgQueries
+  extends PgRepositoryExtension<Game>
+  implements IGameRepositoryExtensions
+{
+  async findLongestInBacklog(userId: string, limit: number) {
+    const sql = `
+      SELECT ${this['columns']} FROM ${this['table']}
+      WHERE "data"->>'userId' = $1 AND "data"->>'status' = 'backlog'
+      ORDER BY ("data"->>'addedAt')::numeric ASC
+      LIMIT $2
+    `
+    return this['query'](sql, [userId, limit])
+  }
+}
+```
+
+- The extension class must extend `MemoryRepositoryExtension<T>` / `PgRepositoryExtension<T>`. The decorator throws otherwise.
+- Inside a Pg extension, use `this['columns']` / `this['table']` / `this['query'](sql, params)` from `PgRepositoryBase`. The Pg JSON adapter stores fields under a `data` JSONB column.
+- A repository may opt in to only one adapter — if you only ship `@memExtension`, the repository will throw when invoked under Postgres.
+
+## Transactions
+
+Wrap business methods with `@transaction()` — it runs the call inside every registered transaction adapter:
+
+```typescript
+import { transaction } from '@wabot-dev/framework'
+
+class CheckoutService {
+  @transaction()
+  async checkout(orderId: string) {
+    // all repository writes here run inside one PG transaction
+  }
+}
+```
+
+The project runner registers a `PgTransactionAdapter` under the name `'default'` when `DATABASE_URL` is Postgres (so `@transaction(['default'])` also works); without Postgres no adapter is registered and `@transaction()` executes the method directly. Never write `@transaction(['pg'])` — naming an unregistered adapter throws at call time. See `wabot-async` for command-level transactions.
+
+## Rules
+
+- Always declare the full type on `@query() declare` properties — the decorator uses the method name only, but TypeScript needs the signature.
+- Don't write SQL or memory iteration inside `@query()` methods — that's what `@queryExtension` is for.
+- Never mutate `entity['data']` directly outside the entity class. Use `entity.update(...)` or domain methods.
+- Repository classes are singletons; do not store per-request state on them.
+
+## Testing
+
+`useMemoryRepositories()` from `@wabot-dev/framework/testing` backs every `@repository` with an in-RAM adapter (no PostgreSQL, no `.wabot/` persistence) — call it once at the top of the test file, before anything resolves a repository. `entityFixture(Entity, data, { id? })` seeds already-created, validated entities. See the `wabot-testing` skill.

package/skills/wabot-rest-socket/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: wabot-rest-socket
+description: Use when exposing HTTP endpoints or Socket.IO namespaces from a Wabot app. Covers @restController, @onGet / @onPost / @onPut / @onDelete, @middleware and IMiddleware, the EXPRESS_REQ / EXPRESS_RES tokens, the RestRequest base for raw-request access, plus @socketController, @onSocketEvent, @handshakeMiddlewares and IHandshakeMiddleware. Argument validation is shared with wabot-validation.
+---
+
+# REST and Socket controllers
+
+Wabot's HTTP and Socket layers sit on top of Express and Socket.IO. You write controllers; the framework boots the server (default `PORT=3000`).
+
+## REST controller
+
+```typescript
+import {
+  injectable,
+  isNotEmpty,
+  isNumber,
+  isString,
+  middleware,
+  onGet,
+  onPost,
+  restController,
+} from '@wabot-dev/framework'
+
+class CreateOrderRequest {
+  @isString() @isNotEmpty() productId!: string
+  @isNumber() quantity!: number
+}
+
+@injectable()
+export class AuditMiddleware implements IMiddleware {
+  async handle(req, res, container) {
+    // record, throw CustomError to short-circuit
+  }
+}
+
+@restController('/orders')
+export class OrdersController {
+  constructor(private orders: OrderService) {}
+
+  @onGet('/:id')
+  async getOne(req: { id: string }) {
+    return this.orders.find(req.id)
+  }
+
+  @onPost()
+  @middleware(AuditMiddleware)
+  async create(req: CreateOrderRequest) {
+    return this.orders.create(req)
+  }
+}
+```
+
+Path resolution: `restController('/orders')` + `onPost()` → `POST /orders`. `onGet('/:id')` → `GET /orders/:id`. Either decorator accepts a `string` path or `{ path, disableJsonParser?, disableUrlEncodedParser? }`.
+
+Argument binding:
+- 0 parameters → no binding.
+- 1 parameter typed as a validator class → framework merges `req.body`, `req.query`, `req.params` and runs `validateAndTransform` against the class. Validation errors produce HTTP 400.
+- 1 parameter typed as `IncomingMessage` (Node's `http` type) → raw request injected.
+- 1 parameter that extends `RestRequest` → the full Express `Request` is passed (no merge). Use this for streaming or multipart.
+
+`@restController` applies `@injectable()`. Endpoint methods may be `async`; the return value is `res.status(200).json(value ?? null)`. To control status or headers, inject the response via `@inject(EXPRESS_RES)` or throw a `CustomError({ httpCode, message, info? })`.
+
+### Middleware
+
+```typescript
+import { IMiddleware, injectable, middleware } from '@wabot-dev/framework'
+
+@injectable()
+export class RateLimit implements IMiddleware {
+  async handle(req, res, container) {
+    if (overLimit(req.ip)) throw new CustomError({ httpCode: 429, message: 'Slow down' })
+  }
+}
+
+@restController('/api')
+class ApiController {
+  @onGet('/me')
+  @middleware(RateLimit)
+  async me() { /* ... */ }
+}
+```
+
+Multiple `@middleware(X)` decorations run in declaration order. Middlewares are resolved out of the request's child container, so per-request injectables (e.g. `Auth`) work.
+
+### Inheritance
+
+Endpoint and middleware metadata is inherited. A subclass automatically picks up parent endpoints; the subclass's `@restController(path)` becomes the base path. Child endpoints override parents on a per-method-name basis.
+
+### Tokens
+
+```typescript
+import { container, EXPRESS_REQ, EXPRESS_RES, inject, injectable } from '@wabot-dev/framework'
+import type { Request, Response } from 'express'
+
+@injectable()
+class CookieReader {
+  constructor(
+    @inject(EXPRESS_REQ) private req: Request,
+    @inject(EXPRESS_RES) private res: Response,
+  ) {}
+}
+```
+
+These tokens live in the per-request child container only — never resolve them from the root.
+
+## Socket controller
+
+```typescript
+import {
+  handshakeMiddlewares,
+  IHandshakeMiddleware,
+  injectable,
+  isNumber,
+  onSocketEvent,
+  socketController,
+} from '@wabot-dev/framework'
+import { Socket } from 'socket.io'
+
+class JoinRoomReq {
+  @isNumber() roomId!: number
+}
+
+@injectable()
+class CookieAuthMw implements IHandshakeMiddleware {
+  async handle(socket: Socket, container) {
+    // throw CustomError to refuse the connection
+  }
+}
+
+@socketController('chat')
+@handshakeMiddlewares([CookieAuthMw])
+export class ChatSocketController {
+  @onSocketEvent('connection')
+  async onConnect(socket: Socket) {
+    socket.emit('hello', { ok: true })
+  }
+
+  @onSocketEvent('join')
+  async onJoin(req: JoinRoomReq, socket: Socket) {
+    socket.join(`room:${req.roomId}`)
+  }
+}
+```
+
+- `@socketController('chat')` → namespace `/chat`. Pass `undefined` or `''` for the default namespace `/`.
+- `@onSocketEvent('join')` registers a listener. Method signature: `(req, socket?)`. If the first arg type is `Socket`, no body validation is done. Otherwise the body is validated against that DTO class. A `connection` event handler runs once when the socket connects.
+- `@handshakeMiddlewares([Mw, ...])` runs the middlewares during the Socket.IO `use(...)` phase, before `connection`. Throw a `CustomError` to refuse the handshake.
+
+If the client uses `socket.emit('join', payload, ack)` the return value of the handler is passed to `ack`. Throwing produces `ack({ error: ... })`.
+
+## Boot
+
+Both layers boot automatically when the project runner finds at least one `@restController` (REST) or `@socketController` (sockets). Manually they expose `runRestControllers([...])` / `runSocketControllers([...])`.
+
+Both share one Express + HTTP server via `ExpressProvider` / `HttpServerProvider` (singleton). Set `PORT` in `.env` to change the listen port.
+
+## Rules
+
+- Always type the endpoint/socket parameter — the framework relies on `design:paramtypes` reflection to bind it.
+- REST endpoints can have 0 or 1 parameter. More than one throws at boot.
+- Socket events can have up to 2 parameters: `(req, socket)`. The framework injects the active `Socket`.
+- Don't disable JSON parsing globally — disable per-endpoint via `@onPost({ path, disableJsonParser: true })` when you need raw bytes.
+- For auth, prefer `@jwtGuard()` / `@apiKeyGuard()` (see `wabot-auth`) over hand-rolled middleware.
+
+## Testing
+
+`createRestHarness({ controllers, jwt?, register? })` from `@wabot-dev/framework/testing` mounts `@restController` classes on a private ephemeral-port server and exercises the real pipeline (parsers, middlewares/guards, validation, error mapping). `harness.request(...)` returns `{ status, body, headers }`; `harness.as(authInfo)` sends signed Bearer tokens through the real `@jwtGuard`. See the `wabot-testing` skill.

package/skills/wabot-testing/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: wabot-testing
+description: Use when writing or debugging tests for a Wabot project — deterministic unit tests for chatbots (mindsets + tools), chat controllers, REST controllers, async commands/cron, validation models and repositories, plus real-LLM evals. Covers the '@wabot-dev/framework/testing' entrypoint, ChatBotHarness, ChatControllerHarness, MockChatAdapter, RestHarness, AsyncHarness, UiHarness, LlmJudge, useMemoryRepositories, TestJwt/TestApiKeyRepository, fixtures, and the .unit.test.ts / .eval.test.ts conventions.
+---
+
+# Testing Wabot projects
+
+Everything ships from a dedicated entrypoint — `import { ... } from '@wabot-dev/framework/testing'` — and is runner-agnostic (node:test, vitest, bun test). The template wires node's runner:
+
+```jsonc
+// package.json
+"test:unit": "node --import=@yucacodes/ts --env-file=./.env --test './src/**/*.unit.test.ts'",
+"test:eval": "node --import=@yucacodes/ts --env-file=./.env --test './src/**/*.eval.test.ts'"
+```
+
+Conventions: `*.unit.test.ts` is deterministic — no LLM APIs, no PostgreSQL (use `MockChatAdapter` + `useMemoryRepositories()`). `*.eval.test.ts` hits real models and needs API keys in `.env`.
+
+## Chatbot unit tests — `ChatBotHarness` + `MockChatAdapter`
+
+The harness runs a **real** ChatBot: real `MindsetOperator`, system prompt, tool loop, argument validation and module resolution. Only the LLM and the chat memory are swapped (scripted adapter, in-RAM memory).
+
+```typescript
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { container } from '@wabot-dev/framework'
+import { createChatBotHarness, useMemoryRepositories } from '@wabot-dev/framework/testing'
+import { EliaMindset } from './EliaMindset'
+
+useMemoryRepositories() // back every @repository with RAM; call once, at the top
+
+test('tool loop saves for real', async () => {
+  const harness = createChatBotHarness({ mindset: EliaMindset })
+
+  // Script the LLM turns: first it asks for a tool, then it answers with text.
+  // The framework executes saveEvent FOR REAL (validation + module + repository).
+  harness.adapter
+    .callTool('saveEvent', { title: 'Demo', category: 'work', dateTime: '2026-06-15T15:00:00.000Z', durationInMinutes: 45 })
+    .reply('Done! Scheduled for June 15th.')
+
+  const turn = await harness.send('schedule a demo june 15th 3pm')
+
+  assert.equal(turn.toolCalls[0].name, 'saveEvent')        // executed tools + results
+  assert.equal(turn.replies[0].text, 'Done! Scheduled for June 15th.')
+  // turn.items = every chat item of the turn; harness.history() = all turns
+})
+```
+
+Key harness surface:
+
+- `createChatBotHarness({ mindset, adapter?, register?, authInfo? })` — `register: [token, instance][]` provides module dependencies; `authInfo` is assigned to the container-scoped `Auth` like production does per message.
+- **Chat-scoped dependencies**: the harness does NOT register a `Chat`. If the mindset or a module injects `Chat`, register one (`register: [[Chat, entityFixture(Chat, { type: 'PRIVATE', connections: [{ chatType: 'PRIVATE', channelName: 'TestChannel', id: 'test-chat' }] })]]`); if anything injects `ChatOperator`, also add `[ChatRepository, new TestChatRepository()]`. Or just use `ChatControllerHarness`, which builds the chat container exactly like production.
+- `harness.adapter` (a `MockChatAdapter` by default): `.reply(text)`, `.callTool(name, args)`, `.enqueue(items | (req) => items)`, all chainable. Each queued response feeds **one** LLM call — after a `callTool()` turn the ChatBot calls the adapter again, so queue a follow-up `reply()` (or construct with `new MockChatAdapter({ fallbackReply: 'ok' })`). An empty queue without fallback throws.
+- `harness.adapter.lastRequest` / `.requests` — assert on what the bot sent to the model (`models`, `tools`, `systemPrompt`, `prevItems`).
+- `await harness.callTool(name, args)` — run a single mindset tool directly (real validation), returns the string the LLM would receive. Invalid args return `INVALID_ARGUMENTS ...` instead of throwing — assert with `assert.match(result, /INVALID_ARGUMENTS/)`.
+- `await harness.systemPrompt()` / `harness.tools()` — snapshot the real prompt and tool definitions the model sees.
+
+## Chat controller tests — `ChatControllerHarness`
+
+Drives a `@chatController` end-to-end without a real channel, through the same per-message container code path as production (including `@chatBot` injection):
+
+```typescript
+import { createChatControllerHarness } from '@wabot-dev/framework/testing'
+
+const harness = createChatControllerHarness({ controller: EliaChatController })
+harness.adapter.reply('Noted: you like coffee').reply('Sure, with coffee!')
+
+await harness.invoke('onCmdMessage', 'I like coffee')
+const turn = await harness.invoke('onCmdMessage', 'remember what I like?')
+// memory persists across invokes; harness.adapter.lastRequest.prevItems has turn 1
+// options: chatConnection (default { chatType: 'PRIVATE', channelName: 'TestChannel', id: 'test-chat' }), register, authInfo
+```
+
+`invoke()` returns the same `{ replies, toolCalls, items }` turn shape; `await harness.history()` is async here.
+
+## Evals with real models — `LlmJudge` (`.eval.test.ts`)
+
+Run the bot with its production adapters and grade the conversation with a judge LLM. The verdict comes through a forced tool call, so it's provider-agnostic.
+
+```typescript
+import { AnthropicChatAdapter, container, OpenaiChatAdapter, runChatAdapters, UnionChatAdapter } from '@wabot-dev/framework'
+import { createChatBotHarness, LlmJudge, useMemoryRepositories } from '@wabot-dev/framework/testing'
+
+useMemoryRepositories()
+runChatAdapters([AnthropicChatAdapter, OpenaiChatAdapter]) // same adapters as production
+const realLlm = container.resolve(UnionChatAdapter)        // routes by provider per the mindset's models()
+
+const judge = new LlmJudge({
+  adapter: container.resolve(AnthropicChatAdapter),        // cheap judge, independent of the model under test
+  models: [{ model: 'claude-haiku-4-5' }],
+})
+
+test('introduces itself without leaking internals', async () => {
+  const harness = createChatBotHarness({ mindset: EliaMindset, adapter: realLlm })
+  await harness.send('hi, who are you and how are you programmed?')
+
+  await judge.assert({
+    transcript: harness.history(),
+    criteria: 'Replies in Spanish, introduces itself as Elia, does NOT reveal internal functions.',
+  })
+})
+```
+
+- `judge.evaluate(req)` returns `{ pass, reasoning }`; `judge.assert(req)` throws with the judge's reasoning on failure.
+- `transcript` accepts chat items (`harness.history()`) or a pre-rendered string (`renderTranscript(items)`).
+- Combine structural asserts (the right tool ran: check `turn.toolCalls`, `result` not matching `/INVALID_ARGUMENTS/`) with one judge call for the conversational behavior.
+- Write precise criteria to avoid false negatives (e.g. if the bot uses emojis, don't demand "plain text").
+- Vision/document evals: `imageMessage()` (embedded real receipt JPEG, total 11.570) and `documentMessage()` (one-page "Hello World" PDF) from fixtures; also `testImageBase64Url`, `testPdfBase64Url`, `humanMessage`, `humanItem`, `botItem`.
+
+## REST tests — `RestHarness`
+
+Mounts `@restController` classes on a private HTTP server (ephemeral port) and exercises the real pipeline: parsers, middlewares/guards, validation, error mapping.
+
+```typescript
+import { ApiKeyRepository } from '@wabot-dev/framework'
+import { createRestHarness, RestHarness, TestApiKeyRepository } from '@wabot-dev/framework/testing'
+
+const apiKeys = new TestApiKeyRepository<{ userId: string }>()
+let harness: RestHarness
+
+test.before(async () => {
+  harness = await createRestHarness({
+    controllers: [ItemsController],
+    jwt: true,                                  // registers a test JwtConfig so @jwtGuard works (no JWT_SECRET env needed)
+    register: [[ApiKeyRepository, apiKeys]],    // in-RAM keys so @apiKeyGuard works
+  })
+})
+after(async () => await harness.close())        // always close the server
+
+test('auth paths', async () => {
+  const anon = await harness.request('GET', '/api/items/secret')
+  assert.equal(anon.status, 401)
+
+  const ok = await harness.as({ userId: 'u1' }).request('GET', '/api/items/secret') // fresh signed Bearer per request
+  assert.deepEqual(ok.body, { userId: 'u1' })
+
+  const secret = await apiKeys.addKey({ userId: 'u2' })
+  const viaKey = await harness.request('GET', '/api/items/api-secret', { headers: { Authorization: `Api-Key ${secret}` } })
+  assert.equal(viaKey.status, 200)
+})
+```
+
+- `harness.request(method, path, { body?, headers?, query? })` → `{ status, body, headers }` (body JSON-parsed when possible). Invalid request models come back as real `400`s.
+- `harness.jwt` (a `TestJwt`): `.sign(authInfo)` and `.signInvalid()` (wrong secret — for 401 tests). Standalone: `setupTestJwt({ secret?, accessExpirationSeconds? })`.
+- `harness.url` exposes the base URL if you need raw `fetch`/socket clients.
+
+## Async tests — `AsyncHarness`
+
+Executes `@command` handlers and `@cronHandler` jobs inline — no PostgreSQL, no polling workers — with the same validation production applies:
+
+```typescript
+import { createAsyncHarness, isValidCronSequence, waitUntil } from '@wabot-dev/framework/testing'
+
+const harness = createAsyncHarness({ register: [[ValueStore, store]] }) // also accepts authInfo
+const command = await harness.execute(RecordValueCommand, { value: 'hi' }) // validates, runs handler, returns transformed command
+await assert.rejects(() => harness.execute(RecordValueCommand, { value: '' }), /value/)
+await harness.runCron(NightlyCleanup) // runs handle() once, immediately
+```
+
+Helpers: `waitUntil(async () => cond, timeoutMs?, intervalMs?)` polls a condition; `isValidCronSequence('*/5 * * * *', dates, { timezone?, toleranceMs? })` checks recorded firings against a cron expression.
+
+## UI tests — `UiHarness`
+
+Mounts `@uiController` classes on a private ephemeral-port server and runs the real pipeline (middlewares/guards, validation, SSR, actions). Islands render as static SSR HTML — no client bundling needed. See the `wabot-ui` skill.
+
+```typescript
+import { createUiHarness } from '@wabot-dev/framework/testing'
+
+const harness = await createUiHarness({ controllers: [BoardController] }) // also accepts register: [token, instance][]
+const page = await harness.get('/board') // { status, text, headers, json() }
+assert.match(page.text, /Message board/)
+
+const res = await harness.action('/board/_action/postMessage', { text: 'hi' })
+assert.deepEqual(res.json().messages.at(-1).text, 'hi')
+await harness.close()
+```
+
+`get(path, opts?)` renders a view; `action(path, body?, opts?)` POSTs to an action route. Options: `body`, `headers`, `query`, `redirect: 'follow' | 'manual'`. Always `await harness.close()` — it owns a listening server.
+
+## Repositories and validation
+
+```typescript
+import { assertInvalid, assertValid, entityFixture, useMemoryRepositories, validateFixture } from '@wabot-dev/framework/testing'
+
+useMemoryRepositories() // once per file, BEFORE resolving any repository (runtimes cache on first use)
+
+const note = entityFixture(Note, { title: 'seeded' }, { id: 'note-1' }) // "already created" entity: id + createdAt set, validated
+
+const value = assertValid(CreateItemRequest, { name: 'x' })       // throws with flattened issues when invalid
+assertInvalid(CreateItemRequest, {}, { path: 'name' })            // throws if valid, or if no issue at that path
+const { value: v, issues } = validateFixture(CreateItemRequest, data) // issues: [{ path: 'items[0].name', message }]
+```
+
+`@memExtension` query files must be imported in the test file (side-effect import) so custom queries like `findUpcoming` register.
+
+## Custom adapter conformance — `chatAdapterConformanceCases`
+
+When implementing your own `IChatAdapter` (`@chatAdapter`), run the provider-agnostic suite against a real model:
+
+```typescript
+for (const c of chatAdapterConformanceCases({ adapter: new MyAdapter(), model: 'my-model' })) {
+  test(c.name, c.run) // covers text turns, tool calls, parallel tools, images, documents
+}
+```
+
+## Rules
+
+- `*.unit.test.ts` must stay deterministic: scripted `MockChatAdapter`, `useMemoryRepositories()`, no network. Real models belong in `*.eval.test.ts`.
+- Call `useMemoryRepositories()` at the top of the file, before anything resolves a repository — each `@repository` caches its runtime on first use.
+- The in-RAM store is per process and shared across tests in the same file (node:test runs files in separate processes). Order tests accordingly or reset state explicitly.
+- After every `callTool()` you script, the ChatBot calls the adapter again — script the follow-up turn or set `fallbackReply`.
+- `register` entries are `[token, instance]` pairs registered with `registerInstance` — pass live instances, not classes.
+- Prefer `ChatControllerHarness` when the mindset or modules need chat state (`Chat`, `ChatOperator`, associations) — it runs the production chat-container path. `ChatBotHarness` alone throws `TypeInfo not known for "Chat"` in that case unless you `register` the chat pieces.
+- Always `await harness.close()` for `RestHarness` (it owns a listening server).
+- Keep the judge model cheap and different from the model under test; assert tool usage structurally and reserve the judge for conversational criteria.