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

package/skills/wabot-async/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: wabot-async
+description: Use when running background work in Wabot — fire-and-forget commands, scheduled deferred commands, cron handlers, or wrapping side-effectful methods in a DB transaction. Covers @command, @commandHandler, @cronHandler, @transaction, the Async service (runCommand, scheduleCommand, IScheduleAt), ICommandHandler / ICronHandler, and how the in-memory vs PG job/cron stores are wired by the project runner.
+---
+
+# Async commands, cron, and transactions
+
+Wabot's async layer handles three kinds of work:
+
+- **Commands** — typed messages with a registered handler. Run immediately (`runCommand`) or scheduled (`scheduleCommand`).
+- **Crons** — handlers that fire on a cron expression.
+- **Transactions** — wrap a method so all repository writes happen inside one DB transaction per registered adapter.
+
+The job store, cron job store, and transaction adapter are auto-selected by the project runner based on `DATABASE_URL` (in-memory ↔ PostgreSQL). No manual registration.
+
+## Commands
+
+A command is a plain class decorated with `@command(name)`. Fields use the standard validators from `wabot-validation`.
+
+```typescript
+import { command, isNumber, isString, min } from '@wabot-dev/framework'
+
+@command('orders.charge')
+export class ChargeOrder {
+  @isString() orderId!: string
+  @isNumber() @min(1) amountCents!: number
+}
+```
+
+The handler implements `ICommandHandler<C>` and is bound with `@commandHandler(Command)`:
+
+```typescript
+import { commandHandler, ICommandHandler, injectable } from '@wabot-dev/framework'
+import { ChargeOrder } from './ChargeOrder'
+
+@commandHandler(ChargeOrder)
+export class ChargeOrderHandler implements ICommandHandler<ChargeOrder> {
+  constructor(private payments: PaymentService) {}
+
+  async handle(cmd: ChargeOrder) {
+    await this.payments.charge(cmd.orderId, cmd.amountCents)
+  }
+}
+```
+
+Trigger it with the `Async` singleton:
+
+```typescript
+import { Async, container } from '@wabot-dev/framework'
+
+const async = container.resolve(Async)
+
+// Run as soon as a worker is free
+await async.runCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 })
+
+// Schedule for later: absolute Date or relative delay
+await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, { minutes: 30 })
+await async.scheduleCommand(ChargeOrder, { orderId: 'o_1', amountCents: 2500 }, new Date('2026-12-31T08:00:00Z'))
+```
+
+`IScheduleAt = Date | { seconds: number } | { minutes: number } | { hours: number } | { days: number }`.
+
+`Async.runCommand` returns a `Job` immediately (it has an `id` you can persist). The payload is validated against the command class before the job is stored — bad shapes throw `CustomError`.
+
+`@commandHandler` applies `@injectable()`. There is at most one handler per command name; registering a second throws.
+
+## Cron handlers
+
+```typescript
+import { cronHandler, ICronHandler } from '@wabot-dev/framework'
+
+@cronHandler({ name: 'daily-cleanup', cron: '0 3 * * *' })
+export class DailyCleanup implements ICronHandler {
+  constructor(private games: GameRepository) {}
+
+  async handle() {
+    // ...
+  }
+
+  // Optional. Called when handle() throws.
+  async handleError(err: any) {
+    // ...
+  }
+}
+```
+
+- `cron` accepts standard 5-field or 6-field (with seconds) cron expressions.
+- `disabled: true` turns a handler off without removing it (useful for guarded rollouts).
+- `@cronHandler` applies `@singleton()` automatically — do not stack lifecycle decorators.
+
+The runner registers these into `CronScheduler`, which persists per-cron state in `CronJobRepository` so missed runs aren't replayed on restart.
+
+## Transactions
+
+`@transaction(dbNames?)` wraps an async method so every adapter listed runs the call inside a transaction. Without arguments, all registered adapters participate (today there is one: the runner registers `PgTransactionAdapter` under the name `'default'` when `DATABASE_URL` is Postgres).
+
+```typescript
+import { transaction } from '@wabot-dev/framework'
+
+@injectable()
+export class Checkout {
+  @transaction()
+  async checkout(orderId: string) {
+    await this.orderRepository.update(...)
+    await this.paymentRepository.create(...)
+  }
+}
+```
+
+Behavior:
+- Repository writes performed inside the method go to the same client/connection.
+- Throwing rolls back; returning commits.
+- Nested `@transaction`-decorated calls reuse the outer transaction (no nested begin).
+- Without Postgres no adapter is registered, so `@transaction()` just executes the method (no wrap). Naming a specific adapter (e.g. `@transaction(['default'])`) throws at call time if it isn't registered — never write `@transaction(['pg'])`.
+
+## Manual run / stop
+
+In production the runner discovers and starts everything. For testing or custom hosts:
+
+```typescript
+import { runCommandHandlers, runCronHandlers, stopCommandHandlers, stopCronHandlers } from '@wabot-dev/framework'
+
+runCommandHandlers([ChargeOrderHandler])
+runCronHandlers([DailyCleanup])
+
+// later
+stopCommandHandlers([ChargeOrderHandler])
+stopCronHandlers([DailyCleanup])
+```
+
+`testAsync` is exported for integration tests against the real job/cron schedulers — see `wabot-ts/src/feature/async/testAsync.ts` for an example.
+
+## Rules
+
+- Command classes are *data* classes. Don't put behavior on them — that belongs in the handler.
+- Don't reuse a command name for two handlers. The framework throws on boot.
+- Don't `await async.runCommand(...)` inside a request handler expecting it to finish synchronously — `runCommand` schedules the job and returns immediately. Use `async.scheduleCommand(..., { seconds: 0 })` if you want the same fire-and-forget behavior explicitly.
+- Cron expressions in seconds (6 fields) are supported but be careful: the in-memory adapter polls fast, the PG adapter polls at a lower rate.
+- Wrap multi-repository writes in `@transaction()` rather than chaining manual `withPgTransaction` calls.
+
+## Testing
+
+`createAsyncHarness({ register?, authInfo? })` from `@wabot-dev/framework/testing` runs `@command` handlers (`harness.execute(Command, data)` — real validation, returns the transformed command) and `@cronHandler` jobs (`harness.runCron(Handler)`) inline, with no PostgreSQL or polling workers. `isValidCronSequence` and `waitUntil` help with schedule assertions. See the `wabot-testing` skill.

package/skills/wabot-auth/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: wabot-auth
+description: Use when adding authentication to a Wabot REST endpoint or Socket.IO namespace, issuing JWT access/refresh tokens, or protecting endpoints with API keys. Covers the chat/request-scoped Auth<D> service, @jwtGuard / @jwtHandshakeGuard, JwtConfig and the JWT_* env vars, Jwt.createToken / findRefreshTokenAuthInfo, JwtRefreshToken, and @apiKeyGuard / @apiKeyHandshakeGuard with PgApiKeyRepository / RemoteApiKeyRepository.
+---
+
+# Authentication
+
+Wabot's auth is request-scoped. A guard middleware verifies the credential, then writes the resolved auth info into the per-request/socket `Auth<D>` instance. Downstream code reads it with `auth.require()`.
+
+## `Auth<D>`
+
+```typescript
+import { Auth, injectable } from '@wabot-dev/framework'
+
+interface SessionInfo {
+  userId: string
+  role: 'admin' | 'user'
+}
+
+@injectable()
+export class OrdersService {
+  constructor(private auth: Auth<SessionInfo>) {}
+
+  list() {
+    const session = this.auth.require() // throws CustomError({ httpCode: 401 }) if not assigned
+    return this.repo.findByUserId(session.userId)
+  }
+}
+```
+
+`Auth` is `@scoped(Lifecycle.ContainerScoped)` and exists once per request, chat, or socket connection. Methods:
+
+- `assign(info)` — sets the auth info (used by guards). Throws if already assigned.
+- `override(info)` — replaces even when assigned (use cautiously).
+- `require()` — returns the info or throws 401.
+- `isAssigned()` / `wasOverrided()` / `clear()`.
+
+## JWT — REST
+
+```typescript
+import { jwtGuard, onGet, onPost, restController } from '@wabot-dev/framework'
+
+@restController('/account')
+export class AccountController {
+  @onGet('/me')
+  @jwtGuard()
+  async me(_, auth: Auth<SessionInfo>) {
+    return auth.require()
+  }
+}
+```
+
+`@jwtGuard()` reads `Authorization: Bearer <token>`, verifies it with `JwtConfig` (env-driven, see below), and calls `auth.assign(payload)`.
+
+## JWT — Socket
+
+```typescript
+import { jwtHandshakeGuard, socketController } from '@wabot-dev/framework'
+
+@socketController('private')
+@jwtHandshakeGuard()
+export class PrivateSocketController { /* ... */ }
+```
+
+The token is read from `socket.handshake.auth.token` first, falling back to the `Authorization` header.
+
+## Issuing tokens
+
+```typescript
+import { Auth, Jwt, JwtAccessAndRefreshTokenDto, injectable, onPost, restController } from '@wabot-dev/framework'
+
+@restController('/auth')
+export class AuthController {
+  constructor(private jwt: Jwt, private auth: Auth<SessionInfo>) {}
+
+  @onPost('/login')
+  async login(body: LoginRequest): Promise<JwtAccessAndRefreshTokenDto> {
+    const session = await this.userService.verify(body)
+    this.auth.assign(session)
+    return this.jwt.createToken({ device: body.device ?? 'unknown' })
+  }
+
+  @onPost('/refresh')
+  async refresh(body: RefreshRequest): Promise<JwtAccessAndRefreshTokenDto> {
+    const session = await this.jwt.findRefreshTokenAuthInfo(body.refreshToken)
+    this.auth.override(session)
+    return this.jwt.createToken()
+  }
+}
+```
+
+`Jwt.createToken(metadata?)`:
+- Reads the current `auth.require()` info.
+- Persists a `JwtRefreshToken` via `JwtRefreshTokenRepository`. The base class throws `Method not implemented` — the project must register an implementation: `container.registerType(JwtRefreshTokenRepository, PgJwtRefreshTokenRepository)` (table `wabot.jwt_refresh_token`), or its own.
+- Returns `{ access: { token, expiration }, refresh: { token, expiration } }`.
+
+`Jwt.findRefreshTokenAuthInfo(secret)` validates the refresh secret (hash-compare + expiration + revocation) and returns the original auth payload. Throws 401 if any check fails.
+
+### Env vars
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `JWT_SECRET` | (required) | Symmetric secret or asymmetric key used for sign/verify |
+| `JWT_ALGORITHM` | `HS256` | Any `jsonwebtoken.Algorithm` |
+| `JWT_ACCESS_EXPIRATION_SECONDS` | `600` (10 min) | Access token lifetime |
+| `JWT_REFRESH_EXPIRATION_SECONDS` | `31536000` (1 yr) | Refresh token lifetime |
+
+`JwtConfig` is `@singleton()` and reads these at boot.
+
+### Refresh-token metadata
+
+`JwtRefreshToken<D>` exposes `metadata` (the arbitrary `Record<string, string>` you passed to `createToken`), `expirationTime`, `revoke()`, and `isValidToken(secret)`. The repository exposes `findByMetadata(metadata)` so you can revoke all tokens issued to a device.
+
+## API key
+
+```typescript
+import { apiKeyGuard, apiKeyHandshakeGuard, onGet, restController, socketController } from '@wabot-dev/framework'
+
+@restController('/internal')
+export class InternalController {
+  @onGet('/health')
+  @apiKeyGuard()
+  async health() { return { ok: true } }
+}
+
+@socketController('admin')
+@apiKeyHandshakeGuard()
+export class AdminSocketController { /* ... */ }
+```
+
+The guard reads `Authorization: Api-Key <secret>` (REST) or `socket.handshake.auth.token` / the `Authorization` handshake header (socket), validates via `ApiKeyRepository`, and assigns the lookup result to `Auth`.
+
+`ApiKeyRepository` is a base class with no storage — register an implementation yourself: `container.registerType(ApiKeyRepository, PgApiKeyRepository)` (table `wabot.api_key`), or `RemoteApiKeyRepository` to delegate validation to an external service:
+
+```typescript
+import { container, ApiKeyRepository, RemoteApiKeyRepository } from '@wabot-dev/framework'
+
+container.registerType(ApiKeyRepository, RemoteApiKeyRepository)
+```
+
+Set `WABOT_API_KEY` and `WABOT_LLM_URL` to point `RemoteApiKeyRepository` at your auth service (it expects the same shape as the Wabot platform).
+
+## Rules
+
+- Always type `Auth<D>` with your session shape. `auth.require()` returns the typed value.
+- A guard runs once per request/connection. Don't reassign manually — use `override(...)` only on token refresh.
+- `@jwtGuard()` and `@apiKeyGuard()` work on REST endpoints; their `*HandshakeGuard()` variants work on socket controllers. Don't mix them up.
+- Never log `auth.require()` results — they may contain PII or token claims. Use a redacted view.
+- If you need a custom guard, implement `IMiddleware` (REST) or `IHandshakeMiddleware` (socket) and wire it with `@middleware(...)` / `@handshakeMiddlewares([...])`.
+
+## Testing
+
+From `@wabot-dev/framework/testing`: `RestHarness` with `jwt: true` registers a test `JwtConfig` so the real `@jwtGuard` works without env secrets (`harness.as(authInfo)` signs per-request tokens; `harness.jwt.signInvalid()` for 401 tests). `TestApiKeyRepository` is an in-RAM `ApiKeyRepository` for `@apiKeyGuard` (`register: [[ApiKeyRepository, repo]]`, `repo.addKey(authInfo)`). Harnesses also accept `authInfo` to populate the container-scoped `Auth` directly. See the `wabot-testing` skill.

package/skills/wabot-chat/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: wabot-chat
+description: Use when wiring chat input/output for a Wabot bot — receiving messages from one or more channels (cmd, socket, telegram, whatsapp, wasender), injecting a ChatBot bound to a mindset, and replying. Covers @chatController, @chatBot, @cmd / @socket / @telegram / @whatsApp / @wasender, IReceivedMessage, the ChatBot.sendMessage callback, and the @chatAdapter / runChatAdapters provider model.
+---
+
+# Chat controllers, channels, and adapters
+
+A chat controller is the entry point for messages from a transport (terminal, socket, Telegram, WhatsApp). It owns a `ChatBot` bound to one mindset and forwards the message into the bot's processing loop.
+
+## Controller shape
+
+```typescript
+import {
+  chatBot,
+  ChatBot,
+  chatController,
+  cmd,
+  socket,
+  telegram,
+  whatsApp,
+  type IReceivedMessage,
+} from '@wabot-dev/framework'
+import { PixelMindset } from './mindset/PixelMindset'
+
+@chatController()
+export class PixelChatController {
+  constructor(@chatBot(PixelMindset) private pixel: ChatBot) {}
+
+  @cmd()
+  @socket({ namespace: 'pixel' })
+  @telegram({ botToken: process.env.TELEGRAM_BOT_TOKEN! })
+  @whatsApp({ number: '+1555…', accessToken: '…', businessNumberId: '…' })
+  async onMessage(ctx: IReceivedMessage) {
+    await this.pixel.sendMessage(ctx.message, async (reply) => {
+      await ctx.reply(reply)
+    })
+  }
+}
+```
+
+Channel decorators stack: each one registers the same method on a different transport. The runner instantiates a channel per registration.
+
+`@chatController()` takes no arguments today — `IchatControllerConfig` is currently empty. It applies `@injectable()`.
+
+## `ChatBot` injection
+
+`@chatBot(MindsetCtor)` injects a `ChatBot` instance scoped to that mindset. You can have several in one controller (e.g. a "support" bot and a "sales" bot) — each gets a unique injection token under the hood.
+
+`ChatBot.sendMessage(message, callback)`:
+- Persists the incoming message as a `humanMessage` chat item.
+- Calls the mindset → adapter loop, executing any tool calls.
+- Invokes `callback(replyMessage)` once per `botMessage` item produced.
+
+Inside the loop, the bot picks `models.visionLlm` if any image is attached, otherwise `models.llm`. It will only use providers registered through `@chatAdapter` (see below).
+
+## `IReceivedMessage` and `IChatMessage`
+
+```typescript
+interface IReceivedMessage {
+  message: IChatMessage
+  reply: (message: IChatMessage) => Promise<Record<string, string> | void>
+}
+
+interface IChatMessage {
+  senderId?: string
+  senderName?: string
+  text?: string
+  images?: IChatMessageImage[]
+  documents?: IChatMessageDocument[]
+  object?: object
+  metadata?: Record<string, string>
+}
+```
+
+The `reply` callback comes from the channel — for `@cmd` it writes to stdout of the connected `cmd:channel` client; for `@socket` it emits a Socket.IO event; for `@telegram`/`@whatsApp`/`@wasender` it calls the provider's send API. You always pass an `IChatMessage` (with `text`, `images`, or `documents`); never raw strings.
+
+## Channels — what each decorator needs
+
+| Decorator | Config | Notes |
+| --- | --- | --- |
+| `@cmd()` | none | Local Unix socket terminal client. Run `npm run cmd` to chat. State stored under `.wabot/cmd-channel/<route>/`. |
+| `@socket({ namespace })` | `namespace: string \| ConfigReference<string>` | Mounts a Socket.IO namespace. Tag-fn refs (`str\`socket.namespace\``) supported. |
+| `@telegram({ botToken })` | `botToken: string \| ConfigReference<string>` | Long-poll Telegram bot. Raw token or `str\`telegram.bot_token\``. |
+| `@whatsApp(numberOrConfig)` | string OR `{ number, accessToken?, businessNumberId? }` (each may be a `ConfigReference`) | WhatsApp Cloud API. |
+| `@wasender(config?)` | `{ apiKey?, webhookSecret?, phoneNumber?, webhookPath? }` (each may be a `ConfigReference`) | WaSender integration. |
+
+Channel configs that accept `ConfigReference` resolve env vars automatically — use `str\`wasender.apiKey\`` from `@wabot-dev/framework` to point to `WASENDER_APIKEY`.
+
+## Chat resolution
+
+When a message arrives, `ChatResolver` looks up the `Chat` by `IChatConnection` (`{ chatType: 'PRIVATE' | 'GROUP', channelName, id }`). If none exists, a new `Chat` is created under a lock. You never write this resolution code — it's already wired.
+
+Inside a chat handler, these tokens are available in the child container:
+- `Chat` — the resolved chat entity
+- `ChatMemory` — append/read chat items for this chat
+- `ChatOperator` — convenience wrapper (see `wabot-mindset`)
+- `Auth` — populated if the channel attached auth (e.g. via `injectInstances`)
+
+## Chat adapters (providers)
+
+Each LLM provider has a `@chatAdapter({ provider: 'name' })` class implementing `IChatAdapter.nextItems`. The framework ships adapters for `openai`, `anthropic`, `google`, `openrouter`, `deepseek`, and `wabot`.
+
+The project runner registers adapters automatically based on env keys (`OPENAI_API_KEY` → OpenAI, etc.). To override, pass `chatAdapters: [...]` to `run({ chatAdapters: [MyAdapter, OpenaiChatAdapter] })`.
+
+To call them manually (outside the runner):
+
+```typescript
+import { runChatAdapters, OpenaiChatAdapter } from '@wabot-dev/framework'
+runChatAdapters([OpenaiChatAdapter])
+```
+
+`runChatAdapters` binds a `UnionChatAdapter` to the `ChatAdapter` token — it dispatches by `IMindsetModelRef.provider`.
+
+To build your own adapter, implement `IChatAdapter`:
+
+```typescript
+import { chatAdapter, IChatAdapter, IChatAdapterNextItemsReq, IChatAdapterNextItemsRes, singleton } from '@wabot-dev/framework'
+
+@chatAdapter({ provider: 'my-llm' })
+@singleton()
+export class MyLlmAdapter implements IChatAdapter {
+  async nextItems(req: IChatAdapterNextItemsReq): Promise<IChatAdapterNextItemsRes> {
+    // map req.systemPrompt + req.prevItems + req.tools to your API, return { nextItems, usage }
+    return { nextItems: [], usage: { inputTokens: 0, outputTokens: 0, provider: 'my-llm', model: req.models[0].model } }
+  }
+}
+```
+
+## Rules
+
+- Keep controllers thin — fetch from `ctx.message`, call `bot.sendMessage`, return. Business logic belongs in modules/services.
+- Don't pass raw strings to `ctx.reply` — wrap them in `{ text: '...' }`.
+- The reply callback is async; await it so the channel actually flushes.
+- `@chatBot(Mindset)` is a parameter decorator — it can only appear in a constructor.
+- If you add a new chat adapter, its file must be imported during the runner's scan (so the `@chatAdapter` side-effect runs); place it inside `directories`.
+- Avoid building a mindset/controller pair when one controller can route between several mindsets with multiple `@chatBot(...)` constructor params.
+
+## Testing
+
+`createChatControllerHarness({ controller })` from `@wabot-dev/framework/testing` drives a `@chatController` end-to-end without a real channel (same per-message container path as production, `@chatBot` included), with a scripted `MockChatAdapter` playing the LLM. Custom `IChatAdapter` implementations should pass `chatAdapterConformanceCases`. See the `wabot-testing` skill.

package/skills/wabot-di-config/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: wabot-di-config
+description: Use when wiring services, choosing service lifecycles, reading env vars, or expressing typed config references for Wabot apps. Covers @injectable / @singleton / @scoped / @inject, the container, the Env service, and the config tag functions (str, num, bool, obj, strArr, numArr, boolArr) that drive resolveConfigReferences in channel and adapter decorators.
+---
+
+# DI, Env, and config references
+
+Wabot uses `tsyringe` under the hood and re-exports the pieces you need from `@wabot-dev/framework`:
+
+```typescript
+import { container, injectable, singleton, scoped, Lifecycle, inject } from '@wabot-dev/framework'
+```
+
+## Lifecycles
+
+| Decorator | When to use | Example |
+| --- | --- | --- |
+| `@singleton()` | App-wide infra: clients, repositories, config holders, caches. One instance for the process. | DB clients, adapters |
+| `@injectable()` | Stateless / per-resolution services. Each `resolve` returns a new instance. | Calculators, mappers |
+| `@scoped(Lifecycle.ContainerScoped)` | Per-request / per-chat / per-socket state. Lives in the child container created by the runner. | `Auth`, request context |
+
+The framework already creates child containers for every chat message, REST request, and socket connection. `ContainerScoped` services do not leak across them.
+
+```typescript
+import { injectable, singleton, scoped, Lifecycle } from '@wabot-dev/framework'
+
+@singleton()
+export class ProductCache {
+  private byId = new Map<string, string>()
+  put(id: string, name: string) { this.byId.set(id, name) }
+}
+
+@injectable()
+export class QuoteCalculator {
+  total(base: number, discount: number) { return base - base * discount }
+}
+
+@scoped(Lifecycle.ContainerScoped)
+export class RequestContext {
+  private userId?: string
+  setUserId(id: string) { this.userId = id }
+  requireUserId() {
+    if (!this.userId) throw new Error('Unauthorized')
+    return this.userId
+  }
+}
+```
+
+Decorators that mark something as a controller/handler also apply `@injectable()` for you (`@chatController`, `@restController`, `@socketController`, `@commandHandler`, `@cronHandler`, `@mindset`, `@mindsetModule`). Do not stack lifecycle decorators on top of those — they will conflict.
+
+## Resolving and registering
+
+```typescript
+import { container, inject, injectable } from '@wabot-dev/framework'
+
+container.register('SMTP_HOST', { useValue: 'smtp.example.com' })
+container.register('SMTP_PORT', { useValue: 587 })
+
+@injectable()
+export class Mailer {
+  constructor(
+    @inject('SMTP_HOST') private host: string,
+    @inject('SMTP_PORT') private port: number,
+  ) {}
+}
+```
+
+You rarely need `container.register*` in app code — for chat/REST/socket components the runner does it. Use registration only for:
+
+- Replacing a default infra binding (e.g. swap `Locker` for a custom implementation).
+- Providing typed config values to classes you cannot decorate.
+- Bootstrapping in tests.
+
+`container.registerInstance(Token, value)` and `container.registerType(From, To)` are the two most common helpers.
+
+## `Env`
+
+```typescript
+import { container, Env } from '@wabot-dev/framework'
+
+const env = container.resolve(Env)
+
+const dbUrl = env.requireString('DATABASE_URL')
+const port = env.requireNumber('PORT', { default: 3000 })
+const isDev = env.isDevelopment() // controlled by WABOT_ENV: 'development' | 'staging' | 'testing' | 'production'
+```
+
+`Env.requireString` / `requireNumber` throw if the variable is missing and no `default` is provided.
+
+## Config tag functions
+
+Some addon decorators (e.g. `@socket`, `@whatsApp`, `@wasender`) accept a config object whose fields may be `ConfigReference` values produced by tag functions. The reference is resolved by `resolveConfigReferences` (called inside the decorator) against `process.env`, with the path translated to UPPER_SNAKE_CASE.
+
+```typescript
+import { socket } from '@wabot-dev/framework' // tag fns also exported from the package root
+import { str, num, bool, obj, strArr, numArr, boolArr } from '@wabot-dev/framework'
+
+@socket({
+  // Resolved from env: SOCKET_NAMESPACE; defaults to "chat" if env is missing.
+  namespace: str`socket.namespace:chat`,
+  maxConnections: num`socket.max:100`,
+})
+class MyController { /* ... */ }
+```
+
+Syntax: `<fn>\`path.with.dots:default\``. The default after the colon is optional. Only literal strings are allowed; interpolation throws.
+
+Available factories: `str`, `num`, `bool`, `obj` (parses JSON), `strArr`, `numArr`, `boolArr` (comma-separated).
+
+If you call `resolveConfigReferences(cfg)` yourself it returns a typed object where each `ConfigReference<T>` field is replaced by `T`.
+
+## Rules
+
+- Default to `@injectable()` for new code. Promote to `@singleton()` only when state must be shared.
+- `@scoped(Lifecycle.ContainerScoped)` only when the value must not leak across requests, chats, or socket connections.
+- Don't call `container.resolve(...)` inside a constructor — declare dependencies as constructor parameters and let DI inject them.
+- Use `Env.requireString/requireNumber` for plain env reads; use config tag functions only inside decorator configs that the framework already resolves.

package/skills/wabot-framework/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: wabot-framework
+description: Use when working with @wabot-dev/framework — building, reviewing, or debugging chat bots, REST APIs, sockets, async jobs, or any project scaffolded with @wabot-dev/create. Covers project boot, the IProjectRunnerConfig flow, file layout, the WABOT_BUNDLED dev/prod split, and where to dive for each subsystem.
+---
+
+# Wabot Framework — Umbrella skill
+
+Wabot is a TypeScript framework for chat bots, REST and Socket.IO APIs, and async/cron work, all wired through a `tsyringe`-based DI container. Code is self-discovered from `src/` at boot time and each subsystem is opt-in via decorators.
+
+## Project boot — `src/_run_.ts`
+
+```typescript
+import { run, IProjectRunnerConfig } from '@wabot-dev/framework'
+
+export const config: IProjectRunnerConfig = {}
+
+export default config
+
+if (process.env.WABOT_BUNDLED !== '1') {
+  run(config)
+}
+```
+
+- `run(config)` is the entry point. It scans `directories` (default `['src']`), imports every `.ts`/`.js` it finds (so decorators register), then starts every discovered subsystem.
+- `WABOT_BUNDLED=1` is set in production by `npm start` after `npm run build` produces `dist/entry.js` (bundled by `@wabot-dev/framework/dist/build/build.js`). In that mode you must not call `run()` at import time — the bundled entry calls it.
+- If `DATABASE_URL` is set to `postgres://…` the runner registers Pg adapters (chat memory/repo, jobs, cron jobs, locker, transaction). Otherwise it registers the in-memory equivalents. There is no manual `container.registerType(ChatRepository, …)` to write.
+
+`IProjectRunnerConfig` fields: `directories?`, `exclude?`, `connectionString?`, `chatAdapters?` (override auto-detect by env keys: `OPENAI_API_KEY` → OpenAI, `OPENROUTER_API_KEY` → OpenRouter, `ANTHROPIC_API_KEY` → Anthropic, `GOOGLE_API_KEY` → Google), `preloaded?` (used by the bundled output — skip filesystem scan).
+
+## Scripts (from `@wabot-dev/template`)
+
+| Script | What it does |
+| --- | --- |
+| `npm run dev` | `node --import=@yucacodes/ts --env-file=./.env ./src/_run_.ts` |
+| `npm run dev:watch` | Same with `--watch --watch-preserve-output` |
+| `npm run cmd` | Runs `runCmdClient()` — connects to the local cmd channel for terminal chats |
+| `npm run build` | Bundles to `dist/entry.js` via the framework's `build.js` |
+| `npm start` | Runs the bundle with `WABOT_BUNDLED=1` |
+| `npm run tsc` | `tsc --noEmit` |
+
+## Typical layout
+
+```text
+src/
+  _run_.ts                       # boot: run(config)
+  _cmd_.ts                       # optional terminal client
+  <bot>/
+    <Bot>ChatController.ts       # @chatController + channel decorators
+    mindset/<Bot>Mindset.ts      # @mindset implementing IMindset
+    modules/<Foo>Module.ts       # @mindsetModule with tool functions
+    models/<x>/<X>.ts            # Entity subclass
+    models/<x>/<X>Repository.ts  # @repository + @memExtension/@pgExtension
+```
+
+The runner discovers `@chatController`, `@restController`, `@socketController`, `@uiController`, `@commandHandler`, `@cronHandler`, and `@chatAdapter` by scanning `directories`. No central registration list.
+
+## Subsystem skills
+
+Load the skill that matches the task:
+
+| Task | Skill |
+| --- | --- |
+| Wire services, lifecycles, env, config | `wabot-di-config` |
+| Validate DTOs, transform input, describe tool args | `wabot-validation` |
+| Define entities, repositories, queries | `wabot-persistence` |
+| Define bot behavior, modules, models | `wabot-mindset` |
+| Receive chat messages, configure channels (cmd, socket, telegram, whatsapp) | `wabot-chat` |
+| Expose REST endpoints or Socket.IO namespaces | `wabot-rest-socket` |
+| Server-render web pages, forms, and interactive islands | `wabot-ui` |
+| Background commands, cron schedules, DB transactions | `wabot-async` |
+| Protect endpoints/sockets with JWT or API key | `wabot-auth` |
+| Logger, locking, errors, password hashing, randomness | `wabot-ops` |
+| Write tests or evals (harnesses, mocks, LlmJudge) | `wabot-testing` |
+
+## Hard rules
+
+- All decorators and helpers ship from a single package: `@wabot-dev/framework`. Never import from internal paths.
+- Code identifiers are in English; user-facing text (mindset prompts, docs) may be in Spanish or the bot's chosen language.
+- Decorators run as **side effects** on import. The project runner relies on this. Do not lazy-load files that contain decorators behind conditional branches.
+- Never invent decorators or types not present in the framework source. If a need is not covered, write a plain class with `@injectable()`/`@singleton()` and inject it.
+- Do not rename or restructure the discovery scripts (`_run_.ts`, `_cmd_.ts`) without also updating `package.json` and the build output.