@wooksjs/event-ws 0.7.0

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@wooksjs/event-ws",
+  "version": "0.7.0",
+  "description": "WebSocket adapter for Wooks with path-based message routing, rooms, and broadcasting",
+  "keywords": [
+    "api",
+    "composables",
+    "framework",
+    "prostojs",
+    "realtime",
+    "rooms",
+    "websocket",
+    "wooks",
+    "ws"
+  ],
+  "homepage": "https://github.com/wooksjs/wooksjs/tree/main/packages/event-ws#readme",
+  "bugs": {
+    "url": "https://github.com/wooksjs/wooksjs/issues"
+  },
+  "license": "MIT",
+  "author": "Artem Maltsev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wooksjs/wooksjs.git",
+    "directory": "packages/event-ws"
+  },
+  "bin": {
+    "wooksjs-event-ws-skill": "./scripts/setup-skills.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts/setup-skills.js"
+  ],
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@wooksjs/event-core": "^0.7.0",
+    "wooks": "^0.7.0"
+  },
+  "peerDependencies": {
+    "@prostojs/logger": "^0.4.3",
+    "@prostojs/router": "^0.3.2",
+    "ws": "^8.0.0",
+    "@wooksjs/event-core": "^0.7.0",
+    "wooks": "^0.7.0"
+  },
+  "scripts": {
+    "build": "rolldown -c ../../rolldown.config.mjs",
+    "setup-skills": "node ./scripts/setup-skills.js"
+  }
+}

package/scripts/setup-skills.js

@@ -0,0 +1,78 @@
+#!/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 = 'wooksjs-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/wooksjs-event-ws/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: wooksjs-event-ws
+description: Use this skill when working with @wooksjs/event-ws — to create a WebSocket server with createWsApp() or WooksWs, register message handlers with onMessage(), handle connections with onConnect()/onDisconnect(), use composables like useWsConnection(), useWsMessage(), useWsRooms(), useWsServer(), manage rooms and broadcasting with WsRoomManager and WsBroadcastTransport, integrate with event-http via upgrade(), throw WsError for error replies, or test handlers with prepareTestWsConnectionContext()/prepareTestWsMessageContext(). Covers the wire protocol (WsClientMessage, WsReplyMessage, WsPushMessage), standalone and HTTP-integrated modes, heartbeat, and custom serializers.
+---
+
+# @wooksjs/event-ws
+
+WebSocket adapter for Wooks with path-based message routing, rooms, broadcasting, and composable context — runs standalone or integrated with `@wooksjs/event-http`.
+
+## 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)               | Creating a WS server, understanding the wire protocol, configuring options, standalone vs HTTP-integrated mode |
+| Composables           | [composables.md](composables.md) | Using `useWsConnection`, `useWsMessage`, `useWsRooms`, `useWsServer`, or `currentConnection` inside handlers   |
+| Rooms & broadcasting  | [rooms.md](rooms.md)             | Managing rooms, broadcasting to groups, cross-instance pub/sub with `WsBroadcastTransport`                     |
+| Testing               | [testing.md](testing.md)         | Unit-testing WS handlers with `prepareTestWsConnectionContext` and `prepareTestWsMessageContext`               |
+
+## Quick reference
+
+```ts
+import {
+  // factory
+  createWsApp,
+  WooksWs,
+  // composables
+  useWsConnection,
+  useWsMessage,
+  useWsRooms,
+  useWsServer,
+  currentConnection,
+  // kinds & types
+  wsConnectionKind,
+  wsMessageKind,
+  WsError,
+  WsConnection,
+  WsRoomManager,
+  // testing
+  prepareTestWsConnectionContext,
+  prepareTestWsMessageContext,
+  // re-exports from event-core
+  useRouteParams,
+  useLogger,
+} from '@wooksjs/event-ws'
+```

package/skills/wooksjs-event-ws/composables.md

@@ -0,0 +1,157 @@
+# Composables — @wooksjs/event-ws
+
+> Composable functions for accessing WebSocket connection, message, room, and server state inside handlers.
+
+## Concepts
+
+All composables follow the Wooks `defineWook` pattern — they read from the current `EventContext` via `AsyncLocalStorage`. They are only valid inside handler functions registered with `onMessage`, `onConnect`, or `onDisconnect`.
+
+The WS adapter creates two context levels:
+
+- **Connection context** — available in `onConnect`, `onDisconnect`, and `onMessage` (via parent chain)
+- **Message context** — only available in `onMessage` handlers
+
+## API Reference
+
+### `useWsConnection(ctx?)`
+
+Access the current WebSocket connection. Works in both connection and message contexts.
+
+Returns:
+
+```ts
+{
+  id: string                    // unique connection ID (UUID)
+  send(event, path, data?, params?): void  // push a message to this client
+  close(code?, reason?): void   // close the connection
+  context: EventContext          // the connection EventContext
+}
+```
+
+```ts
+ws.onMessage('message', '/chat/:room', () => {
+  const { id, send } = useWsConnection()
+  send('ack', '/chat/lobby', { received: true })
+})
+```
+
+### `useWsMessage<T>(ctx?)`
+
+Access the current WebSocket message data. **Only available in message context** (inside `onMessage` handlers).
+
+Returns:
+
+```ts
+{
+  data: T // parsed message data (generic typed)
+  raw: Buffer | string // raw message before parsing
+  id: string | number | undefined // correlation ID
+  path: string // message path
+  event: string // message event type
+}
+```
+
+```ts
+ws.onMessage('message', '/chat/:room', () => {
+  const { data, id, path } = useWsMessage<{ text: string }>()
+  console.log(data.text) // typed as string
+})
+```
+
+### `useWsRooms(ctx?)`
+
+Room management for the current connection. **Only available in message context.** Defaults to the current message path as the room name.
+
+Returns:
+
+```ts
+{
+  join(room?): void              // join a room (default: current message path)
+  leave(room?): void             // leave a room (default: current message path)
+  broadcast(event, data?, options?): void  // broadcast to a room
+  rooms(): string[]              // list rooms this connection has joined
+}
+```
+
+`WsBroadcastOptions`:
+
+```ts
+{
+  room?: string          // target room (default: current message path)
+  excludeSelf?: boolean  // exclude sender (default: true)
+}
+```
+
+```ts
+ws.onMessage('subscribe', '/chat/rooms/:roomId', () => {
+  const { join } = useWsRooms()
+  join() // joins the room matching the current path
+})
+
+ws.onMessage('message', '/chat/rooms/:roomId', () => {
+  const { data } = useWsMessage<{ text: string }>()
+  const { broadcast } = useWsRooms()
+  broadcast('message', data) // sends to all in room except sender
+})
+```
+
+### `useWsServer()`
+
+Server-wide operations. Available in any context (not scoped to a specific connection). Reads directly from adapter state, not from `EventContext`.
+
+Returns:
+
+```ts
+{
+  connections(): Map<string, WsConnection>         // all active connections
+  broadcast(event, path, data?, params?): void     // broadcast to ALL connections
+  getConnection(id: string): WsConnection | undefined
+  roomConnections(room: string): Set<WsConnection> // connections in a room
+}
+```
+
+```ts
+ws.onMessage('rpc', '/admin/broadcast', () => {
+  const { data } = useWsMessage<{ text: string }>()
+  const { broadcast } = useWsServer()
+  broadcast('announcement', '/system', data)
+})
+```
+
+### `currentConnection(ctx?)`
+
+Returns the connection `EventContext` regardless of whether you're in a connection or message handler.
+
+- In `onConnect`/`onDisconnect`: returns `current()` directly
+- In `onMessage`: returns `current().parent` (the connection context)
+
+```ts
+const connCtx = currentConnection()
+```
+
+### Re-exports from `@wooksjs/event-core`
+
+These are re-exported for convenience:
+
+- `useRouteParams(ctx?)` — access path params from the Wooks router
+- `useLogger(ctx?)` — access the scoped logger
+
+```ts
+ws.onMessage('rpc', '/users/:id', () => {
+  const { params } = useRouteParams()
+  return { userId: params.id }
+})
+```
+
+## Best Practices
+
+- Always type `useWsMessage<T>()` with your expected payload type for type safety
+- Use `useWsRooms()` without arguments to default to the current message path as the room — this is the most common pattern
+- Prefer `useWsServer().broadcast()` for server-wide announcements, `useWsRooms().broadcast()` for room-scoped messages
+- The `context` property from `useWsConnection()` gives access to the raw `EventContext` for advanced use (e.g., reading custom context keys set during `onConnect`)
+
+## Gotchas
+
+- `useWsMessage()` and `useWsRooms()` throw if called outside a message context (e.g., inside `onConnect`)
+- `useWsServer()` is not a `defineWook` — it reads from module-level adapter state, so it works anywhere but requires the adapter to be initialized
+- `useWsConnection().send()` silently drops messages if the socket is not in OPEN state (readyState !== 1)

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

@@ -0,0 +1,229 @@
+# Core concepts & setup — @wooksjs/event-ws
+
+> WebSocket adapter for Wooks: creates a WS server, routes messages by event+path, manages connections, and supports standalone or HTTP-integrated modes.
+
+## Concepts
+
+`@wooksjs/event-ws` follows the Wooks adapter pattern. It creates two nested context layers:
+
+1. **Connection context** (`ws:connection` kind) — long-lived, one per connected client. Seeded with `id` and `ws` socket.
+2. **Message context** (`ws:message` kind) — short-lived, one per incoming message. Its `parent` is the connection context.
+
+Messages follow a JSON wire protocol with `event` + `path` for routing and an optional `id` for request-response correlation.
+
+### Wire protocol
+
+**Client → Server (`WsClientMessage`):**
+
+```ts
+interface WsClientMessage {
+  event: string // router method (e.g. "message", "rpc", "subscribe")
+  path: string // route path (e.g. "/chat/rooms/lobby")
+  data?: unknown // payload
+  id?: string | number // correlation ID — triggers a reply
+}
+```
+
+**Server → Client reply (`WsReplyMessage`):**
+
+```ts
+interface WsReplyMessage {
+  id: string | number // matches the client's id
+  data?: unknown // handler return value
+  error?: { code: number; message: string }
+}
+```
+
+**Server → Client push (`WsPushMessage`):**
+
+```ts
+interface WsPushMessage {
+  event: string
+  path: string
+  params?: Record<string, string>
+  data?: unknown
+}
+```
+
+## Installation / Setup
+
+```bash
+pnpm add @wooksjs/event-ws wooks @wooksjs/event-core ws
+```
+
+`ws` is a peer dependency (the default WebSocket server implementation). You can substitute it with a custom `WsServerAdapter`.
+
+## API Reference
+
+### `createWsApp(wooksOrOpts?, opts?)`
+
+Factory that creates a `WooksWs` instance.
+
+- `wooksOrOpts` — a `Wooks` or `WooksAdapterBase` instance (HTTP integration), or `TWooksWsOptions` (standalone)
+- `opts` — `TWooksWsOptions` when the first arg is a Wooks instance
+
+Returns: `WooksWs`
+
+### `TWooksWsOptions`
+
+```ts
+interface TWooksWsOptions {
+  heartbeatInterval?: number // ping interval in ms (default: 30000, 0 = disabled)
+  heartbeatTimeout?: number // pong timeout in ms (default: 5000)
+  messageParser?: (raw: Buffer | string) => WsClientMessage
+  messageSerializer?: (msg: WsReplyMessage | WsPushMessage) => string | Buffer
+  logger?: TConsoleBase
+  maxMessageSize?: number // bytes (default: 1MB), oversized messages are dropped
+  wsServerAdapter?: WsServerAdapter // custom WS engine (default: wraps `ws`)
+  broadcastTransport?: WsBroadcastTransport // for multi-instance
+}
+```
+
+### `WooksWs` class
+
+Extends `WooksAdapterBase`, implements `WooksUpgradeHandler`.
+
+#### `ws.onMessage(event, path, handler)`
+
+Register a routed message handler. Uses the Wooks router — supports path params.
+
+```ts
+ws.onMessage('message', '/chat/rooms/:roomId', () => {
+  const { data } = useWsMessage<{ text: string }>()
+  const { params } = useRouteParams()
+  // ...
+})
+```
+
+#### `ws.onConnect(handler)`
+
+Register a handler that runs when a new WebSocket connection is established. Runs inside the connection context. Throwing or rejecting closes the connection.
+
+```ts
+ws.onConnect(() => {
+  const { id } = useWsConnection()
+  console.log('Connected:', id)
+})
+```
+
+#### `ws.onDisconnect(handler)`
+
+Register a handler that runs when a connection closes.
+
+#### `ws.upgrade()`
+
+Complete the WebSocket handshake from inside an HTTP UPGRADE route handler. Reads `req`/`socket`/`head` from the current HTTP context. The HTTP context becomes the parent of the WS connection context.
+
+#### `ws.handleUpgrade(req, socket, head)`
+
+Fallback for when no UPGRADE route matches (called by the HTTP adapter automatically).
+
+#### `ws.listen(port, hostname?)`
+
+Start a standalone server (without `event-http`). Returns a `Promise<void>`.
+
+#### `ws.close()`
+
+Stop the server, close all connections, clean up heartbeat.
+
+#### `ws.getServer()`
+
+Returns the underlying `http.Server` (standalone mode only).
+
+### `WsError`
+
+Error class with a numeric `code` following HTTP conventions. Throwing `WsError` in a handler sends an error reply to the client.
+
+```ts
+throw new WsError(403, 'Forbidden')
+```
+
+### `WsSocket` interface
+
+Minimal WebSocket instance interface — compatible with `ws`, uWebSockets.js, and Bun.
+
+### `WsServerAdapter` interface
+
+Factory for creating a custom WebSocket server:
+
+```ts
+interface WsServerAdapter {
+  create(): WsServerInstance
+}
+```
+
+## Common Patterns
+
+### Pattern: HTTP-integrated mode (recommended)
+
+```ts
+import { createHttpApp } from '@wooksjs/event-http'
+import { createWsApp } from '@wooksjs/event-ws'
+
+const http = createHttpApp()
+const ws = createWsApp(http) // auto-registers upgrade contract
+
+http.upgrade('/ws', () => ws.upgrade())
+
+ws.onMessage('message', '/chat/rooms/:roomId', () => {
+  const { data } = useWsMessage<{ text: string }>()
+  return { ok: true }
+})
+
+http.listen(3000)
+```
+
+### Pattern: Standalone mode
+
+```ts
+import { createWsApp } from '@wooksjs/event-ws'
+
+const ws = createWsApp({ heartbeatInterval: 30_000 })
+
+ws.onMessage('rpc', '/users/:id', () => {
+  const { data } = useWsMessage()
+  const { params } = useRouteParams()
+  return { userId: params.id }
+})
+
+ws.listen(3000)
+```
+
+### Pattern: Connection authentication
+
+```ts
+ws.onConnect(() => {
+  // Access HTTP context if using HTTP-integrated mode
+  // Throw to reject the connection
+  const token = getTokenFromSomewhere()
+  if (!isValid(token)) {
+    throw new WsError(401, 'Unauthorized')
+  }
+})
+```
+
+### Pattern: Custom serializer (e.g. MessagePack)
+
+```ts
+import { encode, decode } from '@msgpack/msgpack'
+
+const ws = createWsApp({
+  messageParser: (raw) => decode(raw as Buffer) as WsClientMessage,
+  messageSerializer: (msg) => Buffer.from(encode(msg)),
+})
+```
+
+## Best Practices
+
+- Use HTTP-integrated mode for production — it shares the HTTP server and handles UPGRADE routing cleanly
+- Set `maxMessageSize` appropriate for your use case to prevent memory abuse
+- Use `WsError` with HTTP-style codes for structured error replies
+- Keep `onConnect` handlers fast — they block connection acceptance
+- Heartbeat is enabled by default (30s); set to 0 only for short-lived connections
+
+## Gotchas
+
+- Handler return values are only sent as replies when the client message included an `id` field. Fire-and-forget messages (no `id`) get no reply even if the handler returns a value.
+- The `ws` package is a peer dependency — you must install it explicitly.
+- `useWsRooms()` and `useWsMessage()` are only available in message context (inside `onMessage` handlers), not in `onConnect`/`onDisconnect`.
+- When a connection context has an HTTP parent (integrated mode), composables from `@wooksjs/event-http` can read HTTP headers/cookies via the parent chain.