@pikku/skills 0.12.22 → 0.12.25

package/skills/pikku-aws/SKILL.md

@@ -1,161 +0,0 @@
----
-name: pikku-aws
-description: >-
-  Use when setting up AWS services (S3, SQS, Secrets Manager) in a Pikku app. Covers S3Content for
-  file storage, SQSQueueService for queues, and AWSSecrets for secret management. TRIGGER when:
-  code uses S3Content, SQSQueueService, AWSSecrets, or user asks about AWS integration, S3
-  uploads, SQS queues, or AWS Secrets Manager with Pikku. DO NOT TRIGGER when: user asks about AWS
-  Lambda runtime (use pikku-deploy-lambda).
----
-
-# Pikku AWS Services
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-`@pikku/aws-services` provides AWS-backed implementations of Pikku's content, queue, and secret service interfaces.
-
-## Installation
-
-```bash
-yarn add @pikku/aws-services
-```
-
-## API Reference
-
-### `S3Content` (File Storage)
-
-```typescript
-import { S3Content } from '@pikku/aws-services'
-
-const content = new S3Content(
-  config: { bucketName: string; region: string; endpoint?: string },
-  logger: Logger,
-  signConfig: { keyPairId: string; privateKey: string }
-)
-```
-
-`endpoint` is what points the client at LocalStack or an S3-compatible store.
-
-**Methods** — every one takes a single **args object**, matching the shared
-`ContentService` interface. None of them are positional:
-
-- `signURL({ url, dateLessThan, dateGreaterThan? }): Promise<string>` — CloudFront-sign an absolute URL
-- `signContentKey({ bucket, contentKey, dateLessThan, dateGreaterThan? }): Promise<string>`
-- `getUploadURL({ bucket, fileKey, contentType, visibility? }): Promise<{ uploadUrl, assetKey }>` — `visibility` is ignored
-- `readFile({ bucket, key }): Promise<ReadableStream | NodeJS.ReadableStream>`
-- `readFileAsBuffer({ bucket, key }): Promise<Buffer>`
-- `writeFile({ bucket, key, stream }): Promise<boolean>`
-- `copyFile({ bucket, key, fromAbsolutePath }): Promise<boolean>`
-- `deleteFile({ bucket, key }): Promise<boolean>`
-
-### One real bucket, logical buckets as prefixes
-
-The `bucket` on every call is a **logical** bucket stored as a path prefix
-(`${bucket}/${key}`) inside the single S3 bucket named by `bucketName`. Don't
-provision an S3 bucket per logical bucket — the config takes only one.
-
-### Behaviours worth knowing before you rely on them
-
-- **`signURL` fails open.** A signing error is logged and the _unsigned_ URL is
-  returned rather than thrown. If your CloudFront distribution is private the
-  client then gets a 403; if it isn't, you have just handed out an unrestricted
-  link. Check that `signConfig` is a valid CloudFront key pair at boot.
-- **`signContentKey` builds `https://<bucketName>/<bucket>/<contentKey>`** — it
-  uses `bucketName` as the _host_. For signed content the value must therefore be
-  your CloudFront domain, not a plain bucket name, which also means the same
-  config field is doing two jobs.
-- **Presigned upload URLs expire after a fixed 3600s.** It is not configurable
-  through the service.
-- **Write paths swallow failures.** `writeFile`, `copyFile` and `deleteFile` log
-  and return `false` rather than throwing; the read paths throw. Check the
-  boolean.
-
-### `SQSQueueService` (Queue)
-
-```typescript
-import { SQSQueueService } from '@pikku/aws-services'
-
-const queue = new SQSQueueService({
-  region: string,
-  queueUrlPrefix: string, // e.g. 'https://sqs.us-east-1.amazonaws.com/123456789/'
-  endpoint?: string,      // LocalStack or a custom SQS endpoint
-})
-```
-
-Implements `QueueService`. Note: `supportsResults = false` — job status tracking is not supported.
-
-**Methods:**
-
-- `add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>` — Enqueue a message; returns SQS's `MessageId`
-- `getJob()` — always **throws**. SQS is fire-and-forget; reach for BullMQ or PgBoss when you need the result back.
-
-The queue URL is `queueUrlPrefix + queueName`, so the queue name in `wireQueueWorker` has to match the SQS queue exactly.
-
-Constraints inherited from SQS, enforced in `add`:
-
-- `options.delay` is in **milliseconds** and is floored to whole seconds. Over
-  900_000ms (15 minutes) or negative throws before the message is sent.
-- Standard queues only — no FIFO, so no `MessageGroupId` and no ordering
-  guarantee.
-- `data` is `JSON.stringify`d, which is where a `Date` or a `Map` quietly
-  degrades.
-
-### `AWSSecrets` (Secrets Manager)
-
-```typescript
-import { AWSSecrets } from '@pikku/aws-services'
-
-const secrets = new AWSSecrets({ awsRegion: 'eu-west-2' })
-```
-
-`AWSConfig` has one field, `awsRegion` — there is no credentials option; the SDK's
-default provider chain (instance role, env, profile) supplies those.
-
-**Methods:**
-
-- `getSecret<T = string>(SecretId: string): Promise<SecretValue<T>>` — a JSON secret is parsed automatically, so pass a shape as `T` (a non-JSON value comes back as the raw string). The result is a branded `SecretValue`, not a bare value — reveal it where it is used rather than passing it through logs
-- `getSecrets<T>(SecretIds: (keyof T & string)[]): Promise<Partial<T>>` — Batch fetch; missing keys are omitted rather than thrown
-- `hasSecret(SecretId: string): Promise<boolean>` — Check if secret exists
-- `setSecret` / `deleteSecret` — **not implemented** for `AWSSecrets`; it throws. Manage AWS secrets out of band.
-
-Every `getSecret` failure — missing secret, denied permission, a secret holding
-only binary — surfaces as the same `FATAL: Error finding secret: <id>`, with the
-real reason on the error's `cause`. Read `cause` before concluding the secret
-doesn't exist. `hasSecret` performs a full fetch and returns `false` for any
-error, so it can't distinguish "absent" from "not allowed" either.
-
-## Usage Patterns
-
-### S3 Content Service
-
-```typescript
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new PinoLogger()
-  const content = new S3Content(
-    { bucketName: config.s3Bucket, region: config.awsRegion },
-    logger,
-    { keyPairId: config.cfKeyPairId, privateKey: config.cfPrivateKey }
-  )
-  return { config, logger, content }
-})
-```
-
-### SQS Queue
-
-```typescript
-const createSingletonServices = pikkuServices(async (config) => {
-  const queue = new SQSQueueService({
-    region: config.awsRegion,
-    queueUrlPrefix: config.sqsUrlPrefix,
-  })
-  return { config, queue }
-})
-```

package/skills/pikku-backblaze/SKILL.md

@@ -1,104 +0,0 @@
----
-name: pikku-backblaze
-description: >-
-  Use when setting up Backblaze B2 file storage in a Pikku app. Covers B2Content for file uploads,
-  downloads, and signed URLs. TRIGGER when: code uses B2Content, user asks about Backblaze B2, or
-  @pikku/backblaze. DO NOT TRIGGER when: user asks about S3 storage (use pikku-aws).
----
-
-# Pikku Backblaze (B2 Content Storage)
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-`@pikku/backblaze` provides Backblaze B2-backed file storage implementing the `ContentService` interface.
-
-## Installation
-
-```bash
-yarn add @pikku/backblaze
-```
-
-## API Reference
-
-### `B2Content`
-
-```typescript
-import { B2Content } from '@pikku/backblaze'
-
-const content = new B2Content(
-  config: B2ContentConfig,
-  logger: Logger
-)
-```
-
-`B2ContentConfig` has exactly three fields — `applicationKeyId`, `applicationKey`
-and `bucketId`. There is no `cdnUrl`: downloads are served from the `downloadUrl`
-B2 returns at authorization.
-
-**Methods** — every one takes a single **args object**, matching the shared
-`ContentService` interface. None of them are positional:
-
-- `signContentKey({ bucket, contentKey, dateLessThan }): Promise<string>` — a full download URL with an `Authorization` query param
-- `signURL({ url, dateLessThan }): Promise<string>` — re-signs an existing `/file/` URL; a URL with no `/file/` segment is returned untouched
-- `getUploadURL({ bucket, fileKey, contentType, visibility? }): Promise<UploadURLResult>` — `visibility` is ignored by this backend
-- `writeFile({ bucket, key, stream }): Promise<boolean>`
-- `copyFile({ bucket, key, fromAbsolutePath }): Promise<boolean>`
-- `readFile({ bucket, key }): Promise<ReadableStream | NodeJS.ReadableStream>`
-- `readFileAsBuffer({ bucket, key }): Promise<Buffer>`
-- `deleteFile({ bucket, key }): Promise<boolean>`
-
-### One real bucket, logical buckets as prefixes
-
-The `bucket` on every call is a **logical** bucket stored as a path prefix
-(`${bucket}/${key}`) inside the single B2 bucket named by `bucketId`. Don't
-provision a B2 bucket per logical bucket — the config takes only one.
-
-### Behaviours worth knowing before you rely on them
-
-- **Writes are buffered in memory.** `writeFile` drains the whole stream into a
-  `Buffer` before uploading, because B2's upload endpoint needs a SHA-1 and a
-  content length up front. Large uploads should go through `getUploadURL` and be
-  sent by the client directly.
-- **`getUploadURL` sets `X-Bz-Content-Sha1: do_not_verify`**, since the server
-  can't hash a body it never sees. The client-side upload is unverified.
-- **Write paths swallow failures.** `writeFile`, `copyFile` and `deleteFile` log
-  and return `false` rather than throwing; the read paths and the signing paths
-  throw. Check the boolean — an ignored return is a silently lost file.
-- Authorization and the bucket-name lookup are cached on the instance for its
-  lifetime, so a rotated application key needs a new `B2Content`.
-
-## Usage Patterns
-
-```typescript
-import { B2Content } from '@pikku/backblaze'
-
-const createSingletonServices = pikkuServices(async (config) => {
-  const logger = new PinoLogger()
-  const content = new B2Content(
-    {
-      applicationKeyId: config.b2KeyId,
-      applicationKey: config.b2AppKey,
-      bucketId: config.b2BucketId,
-    },
-    logger
-  )
-  return { config, logger, content }
-})
-```
-
-```typescript
-await content.writeFile({ bucket: 'avatars', key: `${userId}.png`, stream })
-const url = await content.signContentKey({
-  bucket: 'avatars',
-  contentKey: `${userId}.png`,
-  dateLessThan: new Date(Date.now() + 60_000),
-})
-```

package/skills/pikku-deploy-cloudflare/SKILL.md

@@ -1,123 +0,0 @@
----
-name: pikku-deploy-cloudflare
-description: >-
-  Use when deploying a Pikku app to Cloudflare Workers. Covers HTTP fetch handler, scheduled
-  tasks, and WebSocket via Durable Objects. TRIGGER when: code imports @pikku/cloudflare, user
-  mentions Cloudflare Workers deployment, or worker entry uses ExportedHandler/wrangler.toml. DO
-  NOT TRIGGER when: just defining functions/wirings without Cloudflare-specific code.
----
-
-# Pikku Cloudflare Workers Deployment
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-```bash
-yarn add @pikku/cloudflare
-```
-
-## Worker Entry
-
-`@pikku/cloudflare` ships the handler factories the deploy codegen emits — use
-them rather than hand-rolling an `ExportedHandler`. Each returns a
-`WorkerEntrypoint` class that sets services up on every invocation (cached after
-the first) and adds an RPC-callable `runRpc(name, args)`:
-
-```typescript
-import { createCloudflareHandler } from '@pikku/cloudflare'
-import { createConfig, createSingletonServices } from './services.js'
-import './.pikku/pikku-bootstrap.gen.js'
-
-export default createCloudflareHandler(
-  { createConfig, createSingletonServices },
-  ['fetch', 'scheduled']
-)
-```
-
-| Factory                                            | For                                              |
-| -------------------------------------------------- | ------------------------------------------------ |
-| `createCloudflareHandler(factories, handlerTypes)` | combined `fetch`/`queue`/`scheduled`             |
-| `createCloudflareWorkerHandler(factories)`         | HTTP / agent / RPC / workflow-orchestrator units |
-| `createCloudflareCronHandler(factories)`           | cron units                                       |
-| `createCloudflareQueueHandler(factories)`          | queue-consumer and workflow-step units           |
-| `createCloudflareMCPHandler(factories)`            | MCP units (same HTTP transport)                  |
-| `createCloudflareWebSocketHandler(factories)`      | channel units, delegating to the DO              |
-
-`factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
-
-## Service Setup
-
-Cloudflare passes env bindings per-request, so services are built from `env`
-rather than at module load. `setupServices(env, factories)` is exported from
-`@pikku/cloudflare` and is what the factories call:
-
-```typescript
-import { setupServices } from '@pikku/cloudflare'
-
-const services = await setupServices(env, {
-  createConfig,
-  createSingletonServices,
-})
-```
-
-**Do not hand-roll this.** Beyond building `LocalVariablesService` /
-`LocalSecretService` and caching the result, it calls `setSingletonServices()` —
-and the core runners (`fetchData`, `runQueueJob`, `runScheduled`) resolve
-services through that global slot, _not_ through the value you were returned. A
-setup function that only returns the services leaves every request throwing
-"Singleton services not initialized" as a CF `1101`. It also stashes the env via
-`setCloudflareEnv`, which `getCloudflareEnv()` reads for bindings.
-
-## HTTP
-
-`runFetch(request, websocketHibernationServer?, options?)`:
-
-- A `GET` with `Upgrade: websocket` is routed to the hibernation server. Without
-  one passed in it answers **426**, so a channel worker that forgets the second
-  argument fails every upgrade while plain HTTP keeps working.
-- `CF-Ray` becomes the traceId when present, so a Cloudflare trace and a Pikku
-  trace line up without extra wiring.
-- `options.exposeErrors` defaults to **`false`** — error detail is withheld from
-  responses unless you opt in.
-
-## Scheduled Tasks
-
-`runScheduled(controller)` matches registered tasks against
-`controller.cron` and **returns after the first match**. Two tasks sharing one
-cron expression means only one of them ever runs — give each its own expression,
-or invoke `runScheduledTask({ name })` per task yourself.
-
-## WebSocket (Durable Objects)
-
-The ready-made DO class is exported; re-export it under the binding name and
-point the worker at it:
-
-```typescript
-export { PikkuWebSocketHibernationServer as WebSocketHibernationServer } from '@pikku/cloudflare'
-export default createCloudflareWebSocketHandler({
-  createConfig,
-  createSingletonServices,
-})
-```
-
-Subclass `CloudflareWebSocketHibernationServer` only when you need something
-`getParams()` cannot express — it is abstract with one method returning
-`{ singletonServices, createWireServices? }`. The channel store
-(`CloudflareWebsocketStore` over the DO's own storage), the event hub and the
-channel handler factory are all built by the base class; do not supply them.
-
-The router looks up the DO through the **`WEBSOCKET_HIBERNATION_SERVER`**
-binding and answers `503` naming it if the binding is missing, so declare it in
-`wrangler.toml` under exactly that name.
-
-A throw during `onConnect` closes the socket with `1008` and answers `403
-Forbidden` with a deliberately generic body — an auth denial and a genuine fault
-look identical to the client. The real reason is on the logger, so read the
-worker logs rather than the status code.

package/skills/pikku-deploy-express/SKILL.md

@@ -1,122 +0,0 @@
----
-name: pikku-deploy-express
-description: >-
-  Use when deploying a Pikku app with Express. Covers PikkuExpressServer standalone and
-  pikkuExpressMiddleware for existing Express apps. TRIGGER when: code imports @pikku/express or
-  @pikku/express-middleware, user mentions Express deployment, or start.ts creates a
-  PikkuExpressServer. DO NOT TRIGGER when: just defining functions/wirings without
-  Express-specific code.
----
-
-# Pikku Express Deployment
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-## Standalone Server
-
-```bash
-yarn add @pikku/express
-```
-
-```typescript
-import { PikkuExpressServer } from '@pikku/express'
-import './.pikku/pikku-bootstrap.gen.js'
-import { createConfig, createSingletonServices } from './services.js'
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-const appServer = new PikkuExpressServer(
-  { ...config, port: 4002, hostname: 'localhost' },
-  singletonServices.logger
-)
-appServer.enableExitOnSigInt()
-await appServer.init()
-await appServer.start()
-```
-
-**Constructor:** `new PikkuExpressServer(config, logger)`
-
-**Config extends CoreConfig with:**
-
-- `port: number`
-- `hostname: string`
-- `healthCheckPath?: string`
-- `limits?: Partial<Record<string, string>>`
-- `content?: LocalContentConfig` (for static assets / file uploads)
-
-**Methods:**
-
-- `init(httpOptions?: RunHTTPWiringOptions): Promise<void>` — installs the body parsers, the cookie parser and the Pikku middleware
-- `start(): Promise<void>` — Start listening
-- `stop(): Promise<void>` — Graceful shutdown; throws if the server was never started
-- `enableExitOnSigInt(): Promise<void>` — SIGINT handler: stops the singleton services, then the server, then exits 0
-- `enableCors(options): void` — Enable CORS
-- `enableStaticAssets(): void` — serve `content.localFileUploadPath` under `content.assetUrlPrefix`
-- `enableReaper(): void` — a `PUT /reaper/*path` upload sink for local development, path-traversal checked and bounded by `content.sizeLimit` (default `1mb`)
-- `getHttpServer(): Server` — the underlying `http.Server`, e.g. to attach a WebSocket server; throws before `start()`
-
-`enableStaticAssets` and `enableReaper` both throw when `content` is unset.
-
-**Property:** `app: Express` — Direct access to Express instance for custom middleware.
-
-### Ordering, and what `init` installs for you
-
-The health check is registered in the **constructor**, so it answers before any
-middleware you add and cannot be wrapped in auth. It defaults to
-`/health-check`; override with `healthCheckPath`.
-
-Everything else is installed by `init()`: `express.json`, `express.text` (for
-`text/xml`), `express.urlencoded`, `cookie-parser`, then the Pikku middleware.
-Call `enableCors` **before** `init` if you want CORS applied to Pikku's routes.
-
-Express buffers the body before Pikku sees it, so the parser limit is the only
-place an oversized request can actually be stopped. `httpOptions.maxBodySize`
-therefore feeds those parser limits, with an explicit `config.limits` entry
-(`json` / `xml` / `urlencoded`) still winning. Everything defaults to `1mb`.
-
-`init` passes `logRoutes: true` and `loadSchemas: true` by default; your
-`httpOptions` spread over them, so you can turn either off.
-
-## Middleware (existing Express app)
-
-```bash
-yarn add @pikku/express-middleware
-```
-
-```typescript
-import express from 'express'
-import { pikkuExpressMiddleware } from '@pikku/express-middleware'
-import './.pikku/pikku-bootstrap.gen.js'
-
-const app = express()
-app.use(express.json())
-app.use(cookieParser())
-app.use(
-  pikkuExpressMiddleware({
-    logger: singletonServices.logger,
-    logRoutes: true,
-    loadSchemas: true,
-    // plus any RunHTTPWiringOptions: maxBodySize, respondWith404, coerceDataFromSchema
-  })
-)
-```
-
-Options beyond `logger` are all optional: `logRoutes` logs the wiring table once
-at startup, `loadSchemas` compiles every schema up front, and the rest are
-`RunHTTPWiringOptions` passed through per request.
-
-On your own app **you** own the parser stack — the middleware reads
-`req.body`, so a body parser and `cookie-parser` must be registered before it,
-and `maxBodySize` alone will not stop an oversized request that your parser
-already accepted. Unmatched requests fall through to `next()` (unless
-`respondWith404` is set), so Pikku's routes coexist with your existing ones;
-a streaming response is the exception and does not call `next()`.

package/skills/pikku-deploy-uws/SKILL.md

@@ -1,144 +0,0 @@
----
-name: pikku-deploy-uws
-description: >-
-  Use when deploying a Pikku app with uWebSockets.js. Covers PikkuUWSServer with built-in HTTP and
-  WebSocket support, and pikkuWebsocketHandler for standalone ws library. TRIGGER when: code
-  imports @pikku/uws or @pikku/ws, user mentions uWebSockets or high-performance server, or
-  start.ts creates a PikkuUWSServer. DO NOT TRIGGER when: just defining functions/wirings without
-  uWS-specific code.
----
-
-# Pikku uWebSockets.js Deployment
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Highest-throughput option among Pikku's runtimes. Handles both HTTP and WebSocket automatically.
-
-```bash
-yarn add @pikku/uws
-```
-
-```typescript
-import { PikkuUWSServer } from '@pikku/uws'
-import './.pikku/pikku-bootstrap.gen.js'
-import { createConfig, createSingletonServices } from './services.js'
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-const appServer = new PikkuUWSServer(
-  { ...config, hostname: 'localhost', port: 4002 },
-  singletonServices.logger
-)
-appServer.enableExitOnSigInt()
-await appServer.init()
-await appServer.start()
-```
-
-**Constructor:** `new PikkuUWSServer(config, logger)`
-
-**Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
-
-**Methods:** `init(httpOptions?: RunHTTPWiringOptions)`, `start()`, `stop()`, `enableExitOnSigInt()`
-
-**Property:** `app: uWS.App` — Direct access to uWebSockets app instance.
-
-### What the server does and does not give you
-
-`init()` registers three things in order: the health check (`healthCheckPath`,
-default `/health-check`), a catch-all `app.any('/*')` HTTP handler, and a
-catch-all `app.ws('/*')` websocket handler. Nothing is registered by the
-constructor, so nothing answers before `init` runs.
-
-**There is no `enableCors`, no static assets and no `content` support** — unlike
-the Express server. The class is explicitly a prototyping convenience; for
-anything that needs extra handlers, use `@pikku/uws-handler` directly and treat
-`pikku-uws-server.ts` as the template (that is what its own JSDoc says).
-
-`httpOptions` reaches the HTTP handler only. The websocket handler is
-constructed with a fixed `{ logger, logRoutes: true }`, so per-request options
-do not apply to the upgrade path. `loadSchemas` is also never passed by the
-server, so schemas compile lazily on first use rather than at startup — pass
-`loadSchemas: true` in `httpOptions` if you want the startup cost paid up front.
-
-`stop()` closes the listen socket and then waits a fixed 2 seconds for
-connections to drain. Called before `start()`, it throws a bare **string**, not
-an `Error`, so `catch (e) { e.message }` reads `undefined`.
-
-### Body limits
-
-uWS hands over raw chunks with no limit of its own, so the handler counts the
-bytes itself. A request over `maxBodySize` (default `DEFAULT_MAX_BODY_SIZE`) is
-answered `413` with a `PayloadTooLargeError` body, and the chunks are dropped
-rather than concatenated — an oversized request never accumulates in memory. A
-`content-length` header that already exceeds the limit short-circuits before any
-data arrives.
-
-### Handlers directly (own uWS app)
-
-```typescript
-import { pikkuHTTPHandler, pikkuWebsocketHandler } from '@pikku/uws-handler'
-
-app.any('/*', pikkuHTTPHandler({ logger, logRoutes: true, loadSchemas: true }))
-app.ws('/*', pikkuWebsocketHandler({ logger, logRoutes: true }))
-```
-
-Both take `{ logger, logRoutes?, loadSchemas? } & RunHTTPWiringOptions`.
-
-## WebSocket Standalone (ws library)
-
-For WebSocket-only servers using the `ws` library:
-
-```bash
-yarn add @pikku/ws
-```
-
-```typescript
-import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
-import { stopSingletonServices } from '@pikku/core'
-import { Server } from 'http'
-import { WebSocketServer } from 'ws'
-import './.pikku/pikku-bootstrap.gen.js'
-
-const server = new Server()
-const wss = new WebSocketServer({
-  noServer: true,
-  maxPayload: DEFAULT_WS_MAX_PAYLOAD,
-})
-
-pikkuWebsocketHandler({
-  server,
-  wss,
-  logger: singletonServices.logger,
-})
-
-server.listen(4002, 'localhost', () => {
-  console.log('Server running at http://localhost:4002/')
-})
-
-process.on('SIGINT', async () => {
-  await stopSingletonServices()
-  wss.close()
-  server.close()
-  process.exit(0)
-})
-```
-
-`pikkuWebsocketHandler` takes `{ server, wss, logger, logRoutes?, loadSchemas? }`
-plus `RunHTTPWiringOptions`, and there is no server class in `@pikku/ws` — the
-handler attaches to a `Server` you own.
-
-`noServer: true` is required, not stylistic: the handler listens for the HTTP
-server's own `upgrade` event, opens the channel (running middleware and auth
-first), and only then calls `wss.handleUpgrade`. A `WebSocketServer` bound to
-the server would take the socket before any of that ran. An upgrade the channel
-rejects gets the socket destroyed, and an auth failure is written as a real HTTP
-response on the raw socket rather than a silent drop.