@wabot-dev/create 0.0.3 → 0.0.4

package/skills/wabot-persistence/SKILL.md

@@ -0,0 +1,155 @@
+---
+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(['pg'])` (or `@transaction()` to run in every registered adapter):
+
+```typescript
+import { transaction } from '@wabot-dev/framework'
+
+class CheckoutService {
+  @transaction(['pg'])
+  async checkout(orderId: string) {
+    // all repository writes here run inside one PG transaction
+  }
+}
+```
+
+The framework injects a `PgTransactionAdapter` automatically under Postgres mode. 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.

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

@@ -0,0 +1,163 @@
+---
+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.

package/skills/wabot-validation/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: wabot-validation
+description: Use when defining request DTOs, mindset module argument classes, or any class that must be validated and transformed by Wabot — including REST/socket inputs and tool function parameters. Covers the validator decorators (@isString, @isNumber, @isBoolean, @isDate, @isIn, @isNotEmpty, @isPresent, @isRecord, @isOptional, @isModel, @isArray, @min, @max), @description, validateAndTransform, and Mapper.
+---
+
+# Validation, description, mapping
+
+Wabot validates request shapes through decorator-driven metadata. The same metadata feeds:
+
+- REST endpoint argument binding (`@onPost`, etc.).
+- Socket event payloads (`@onSocketEvent`).
+- Mindset tool function parameters (the LLM sees the validator type and the `@description`).
+- `Async.runCommand` / `Async.scheduleCommand` payloads (validated against the `@command` class).
+
+## Field validators
+
+All decorators are exported from `@wabot-dev/framework`. Apply them to public class fields.
+
+| Decorator | Effect |
+| --- | --- |
+| `@isString()` | Value must be `string` |
+| `@isNumber()` | Value must be `number` |
+| `@isBoolean()` | Value must be `boolean` |
+| `@isDate()` | Value must parse as `Date` (ISO 8601 input) |
+| `@isIn([...values])` | Value must be one of the listed literals |
+| `@isNotEmpty()` | String must be non-empty after trim |
+| `@isPresent()` | Field must be present (not `undefined`) |
+| `@isRecord(keyType, valueType)` | Plain object with typed keys/values; `keyType: 'number' \| 'string'`, `valueType: 'number' \| 'string' \| 'boolean'` |
+| `@isOptional()` | Skip remaining validators when the value is null/undefined |
+| `@isModel(OtherClass)` | Nested model validated against `OtherClass` |
+| `@isArray({ minLength?, maxLength? })` | Field must be an array |
+| `@min(n)` | Numeric / length minimum |
+| `@max(n)` | Numeric / length maximum |
+
+Validators chain top-to-bottom. Put `@isOptional()` **above** the type validator if the field is optional.
+
+```typescript
+import { description, isIn, isNotEmpty, isNumber, isOptional, isString, max, min } from '@wabot-dev/framework'
+
+export class ListGamesRequest {
+  @isString()
+  @isIn(['backlog', 'playing', 'finished', 'abandoned'])
+  @description('Filter by status')
+  status: 'backlog' | 'playing' | 'finished' | 'abandoned' = 'backlog'
+
+  @isNumber()
+  @min(1)
+  @max(20)
+  @description('Maximum number of games to return')
+  limit: number = 5
+
+  @isOptional()
+  @isString()
+  cursor?: string
+}
+```
+
+The `default` value on the field becomes the value when the input is missing and the field is optional.
+
+## `@description`
+
+`@description('...')` annotates a field or method. Two roles:
+
+1. On a request-class field: it becomes the LLM-facing parameter description for mindset tool functions.
+2. On a `@mindsetModule()` method: it becomes the tool's description (without it the function is not exposed as a tool).
+
+Mindset module functions **must** have a single request-object parameter (or no parameter), and every property of that request class must have both a type validator (e.g. `@isString()`) and a `@description(...)`. The framework throws at boot otherwise.
+
+## `validateAndTransform`
+
+```typescript
+import { validateAndTransform } from '@wabot-dev/framework'
+
+const { value, error } = validateAndTransform(rawInput, ListGamesRequest)
+if (error) {
+  // error.description + error.properties (per-field errors)
+}
+```
+
+Use this when you receive a payload outside a framework-managed boundary (e.g. a manually parsed file or queue message). Inside a REST/socket controller or a command handler the framework already validates the parameter for you.
+
+## `Mapper`
+
+`Mapper` is an injectable utility that combines deep-copy + `validateAndTransform`. It is useful when you need to convert a database row, a remote response, or a Storable into a typed model and you want a hard failure on shape mismatch (it throws `CustomError` with `httpCode: 500`).
+
+```typescript
+import { container, Mapper } from '@wabot-dev/framework'
+
+const mapper = container.resolve(Mapper)
+const game: GameDto = mapper.map(rawRow, GameDto)
+```
+
+`Mapper.map(data, ctor)` will:
+
+- Deep-copy `data` (Storables → plain objects, Dates → epoch ms).
+- Run all validators on the target class.
+- Return a typed instance, or throw.
+
+## Rules
+
+- Every public DTO/Request field needs at least one type validator. Without it, the framework can't introspect the type at runtime (TypeScript types are erased).
+- Always pair `@description` with a type validator on mindset module request fields.
+- Prefer field defaults over `@isOptional()` when you have a sensible default; reserve `@isOptional()` for fields that may genuinely be absent.
+- Don't subclass `RestRequest` unless you want the raw Express `Request` injected into the endpoint — see `wabot-rest-socket`.

package/skills/wabot-framework/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Wabot Framework"
-  short_description: "Build apps with @wabot-dev/framework"
-  default_prompt: "Use this skill to implement, review, or debug Wabot applications using the bundled offline examples and reference files."
-

package/skills/wabot-framework/references/async-and-cron.md

@@ -1,57 +0,0 @@
-# Async And Cron
-
-Use this when scheduling work in the background or recurring jobs.
-
-## Command and handler
-
-```typescript
-import { command, commandHandler, type ICommandHandler } from '@wabot-dev/framework'
-import { isString } from '@wabot-dev/framework'
-
-@command('save-test-tag')
-export class SaveTestTag {
-  @isString()
-  value!: string
-}
-
-@commandHandler(SaveTestTag)
-export class SaveTestTagHandler implements ICommandHandler<SaveTestTag> {
-  constructor(private tags: TagRepository) {}
-
-  async handle(input: SaveTestTag) {
-    await this.tags.save(input.value)
-  }
-}
-```
-
-## Run or schedule a command
-
-```typescript
-import { Async } from '@wabot-dev/framework'
-
-const job = await async.runCommand(SaveTestTag, { value: 'hello' })
-await async.scheduleCommand(SaveTestTag, { value: 'later' }, { minutes: 10 })
-```
-
-## Cron handler
-
-```typescript
-import { cron } from '@wabot-dev/framework'
-
-@cron({ name: 'sync-leads', cron: '0 * * * *' })
-export class SyncLeadsCron {
-  constructor(private leadService: LeadService) {}
-
-  async handle() {
-    await this.leadService.sync()
-  }
-}
-```
-
-## Good practice
-
-- Use commands for one-off background work.
-- Use cron for repeated schedules.
-- Keep command DTOs validated and small.
-- Keep cron handlers idempotent because they can run many times.
-

package/skills/wabot-framework/references/controllers-and-auth.md

@@ -1,104 +0,0 @@
-# Controllers And Auth
-
-Use this when exposing HTTP endpoints, socket events, or protected routes.
-
-## REST controller
-
-```typescript
-import { IncomingMessage } from 'http'
-import { onPost, restController } from '@wabot-dev/framework'
-
-class PaymentService {
-  processWebhook(rawBody: string) {
-    return { ok: true, rawBody }
-  }
-}
-
-@restController('/webhooks/bold')
-export class BoldWebhookController {
-  constructor(private paymentService: PaymentService) {}
-
-  @onPost({
-    disableJsonParser: true,
-    disableUrlEncodedParser: true,
-  })
-  async receiveWebhook(request: IncomingMessage) {
-    const rawBody = await this.readRawBody(request)
-    return this.paymentService.processWebhook(rawBody)
-  }
-}
-```
-
-## Socket controller
-
-```typescript
-import { jwtHandshakeGuard, onSocketEvent, socketController } from '@wabot-dev/framework'
-
-@jwtHandshakeGuard()
-@socketController('/sales')
-export class SalesSocketController {
-  @onSocketEvent('message')
-  async onMessage(payload: { text: string }) {
-    return { ok: true, received: payload.text }
-  }
-}
-```
-
-## JWT and API key auth
-
-Use JWT when the client already has a signed token. Use API keys when the client should present a shared secret.
-
-```typescript
-import {
-  apiKeyGuard,
-  apiKeyHandshakeGuard,
-  jwtGuard,
-  jwtHandshakeGuard,
-  onGet,
-  onPost,
-  restController,
-  socketController,
-} from '@wabot-dev/framework'
-
-class CreateLeadDto {
-  name!: string
-}
-
-class LeadService {
-  async create(body: CreateLeadDto) {
-    return { created: true, lead: body }
-  }
-}
-
-@restController('/api/leads')
-export class LeadApiController {
-  constructor(private leadService: LeadService) {}
-
-  @apiKeyGuard()
-  @onGet()
-  async listLeads() {
-    return []
-  }
-
-  @jwtGuard()
-  @onPost()
-  async createLead(body: CreateLeadDto) {
-    return this.leadService.create(body)
-  }
-}
-
-@socketController('/lead-room')
-@jwtHandshakeGuard()
-export class LeadRoomSocketController {}
-
-@apiKeyHandshakeGuard()
-@socketController('/api-room')
-export class ApiRoomSocketController {}
-```
-
-## Rule of thumb
-
-- REST for request/response workflows, webhooks, and admin APIs.
-- Socket for live events and long-lived sessions.
-- JWT when the client already has a signed token.
-- API key when the client should present a shared secret.

package/skills/wabot-framework/references/core-patterns.md

@@ -1,83 +0,0 @@
-# Core Patterns
-
-Use this when deciding how to register and inject services.
-
-## Lifecycles
-
-| Decorator | Use for | Example |
-| --- | --- | --- |
-| `@singleton()` | Shared clients, repositories, config, caches | one DB repository for the app |
-| `@injectable()` | Stateless services and modules | calculators, adapters, helpers |
-| `@scoped(Lifecycle.ContainerScoped)` | Request/chat/socket-local state | auth context, request context |
-
-## Singleton example
-
-```typescript
-import { singleton } from '@wabot-dev/framework'
-
-@singleton()
-export class ProductRepository {
-  private products = new Map<string, string>()
-
-  save(id: string, name: string) {
-    this.products.set(id, name)
-  }
-}
-```
-
-## Injectable example
-
-```typescript
-import { injectable } from '@wabot-dev/framework'
-
-@injectable()
-export class QuoteCalculator {
-  total(base: number, discount: number) {
-    return base - base * discount
-  }
-}
-```
-
-## Scoped example
-
-```typescript
-import { Lifecycle, scoped } from '@wabot-dev/framework'
-
-@scoped(Lifecycle.ContainerScoped)
-export class RequestContext {
-  private userId?: string
-
-  setUserId(userId: string) {
-    this.userId = userId
-  }
-
-  requireUserId() {
-    if (!this.userId) throw new Error('Unauthorized')
-    return this.userId
-  }
-}
-```
-
-## Token injection
-
-```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 smtpHost: string,
-    @inject('SMTP_PORT') private smtpPort: number,
-  ) {}
-}
-```
-
-## Rule of thumb
-
-- Use singleton for shared infrastructure.
-- Use injectable for pure business logic.
-- Use scoped only when state must not leak across requests or chats.
-