@moostjs/event-http 0.6.5 → 0.6.7

package/dist/index.cjs

@@ -662,6 +662,7 @@ const CONTEXT_TYPE = "HTTP";
 					raw.on("end", unscope);
 				} },
 				targetPath,
+				controllerPrefix: opts.prefix,
 				handlerType: handler.type
 			});
 			const routerBinding = handler.method === "UPGRADE" ? this.httpApp.upgrade(targetPath, fn) : this.httpApp.on(handler.method, targetPath, fn);
@@ -694,7 +695,7 @@ const CONTEXT_TYPE = "HTTP";
 			image: "https://moost.org/moost-full-logo.svg",
 			link: "https://moost.org/",
 			poweredBy: "moostjs",
-			version: "0.6.4"
+			version: "0.6.6"
 		});
 		if (httpApp && httpApp instanceof __wooksjs_event_http.WooksHttp) this.httpApp = httpApp;
 		else if (httpApp) this.httpApp = (0, __wooksjs_event_http.createHttpApp)({

package/dist/index.mjs

@@ -639,6 +639,7 @@ const CONTEXT_TYPE = "HTTP";
 					raw.on("end", unscope);
 				} },
 				targetPath,
+				controllerPrefix: opts.prefix,
 				handlerType: handler.type
 			});
 			const routerBinding = handler.method === "UPGRADE" ? this.httpApp.upgrade(targetPath, fn) : this.httpApp.on(handler.method, targetPath, fn);
@@ -671,7 +672,7 @@ const CONTEXT_TYPE = "HTTP";
 			image: "https://moost.org/moost-full-logo.svg",
 			link: "https://moost.org/",
 			poweredBy: "moostjs",
-			version: "0.6.4"
+			version: "0.6.6"
 		});
 		if (httpApp && httpApp instanceof WooksHttp) this.httpApp = httpApp;
 		else if (httpApp) this.httpApp = createHttpApp({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moostjs/event-http",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "@moostjs/event-http",
   "keywords": [
     "composables",
@@ -21,13 +21,8 @@
     "url": "git+https://github.com/moostjs/moostjs.git",
     "directory": "packages/event-http"
   },
-  "bin": {
-    "moostjs-event-http-skill": "./scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts/setup-skills.js"
+    "dist"
   ],
   "type": "module",
   "sideEffects": false,
@@ -43,20 +38,19 @@
     }
   },
   "dependencies": {
-    "@wooksjs/event-http": "^0.7.8",
-    "@wooksjs/http-body": "^0.7.8"
+    "@wooksjs/event-http": "^0.7.9",
+    "@wooksjs/http-body": "^0.7.9"
   },
   "devDependencies": {
     "vitest": "3.2.4"
   },
   "peerDependencies": {
     "@prostojs/infact": "^0.4.1",
-    "@wooksjs/event-core": "^0.7.8",
-    "moost": "^0.6.5"
+    "@wooksjs/event-core": "^0.7.9",
+    "moost": "^0.6.7"
   },
   "scripts": {
     "pub": "pnpm publish --access public",
-    "test": "vitest",
-    "setup-skills": "node ./scripts/setup-skills.js"
+    "test": "vitest"
   }
 }

package/scripts/setup-skills.js

@@ -1,76 +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-http'
-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)
-
-  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(`[${SKILL_NAME}] installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`[${SKILL_NAME}] failed — ${err.message}`)
-  }
-}
-
-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(`[${SKILL_NAME}] added 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(`Done! Restart your AI agent to pick up the "${SKILL_NAME}" skill.`)
-}

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

@@ -1,32 +0,0 @@
----
-name: moostjs-event-http
-description: Use this skill when working with @moostjs/event-http — to create an HTTP server with MoostHttp adapter, register route handlers with @Get()/@Post()/@Put()/@Delete()/@Patch()/@All(), extract request data with @Query(), @Header(), @Cookie(), @Body(), @RawBody(), @Authorization(), @Url(), @Method(), @Req(), @Res(), @ReqId(), @Ip(), @IpList(), control responses with @SetHeader(), @SetCookie(), @SetStatus(), @StatusRef(), @HeaderRef(), @CookieRef(), @CookieAttrsRef(), throw HTTP errors with HttpError, enforce body limits with @BodySizeLimit()/@CompressedBodySizeLimit()/@BodyReadTimeoutMs(), define auth guards with defineAuthGuard()/AuthGuard/Authenticate, or handle WebSocket upgrades with @Upgrade().
----
-
-# @moostjs/event-http
-
-Moost HTTP adapter — decorator-driven HTTP server built on `@wooksjs/event-http`. Provides route decorators, request data extractors, response control, auth guards, and body limits for Moost applications.
-
-## 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, understanding the mental model, configuring MoostHttp adapter |
-| Routing & handlers | [routing.md](routing.md) | Defining routes with @Get/@Post/etc, route parameters, wildcards, path patterns |
-| Request data | [request.md](request.md) | Extracting query params, headers, cookies, body, auth, IP, URL from requests |
-| Response control | [response.md](response.md) | Setting status codes, headers, cookies, error handling, raw response access |
-| Authentication | [auth.md](auth.md) | Auth guards, credential extraction, bearer/basic/apiKey/cookie transports, @Authenticate |
-
-## Quick reference
-
-```ts
-// Imports
-import { MoostHttp, Get, Post, Put, Delete, Patch, All, HttpMethod, Upgrade } from '@moostjs/event-http'
-import { Query, Header, Cookie, Body, RawBody, Authorization, Url, Method, Req, Res, ReqId, Ip, IpList } from '@moostjs/event-http'
-import { SetHeader, SetCookie, SetStatus, StatusRef, HeaderRef, CookieRef, CookieAttrsRef } from '@moostjs/event-http'
-import { BodySizeLimit, CompressedBodySizeLimit, BodyReadTimeoutMs } from '@moostjs/event-http'
-import { Authenticate, AuthGuard, defineAuthGuard, HttpError } from '@moostjs/event-http'
-import { Controller, Param, Params } from 'moost'
-```

package/skills/moostjs-event-http/auth.md

@@ -1,275 +0,0 @@
-# Authentication — @moostjs/event-http
-
-> Declarative auth guards with automatic credential extraction and Swagger integration.
-
-## Concepts
-
-The auth guard system has three components:
-
-1. **Transport declaration** — describes *where* credentials come from (bearer token, basic auth, API key, cookie)
-2. **Guard handler** — your verification logic, receives the extracted credentials
-3. **`@Authenticate` decorator** — applies the guard to a controller or handler
-
-Two APIs are provided:
-- **Functional** (`defineAuthGuard`) — stateless, simple guards
-- **Class-based** (`AuthGuard`) — when you need dependency injection
-
-Auth guard transport declarations are stored in metadata, enabling automatic Swagger/OpenAPI security scheme discovery.
-
-## API Reference
-
-### `defineAuthGuard(transports, handler)`
-
-Create a functional auth guard.
-
-```ts
-import { defineAuthGuard, HttpError } from '@moostjs/event-http'
-
-const jwtGuard = defineAuthGuard(
-  { bearer: { format: 'JWT' } },
-  (transports) => {
-    const user = verifyJwt(transports.bearer)
-    if (!user) throw new HttpError(401, 'Invalid token')
-    // return value is optional — if returned, it becomes the handler's response (short-circuit)
-  },
-)
-```
-
-**Parameters:**
-- `transports: TAuthTransportDeclaration` — which credentials to extract
-- `handler: (transports: TAuthTransportValues<T>) => unknown | Promise<unknown>` — verification logic
-
-**Returns:** `TAuthGuardDef` — an interceptor def with transport metadata attached.
-
-### `AuthGuard<T>`
-
-Abstract base class for class-based auth guards. Use when you need DI.
-
-```ts
-import { AuthGuard, HttpError } from '@moostjs/event-http'
-import { Injectable } from 'moost'
-
-@Injectable()
-class JwtGuard extends AuthGuard<{ bearer: { format: 'JWT' } }> {
-  static transports = { bearer: { format: 'JWT' } } as const
-
-  constructor(private userService: UserService) {}
-
-  handle(transports: { bearer: string }) {
-    const user = this.userService.verifyToken(transports.bearer)
-    if (!user) throw new HttpError(401, 'Invalid token')
-  }
-}
-```
-
-Requirements:
-- Extend `AuthGuard<T>` with transport declaration as generic parameter
-- Set `static transports` matching the generic (read at runtime)
-- Implement `handle(transports)` with verification logic
-- Use `@Injectable()` for constructor injection
-
-### `@Authenticate(handler)`
-
-Apply an auth guard to a controller or handler method.
-
-```ts
-import { Authenticate, Get } from '@moostjs/event-http'
-import { Controller } from 'moost'
-
-// Controller-level — all handlers require auth
-@Authenticate(jwtGuard)
-@Controller('users')
-class UsersController {
-  @Get('')
-  list() {}
-
-  @Get(':id')
-  find() {}
-}
-
-// Handler-level — specific endpoints only
-@Controller('products')
-class ProductsController {
-  @Get('')
-  list() { /* public */ }
-
-  @Authenticate(jwtGuard)
-  @Post('')
-  create() { /* requires auth */ }
-}
-```
-
-Accepts both functional (`TAuthGuardDef`) and class-based (`TAuthGuardClass`) guards.
-
-### `extractTransports(declaration)`
-
-Low-level function that extracts credentials from the current request context. Called internally by auth guards — rarely needed directly.
-
-```ts
-import { extractTransports } from '@moostjs/event-http'
-
-const values = extractTransports({ bearer: { format: 'JWT' } })
-// values.bearer = 'eyJ...' (the raw token)
-```
-
-Throws `HttpError(401, 'No authentication credentials provided')` if none of the declared transports are present.
-
-## Transport types
-
-### Bearer token
-
-Extracts from `Authorization: Bearer <token>`:
-
-```ts
-{ bearer: { format?: string, description?: string } }
-// Extracted value: string (raw token without "Bearer " prefix)
-```
-
-### Basic authentication
-
-Extracts from `Authorization: Basic <base64>`:
-
-```ts
-{ basic: { description?: string } }
-// Extracted value: { username: string, password: string }
-```
-
-### API key
-
-Extracts from a header, query parameter, or cookie:
-
-```ts
-{ apiKey: { name: string, in: 'header' | 'query' | 'cookie', description?: string } }
-// Extracted value: string
-```
-
-```ts
-// From header
-defineAuthGuard({ apiKey: { name: 'X-API-Key', in: 'header' } }, (t) => { t.apiKey /* string */ })
-
-// From query param
-defineAuthGuard({ apiKey: { name: 'api_key', in: 'query' } }, (t) => { t.apiKey /* string */ })
-
-// From cookie
-defineAuthGuard({ apiKey: { name: 'api_key', in: 'cookie' } }, (t) => { t.apiKey /* string */ })
-```
-
-### Cookie
-
-Extracts a value from a named cookie:
-
-```ts
-{ cookie: { name: string, description?: string } }
-// Extracted value: string
-```
-
-## Common Patterns
-
-### Pattern: JWT bearer guard
-
-```ts
-const jwtGuard = defineAuthGuard(
-  { bearer: { format: 'JWT', description: 'JWT access token' } },
-  (transports) => {
-    const payload = verifyJwt(transports.bearer)
-    if (!payload) throw new HttpError(401, 'Invalid or expired token')
-  },
-)
-```
-
-### Pattern: API key guard
-
-```ts
-const apiKeyGuard = defineAuthGuard(
-  { apiKey: { name: 'X-API-Key', in: 'header' } },
-  (transports) => {
-    if (!isValidApiKey(transports.apiKey)) {
-      throw new HttpError(401, 'Invalid API key')
-    }
-  },
-)
-```
-
-### Pattern: Auth + authorization stacking
-
-```ts
-@Authenticate(jwtGuard)          // step 1: verify credentials
-@RequireRole('admin')            // step 2: check authorization
-@Controller('admin')
-class AdminController {
-  @Get('dashboard')
-  dashboard() { /* authenticated + admin */ }
-}
-```
-
-### Pattern: Class-based guard with DI
-
-```ts
-@Injectable()
-class SessionGuard extends AuthGuard<{ cookie: { name: 'session' } }> {
-  static transports = { cookie: { name: 'session' } } as const
-
-  constructor(private sessionService: SessionService) {}
-
-  handle(transports: { cookie: string }) {
-    const session = this.sessionService.validate(transports.cookie)
-    if (!session) throw new HttpError(401, 'Invalid session')
-  }
-}
-
-@Authenticate(SessionGuard)
-@Controller('dashboard')
-class DashboardController {}
-```
-
-### Pattern: Handler-level override
-
-```ts
-@Authenticate(apiKeyGuard)
-@Controller('products')
-class ProductsController {
-  @Get('')
-  list() { /* uses apiKeyGuard */ }
-
-  @Authenticate(basicGuard)
-  @Post('')
-  create() { /* uses basicGuard instead */ }
-}
-```
-
-## Integration
-
-- **Swagger**: Transport declarations map directly to OpenAPI security schemes. The `@moostjs/swagger` package auto-discovers `@Authenticate` metadata.
-- **Guards**: Auth guards run at `GUARD` priority. Combine with custom authorization guards (also at `GUARD` priority) — they execute in decorator declaration order.
-
-## Types
-
-```ts
-interface TAuthTransportDeclaration {
-  bearer?: { format?: string; description?: string }
-  basic?: { description?: string }
-  apiKey?: { name: string; in: 'header' | 'query' | 'cookie'; description?: string }
-  cookie?: { name: string; description?: string }
-}
-
-type TAuthTransportValues<T> = {
-  [K in keyof T]: K extends 'basic' ? { username: string; password: string } : string
-}
-
-type TAuthGuardHandler = TAuthGuardDef | TAuthGuardClass
-```
-
-## Best Practices
-
-- Use functional guards (`defineAuthGuard`) for simple, stateless checks
-- Use class-based guards (`AuthGuard`) when you need DI services (e.g., database, token service)
-- Apply `@Authenticate` at the controller level for protected resources, handler level for mixed access
-- Always throw `HttpError` with meaningful messages for auth failures
-- Combine with `@moostjs/swagger` for automatic OpenAPI security documentation
-
-## Gotchas
-
-- If none of the declared transports are present in the request, `extractTransports` throws `HttpError(401)` automatically — your handler won't be called
-- Class-based guards must set `static transports` — it's read at runtime, not from the generic parameter
-- Auth guards run at `GUARD` priority — they execute before `INTERCEPTOR`-priority interceptors
-- The handler's return value (if any) short-circuits the response — use this for redirects or custom auth responses

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

@@ -1,193 +0,0 @@
-# Core concepts & setup — @moostjs/event-http
-
-> How to create and configure an HTTP server with the Moost HTTP adapter.
-
-## Concepts
-
-`@moostjs/event-http` is the HTTP adapter for the Moost framework. It bridges Moost's decorator-driven controller system with `@wooksjs/event-http` (the underlying HTTP engine). The adapter handles:
-
-- Binding decorated handler methods to HTTP routes
-- Managing request scoping and cleanup
-- Providing dependency injection for the underlying WooksHttp instance
-
-**Key classes:**
-- `MoostHttp` — the adapter class you instantiate and attach to your Moost app
-- `WooksHttp` — the underlying Wooks HTTP engine (available via DI if needed)
-
-## Installation
-
-```bash
-npm install @moostjs/event-http moost
-# or
-pnpm add @moostjs/event-http moost
-```
-
-Peer dependencies (installed automatically with moost):
-- `@wooksjs/event-core` — async event context
-- `@prostojs/infact` — dependency injection
-- `@prostojs/router` — route matching
-
-## Setup
-
-### Minimal HTTP server
-
-```ts
-import { MoostHttp, Get } from '@moostjs/event-http'
-import { Moost, Controller, Param } from 'moost'
-
-@Controller()
-class AppController {
-  @Get('hello/:name')
-  greet(@Param('name') name: string) {
-    return `Hello, ${name}!`
-  }
-}
-
-const app = new Moost()
-void app.adapter(new MoostHttp()).listen(3000, () => {
-  app.getLogger('app').info('Up on port 3000')
-})
-void app.registerControllers(AppController).init()
-```
-
-### Scaffold a project
-
-```bash
-npm create moost -- --http
-# or with a name:
-npm create moost my-web-app -- --http
-```
-
-## API Reference
-
-### `MoostHttp`
-
-The HTTP adapter class implementing `TMoostAdapter`.
-
-```ts
-import { MoostHttp } from '@moostjs/event-http'
-
-// Default — creates a new WooksHttp internally
-const http = new MoostHttp()
-
-// With options passed to WooksHttp
-const http = new MoostHttp({ onNotFound: customHandler })
-
-// With an existing WooksHttp instance
-const http = new MoostHttp(existingWooksHttp)
-```
-
-**Methods:**
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `listen(port?, ...)` | `Promise<void>` | Start the HTTP server (same overloads as `net.Server.listen`) |
-| `getHttpApp()` | `WooksHttp` | Access the underlying Wooks HTTP engine |
-| `getServerCb()` | `RequestListener` | Get the request handler callback for use with existing Node.js servers |
-
-### `getServerCb()` — Custom server integration
-
-Use `getServerCb()` to integrate with an existing Node.js HTTP/HTTPS server:
-
-```ts
-import { createServer } from 'https'
-import { MoostHttp } from '@moostjs/event-http'
-import { Moost } from 'moost'
-
-const http = new MoostHttp()
-const app = new Moost()
-app.adapter(http)
-
-const server = createServer(tlsOptions, http.getServerCb())
-server.listen(443)
-await app.init()
-```
-
-### `HttpError`
-
-Re-exported from `@wooksjs/event-http`. Throw to produce an HTTP error response with a specific status code.
-
-```ts
-import { HttpError } from '@moostjs/event-http'
-
-throw new HttpError(404, 'Not Found')
-throw new HttpError(422, { message: 'Validation failed', errors: [...] })
-```
-
-### `httpKind`
-
-Re-exported from `@wooksjs/event-http`. The event kind identifier for HTTP events.
-
-### `useHttpContext()`
-
-Re-exported from `@wooksjs/event-http`. Access the raw Wooks HTTP context from within a handler (advanced use only — prefer decorators).
-
-## Common Patterns
-
-### Pattern: Class extending Moost
-
-Instead of creating a separate `Moost` instance and registering controllers, extend `Moost` directly:
-
-```ts
-import { MoostHttp, Get } from '@moostjs/event-http'
-import { Moost, Param } from 'moost'
-
-class MyServer extends Moost {
-  @Get('test/:name')
-  test(@Param('name') name: string) {
-    return { message: `Hello ${name}!` }
-  }
-}
-
-const app = new MyServer()
-app.adapter(new MoostHttp()).listen(3000)
-void app.init()
-```
-
-### Pattern: Multiple controllers
-
-```ts
-import { Moost } from 'moost'
-import { MoostHttp } from '@moostjs/event-http'
-
-const app = new Moost()
-app.adapter(new MoostHttp()).listen(3000)
-void app
-  .registerControllers(UserController, ProductController, OrderController)
-  .init()
-```
-
-## DI-available services
-
-When MoostHttp is attached, these are available via constructor injection:
-
-| Token | Type | Description |
-|-------|------|-------------|
-| `WooksHttp` | class | The underlying Wooks HTTP app |
-| `'WooksHttp'` | string | Same, by string token |
-| `HttpServer` | `http.Server` | The Node.js HTTP server instance |
-| `HttpsServer` | `https.Server` | The Node.js HTTPS server instance |
-
-```ts
-import { Injectable } from 'moost'
-import { WooksHttp } from '@wooksjs/event-http'
-
-@Injectable()
-class MyService {
-  constructor(private wooks: WooksHttp) {}
-}
-```
-
-## Best Practices
-
-- Call `app.adapter(http).listen(port)` before `app.init()` — the adapter must be attached before initialization
-- Use `registerControllers()` to add controller classes, not instances
-- Prefer the decorator-based API (`@Get`, `@Body`, etc.) over accessing wooks composables directly
-- Use `getServerCb()` when integrating with existing HTTP/HTTPS servers instead of calling `listen()`
-
-## Gotchas
-
-- The `path` argument in route decorators is optional — when omitted, the method name is used as the path segment
-- `@Get('')` (empty string) maps to the controller root, while `@Get()` (no argument) uses the method name
-- `app.init()` must be called after `registerControllers()` — routes are bound during initialization
-- MoostHttp registers a default 404 handler that runs through the global interceptor chain

package/skills/moostjs-event-http/request.md

@@ -1,230 +0,0 @@
-# Request data — @moostjs/event-http
-
-> Extracting data from incoming HTTP requests using resolver decorators.
-
-## Concepts
-
-Moost provides **resolver decorators** that extract values from the incoming request and inject them as handler method parameters. Each decorator wraps a `@Resolve()` call that invokes the appropriate `@wooksjs/event-http` composable. All resolver decorators can also be used as **property decorators** on `FOR_EVENT`-scoped controllers.
-
-## API Reference
-
-### `@Query(name?)`
-
-Extract query parameters. With a name, returns a single value; without, returns all as an object.
-
-```ts
-import { Get, Query } from '@moostjs/event-http'
-
-@Get('search')
-search(
-  @Query('q') query: string,                // single param
-  @Query() params: Record<string, string>,   // all params
-) {}
-// GET /search?q=moost&limit=10
-// query = 'moost', params = { q: 'moost', limit: '10' }
-```
-
-- Returns `undefined` if the parameter is missing
-- `@Query()` returns `undefined` (not `{}`) when there are no query params at all
-- Sets metadata: `paramSource: 'QUERY_ITEM'` (named) or `'QUERY'` (all)
-
-### `@Header(name)`
-
-Extract a request header value.
-
-```ts
-import { Get, Header } from '@moostjs/event-http'
-
-@Get('test')
-test(@Header('content-type') contentType: string) {}
-```
-
-Header names are case-insensitive.
-
-### `@Cookie(name)`
-
-Extract a request cookie value.
-
-```ts
-import { Get, Cookie } from '@moostjs/event-http'
-
-@Get('profile')
-profile(@Cookie('session') session: string) {}
-```
-
-### `@Body()`
-
-Parse and return the request body. Automatically detects JSON, form-encoded, and text content types.
-
-```ts
-import { Post, Body } from '@moostjs/event-http'
-
-@Post('users')
-create(@Body() data: { name: string, email: string }) {}
-```
-
-- Sets metadata: `paramSource: 'BODY'`
-- Uses `@wooksjs/http-body` for parsing
-
-### `@RawBody()`
-
-Get the raw request body as a `Buffer`.
-
-```ts
-import { Post, RawBody } from '@moostjs/event-http'
-
-@Post('upload')
-upload(@RawBody() raw: Buffer) {}
-```
-
-### `@Authorization(field)`
-
-Extract parts of the `Authorization` header.
-
-```ts
-import { Get, Authorization } from '@moostjs/event-http'
-
-@Get('profile')
-profile(
-  @Authorization('bearer') token: string,      // Bearer token (no prefix)
-  @Authorization('type') authType: string,     // "Bearer", "Basic", etc.
-  @Authorization('username') user: string,     // from Basic auth
-  @Authorization('password') pass: string,     // from Basic auth
-  @Authorization('raw') credentials: string,   // raw credentials string
-) {}
-```
-
-Valid fields: `'username'`, `'password'`, `'bearer'`, `'raw'`, `'type'`
-
-### `@Url()`
-
-Get the requested URL string.
-
-```ts
-import { Get, Url } from '@moostjs/event-http'
-
-@Get('info')
-info(@Url() url: string) {}
-// url = '/info?page=1'
-```
-
-### `@Method()`
-
-Get the HTTP method string.
-
-```ts
-import { All, Method } from '@moostjs/event-http'
-
-@All('proxy')
-proxy(@Method() method: string) {}
-// method = 'GET', 'POST', etc.
-```
-
-### `@Req()`
-
-Get the raw Node.js `IncomingMessage`.
-
-```ts
-import { Get, Req } from '@moostjs/event-http'
-import type { IncomingMessage } from 'http'
-
-@Get('raw')
-raw(@Req() request: IncomingMessage) {
-  return { httpVersion: request.httpVersion }
-}
-```
-
-### `@Res(opts?)`
-
-Get the raw Node.js `ServerResponse`. When used, the framework does **not** process the return value.
-
-```ts
-import { Get, Res } from '@moostjs/event-http'
-import type { ServerResponse } from 'http'
-
-@Get('raw')
-raw(@Res() res: ServerResponse) {
-  res.writeHead(200, { 'content-type': 'text/plain' })
-  res.end('Manual response')
-}
-```
-
-Pass `{ passthrough: true }` to get the raw response but still let the framework handle the return value:
-
-```ts
-@Get('hybrid')
-hybrid(@Res({ passthrough: true }) res: ServerResponse) {
-  res.setHeader('x-custom', 'value')
-  return { data: 'processed by framework' }
-}
-```
-
-### `@ReqId()`
-
-Get the unique request UUID.
-
-```ts
-import { Get, ReqId } from '@moostjs/event-http'
-
-@Get('test')
-test(@ReqId() requestId: string) {}
-```
-
-### `@Ip(opts?)`
-
-Get the client IP address.
-
-```ts
-import { Get, Ip } from '@moostjs/event-http'
-
-@Get('client')
-client(
-  @Ip() ip: string,                          // direct client IP
-  @Ip({ trustProxy: true }) realIp: string,  // considers x-forwarded-for
-) {}
-```
-
-### `@IpList()`
-
-Get the full IP address chain.
-
-```ts
-import { Get, IpList } from '@moostjs/event-http'
-
-@Get('client')
-client(@IpList() allIps: string[]) {}
-```
-
-## Decorator summary table
-
-| Decorator | Returns | Import |
-|-----------|---------|--------|
-| `@Param(name)` | Route parameter | `moost` |
-| `@Params()` | All route params | `moost` |
-| `@Query(name?)` | Query param(s) | `@moostjs/event-http` |
-| `@Header(name)` | Header value | `@moostjs/event-http` |
-| `@Cookie(name)` | Cookie value | `@moostjs/event-http` |
-| `@Body()` | Parsed body | `@moostjs/event-http` |
-| `@RawBody()` | Raw Buffer | `@moostjs/event-http` |
-| `@Authorization(field)` | Auth field | `@moostjs/event-http` |
-| `@Url()` | URL string | `@moostjs/event-http` |
-| `@Method()` | HTTP method | `@moostjs/event-http` |
-| `@ReqId()` | Request UUID | `@moostjs/event-http` |
-| `@Ip(opts?)` | Client IP | `@moostjs/event-http` |
-| `@IpList()` | IP chain | `@moostjs/event-http` |
-| `@Req()` | IncomingMessage | `@moostjs/event-http` |
-| `@Res(opts?)` | ServerResponse | `@moostjs/event-http` |
-
-## Best Practices
-
-- Use `@Authorization()` for quick header parsing; use `@Authenticate()` guards for production auth
-- Prefer `@Body()` over `@RawBody()` unless you need the raw bytes
-- Query values are always strings — use pipes to transform to numbers or other types
-- Use `@Ip({ trustProxy: true })` behind reverse proxies to get the real client IP
-
-## Gotchas
-
-- `@Query('name')` returns `undefined` when the parameter is missing (not `null` or empty string)
-- `@Query()` (all params) returns `undefined` when there are no query params, not an empty object
-- `@Res()` without `passthrough` takes over the response — the handler's return value is ignored
-- `@Param` and `@Params` are imported from `moost`, not from `@moostjs/event-http`

package/skills/moostjs-event-http/response.md

@@ -1,287 +0,0 @@
-# Response control — @moostjs/event-http
-
-> Setting status codes, headers, cookies, handling errors, and controlling HTTP responses.
-
-## Concepts
-
-Moost provides two styles for response control:
-
-1. **Static decorators** (`@SetStatus`, `@SetHeader`, `@SetCookie`) — applied via interceptors at `AFTER_ALL` priority, declarative and fixed
-2. **Dynamic refs** (`@StatusRef`, `@HeaderRef`, `@CookieRef`, `@CookieAttrsRef`) — Proxy-based reactive bindings, set values programmatically at runtime
-
-Both work as method decorators. Ref decorators also work as parameter decorators and property decorators (on `FOR_EVENT`-scoped controllers).
-
-## API Reference
-
-### `@SetStatus(code, opts?)`
-
-Set the response status code. Runs as an `after` interceptor.
-
-```ts
-import { Post, SetStatus } from '@moostjs/event-http'
-
-@Post('users')
-@SetStatus(201)
-create() { return { created: true } }
-
-// Force override even if status was already set
-@SetStatus(200, { force: true })
-```
-
-### `@StatusRef()`
-
-Dynamic status code control via a `{ value: number }` proxy object.
-
-```ts
-import { Get, StatusRef } from '@moostjs/event-http'
-import type { TStatusRef } from '@moostjs/event-http'
-
-@Get('process')
-process(@StatusRef() status: TStatusRef) {
-  if (someCondition) {
-    status.value = 202
-    return { status: 'processing' }
-  }
-  return { status: 'done' } // default 200
-}
-```
-
-Works as a property decorator too:
-
-```ts
-@Injectable('FOR_EVENT')
-@Controller()
-class MyController {
-  @StatusRef()
-  status = 200  // initial value
-
-  @Get('test')
-  test() {
-    this.status = 201  // reactive — sets the response status
-    return 'created'
-  }
-}
-```
-
-### `@SetHeader(name, value, opts?)`
-
-Set a response header. Runs as an `after` interceptor (and optionally on error).
-
-```ts
-import { Get, SetHeader } from '@moostjs/event-http'
-
-@Get('test')
-@SetHeader('x-powered-by', 'moost')
-@SetHeader('cache-control', 'no-store')
-test() { return 'ok' }
-```
-
-Options:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `force` | `boolean` | Override header even if already set |
-| `status` | `number` | Only set when response has this status |
-| `when` | `'always' \| 'error' \| 'ok'` | When to apply (default: success only) |
-
-```ts
-@SetHeader('content-type', 'text/plain', { status: 400 })
-@SetHeader('x-request-id', 'abc', { when: 'always' })
-@SetHeader('x-error', 'true', { when: 'error' })
-```
-
-### `@HeaderRef(name)`
-
-Dynamic header control via a `{ value: string | string[] | undefined }` proxy.
-
-```ts
-import { Get, HeaderRef } from '@moostjs/event-http'
-import type { THeaderRef } from '@moostjs/event-http'
-
-@Get('test')
-test(@HeaderRef('x-custom') header: THeaderRef) {
-  header.value = `generated-${Date.now()}`
-  return 'ok'
-}
-```
-
-### `@SetCookie(name, value, attrs?)`
-
-Set a response cookie. Only sets if the cookie hasn't already been set in the response.
-
-```ts
-import { Get, SetCookie } from '@moostjs/event-http'
-
-@Get('login')
-@SetCookie('session', 'abc123', { maxAge: '1h', httpOnly: true })
-login() { return { ok: true } }
-```
-
-Cookie attributes (`TCookieAttributesInput`): `maxAge`, `expires`, `domain`, `path`, `secure`, `httpOnly`, `sameSite`, etc.
-
-### `@CookieRef(name)`
-
-Dynamic cookie value control.
-
-```ts
-import { Post, CookieRef } from '@moostjs/event-http'
-import type { TCookieRef } from '@moostjs/event-http'
-
-@Post('login')
-login(@CookieRef('session') cookie: TCookieRef) {
-  cookie.value = generateToken()
-  return { ok: true }
-}
-```
-
-### `@CookieAttrsRef(name)`
-
-Dynamic cookie attributes control.
-
-```ts
-import { Post, CookieAttrsRef } from '@moostjs/event-http'
-import type { TCookieAttributes } from '@moostjs/event-http'
-
-@Post('login')
-login(@CookieAttrsRef('session') attrs: { value: TCookieAttributes }) {
-  attrs.value = { maxAge: '1h', httpOnly: true, secure: true }
-  return { ok: true }
-}
-```
-
-## Body limits
-
-Interceptor-based decorators for controlling request body parsing limits.
-
-### `@BodySizeLimit(n)`
-
-Limit the maximum inflated (decompressed) body size in bytes. Default: 10 MB.
-
-```ts
-import { Post, BodySizeLimit } from '@moostjs/event-http'
-
-@Post('upload')
-@BodySizeLimit(50 * 1024 * 1024) // 50 MB
-upload() {}
-```
-
-### `@CompressedBodySizeLimit(n)`
-
-Limit the maximum compressed body size in bytes. Default: 1 MB.
-
-```ts
-@Post('upload')
-@CompressedBodySizeLimit(5 * 1024 * 1024) // 5 MB
-upload() {}
-```
-
-### `@BodyReadTimeoutMs(n)`
-
-Set the timeout for reading the request body in milliseconds. Default: 10 s.
-
-```ts
-@Post('upload')
-@BodyReadTimeoutMs(30000) // 30 seconds
-upload() {}
-```
-
-### Global limit interceptors
-
-For applying limits globally:
-
-```ts
-import { globalBodySizeLimit, globalCompressedBodySizeLimit, globalBodyReadTimeoutMs } from '@moostjs/event-http'
-
-const app = new Moost()
-app.applyGlobalInterceptors(
-  globalBodySizeLimit(20 * 1024 * 1024),
-  globalCompressedBodySizeLimit(2 * 1024 * 1024),
-  globalBodyReadTimeoutMs(15000),
-)
-```
-
-## Error handling
-
-### `HttpError`
-
-Throw to produce an HTTP error response:
-
-```ts
-import { HttpError } from '@moostjs/event-http'
-
-throw new HttpError(404, 'Not Found')
-throw new HttpError(403, 'Access denied')
-throw new HttpError(422, {
-  message: 'Validation failed',
-  statusCode: 422,
-  errors: [
-    { field: 'email', message: 'Invalid email format' },
-  ],
-})
-```
-
-Uncaught exceptions become HTTP 500 responses. The response format (JSON or HTML) adapts based on the `Accept` header.
-
-## Common Patterns
-
-### Pattern: CRUD with proper status codes
-
-```ts
-@Controller('items')
-class ItemController {
-  @Get('')
-  list() { return items }
-
-  @Post('')
-  @SetStatus(201)
-  create(@Body() data: CreateItemDto) { return createItem(data) }
-
-  @Put(':id')
-  update(@Param('id') id: string, @Body() data: UpdateItemDto) {
-    return updateItem(id, data)
-  }
-
-  @Delete(':id')
-  @SetStatus(204)
-  remove(@Param('id') id: string) { deleteItem(id) }
-}
-```
-
-### Pattern: Conditional response headers
-
-```ts
-@Get('data')
-@SetHeader('x-cache', 'miss', { when: 'always' })
-getData(@HeaderRef('x-cache') cache: THeaderRef) {
-  const cached = getFromCache()
-  if (cached) {
-    cache.value = 'hit'
-    return cached
-  }
-  return fetchFreshData()
-}
-```
-
-## Types
-
-```ts
-export interface TStatusRef { value: number }
-export interface THeaderRef { value: string | string[] | undefined }
-export interface TCookieRef { value: string; attrs?: TCookieAttributes }
-export type TCookieAttributes = Partial<TCookieAttributesRequired>
-```
-
-## Best Practices
-
-- Use `@SetStatus` for fixed status codes (201 for creation, 204 for deletion)
-- Use `@StatusRef` when the status depends on runtime logic
-- Use `@SetHeader` for static headers, `@HeaderRef` for dynamic ones
-- Apply body limits on upload endpoints to prevent abuse
-- Use global limit interceptors for application-wide defaults
-
-## Gotchas
-
-- `@SetStatus` won't override a status already set (e.g., by an error) unless `{ force: true }` is passed
-- `@SetCookie` won't overwrite a cookie already set in the response — this prevents accidental overwrites
-- `@SetHeader` defaults to success-only (`after` interceptor); use `{ when: 'always' }` to include error responses
-- Ref decorators use Proxy objects — the `.value` property is reactive, not a plain field

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

@@ -1,210 +0,0 @@
-# Routing & handlers — @moostjs/event-http
-
-> Defining HTTP routes, methods, parameters, wildcards, and handler return values.
-
-## Concepts
-
-Every HTTP endpoint is defined by a method decorator (`@Get`, `@Post`, etc.) on a controller method. The decorator specifies the HTTP method and optional path. Route parameters (`:param`), wildcards (`*`), and regex constraints provide flexible URL matching. Controllers group related handlers under a shared prefix.
-
-## API Reference
-
-### HTTP method decorators
-
-All imported from `@moostjs/event-http`:
-
-| Decorator | HTTP Method | Usage |
-|-----------|-------------|-------|
-| `@Get(path?)` | GET | `@Get('users/:id')` |
-| `@Post(path?)` | POST | `@Post('users')` |
-| `@Put(path?)` | PUT | `@Put('users/:id')` |
-| `@Delete(path?)` | DELETE | `@Delete('users/:id')` |
-| `@Patch(path?)` | PATCH | `@Patch('users/:id')` |
-| `@All(path?)` | All methods | `@All('proxy/*')` |
-| `@HttpMethod(method, path?)` | Any method | `@HttpMethod('OPTIONS', '')` |
-| `@Upgrade(path?)` | UPGRADE | `@Upgrade('/ws')` |
-
-```ts
-import { Get, Post, Put, Delete, Patch, All, HttpMethod, Upgrade } from '@moostjs/event-http'
-```
-
-### `@HttpMethod(method, path?)`
-
-The base decorator — all convenience decorators (`@Get`, `@Post`, etc.) call this internally.
-
-```ts
-@HttpMethod('HEAD', 'health')
-healthCheck() { /* HEAD /health */ }
-
-@HttpMethod('OPTIONS', '')
-cors() { /* OPTIONS / */ }
-```
-
-Valid methods: `'GET'`, `'PUT'`, `'POST'`, `'PATCH'`, `'DELETE'`, `'HEAD'`, `'OPTIONS'`, `'UPGRADE'`, `'*'`
-
-### `@Upgrade(path?)`
-
-Registers an UPGRADE route for WebSocket handshakes. Use with `@moostjs/event-ws`:
-
-```ts
-@Upgrade('/ws')
-handleUpgrade(ws: WooksWs) {
-  return ws.upgrade()
-}
-```
-
-### Route parameters — `@Param` and `@Params`
-
-Imported from `moost` (not from `@moostjs/event-http`):
-
-```ts
-import { Controller, Param, Params } from 'moost'
-import { Get } from '@moostjs/event-http'
-
-@Controller('users')
-class UserController {
-  @Get(':id')
-  find(@Param('id') id: string) {
-    return { id } // GET /users/123
-  }
-
-  @Get(':type/:type/:id')
-  getAsset(@Params() params: { type: string[], id: string }) {
-    return params
-  }
-}
-```
-
-## Common Patterns
-
-### Pattern: Path defaults
-
-```ts
-@Get()         // path = method name, e.g. GET /getUsers
-getUsers() {}
-
-@Get('')       // path = controller root, e.g. GET /
-root() {}
-
-@Get('list')   // explicit path, e.g. GET /list
-listItems() {}
-```
-
-### Pattern: Multiple parameters
-
-```ts
-// Slash-separated: /flights/SFO/LAX
-@Get('flights/:from/:to')
-getFlight(@Param('from') from: string, @Param('to') to: string) {}
-
-// Hyphen-separated: /dates/2024-01-15
-@Get('dates/:year-:month-:day')
-getDate(
-  @Param('year') year: string,
-  @Param('month') month: string,
-  @Param('day') day: string,
-) {}
-```
-
-### Pattern: Regex-constrained parameters
-
-```ts
-// Only matches two-digit hours and minutes: /time/09h30m
-@Get('time/:hours(\\d{2})h:minutes(\\d{2})m')
-getTime(@Param('hours') hours: string, @Param('minutes') minutes: string) {}
-```
-
-### Pattern: Repeated parameters (arrays)
-
-```ts
-// /rgb/255/128/0 -> color = ['255', '128', '0']
-@Get('rgb/:color/:color/:color')
-getRgb(@Param('color') color: string[]) {}
-```
-
-### Pattern: Wildcards
-
-```ts
-@Controller('static')
-class StaticController {
-  @Get('*')
-  handleAll(@Param('*') path: string) {}
-
-  @Get('*.js')
-  handleJS(@Param('*') name: string) {}
-
-  // Multiple wildcards -> array
-  @Get('*/test/*')
-  handleTest(@Param('*') paths: string[]) {}
-
-  // Regex on wildcard: only digits
-  @Get('*(\\d+)')
-  handleNumbers(@Param('*') path: string) {}
-}
-```
-
-### Pattern: Controller prefix
-
-```ts
-import { Controller } from 'moost'
-
-@Controller('api/v1/users')
-class UserController {
-  @Get('')     // GET /api/v1/users
-  list() {}
-
-  @Get(':id')  // GET /api/v1/users/123
-  find() {}
-}
-```
-
-### Pattern: Nested controllers
-
-```ts
-import { Controller, ImportController } from 'moost'
-
-@Controller('api')
-class ApiController {
-  @ImportController(() => UserController)
-  users!: UserController
-
-  @ImportController(() => ProductController)
-  products!: ProductController
-}
-// Routes: GET /api/users/..., GET /api/products/...
-```
-
-## Handler return values
-
-Whatever the handler returns becomes the response body:
-
-| Return type | Content-Type |
-|-------------|--------------|
-| `string` | `text/plain` |
-| object / array | `application/json` |
-| `ReadableStream` | streamed |
-| fetch `Response` | forwarded as-is |
-
-```ts
-@Get('text')
-getText() { return 'Hello!' }           // text/plain
-
-@Get('json')
-getJson() { return { message: 'Hi' } }  // application/json
-
-@Get('data')
-async getData() { return await fetchFromDb() }  // async works
-```
-
-## Best Practices
-
-- Use `@Get('')` (empty string) for the controller root path, not `@Get()` (which uses the method name)
-- Keep controller prefixes as REST resource names: `@Controller('users')`, `@Controller('products')`
-- Use `@Param` for individual route parameters, `@Params` when you need the full params object
-- Prefer convenience decorators (`@Get`, `@Post`) over `@HttpMethod` for standard methods
-
-## Gotchas
-
-- `@Get()` without arguments uses the **method name** as the path — this is rarely what you want
-- Route parameters are always strings — use pipes to transform to numbers/booleans
-- An explicit double slash `//` at the end of a path forces the URL to end with a trailing slash
-- Query parameters are not part of the route path — use `@Query()` to extract them