@wabot-dev/create 0.0.2 → 0.0.4

package/skills/wabot-ops/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: wabot-ops
+description: Use when reaching for cross-cutting utilities in a Wabot app — structured logging, distributed/in-process locking, custom errors with HTTP codes, password hashing, secure random generators, or process-level error handlers. Covers Logger (6 levels via debug + optional IErrorMonitor), Locker / ILockKey / ILockerKey (in-memory + PG implementations selected by DATABASE_URL), CustomError, setupErrorHandlers, Password (scrypt-based), and Random.
+---
+
+# Operations utilities
+
+## Logger
+
+```typescript
+import { Logger } from '@wabot-dev/framework'
+
+const log = new Logger('myapp:orders')
+
+log.trace('http request', { method: 'GET', path: '/orders' })
+log.debug('reconciling', { batchId })
+log.info('orders worker started', { workers: 4 })
+log.warn('retrying', err)
+log.error('charge failed', err, { orderId })
+log.fatal('out of memory', err)
+```
+
+The logger is a thin wrapper over the `debug` package. Each level publishes to namespace `<name>:<level>` so you can enable subsets via `DEBUG`:
+
+```
+DEBUG=wabot:*:error,wabot:*:warn,wabot:*:info
+DEBUG=myapp:orders:*
+```
+
+Severity levels and intent (matches the framework's own usage):
+
+| Level | Use for |
+| --- | --- |
+| `trace` | Per-request / per-message firehose |
+| `debug` | Developer-facing flow detail |
+| `info` | Lifecycle events worth keeping |
+| `warn` | Recoverable anomaly, handled gracefully |
+| `error` | Operation failed; include the `Error` object |
+| `fatal` | Process cannot continue (uncaught exception / unhandled rejection) |
+
+Always pass the `Error` instance as one of the args — the logger serializes it cleanly. Extra object args are merged into a `extra` field reported to the monitor (see below).
+
+### Optional error monitor
+
+`Logger.setMonitor(monitor)` attaches an `IErrorMonitor` that receives `warn` / `error` / `fatal` events. Use this to plug Sentry / Datadog / etc.:
+
+```typescript
+import { Logger, IErrorMonitor, IErrorMonitorContext } from '@wabot-dev/framework'
+
+const monitor: IErrorMonitor = {
+  captureError(err, ctx) { /* Sentry.captureException(err, { extra: ctx }) */ },
+  captureMessage(msg, ctx) { /* ... */ },
+}
+
+Logger.setMonitor(monitor)
+```
+
+### `setupErrorHandlers`
+
+Call once at boot to convert `uncaughtException` / `unhandledRejection` into structured logs (and process exits, by default):
+
+```typescript
+import { setupErrorHandlers } from '@wabot-dev/framework'
+
+setupErrorHandlers({
+  exitOnUncaughtException: true,
+  exitOnUnhandledRejection: true,
+})
+```
+
+When using the project runner, the framework wires its own logger; you usually don't need to call this in app code.
+
+## `CustomError`
+
+```typescript
+import { CustomError } from '@wabot-dev/framework'
+
+throw new CustomError({
+  message: 'Order not found',
+  humanMessage: 'No encontramos esa orden.',
+  code: 'ORDER_NOT_FOUND',
+  httpCode: 404,
+  info: { orderId },
+})
+```
+
+REST + Socket controllers translate thrown `CustomError`s into the right HTTP status / socket ack `{ error }`. `code` is meant for machine consumers; `humanMessage` is what you show users.
+
+## `Locker`
+
+`Locker.withKey(key)` returns an `ILockKey` you run code under. Two implementations are selected by the runner:
+
+- `InMemoryLocker` — single-process locks.
+- `PgLocker` — `pg_advisory_lock`-based locks, safe across processes.
+
+```typescript
+import { container, Locker, type ILockerKey } from '@wabot-dev/framework'
+
+const locker = container.resolve(Locker)
+
+// Any string or number
+await locker.withKey('checkout:order-1').run(async () => {
+  // critical section; waits for the lock
+})
+
+// tryRun returns undefined if the lock is held instead of waiting
+const result = await locker.withKey('checkout:order-1').tryRun(async () => {
+  return await charge()
+})
+
+// Anything implementing ILockerKey works — Entities do (their id is the key)
+await locker.withKey(orderEntity).run(async () => { ... })
+```
+
+`ILockerKey { lockerKey(): string | number }` — implement on a domain type if you want to pass it directly.
+
+## `Password`
+
+```typescript
+import { Password } from '@wabot-dev/framework'
+
+const hash = Password.hash({ password: input })
+
+const ok = Password.isValid({ password: candidate, hash })
+
+const tempPassword = Password.generate(16)
+```
+
+`scrypt` with a random salt; defaults `saltLength: 16`, `keyLength: 64`. The hash format is `<salt>:<key>` (both hex).
+
+## `Random`
+
+```typescript
+import { Random } from '@wabot-dev/framework'
+
+Random.integer({ min: 0, max: 99 })       // uniform
+Random.slug('Hola Mundo', { randomLength: 6 }) // "hola-mundo-x9k2qr"
+Random.alphaNumeric(32)
+Random.alphaNumericLowerCase(32)
+Random.numberCode(6)                      // 6-digit OTP
+```
+
+All generators use `crypto.randomBytes` and reject biased ranges — safe to use for tokens, OTPs, and slugs.
+
+## Rules
+
+- Pass `Error` objects to `log.error/log.fatal`, not stringified messages. The monitor pipeline expects the real Error.
+- Use `CustomError` for any error that crosses a controller boundary so HTTP/socket clients get a sensible status.
+- Don't roll your own password hashing — use `Password.hash` / `Password.isValid`.
+- Don't use `Math.random()` for IDs, tokens, OTPs, or anything user-facing. Use `Random`.
+- Lock keys should encode the *resource* being protected. Prefer entities (via `ILockerKey`) over loose strings to prevent typos.

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`.