@moostjs/event-ws 0.6.6 → 0.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/event-ws",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "@moostjs/event-ws",
   "keywords": [
     "composables",
@@ -22,13 +22,8 @@
     "url": "git+https://github.com/moostjs/moostjs.git",
     "directory": "packages/event-ws"
   },
-  "bin": {
-    "moostjs-event-ws-skill": "./scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts/setup-skills.js"
+    "dist"
   ],
   "type": "module",
   "sideEffects": false,
@@ -44,19 +39,18 @@
     }
   },
   "dependencies": {
-    "@wooksjs/event-ws": "^0.7.8"
+    "@wooksjs/event-ws": "^0.7.10"
   },
   "devDependencies": {
     "vitest": "3.2.4"
   },
   "peerDependencies": {
     "@prostojs/infact": "^0.4.1",
-    "@wooksjs/event-core": "^0.7.8",
-    "moost": "^0.6.6"
+    "@wooksjs/event-core": "^0.7.10",
+    "moost": "^0.6.8"
   },
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "test": "vitest"
   }
 }

package/scripts/setup-skills.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-import { fileURLToPath } from 'url'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-const SKILL_NAME = 'moostjs-event-ws'
-const SKILL_SRC = path.join(__dirname, '..', 'skills', SKILL_NAME)
-
-if (!fs.existsSync(SKILL_SRC)) {
-  console.error(`No skills found at ${SKILL_SRC}`)
-  console.error('Add your SKILL.md files to the skills/' + SKILL_NAME + '/ directory first.')
-  process.exit(1)
-}
-
-const AGENTS = {
-  'Claude Code': { dir: '.claude/skills',   global: path.join(os.homedir(), '.claude', 'skills') },
-  'Cursor':      { dir: '.cursor/skills',   global: path.join(os.homedir(), '.cursor', 'skills') },
-  'Windsurf':    { dir: '.windsurf/skills', global: path.join(os.homedir(), '.windsurf', 'skills') },
-  'Codex':       { dir: '.codex/skills',    global: path.join(os.homedir(), '.codex', 'skills') },
-  'OpenCode':    { dir: '.opencode/skills', global: path.join(os.homedir(), '.opencode', 'skills') },
-}
-
-const args = process.argv.slice(2)
-const isGlobal = args.includes('--global') || args.includes('-g')
-const isPostinstall = args.includes('--postinstall')
-let installed = 0, skipped = 0
-const installedDirs = []
-
-for (const [agentName, cfg] of Object.entries(AGENTS)) {
-  const targetBase = isGlobal ? cfg.global : path.join(process.cwd(), cfg.dir)
-  const agentRootDir = path.dirname(cfg.global) // Check if the agent has ever been installed globally
-
-  // In postinstall mode: silently skip agents that aren't set up globally
-  if (isPostinstall || isGlobal) {
-    if (!fs.existsSync(agentRootDir)) { skipped++; continue }
-  }
-
-  const dest = path.join(targetBase, SKILL_NAME)
-  try {
-    fs.mkdirSync(dest, { recursive: true })
-    fs.cpSync(SKILL_SRC, dest, { recursive: true })
-    console.log(`✅  ${agentName}: installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`⚠️   ${agentName}: failed — ${err.message}`)
-  }
-}
-
-// Add locally-installed skill dirs to .gitignore
-if (!isGlobal && installedDirs.length > 0) {
-  const gitignorePath = path.join(process.cwd(), '.gitignore')
-  let gitignoreContent = ''
-  try { gitignoreContent = fs.readFileSync(gitignorePath, 'utf8') } catch {}
-  const linesToAdd = installedDirs.filter(d => !gitignoreContent.includes(d))
-  if (linesToAdd.length > 0) {
-    const hasHeader = gitignoreContent.includes('# AI agent skills')
-    const block = (gitignoreContent && !gitignoreContent.endsWith('\n') ? '\n' : '')
-      + (hasHeader ? '' : '\n# AI agent skills (auto-generated by setup-skills)\n')
-      + linesToAdd.join('\n') + '\n'
-    fs.appendFileSync(gitignorePath, block)
-    console.log(`📝  Added ${linesToAdd.length} entries to .gitignore`)
-  }
-}
-
-if (installed === 0 && isPostinstall) {
-  // Silence is fine — no agents present, nothing to do
-} else if (installed === 0 && skipped === Object.keys(AGENTS).length) {
-  console.log('No agent directories detected. Try --global or run without it for project-local install.')
-} else if (installed === 0) {
-  console.log('Nothing installed. Run without --global to install project-locally.')
-} else {
-  console.log(`\n✨  Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

package/skills/moostjs-event-ws/SKILL.md

@@ -1,42 +0,0 @@
----
-name: moostjs-event-ws
-description: Use this skill when working with @moostjs/event-ws — to build WebSocket servers with Moost using MoostWs adapter or WsApp quick factory, register message handlers with @Message(), handle connections with @Connect()/@Disconnect(), extract data with @MessageData()/@ConnectionId()/@RawMessage()/@MessageId()/@MessageType()/@MessagePath(), use composables like useWsConnection(), useWsMessage(), useWsRooms(), useWsServer(), manage rooms and broadcasting, integrate with @moostjs/event-http via @Upgrade() routes, throw WsError for error replies, or test handlers with prepareTestWsConnectionContext()/prepareTestWsMessageContext(). Covers the wire protocol (WsClientMessage, WsReplyMessage, WsPushMessage), standalone and HTTP-integrated modes, heartbeat, custom serializers, and multi-instance broadcasting with WsBroadcastTransport.
----
-
-# @moostjs/event-ws
-
-Moost WebSocket adapter — decorator-based routing, DI, interceptors, and pipes for WebSocket handlers, wrapping `@wooksjs/event-ws`.
-
-## How to use this skill
-
-Read the domain file that matches the task. Do not load all files — only what you need.
-
-| Domain | File | Load when... |
-|--------|------|------------|
-| Core concepts & setup | [core.md](core.md) | Starting a new project, choosing standalone vs HTTP-integrated mode, configuring MoostWs or WsApp |
-| Handlers | [handlers.md](handlers.md) | Defining @Message, @Connect, @Disconnect handlers, understanding handler lifecycle |
-| Routing | [routing.md](routing.md) | Event+path routing, controller prefixes, parametric routes, wildcards |
-| Request data | [request-data.md](request-data.md) | Extracting message data, connection info, route params with resolver decorators |
-| Rooms & broadcasting | [rooms.md](rooms.md) | Room management, broadcasting, direct sends, server-wide queries, multi-instance scaling |
-| Wire protocol | [protocol.md](protocol.md) | JSON message format, client/server message types, error codes, heartbeat, custom serialization |
-| Testing | [testing.md](testing.md) | Unit-testing handlers with prepareTestWsMessageContext/prepareTestWsConnectionContext |
-
-## Quick reference
-
-```ts
-import {
-  // Adapter & factory
-  MoostWs, WsApp, WooksWs,
-  // Decorators
-  Message, Connect, Disconnect,
-  MessageData, RawMessage, MessageId, MessageType, MessagePath, ConnectionId,
-  // Composables
-  useWsConnection, useWsMessage, useWsRooms, useWsServer, currentConnection,
-  // Errors
-  WsError,
-  // Testing
-  prepareTestWsMessageContext, prepareTestWsConnectionContext,
-  // Re-exports from moost
-  Controller, Param, Intercept, Description,
-} from '@moostjs/event-ws'
-```

package/skills/moostjs-event-ws/core.md

@@ -1,157 +0,0 @@
-# Core concepts & setup — @moostjs/event-ws
-
-> Installation, mental model, standalone vs HTTP-integrated modes, and adapter configuration.
-
-## Concepts
-
-`@moostjs/event-ws` is a Moost adapter for WebSocket events. It wraps `@wooksjs/event-ws` and adds decorator-based routing, dependency injection, interceptors, and pipes to WebSocket handlers.
-
-**Two modes:**
-- **Standalone** — dedicated WebSocket server, no HTTP. Use `WsApp` for quick setup or `MoostWs` with `listen()`.
-- **HTTP-integrated** (recommended for production) — shares the HTTP port, requires explicit `@Upgrade()` route from `@moostjs/event-http`.
-
-**Wire protocol:** JSON-over-WebSocket with `event` + `path` routing. Clients send `{ event, path, data?, id? }`. Server replies with `{ id, data?, error? }` or pushes `{ event, path, data? }`.
-
-## Installation
-
-```bash
-npm install @moostjs/event-ws
-```
-
-For HTTP-integrated mode, also install:
-```bash
-npm install @moostjs/event-ws @moostjs/event-http
-```
-
-## Standalone Mode — WsApp
-
-`WsApp` extends `Moost` and sets up a standalone `MoostWs` adapter automatically:
-
-```ts
-import { WsApp, Message, MessageData, Connect, ConnectionId } from '@moostjs/event-ws'
-import { Controller } from 'moost'
-
-@Controller()
-class ChatController {
-  @Connect()
-  onConnect(@ConnectionId() id: string) {
-    console.log(`Connected: ${id}`)
-  }
-
-  @Message('echo', '/echo')
-  echo(@MessageData() data: unknown) {
-    return data
-  }
-}
-
-new WsApp()
-  .controllers(ChatController)
-  .start(3000)
-```
-
-### WsApp API
-
-```ts
-class WsApp extends Moost {
-  controllers(...controllers: (object | Function | [string, object | Function])[]): this
-  useWsOptions(opts: { ws?: TWooksWsOptions }): this
-  getWsAdapter(): MoostWs | undefined
-  start(port: number, hostname?: string): Promise<void>
-}
-```
-
-## HTTP-Integrated Mode — MoostWs
-
-Pass the HTTP app to share the port. Requires an `@Upgrade()` route:
-
-```ts
-import { MoostHttp } from '@moostjs/event-http'
-import { MoostWs } from '@moostjs/event-ws'
-import { Moost } from 'moost'
-
-const app = new Moost()
-const http = new MoostHttp()
-const ws = new MoostWs({ httpApp: http.getHttpApp() })
-
-app.adapter(http)
-app.adapter(ws)
-app.registerControllers(AppController, ChatController)
-
-await http.listen(3000)
-await app.init()
-```
-
-The upgrade controller:
-
-```ts
-import { Upgrade } from '@moostjs/event-http'
-import type { WooksWs } from '@moostjs/event-ws'
-import { Controller, Inject } from 'moost'
-
-@Controller()
-export class AppController {
-  constructor(@Inject('WooksWs') private ws: WooksWs) {}
-
-  @Upgrade('ws')
-  upgrade() {
-    return this.ws.upgrade()
-  }
-}
-```
-
-### MoostWs API
-
-```ts
-interface TMoostWsOpts {
-  wooksWs?: WooksWs | TWooksWsOptions
-}
-
-class MoostWs {
-  constructor(opts?: TMoostWsOpts & { httpApp?: { getHttpApp(): unknown } | object })
-  getWsApp(): WooksWs
-  listen(port: number, hostname?: string): Promise<void>  // standalone only
-  close(): void
-}
-```
-
-### TWooksWsOptions
-
-```ts
-interface TWooksWsOptions {
-  heartbeatInterval?: number       // ping interval ms (default: 30000, 0 = disabled)
-  heartbeatTimeout?: number        // pong timeout ms (default: 5000)
-  messageParser?: (raw: Buffer | string) => WsClientMessage
-  messageSerializer?: (msg: WsReplyMessage | WsPushMessage) => string | Buffer
-  logger?: TConsoleBase
-  maxMessageSize?: number          // bytes (default: 1MB)
-  wsServerAdapter?: WsServerAdapter
-  broadcastTransport?: WsBroadcastTransport
-}
-```
-
-## DI: Injecting Adapter Instances
-
-The adapter registers both class and string keys:
-
-| Key | Resolves To |
-|-----|-------------|
-| `MoostWs` / `'MoostWs'` | The `MoostWs` adapter instance |
-| `WooksWs` / `'WooksWs'` | The underlying `WooksWs` instance |
-
-Use string keys for reliability (avoids esbuild/tsx metadata issues):
-
-```ts
-constructor(@Inject('WooksWs') private ws: WooksWs) {}
-```
-
-## Best Practices
-
-- Use HTTP-integrated mode for production — single port, explicit upgrade control, easier auth
-- Use `WsApp` for quick prototyping or standalone WebSocket services
-- Use `@Inject('WooksWs')` (string key) rather than class reference to avoid module init order issues
-
-## Gotchas
-
-- `WsApp.start()` must be awaited — it calls `this.init()` and `listen()` internally
-- In HTTP-integrated mode, `ws.listen()` is NOT called — the HTTP server handles the port
-- The package is marked experimental — the API may change without semver until stable

package/skills/moostjs-event-ws/handlers.md

@@ -1,162 +0,0 @@
-# Handlers — @moostjs/event-ws
-
-> Defining WebSocket event handlers with @Message, @Connect, and @Disconnect decorators.
-
-## Concepts
-
-Moost WS provides three handler decorators:
-- `@Message(event, path?)` — handles routed WebSocket messages
-- `@Connect()` — runs when a new connection is established
-- `@Disconnect()` — runs when a connection closes
-
-All handlers participate in the full Moost event lifecycle (scope registration, interceptor init, argument resolution, handler execution, interceptor after/onError, scope cleanup).
-
-## API Reference
-
-### `@Message(event: string, path?: string)`
-
-Registers a handler for routed WebSocket messages. Matches on both the `event` field and `path` from the client message.
-
-```ts
-import { Message, MessageData } from '@moostjs/event-ws'
-import { Controller } from 'moost'
-
-@Controller()
-export class EchoController {
-  @Message('echo', '/echo')
-  echo(@MessageData() data: unknown) {
-    return data // sent back as reply if client included an id
-  }
-}
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `event` | `string` | Message event type to match (e.g. `"message"`, `"join"`, `"rpc"`) |
-| `path` | `string` (optional) | Route path with optional params. When omitted, the method name is used. |
-
-**Return values:** The return value is sent as a reply only when the client included a correlation `id` (RPC). Fire-and-forget messages (no `id`) ignore the return value.
-
-### `@Connect()`
-
-Runs when a new WebSocket connection is established. Executes inside the connection context.
-
-```ts
-import { Connect, ConnectionId } from '@moostjs/event-ws'
-import { Controller } from 'moost'
-
-@Controller()
-export class LifecycleController {
-  @Connect()
-  onConnect(@ConnectionId() id: string) {
-    console.log(`New connection: ${id}`)
-  }
-}
-```
-
-If the handler throws or returns a rejected promise, the connection is closed immediately.
-
-### `@Disconnect()`
-
-Runs when a WebSocket connection closes. Use for cleanup.
-
-```ts
-import { Disconnect, ConnectionId } from '@moostjs/event-ws'
-import { Controller } from 'moost'
-
-@Controller()
-export class LifecycleController {
-  @Disconnect()
-  onDisconnect(@ConnectionId() id: string) {
-    console.log(`Connection ${id} closed`)
-  }
-}
-```
-
-Room membership is automatically cleaned up on disconnect — no need to manually leave rooms.
-
-## Common Patterns
-
-### Pattern: Multiple events on the same path
-
-```ts
-@Controller('chat')
-export class ChatController {
-  @Message('join', ':room')
-  join(@Param('room') room: string) { /* ... */ }
-
-  @Message('leave', ':room')
-  leave(@Param('room') room: string) { /* ... */ }
-
-  @Message('message', ':room')
-  message(@Param('room') room: string) { /* ... */ }
-}
-```
-
-### Pattern: Mixed HTTP and WS handlers in one controller
-
-A single controller can contain both HTTP and WebSocket handlers when both adapters are registered:
-
-```ts
-import { Get } from '@moostjs/event-http'
-import { Message, MessageData } from '@moostjs/event-ws'
-import { Controller } from 'moost'
-
-@Controller('api')
-export class ApiController {
-  @Get('status')
-  getStatus() { return { online: true } }
-
-  @Message('query', '/status')
-  wsStatus() { return { online: true } }
-}
-```
-
-### Pattern: Protected handlers with interceptors
-
-```ts
-import { Message, MessageData } from '@moostjs/event-ws'
-import { Controller, Intercept, Validate } from 'moost'
-import { AuthGuard } from './auth.guard'
-
-@Controller('admin')
-@Intercept(AuthGuard)
-export class AdminController {
-  @Message('broadcast', '/announce')
-  announce(@MessageData() @Validate() data: AnnounceDto) {
-    // protected by AuthGuard and validated
-  }
-}
-```
-
-### Pattern: Full lifecycle controller
-
-```ts
-@Controller('chat')
-export class ChatController {
-  @Connect()
-  onConnect(@ConnectionId() id: string) { /* ... */ }
-
-  @Disconnect()
-  onDisconnect(@ConnectionId() id: string) { /* ... */ }
-
-  @Message('join', ':room')
-  join(@Param('room') room: string) { /* ... */ }
-
-  @Message('message', ':room')
-  message(@Param('room') room: string) { /* ... */ }
-}
-```
-
-## Best Practices
-
-- Keep `@Connect` handlers lightweight — they block the connection establishment
-- Use `@Disconnect` for cleanup, but don't rely on it for room management (rooms auto-clean)
-- One controller can have at most one `@Connect` and one `@Disconnect` handler
-- Use interceptors (`@Intercept`) for cross-cutting concerns like auth and logging
-
-## Gotchas
-
-- Throwing in `@Connect` closes the connection immediately — use `WsError` for meaningful error codes
-- Fire-and-forget messages (no `id`) silently discard handler return values
-- `@Message` path is relative to the controller prefix, not absolute

package/skills/moostjs-event-ws/protocol.md

@@ -1,181 +0,0 @@
-# Wire protocol — @moostjs/event-ws
-
-> JSON message format, message types, error codes, heartbeat, and custom serialization.
-
-## Concepts
-
-Moost WS uses a simple JSON-over-WebSocket protocol. Messages are plain JSON objects sent as text frames. There are three message types:
-
-1. **Client → Server** (`WsClientMessage`) — routed by event + path
-2. **Server → Client: Reply** (`WsReplyMessage`) — response to an RPC call
-3. **Server → Client: Push** (`WsPushMessage`) — server-initiated message
-
-## Message Types
-
-### WsClientMessage (Client → Server)
-
-```ts
-interface WsClientMessage {
-  event: string            // Router method (e.g. "message", "join", "query")
-  path: string             // Route path (e.g. "/chat/general")
-  data?: unknown           // Payload
-  id?: string | number     // Correlation ID — present for RPC, absent for fire-and-forget
-}
-```
-
-**Fire-and-forget** (no reply expected):
-```json
-{ "event": "message", "path": "/chat/general", "data": { "text": "Hello!" } }
-```
-
-**RPC** (reply expected):
-```json
-{ "event": "join", "path": "/chat/general", "data": { "name": "Alice" }, "id": 1 }
-```
-
-### WsReplyMessage (Server → Client)
-
-Sent in response to a client message that included an `id`. Exactly one reply per request.
-
-```ts
-interface WsReplyMessage {
-  id: string | number                          // Matches client's correlation ID
-  data?: unknown                                // Handler return value
-  error?: { code: number; message: string }     // Error details (if handler threw)
-}
-```
-
-**Success:**
-```json
-{ "id": 1, "data": { "joined": true, "room": "general" } }
-```
-
-**Error:**
-```json
-{ "id": 1, "error": { "code": 400, "message": "Name is required" } }
-```
-
-### WsPushMessage (Server → Client)
-
-Server-initiated messages from broadcasts, subscriptions, or direct sends.
-
-```ts
-interface WsPushMessage {
-  event: string                        // Event type
-  path: string                         // Concrete path
-  params?: Record<string, string>      // Route params extracted by router
-  data?: unknown                       // Payload
-}
-```
-
-```json
-{ "event": "message", "path": "/chat/general", "data": { "from": "Alice", "text": "Hello!" } }
-```
-
-## Error Codes
-
-| Code | Meaning |
-|------|---------|
-| 400 | Bad request / validation error |
-| 401 | Unauthorized |
-| 403 | Forbidden |
-| 404 | Not found (auto-sent for unmatched routes) |
-| 409 | Conflict |
-| 429 | Too many requests |
-| 500 | Internal server error (auto-sent for unhandled exceptions) |
-| 503 | Service unavailable |
-
-### WsError
-
-Throw `WsError` for structured error responses:
-
-```ts
-import { WsError } from '@moostjs/event-ws'
-
-throw new WsError(400, 'Name is required')
-throw new WsError(401, 'Unauthorized')
-```
-
-```ts
-class WsError extends Error {
-  readonly code: number
-  constructor(code: number, message?: string)
-}
-```
-
-`WsError` works in:
-- `@Message` handlers — sends error reply to client (if RPC)
-- `@Upgrade` handlers — rejects the WebSocket connection
-- `@Connect` handlers — closes the connection
-
-Unhandled (non-`WsError`) exceptions send a generic `{ code: 500, message: "Internal Error" }` without leaking details.
-
-## Heartbeat
-
-The server sends periodic WebSocket `ping` frames to detect stale connections. Configure via `TWooksWsOptions`:
-
-```ts
-const ws = new MoostWs({
-  wooksWs: {
-    heartbeatInterval: 30000, // ms (default: 30000)
-    heartbeatTimeout: 5000,   // ms (default: 5000)
-  },
-})
-```
-
-Set `heartbeatInterval: 0` to disable.
-
-## Custom Serialization
-
-Both server and client support pluggable serialization (e.g. MessagePack, CBOR):
-
-```ts
-const ws = new MoostWs({
-  wooksWs: {
-    messageParser: (raw: string) => myCustomParse(raw),
-    messageSerializer: (msg: unknown) => myCustomSerialize(msg),
-  },
-})
-```
-
-Both sides must use the same serialization format.
-
-## Client Library
-
-Use `@wooksjs/ws-client` for a type-safe client:
-
-```bash
-npm install @wooksjs/ws-client
-```
-
-```ts
-import { createWsClient } from '@wooksjs/ws-client'
-
-const client = createWsClient('ws://localhost:3000/ws', {
-  reconnect: true,
-  rpcTimeout: 5000,
-})
-
-// RPC
-const result = await client.call('join', '/chat/general', { name: 'Alice' })
-
-// Listen for pushes
-client.on('message', '/chat/general', ({ data }) => {
-  console.log(`${data.from}: ${data.text}`)
-})
-
-// Fire-and-forget
-client.send('message', '/chat/general', { from: 'Alice', text: 'Hello!' })
-```
-
-## Best Practices
-
-- Use `id` (RPC) when the client needs a response, omit for fire-and-forget
-- Use HTTP-style numeric codes for errors (400, 401, 404, etc.)
-- Keep payloads small — default `maxMessageSize` is 1MB
-
-## Gotchas
-
-- Fire-and-forget messages that hit unmatched routes are logged but no error is sent to the client
-- Oversized messages (exceeding `maxMessageSize`) are silently dropped
-- Reply is only sent when client message includes `id` — handler return values are discarded otherwise

package/skills/moostjs-event-ws/request-data.md

@@ -1,185 +0,0 @@
-# Request data — @moostjs/event-ws
-
-> Resolver decorators for extracting message data, connection info, and route parameters from WebSocket events.
-
-## Concepts
-
-Moost WS provides parameter decorators that resolve values from the WebSocket event context. These decorators are applied to handler method arguments and participate in the Moost pipes pipeline (resolve, transform, validate).
-
-There are two categories:
-- **Message decorators** — only available in `@Message` handlers
-- **Connection decorators** — available in all handler types (`@Message`, `@Connect`, `@Disconnect`)
-
-Additionally, Wooks composable functions (`useWsMessage()`, `useWsConnection()`, etc.) can be called directly inside handler bodies.
-
-## API Reference
-
-### `@MessageData()`
-
-Resolves the parsed message payload (the `data` field from the client message).
-
-```ts
-@Message('message', '/chat/:room')
-onMessage(@MessageData() data: { from: string; text: string }) {
-  console.log(`${data.from}: ${data.text}`)
-}
-```
-
-**Returns:** `unknown` (typed by the parameter's type annotation)
-**Available in:** `@Message` only
-
-### `@RawMessage()`
-
-Resolves the raw message before JSON parsing.
-
-```ts
-@Message('debug', '/raw')
-onRaw(@RawMessage() raw: Buffer | string) {
-  console.log('Raw message:', raw.toString())
-}
-```
-
-**Returns:** `Buffer | string`
-**Available in:** `@Message` only
-
-### `@MessageId()`
-
-Resolves the message correlation ID. `undefined` for fire-and-forget, `string | number` for RPC calls.
-
-```ts
-@Message('query', '/info')
-info(@MessageId() messageId: string | number | undefined) {
-  console.log('Correlation ID:', messageId)
-  return { timestamp: Date.now() }
-}
-```
-
-**Returns:** `string | number | undefined`
-**Available in:** `@Message` only
-
-### `@MessageType()`
-
-Resolves the event type string from the message.
-
-```ts
-@Message('*', '/log')
-onAny(@MessageType() event: string) {
-  console.log('Event type:', event)
-}
-```
-
-**Returns:** `string`
-**Available in:** `@Message` only
-
-### `@MessagePath()`
-
-Resolves the concrete message path (after routing).
-
-```ts
-@Message('action', '/game/:id')
-onAction(@MessagePath() path: string) {
-  console.log('Message path:', path) // e.g. "/game/42"
-}
-```
-
-**Returns:** `string`
-**Available in:** `@Message` only
-
-### `@ConnectionId()`
-
-Resolves the unique connection identifier (UUID).
-
-```ts
-@Connect()
-onConnect(@ConnectionId() id: string) {
-  console.log(`Connected: ${id}`)
-}
-
-@Message('ping', '/ping')
-ping(@ConnectionId() id: string) {
-  return { pong: true, connectionId: id }
-}
-
-@Disconnect()
-onDisconnect(@ConnectionId() id: string) {
-  console.log(`Disconnected: ${id}`)
-}
-```
-
-**Returns:** `string`
-**Available in:** All handlers (`@Message`, `@Connect`, `@Disconnect`)
-
-### `@Param(name: string)`
-
-Resolves a named route parameter from the message path. Same decorator as HTTP routing (re-exported from `moost`).
-
-```ts
-@Message('message', ':room')
-onMessage(@Param('room') room: string, @MessageData() data: { text: string }) {
-  console.log(`[${room}] ${data.text}`)
-}
-```
-
-**Returns:** `string`
-**Available in:** `@Message` only
-
-### `@Params()`
-
-Resolves all route parameters as an object. Re-exported from `moost`.
-
-```ts
-@Message('move', '/game/:gameId/player/:playerId')
-onMove(@Params() params: { gameId: string; playerId: string }) {
-  console.log(params) // { gameId: '1', playerId: 'alice' }
-}
-```
-
-**Returns:** `Record<string, string>`
-**Available in:** `@Message` only
-
-## Using Composables Directly
-
-You can also call Wooks composables inside handler bodies instead of using decorators:
-
-```ts
-import { useWsMessage, useWsConnection } from '@moostjs/event-ws'
-
-@Message('echo', '/echo')
-echo() {
-  const { data, id, path, event } = useWsMessage()
-  const { id: connId, send } = useWsConnection()
-  return data
-}
-```
-
-## HTTP Context in WS Handlers
-
-In HTTP-integrated mode, HTTP composables from the upgrade request are available:
-
-```ts
-import { Connect, ConnectionId } from '@moostjs/event-ws'
-import { useHeaders, useRequest } from '@wooksjs/event-http'
-
-@Connect()
-onConnect(@ConnectionId() id: string) {
-  const { url } = useRequest()
-  const headers = useHeaders()
-  console.log('Upgrade URL:', url)
-  console.log('User-Agent:', headers['user-agent'])
-}
-```
-
-HTTP composables are read-only — response composables like `useResponse()` are not available in WS handlers.
-
-## Summary
-
-| Decorator | Returns | Available In |
-|-----------|---------|-------------|
-| `@MessageData()` | Parsed message payload | `@Message` |
-| `@RawMessage()` | Raw `Buffer \| string` | `@Message` |
-| `@MessageId()` | Correlation ID `string \| number \| undefined` | `@Message` |
-| `@MessageType()` | Event type `string` | `@Message` |
-| `@MessagePath()` | Concrete message path `string` | `@Message` |
-| `@ConnectionId()` | Connection UUID `string` | All handlers |
-| `@Param(name)` | Named route parameter `string` | `@Message` |
-| `@Params()` | All route parameters `object` | `@Message` |

package/skills/moostjs-event-ws/rooms.md

@@ -1,196 +0,0 @@
-# Rooms & broadcasting — @moostjs/event-ws
-
-> Room management, broadcasting, direct sends, server-wide queries, and multi-instance scaling.
-
-## Concepts
-
-Rooms group WebSocket connections for targeted broadcasting. A connection can join multiple rooms. Room names are strings — by default, the current message path is used as the room name.
-
-Three composables handle communication:
-- `useWsRooms()` — room-scoped operations (join, leave, broadcast). Available in message handlers only.
-- `useWsConnection()` — direct send to the current connection. Available in all handlers.
-- `useWsServer()` — server-wide operations (broadcast to all, query connections). Available in any context.
-
-## API Reference
-
-### `useWsRooms()`
-
-Room management for the current connection. Only available in `@Message` handlers.
-
-```ts
-const { join, leave, broadcast, rooms } = useWsRooms()
-```
-
-| Method | Description |
-|--------|-------------|
-| `join(room?)` | Join a room (default: current message path) |
-| `leave(room?)` | Leave a room (default: current message path) |
-| `broadcast(event, data?, opts?)` | Broadcast to room members |
-| `rooms()` | List rooms this connection has joined (`string[]`) |
-
-**Broadcast options:**
-```ts
-broadcast('message', data, {
-  room: '/custom-room',  // target a different room (default: current path)
-  excludeSelf: false,     // include the sender (default: true)
-})
-```
-
-### `useWsConnection()`
-
-Access the current WebSocket connection. Available in all handler types.
-
-```ts
-const { id, send, close } = useWsConnection()
-```
-
-| Property/Method | Description |
-|----------------|-------------|
-| `id` | Connection UUID (`string`) |
-| `send(event, path, data?, params?)` | Push a message to this client |
-| `close(code?, reason?)` | Close the connection |
-| `context` | The connection `EventContext` |
-
-### `useWsServer()`
-
-Server-wide operations. Available in any context.
-
-```ts
-const server = useWsServer()
-```
-
-| Method | Description |
-|--------|-------------|
-| `broadcast(event, path, data?)` | Broadcast to ALL connected clients |
-| `connections()` | Get all connections (`Map<string, WsConnection>`) |
-| `roomConnections(room)` | Get connections in a room (`Set<WsConnection>`) |
-| `getConnection(id)` | Get connection by ID (`WsConnection \| undefined`) |
-
-### `currentConnection()`
-
-Returns the connection `EventContext` regardless of context level:
-- In `@Connect`/`@Disconnect`: returns `current()` directly
-- In `@Message`: returns `current().parent` (the connection context)
-
-## Common Patterns
-
-### Pattern: Join a room and broadcast
-
-```ts
-@Controller('chat')
-export class ChatController {
-  @Message('join', ':room')
-  join(
-    @Param('room') room: string,
-    @ConnectionId() id: string,
-    @MessageData() data: { name: string },
-  ) {
-    const { join, broadcast, rooms } = useWsRooms()
-    join() // joins room matching current path (e.g. "/chat/general")
-    broadcast('system', { text: `${data.name} joined` })
-    return { joined: true, room, rooms: rooms() }
-  }
-}
-```
-
-### Pattern: Broadcast a message to a room
-
-```ts
-@Message('message', ':room')
-onMessage(@MessageData() data: { from: string; text: string }) {
-  const { broadcast } = useWsRooms()
-  broadcast('message', { from: data.from, text: data.text })
-  // all room members except sender receive the message
-}
-```
-
-### Pattern: Direct send to current connection
-
-```ts
-@Message('notify', '/self')
-notify() {
-  const { send } = useWsConnection()
-  send('notification', '/alerts', { text: 'Just for you' })
-}
-```
-
-### Pattern: Server-wide broadcast
-
-```ts
-@Message('admin', '/announce')
-announce(@MessageData() data: { text: string }) {
-  const server = useWsServer()
-  server.broadcast('announcement', '/announce', { text: data.text })
-  return { announced: true }
-}
-```
-
-### Pattern: Send to a specific connection by ID
-
-```ts
-@Message('dm', '/direct')
-directMessage(@MessageData() data: { targetId: string; text: string }) {
-  const server = useWsServer()
-  const target = server.getConnection(data.targetId)
-  if (target) {
-    target.send('dm', '/direct', { text: data.text })
-  }
-}
-```
-
-## Multi-Instance Broadcasting
-
-For horizontal scaling, implement `WsBroadcastTransport` to relay room broadcasts across instances:
-
-```ts
-import type { WsBroadcastTransport } from '@moostjs/event-ws'
-
-class RedisBroadcastTransport implements WsBroadcastTransport {
-  publish(channel: string, payload: string) {
-    redis.publish(channel, payload)
-  }
-  subscribe(channel: string, handler: (payload: string) => void) {
-    redis.subscribe(channel, handler)
-  }
-  unsubscribe(channel: string) {
-    redis.unsubscribe(channel)
-  }
-}
-```
-
-Pass it in adapter options:
-
-```ts
-const ws = new MoostWs({
-  httpApp: http.getHttpApp(),
-  wooksWs: {
-    broadcastTransport: new RedisBroadcastTransport(),
-  },
-})
-```
-
-Channels follow the pattern `ws:room:<room-path>`.
-
-### WsBroadcastTransport Interface
-
-```ts
-interface WsBroadcastTransport {
-  publish(channel: string, payload: string): void | Promise<void>
-  subscribe(channel: string, handler: (payload: string) => void): void | Promise<void>
-  unsubscribe(channel: string): void | Promise<void>
-}
-```
-
-## Best Practices
-
-- Let rooms auto-clean on disconnect — don't manually leave in `@Disconnect` handlers
-- Use `excludeSelf: true` (default) to prevent echo in chat-like scenarios
-- Use `useWsServer()` sparingly — prefer room-scoped broadcasts over server-wide
-- For large-scale deployments, implement `WsBroadcastTransport` with Redis/NATS
-
-## Gotchas
-
-- `useWsRooms()` throws if called outside a message context (e.g. inside `@Connect`)
-- `join()` without arguments uses the current message path as the room name, including the controller prefix
-- `useWsConnection().send()` silently drops messages if the socket is not in OPEN state
-- Broadcast `excludeId` only prevents echo on the originating server instance — the same user's other connections still receive it

package/skills/moostjs-event-ws/routing.md

@@ -1,115 +0,0 @@
-# Routing — @moostjs/event-ws
-
-> Event+path routing, controller prefixes, parametric routes, and wildcards.
-
-## Concepts
-
-WebSocket message routing uses a two-dimensional scheme: messages are matched by both **event type** and **path**. This is powered by the same Wooks router used for HTTP routes.
-
-Every client message carries: `{ event: "message", path: "/chat/general", data: {...} }`
-
-The `@Message` decorator matches both dimensions. The `event` must match exactly. The `path` supports parametric patterns (`:param`) and wildcards (`*`).
-
-## Routing Rules
-
-### Event + Path
-
-```ts
-@Message('message', '/chat/general')
-onMessage(@MessageData() data: { text: string }) {
-  // matches event="message" at path="/chat/general"
-}
-```
-
-### Controller Prefixes
-
-The `@Controller` prefix is prepended to handler paths:
-
-```ts
-@Controller('game')
-export class GameController {
-  @Message('move', 'board/:id')
-  // effective path: /game/board/:id
-  onMove(@Param('id') id: string) { /* ... */ }
-}
-```
-
-Nested controllers with `@ImportController` compose prefixes:
-
-```ts
-@Controller('v2')
-export class V2Controller {
-  @ImportController(() => GameController)
-  game!: GameController
-  // GameController routes become /v2/game/board/:id
-}
-```
-
-### Parametric Routes
-
-Use `:param` syntax for path parameters:
-
-```ts
-@Controller('chat')
-export class ChatController {
-  @Message('join', ':room')
-  join(@Param('room') room: string) { /* ... */ }
-
-  @Message('dm', ':sender/:receiver')
-  dm(
-    @Param('sender') sender: string,
-    @Param('receiver') receiver: string,
-  ) { /* ... */ }
-}
-```
-
-Client message `{ event: "dm", path: "/chat/alice/bob" }` resolves `sender="alice"`, `receiver="bob"`.
-
-### All Route Parameters
-
-Use `@Params()` to get all parameters as an object:
-
-```ts
-import { Params } from 'moost'
-
-@Message('action', ':type/:id')
-handle(@Params() params: { type: string; id: string }) {
-  console.log(params) // { type: 'move', id: '42' }
-}
-```
-
-### Wildcards
-
-```ts
-@Message('log', '/events/*')
-handleAllEvents(@Param('*') subPath: string) {
-  // matches /events/user/login, /events/system/error, etc.
-}
-```
-
-### Path Omission
-
-When `path` is omitted, the method name becomes the path:
-
-```ts
-@Controller('api')
-export class ApiController {
-  @Message('query')
-  status() {
-    // effective path: /api/status
-    return { ok: true }
-  }
-}
-```
-
-## Best Practices
-
-- Use controller prefixes to namespace related handlers
-- Prefer explicit `path` argument over relying on method name inference for clarity
-- Use parametric routes (`:room`) rather than separate handlers per room
-
-## Gotchas
-
-- Event matching is exact — no wildcard support on the event field itself
-- Path parameters are always strings, even if they look like numbers
-- Leading slash in `@Message` path is optional — `':room'` and `'/:room'` behave the same when composed with a controller prefix

package/skills/moostjs-event-ws/testing.md

@@ -1,209 +0,0 @@
-# Testing — @moostjs/event-ws
-
-> Unit-testing WebSocket handlers with mock contexts using prepareTestWsMessageContext and prepareTestWsConnectionContext.
-
-## Concepts
-
-`@moostjs/event-ws` re-exports test helpers from `@wooksjs/event-ws` that create mock event contexts for unit-testing handlers and composables without starting a real server.
-
-Two context factories match the two context layers:
-1. **`prepareTestWsConnectionContext`** — for `@Connect`/`@Disconnect` handler logic
-2. **`prepareTestWsMessageContext`** — for `@Message` handler logic (includes a parent connection context)
-
-Both return a **runner function** `<T>(cb: () => T) => T` that executes a callback inside a fully initialized event context.
-
-## API Reference
-
-### `prepareTestWsMessageContext(options)`
-
-Creates a message context with a parent connection context. Both contexts are fully seeded.
-
-```ts
-interface TTestWsMessageContext {
-  event: string                                 // required — message event type
-  path: string                                  // required — message route path
-  data?: unknown                                // parsed message payload
-  messageId?: string | number                   // correlation ID
-  rawMessage?: Buffer | string                  // raw message before parsing
-  id?: string                                   // connection ID (default: 'test-conn-id')
-  params?: Record<string, string | string[]>    // pre-set route parameters
-  parentCtx?: EventContext                      // optional parent context (e.g. HTTP)
-}
-```
-
-**Returns:** `<T>(cb: (...a: any[]) => T) => T`
-
-```ts
-import { prepareTestWsMessageContext, useWsMessage, useWsConnection } from '@moostjs/event-ws'
-
-const runInCtx = prepareTestWsMessageContext({
-  event: 'message',
-  path: '/chat/general',
-  data: { from: 'Alice', text: 'Hello!' },
-  messageId: 1,
-})
-
-runInCtx(() => {
-  const { data, id, path, event } = useWsMessage<{ from: string; text: string }>()
-  expect(data.from).toBe('Alice')
-  expect(id).toBe(1)
-})
-```
-
-### `prepareTestWsConnectionContext(options?)`
-
-Creates a connection context for testing connection lifecycle handlers.
-
-```ts
-interface TTestWsConnectionContext {
-  id?: string                                   // connection ID (default: 'test-conn-id')
-  params?: Record<string, string | string[]>    // pre-set route parameters
-  parentCtx?: EventContext                      // optional parent context
-}
-```
-
-**Returns:** `<T>(cb: (...a: any[]) => T) => T`
-
-```ts
-import { prepareTestWsConnectionContext, useWsConnection } from '@moostjs/event-ws'
-
-const runInCtx = prepareTestWsConnectionContext({ id: 'conn-456' })
-
-runInCtx(() => {
-  const { id } = useWsConnection()
-  expect(id).toBe('conn-456')
-})
-```
-
-## Common Patterns
-
-### Pattern: Testing message data access
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { prepareTestWsMessageContext, useWsMessage } from '@moostjs/event-ws'
-
-describe('ChatController', () => {
-  it('should access message data', () => {
-    const runInCtx = prepareTestWsMessageContext({
-      event: 'message',
-      path: '/chat/general',
-      data: { from: 'Alice', text: 'Hello!' },
-      messageId: 1,
-    })
-
-    runInCtx(() => {
-      const { data, id, path, event } = useWsMessage<{ from: string; text: string }>()
-      expect(data.from).toBe('Alice')
-      expect(data.text).toBe('Hello!')
-      expect(id).toBe(1)
-      expect(path).toBe('/chat/general')
-      expect(event).toBe('message')
-    })
-  })
-})
-```
-
-### Pattern: Testing with route parameters
-
-```ts
-import { prepareTestWsMessageContext } from '@moostjs/event-ws'
-import { useRouteParams } from '@wooksjs/event-core'
-
-it('should resolve route params', () => {
-  const runInCtx = prepareTestWsMessageContext({
-    event: 'join',
-    path: '/chat/rooms/lobby',
-    params: { room: 'lobby' },
-    data: { name: 'Alice' },
-  })
-
-  runInCtx(() => {
-    const { get } = useRouteParams<{ room: string }>()
-    expect(get('room')).toBe('lobby')
-  })
-})
-```
-
-### Pattern: Testing connection ID
-
-```ts
-it('should access connection id in message context', () => {
-  const runInCtx = prepareTestWsMessageContext({
-    event: 'join',
-    path: '/chat/general',
-    data: { name: 'Alice' },
-    id: 'conn-123',
-  })
-
-  runInCtx(() => {
-    const { id } = useWsConnection()
-    expect(id).toBe('conn-123')
-  })
-})
-```
-
-### Pattern: Testing with HTTP parent context
-
-For handlers that access HTTP composables from the upgrade request:
-
-```ts
-import { EventContext } from '@wooksjs/event-core'
-import { prepareTestWsMessageContext, currentConnection } from '@moostjs/event-ws'
-
-it('should have access to parent HTTP context', () => {
-  const httpCtx = new EventContext({ logger: console as any })
-
-  const runInCtx = prepareTestWsMessageContext({
-    event: 'test',
-    path: '/test',
-    parentCtx: httpCtx,
-  })
-
-  runInCtx(() => {
-    const connCtx = currentConnection()
-    expect(connCtx.parent).toBe(httpCtx)
-  })
-})
-```
-
-### Pattern: Testing handler functions directly
-
-Extract handler logic into testable functions:
-
-```ts
-import { prepareTestWsMessageContext, useWsRooms } from '@moostjs/event-ws'
-
-function handleJoin(room: string, name: string) {
-  const { join, broadcast, rooms } = useWsRooms()
-  join()
-  broadcast('system', { text: `${name} joined` })
-  return { joined: true, room, rooms: rooms() }
-}
-
-it('should join a room and return room list', () => {
-  const runInCtx = prepareTestWsMessageContext({
-    event: 'join',
-    path: '/chat/general',
-    data: { name: 'Alice' },
-  })
-
-  const result = runInCtx(() => handleJoin('general', 'Alice'))
-  expect(result.joined).toBe(true)
-  expect(result.room).toBe('general')
-})
-```
-
-## Best Practices
-
-- Use test helpers rather than manually constructing `EventContext`
-- Keep handler logic testable by extracting business logic into composable-using functions
-- Test edge cases with different message data, missing fields, and error conditions
-- Use `parentCtx` to simulate HTTP-integrated mode
-- Default connection ID is `'test-conn-id'` — override with the `id` option when needed
-
-## Gotchas
-
-- `useWsRooms()` and `useWsServer()` depend on adapter state — for full integration testing with rooms and broadcasting, you may need to set up `WsRoomManager` manually
-- The runner function is synchronous — wrap async handler logic in a returned promise if needed
-- Route parameters must be pre-set via the `params` option — the test context doesn't run the router