@wooksjs/event-http 0.7.7 → 0.7.9

package/dist/index.cjs

@@ -1449,7 +1449,7 @@ function error_tl_default(ctx) {
 //#endregion
 //#region packages/event-http/src/response/wooks-http-response.ts
 let framework = {
-	version: "0.7.6",
+	version: "0.7.8",
 	poweredBy: "wooksjs",
 	link: "https://wooks.moost.org/",
 	image: "https://wooks.moost.org/wooks-full-logo.svg"

package/dist/index.mjs

@@ -1426,7 +1426,7 @@ function error_tl_default(ctx) {
 //#endregion
 //#region packages/event-http/src/response/wooks-http-response.ts
 let framework = {
-	version: "0.7.6",
+	version: "0.7.8",
 	poweredBy: "wooksjs",
 	link: "https://wooks.moost.org/",
 	image: "https://wooks.moost.org/wooks-full-logo.svg"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wooksjs/event-http",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "@wooksjs/event-http",
   "keywords": [
     "api",
@@ -25,13 +25,8 @@
     "url": "git+https://github.com/wooksjs/wooksjs.git",
     "directory": "packages/event-http"
   },
-  "bin": {
-    "wooksjs-event-http-skill": "scripts/setup-skills.js"
-  },
   "files": [
-    "dist",
-    "skills",
-    "scripts"
+    "dist"
   ],
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -47,17 +42,16 @@
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@wooksjs/event-core": "^0.7.7",
-    "wooks": "^0.7.7"
+    "@wooksjs/event-core": "^0.7.9",
+    "wooks": "^0.7.9"
   },
   "peerDependencies": {
     "@prostojs/logger": "^0.4.3",
     "@prostojs/router": "^0.3.3",
-    "@wooksjs/event-core": "^0.7.7",
-    "wooks": "^0.7.7"
+    "@wooksjs/event-core": "^0.7.9",
+    "wooks": "^0.7.9"
   },
   "scripts": {
-    "build": "rolldown -c ../../rolldown.config.mjs",
-    "setup-skills": "node scripts/setup-skills.js"
+    "build": "rolldown -c ../../rolldown.config.mjs"
   }
 }

package/scripts/setup-skills.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-/* prettier-ignore */
-'use strict'
-
-const fs = require('fs')
-const path = require('path')
-const os = require('os')
-
-const SKILL_NAME = 'wooksjs-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) // 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(`[${SKILL_NAME}] installed to ${dest}`)
-    installed++
-    if (!isGlobal) installedDirs.push(cfg.dir + '/' + SKILL_NAME)
-  } catch (err) {
-    console.warn(`[${SKILL_NAME}] 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(`[${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/wooksjs-event-http/SKILL.md

@@ -1,44 +0,0 @@
----
-name: wooksjs-event-http
-description: Use this skill when working with @wooksjs/event-http — to create HTTP servers with createHttpApp(), register route handlers with app.get()/post()/put()/patch()/delete(), read request data with useRequest()/useHeaders()/useCookies()/useUrlParams()/useAuthorization()/useAccept(), control responses with useResponse() and HttpResponse (status, headers, cookies, cache control, streaming), throw HTTP errors with HttpError, test handlers with prepareTestHttpContext(), or integrate with existing Node.js servers via getServerCb().
----
-
-# @wooksjs/event-http
-
-HTTP adapter for Wooks. Composable-based request handling where every piece of data is available on demand, typed, and cached per request. No middleware, no `req`/`res` parameters — just function calls.
-
-## 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 setup & routing | [core.md](core.md)         | Creating an app, registering routes, starting a server, understanding the architecture |
-| Request composables  | [request.md](request.md)   | Reading request data: headers, cookies, query params, body, authorization, IP          |
-| Response API         | [response.md](response.md) | Setting status, headers, cookies, cache control, sending responses, error handling     |
-| Testing              | [testing.md](testing.md)   | Writing tests for handlers and composables with `prepareTestHttpContext`               |
-
-## Quick reference
-
-```ts
-import { createHttpApp } from '@wooksjs/event-http'
-
-// Composables (no arguments — context via AsyncLocalStorage)
-import {
-  useRequest,
-  useResponse,
-  useHeaders,
-  useCookies,
-  useUrlParams,
-  useAuthorization,
-  useAccept,
-  useRouteParams,
-  useLogger,
-} from '@wooksjs/event-http'
-
-// Errors
-import { HttpError } from '@wooksjs/event-http'
-
-// Testing
-import { prepareTestHttpContext } from '@wooksjs/event-http'
-```

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

@@ -1,152 +0,0 @@
-# Core setup & routing — @wooksjs/event-http
-
-> Creating an app, registering routes, server lifecycle, and architecture overview.
-
-## Concepts
-
-`@wooksjs/event-http` wraps a Node.js HTTP server with Wooks' composable architecture. Each incoming request gets its own `EventContext` (from `@wooksjs/event-core`), and handlers are plain functions that return their response. All request data is accessed through composables — on demand, typed, cached.
-
-The adapter creates context, seeds it with the `IncomingMessage` and `HttpResponse`, looks up routes, and runs handlers. Handlers never receive `req`/`res` parameters.
-
-## Installation
-
-```bash
-pnpm add @wooksjs/event-http
-```
-
-Peer dependencies: `@wooksjs/event-core`, `wooks`, `@prostojs/router`, `@prostojs/logger`.
-
-## API Reference
-
-### `createHttpApp(opts?): WooksHttp`
-
-Creates and returns a `WooksHttp` instance.
-
-```ts
-import { createHttpApp } from '@wooksjs/event-http'
-
-const app = createHttpApp()
-app.get('/hello', () => 'Hello World!')
-app.listen(3000)
-```
-
-**Options (`TWooksHttpOptions`):**
-
-| Option           | Type                                 | Description                                                               |
-| ---------------- | ------------------------------------ | ------------------------------------------------------------------------- |
-| `logger`         | `TConsoleBase`                       | Custom logger instance                                                    |
-| `onNotFound`     | `TWooksHandler`                      | Handler called when no route matches (default: 404 HttpError)             |
-| `router`         | router options                       | Custom router configuration                                               |
-| `requestLimits`  | `Omit<TRequestLimits, 'perRequest'>` | Default body size/timeout limits for all requests                         |
-| `responseClass`  | `typeof WooksHttpResponse`           | Custom response subclass (default: `WooksHttpResponse`)                   |
-| `defaultHeaders` | `Record<string, string \| string[]>` | Default headers applied to every response (e.g. from `securityHeaders()`) |
-
-### Route registration
-
-```ts
-app.get(path, handler)
-app.post(path, handler)
-app.put(path, handler)
-app.patch(path, handler)
-app.delete(path, handler)
-app.head(path, handler)
-app.options(path, handler)
-app.all(path, handler) // matches any HTTP method
-```
-
-Handlers are plain functions. Return value becomes the response body:
-
-```ts
-app.get('/users/:id', () => {
-  const { params } = useRouteParams<{ id: string }>()
-  return { id: params.id } // → 200 application/json
-})
-
-app.post('/users', async () => {
-  const { parseBody } = useBody() // from @wooksjs/http-body
-  const user = await parseBody<{ name: string }>()
-  return { created: user.name } // → 201 application/json (POST auto-status)
-})
-```
-
-### Server lifecycle
-
-```ts
-// Start server
-await app.listen(3000)
-await app.listen(3000, '0.0.0.0')
-
-// Use with existing server
-import http from 'http'
-const server = http.createServer(app.getServerCb())
-server.listen(3000)
-app.attachServer(server)
-
-// Stop server
-await app.close()
-```
-
-### `getServerCb()`
-
-Returns a `(req, res) => void` callback for use with any Node.js HTTP server:
-
-```ts
-const cb = app.getServerCb()
-http.createServer(cb).listen(3000)
-// or with https, http2, etc.
-```
-
-## Routing
-
-Built on [`@prostojs/router`](https://github.com/prostojs/router). Supports:
-
-- Static routes: `/api/users`
-- Parametric routes: `/users/:id`
-- Wildcards: `/static/*`
-- Multiple wildcards: `/static/*/assets/*`
-- Regex constraints: `/api/time/:hours(\\d{2})h:minutes(\\d{2})m`
-- Regex wildcards: `/static/*(\\d+)`
-
-Route params accessed via `useRouteParams()`:
-
-```ts
-app.get('/users/:id', () => {
-  const { params } = useRouteParams<{ id: string }>()
-  return { userId: params.id }
-})
-```
-
-## Auto-status
-
-When no explicit status is set, it's inferred from the HTTP method and response body:
-
-| Method | With body    | Without body   |
-| ------ | ------------ | -------------- |
-| GET    | 200 OK       | 204 No Content |
-| POST   | 201 Created  | 204 No Content |
-| PUT    | 201 Created  | 204 No Content |
-| PATCH  | 202 Accepted | 204 No Content |
-| DELETE | 202 Accepted | 204 No Content |
-
-## Handler chain
-
-Multiple handlers can be registered for the same route. If one throws, the next is tried:
-
-```ts
-app.get('/resource', authHandler, mainHandler)
-```
-
-If all handlers throw, the last error is sent as the response.
-
-## Best Practices
-
-- Return values directly — the framework handles serialization and status codes
-- Use `HttpError` for error responses: `throw new HttpError(404)` or `throw new HttpError(400, 'Invalid input')`
-- Use `useResponse()` only when you need explicit control over headers, cookies, or status
-- For `getServerCb()`, call `attachServer(server)` if you want `close()` to work
-
-## Gotchas
-
-- Handlers receive no arguments — all data comes from composables
-- `listen()` returns a Promise — `await` it or handle rejection
-- `getServerCb()` doesn't automatically attach the server — call `attachServer()` if needed

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

@@ -1,204 +0,0 @@
-# Request composables — @wooksjs/event-http
-
-> Reading request data: headers, cookies, query params, body, authorization, IP address.
-
-## Concepts
-
-All request data is accessed through composables — functions that resolve context via `AsyncLocalStorage`. They take no arguments (optionally accept `ctx` for performance). Data is parsed lazily on first access and cached for the request lifetime.
-
-All composables are importable from `@wooksjs/event-http`.
-
-## API Reference
-
-### `useRequest(ctx?)`
-
-The primary request composable. Returns method, URL, headers, raw body, IP, and request limit controls.
-
-```ts
-import { useRequest } from '@wooksjs/event-http'
-
-const { method, url, headers, rawBody, getIp, reqId } = useRequest()
-```
-
-**Returned properties:**
-
-| Property         | Type                                              | Description                                        |
-| ---------------- | ------------------------------------------------- | -------------------------------------------------- |
-| `raw`            | `IncomingMessage`                                 | Node.js raw request object                         |
-| `url`            | `string`                                          | Request URL                                        |
-| `method`         | `string`                                          | HTTP method                                        |
-| `headers`        | `IncomingHttpHeaders`                             | Request headers                                    |
-| `rawBody`        | `() => Promise<Buffer>`                           | Lazy — reads and decompresses request body on call |
-| `reqId`          | `() => string`                                    | Lazy UUID per request                              |
-| `getIp(opts?)`   | `(opts?: { trustProxy: boolean }) => string`      | Client IP (with optional proxy trust)              |
-| `getIpList()`    | `() => { remoteIp: string; forwarded: string[] }` | All IPs (remote + X-Forwarded-For)                 |
-| `isCompressed()` | `() => boolean`                                   | Whether the request body is compressed             |
-
-**Request limits (per-request override):**
-
-```ts
-const { setMaxCompressed, setMaxInflated, setMaxRatio, setReadTimeoutMs } = useRequest()
-setMaxCompressed(5 * 1024 * 1024) // 5 MB
-setReadTimeoutMs(30_000) // 30 seconds
-```
-
-Default limits: `maxCompressed: 1MB`, `maxInflated: 10MB`, `maxRatio: 100`, `readTimeoutMs: 10s`.
-
-### `useHeaders(ctx?): IncomingHttpHeaders`
-
-Returns request headers directly. Shorthand for `useRequest().headers`.
-
-```ts
-import { useHeaders } from '@wooksjs/event-http'
-
-const { host, authorization, 'content-type': contentType } = useHeaders()
-```
-
-### `useCookies(ctx?)`
-
-Parses incoming request cookies lazily (per cookie name, via `cachedBy`).
-
-```ts
-import { useCookies } from '@wooksjs/event-http'
-
-const { getCookie, raw } = useCookies()
-const session = getCookie('session_id') // parsed + cached
-const theme = getCookie('theme') // parsed + cached (different key)
-// raw = raw Cookie header string
-```
-
-### `useUrlParams(ctx?)`
-
-Provides access to URL query parameters.
-
-```ts
-import { useUrlParams } from '@wooksjs/event-http'
-
-const { params, toJson, raw } = useUrlParams()
-
-// URLSearchParams API
-const page = params().get('page')
-const tags = params().getAll('tag')
-
-// As a plain object
-const query = toJson() // { page: '1', tag: ['a', 'b'] }
-
-// Raw query string
-const rawQuery = raw() // '?page=1&tag=a&tag=b'
-```
-
-### `useAuthorization(ctx?)`
-
-Parses the Authorization header (supports Basic and Bearer).
-
-```ts
-import { useAuthorization } from '@wooksjs/event-http'
-
-const { authorization, type, credentials, is, basicCredentials } = useAuthorization()
-
-if (is('bearer')) {
-  const token = credentials() // the raw token string
-}
-
-if (is('basic')) {
-  const { username, password } = basicCredentials()!
-}
-```
-
-**Returned properties:**
-
-| Property             | Type                             | Description                                                    |
-| -------------------- | -------------------------------- | -------------------------------------------------------------- |
-| `authorization`      | `string \| undefined`            | Raw Authorization header value                                 |
-| `type()`             | `string \| null`                 | Auth scheme: `'Basic'`, `'Bearer'`, etc.                       |
-| `credentials()`      | `string \| null`                 | Everything after the scheme                                    |
-| `is(type)`           | `boolean`                        | Check auth scheme: `'basic'`, `'bearer'`, or any custom scheme |
-| `basicCredentials()` | `{ username, password } \| null` | Decoded Basic credentials                                      |
-
-### `useAccept(ctx?)`
-
-Checks the request's `Accept` header for MIME type support. Uses short names (`'json'`, `'html'`, `'xml'`, `'text'`) or full MIME types.
-
-```ts
-import { useAccept } from '@wooksjs/event-http'
-
-const { accept, has } = useAccept()
-
-if (has('json')) {
-  /* ... */
-}
-if (has('image/png')) {
-  /* ... */
-}
-```
-
-### `useRouteParams<T>(ctx?)`
-
-Route parameters from the URL. Re-exported from `@wooksjs/event-core`.
-
-```ts
-import { useRouteParams } from '@wooksjs/event-http'
-
-// Given route: /users/:id/posts/:postId
-const { params, get } = useRouteParams<{ id: string; postId: string }>()
-params.id // '42'
-get('postId') // '7'
-```
-
-### `useLogger(ctx?): Logger`
-
-Logger from the current event context. Re-exported from `@wooksjs/event-core`.
-
-```ts
-import { useLogger } from '@wooksjs/event-http'
-
-const log = useLogger()
-log.info('handling request')
-```
-
-## Common Patterns
-
-### Pattern: Auth guard with early return
-
-```ts
-app.post('/admin/action', async () => {
-  const { is, credentials } = useAuthorization()
-  if (!is('bearer')) throw new HttpError(401)
-
-  const token = credentials()!
-  const user = await verifyToken(token)
-  if (!user.isAdmin) throw new HttpError(403)
-
-  // Body is never parsed if auth fails
-  const { parseBody } = useBody() // from @wooksjs/http-body
-  return parseBody()
-})
-```
-
-### Pattern: Performance — resolve context once
-
-```ts
-import { current } from '@wooksjs/event-core'
-
-app.get('/hot-path', () => {
-  const ctx = current()
-  const { method } = useRequest(ctx)
-  const { getCookie } = useCookies(ctx)
-  const { params } = useUrlParams(ctx)
-  // 1 ALS lookup instead of 3
-})
-```
-
-## Best Practices
-
-- Composables are lazy — call them only when you need the data
-- Pass `ctx` explicitly in hot paths with multiple composable calls
-- Use `getCookie(name)` over parsing all cookies when you need only a few
-- `rawBody()` handles decompression (gzip, deflate, brotli) automatically with limits enforcement
-
-## Gotchas
-
-- `rawBody()` returns a `Promise<Buffer>` — always `await` it
-- `rawBody()` consumes the stream — it's cached, so second call returns the same buffer
-- `getCookie()` returns `null` (not `undefined`) when a cookie doesn't exist
-- `useRequest()` limits setters use copy-on-write — they don't affect other requests

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

@@ -1,267 +0,0 @@
-# Response API — @wooksjs/event-http
-
-> Status, headers, cookies, cache control, error handling, and response sending.
-
-## Concepts
-
-`useResponse()` returns an `HttpResponse` instance for the current request. All response operations — status, headers, cookies, cache control — are methods on this single object. Methods are chainable.
-
-The response is also controlled implicitly by return values: returning an object sends JSON, returning a string sends text, returning nothing sends 204.
-
-## API Reference
-
-### `useResponse(ctx?): HttpResponse`
-
-Returns the `HttpResponse` for the current request.
-
-```ts
-import { useResponse } from '@wooksjs/event-http'
-
-const response = useResponse()
-response.setStatus(200).setHeader('x-custom', 'value')
-```
-
-### Status
-
-```ts
-response.status = 201 // set via property
-response.setStatus(201) // set via method (chainable)
-const code = response.status // get current status
-```
-
-If not set explicitly, status is inferred automatically (see core.md Auto-status).
-
-### Headers
-
-```ts
-response.setHeader('x-custom', 'value') // set a header (chainable)
-response.setHeaders({ 'x-one': '1', 'x-two': '2' }) // batch-set headers
-response.setHeader('x-multi', ['a', 'b']) // multi-value header
-response.getHeader('x-custom') // get header value
-response.removeHeader('x-custom') // remove a header (chainable)
-response.headers() // all headers as Record
-response.setContentType('application/xml') // shorthand for content-type
-response.getContentType() // get content-type
-response.enableCors('*') // set Access-Control-Allow-Origin (chainable)
-```
-
-### Cookies (outgoing)
-
-Set-Cookie headers are managed via `HttpResponse`:
-
-```ts
-response.setCookie('session', 'abc123', {
-  httpOnly: true,
-  secure: true,
-  sameSite: 'Strict',
-  maxAge: 3600, // seconds (also accepts time strings)
-  path: '/',
-  domain: '.example.com',
-  expires: new Date('2025-12-31'),
-})
-
-response.getCookie('session') // { value, attrs } or undefined
-response.removeCookie('session')
-response.clearCookies()
-response.setCookieRaw('name=value; Path=/; HttpOnly') // raw Set-Cookie string
-```
-
-**`TCookieAttributes`:**
-
-| Attribute  | Type                                     | Description        |
-| ---------- | ---------------------------------------- | ------------------ |
-| `expires`  | `Date \| string \| number`               | Expiration date    |
-| `maxAge`   | `number \| TTimeMultiString`             | Max age in seconds |
-| `domain`   | `string`                                 | Cookie domain      |
-| `path`     | `string`                                 | Cookie path        |
-| `secure`   | `boolean`                                | Secure flag        |
-| `httpOnly` | `boolean`                                | HttpOnly flag      |
-| `sameSite` | `boolean \| 'Lax' \| 'None' \| 'Strict'` | SameSite policy    |
-
-### Cache control
-
-```ts
-response.setCacheControl({
-  public: true,
-  maxAge: 3600,
-  sMaxage: 7200,
-  noStore: false,
-  noCache: false,
-  mustRevalidate: true,
-})
-
-response.setAge(300) // Age header (seconds)
-response.setExpires(new Date('2025-12-31')) // Expires header
-response.setExpires('2025-12-31') // also accepts strings
-response.setPragmaNoCache() // Pragma: no-cache
-```
-
-### Body and content type inference
-
-Return values are automatically serialized:
-
-| Return type                      | Content-Type          | Status         |
-| -------------------------------- | --------------------- | -------------- |
-| `string`                         | `text/plain`          | Auto           |
-| `number` / `boolean`             | `text/plain`          | Auto           |
-| `object` / `array`               | `application/json`    | Auto           |
-| `Buffer` / `Uint8Array`          | (none — set manually) | Auto           |
-| `Readable` stream                | (none — set manually) | Auto           |
-| `Response` (fetch)               | From fetch response   | Auto           |
-| `undefined` / `null` / no return | —                     | 204 No Content |
-
-### Raw response access
-
-For escape hatches (SSE, WebSocket upgrades, etc.):
-
-```ts
-// Take full control — framework won't send anything
-const res = response.getRawRes()
-res.writeHead(200, { 'content-type': 'text/event-stream' })
-res.write('data: hello\n\n')
-
-// Passthrough — you write to res, but framework still finalizes
-const res = response.getRawRes(true)
-```
-
-### `responded` property
-
-```ts
-if (response.responded) {
-  // Response already sent — don't try to send again
-}
-```
-
-## HttpError
-
-For error responses, throw `HttpError`:
-
-```ts
-import { HttpError } from '@wooksjs/event-http'
-
-throw new HttpError(404) // 404 with default message
-throw new HttpError(400, 'Invalid email') // 400 with custom message
-throw new HttpError(422, { message: 'Validation failed', fields: ['email'] }) // structured body
-```
-
-`HttpError` skips stack trace capture for performance (these are expected control-flow errors).
-
-**Error rendering (`WooksHttpResponse`):**
-
-The default response class renders errors based on the `Accept` header:
-
-- `application/json` → JSON `{ statusCode, message, error }`
-- `text/html` → Styled HTML error page with SVG icons
-- `text/plain` → Plain text error
-
-Override by providing a custom `responseClass` to `createHttpApp()`:
-
-```ts
-class MyResponse extends WooksHttpResponse {
-  protected renderError(data, ctx) {
-    this._status = data.statusCode
-    this._headers['content-type'] = 'application/json'
-    this._body = JSON.stringify({ error: data.message })
-  }
-}
-
-const app = createHttpApp({ responseClass: MyResponse })
-```
-
-### Default headers and security headers
-
-Pre-populate response headers for every request via `defaultHeaders`:
-
-```ts
-import { createHttpApp, securityHeaders } from '@wooksjs/event-http'
-
-const app = createHttpApp({ defaultHeaders: securityHeaders() })
-```
-
-`securityHeaders(opts?)` returns recommended HTTP security headers:
-
-| Header                         | Default                                                                           |
-| ------------------------------ | --------------------------------------------------------------------------------- |
-| `content-security-policy`      | `default-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'` |
-| `cross-origin-opener-policy`   | `same-origin`                                                                     |
-| `cross-origin-resource-policy` | `same-origin`                                                                     |
-| `referrer-policy`              | `no-referrer`                                                                     |
-| `x-content-type-options`       | `nosniff`                                                                         |
-| `x-frame-options`              | `SAMEORIGIN`                                                                      |
-
-Options: `string` (override) or `false` (disable). `strictTransportSecurity` is opt-in only.
-
-```ts
-securityHeaders({
-  contentSecurityPolicy: false,
-  referrerPolicy: 'strict-origin-when-cross-origin',
-  strictTransportSecurity: 'max-age=31536000; includeSubDomains',
-})
-```
-
-Per-endpoint: `response.setHeaders(securityHeaders({ ... }))`.
-
-## Common Patterns
-
-### Pattern: Full response control
-
-```ts
-app.get('/data', () => {
-  useResponse()
-    .setStatus(200)
-    .setHeader('x-request-id', useRequest().reqId())
-    .setCookie('visited', 'true', { httpOnly: true })
-    .setCacheControl({ public: true, maxAge: 3600 })
-
-  return { data: 'hello' }
-})
-```
-
-### Pattern: Redirect
-
-```ts
-app.get('/old-path', () => {
-  useResponse().setStatus(301).setHeader('location', '/new-path')
-})
-```
-
-### Pattern: Streaming response
-
-```ts
-import { createReadStream } from 'fs'
-
-app.get('/file', () => {
-  useResponse().setContentType('application/octet-stream')
-  return createReadStream('/path/to/file')
-})
-```
-
-### Pattern: Server-Sent Events
-
-```ts
-app.get('/events', () => {
-  const res = useResponse().getRawRes()
-  res.writeHead(200, {
-    'content-type': 'text/event-stream',
-    'cache-control': 'no-cache',
-    connection: 'keep-alive',
-  })
-  // Write events...
-  return res // returning the raw response signals "already handled"
-})
-```
-
-## Best Practices
-
-- Return values for simple responses — only use `useResponse()` when you need headers, cookies, or explicit status
-- Use `HttpError` for all error responses — don't manually set error status and body
-- The chainable API means you can do `useResponse().setStatus(200).setHeader(...)` in one statement
-- For custom error rendering, subclass `WooksHttpResponse` and override `renderError()`
-
-## Gotchas
-
-- Calling `send()` twice throws — check `response.responded` if unsure
-- `getRawRes()` without `passthrough` marks the response as "responded" — the framework won't touch it
-- `getRawRes(true)` (passthrough mode) lets you write headers/data while the framework still finalizes cookies and status
-- Cookie `maxAge` is in seconds, not milliseconds
-- `setContentType()` overwrites any previously set content-type

package/skills/wooksjs-event-http/testing.md

@@ -1,150 +0,0 @@
-# Testing — @wooksjs/event-http
-
-> Writing tests for handlers and composables with `prepareTestHttpContext`.
-
-## Concepts
-
-`prepareTestHttpContext` creates a fully initialized HTTP event context for testing. It sets up an `EventContext` with `httpKind` seeds (fake `IncomingMessage`, `HttpResponse`, route params, and optional pre-seeded body), then returns a runner function that executes callbacks inside the context scope.
-
-## API Reference
-
-### `prepareTestHttpContext(options): (cb) => T`
-
-```ts
-import { prepareTestHttpContext } from '@wooksjs/event-http'
-```
-
-**Options (`TTestHttpContext`):**
-
-| Option           | Type                                 | Required | Description                                     |
-| ---------------- | ------------------------------------ | -------- | ----------------------------------------------- |
-| `url`            | `string`                             | Yes      | Request URL (e.g. `/api/users?page=1`)          |
-| `method`         | `string`                             | No       | HTTP method (default: `'GET'`)                  |
-| `headers`        | `Record<string, string>`             | No       | Request headers                                 |
-| `params`         | `Record<string, string \| string[]>` | No       | Pre-set route parameters                        |
-| `requestLimits`  | `TRequestLimits`                     | No       | Custom request limits                           |
-| `rawBody`        | `string \| Buffer`                   | No       | Pre-seed the raw body (skips stream reading)    |
-| `defaultHeaders` | `Record<string, string \| string[]>` | No       | Default headers to pre-populate on the response |
-
-**Returns:** `(cb: () => T) => T` — a runner function.
-
-```ts
-const run = prepareTestHttpContext({
-  url: '/users/42',
-  method: 'GET',
-  headers: { authorization: 'Bearer abc123' },
-  params: { id: '42' },
-})
-
-run(() => {
-  // All composables work here
-  const { method } = useRequest()
-  const { params } = useRouteParams()
-  const { is } = useAuthorization()
-  expect(method).toBe('GET')
-  expect(params.id).toBe('42')
-  expect(is('bearer')).toBe(true)
-})
-```
-
-## Common Patterns
-
-### Pattern: Testing a custom composable
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { prepareTestHttpContext, useHeaders } from '@wooksjs/event-http'
-import { defineWook, cached } from '@wooksjs/event-core'
-
-const useApiKey = defineWook((ctx) => {
-  const headers = useHeaders(ctx)
-  return {
-    apiKey: headers['x-api-key'] as string | undefined,
-    isValid: () => headers['x-api-key'] === 'secret',
-  }
-})
-
-describe('useApiKey', () => {
-  it('extracts API key from headers', () => {
-    const run = prepareTestHttpContext({
-      url: '/api/data',
-      headers: { 'x-api-key': 'secret' },
-    })
-
-    run(() => {
-      const { apiKey, isValid } = useApiKey()
-      expect(apiKey).toBe('secret')
-      expect(isValid()).toBe(true)
-    })
-  })
-})
-```
-
-### Pattern: Testing body parsing
-
-```ts
-import { useBody } from '@wooksjs/http-body'
-
-it('parses JSON body', async () => {
-  const run = prepareTestHttpContext({
-    url: '/api/users',
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    rawBody: JSON.stringify({ name: 'Alice' }),
-  })
-
-  await run(async () => {
-    const { parseBody } = useBody()
-    const body = await parseBody<{ name: string }>()
-    expect(body.name).toBe('Alice')
-  })
-})
-```
-
-### Pattern: Testing response composable
-
-```ts
-it('sets response headers', () => {
-  const run = prepareTestHttpContext({ url: '/test' })
-
-  run(() => {
-    const response = useResponse()
-    response.setHeader('x-custom', 'value')
-    response.setCookie('session', 'abc', { httpOnly: true })
-
-    expect(response.getHeader('x-custom')).toBe('value')
-    expect(response.getCookie('session')?.value).toBe('abc')
-  })
-})
-```
-
-### Pattern: Testing cookies
-
-```ts
-it('reads cookies from request', () => {
-  const run = prepareTestHttpContext({
-    url: '/dashboard',
-    headers: { cookie: 'session=abc123; theme=dark' },
-  })
-
-  run(() => {
-    const { getCookie } = useCookies()
-    expect(getCookie('session')).toBe('abc123')
-    expect(getCookie('theme')).toBe('dark')
-    expect(getCookie('missing')).toBeNull()
-  })
-})
-```
-
-## Best Practices
-
-- Always use `prepareTestHttpContext` — don't manually construct `EventContext` for HTTP tests
-- Pre-seed `rawBody` for body parsing tests to avoid stream setup
-- Pre-seed `params` to test route parameter logic without a router
-- The runner function supports async callbacks — `await run(async () => { ... })`
-
-## Gotchas
-
-- `prepareTestHttpContext` uses a real `IncomingMessage` and `ServerResponse` (from `new Socket({})`) — they're functional but not connected to a network
-- The `HttpResponse` in tests is the base `HttpResponse`, not `WooksHttpResponse` — error rendering won't do content negotiation
-- `rawBody` pre-seeding stores a resolved Promise — `useRequest().rawBody()` returns immediately