@wabot-dev/create 0.0.4 → 2.0.0-beta.0

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

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

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