@nifrajs/cli 1.0.0 → 1.2.0

package/dist/cli.js

@@ -68,7 +68,7 @@ routes/ from the current directory. Run from your project root.
 Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with \`--port <n>\` (alias \`-p\`) or the
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`;
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "1.0.0";
+const CLI_VERSION = "1.2.0";
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v) => v;
 const asBunPlugins = (v) => v;

package/dist/mcp-http.js

@@ -19,7 +19,7 @@ import { loadTypesCorpus } from "./types-search.js";
 // tool factory + the transport core from one entry: `import { respondMcpHttp, docsTools } from "@nifrajs/cli/mcp"`.
 export { docsTools } from "./mcp-docs-tools.js";
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "1.0.0";
+const VERSION = "1.2.0";
 const SERVER_INFO = { name: "nifra-docs", version: VERSION };
 const DOCS_HEALTH = "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example.";
 /** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */

package/docs/llms-full.txt

@@ -8,7 +8,7 @@ nifra is a Bun-native, contract-first, framework-agnostic full-stack TypeScript
 
 - **ESM-only.** Bun is the first-class runtime (`app.listen(port)` → `Bun.serve`); every other runtime uses `app.fetch`. No CommonJS.
 - **The client never throws.** Every `@nifrajs/client` call returns `{ ok, status, data, error }` — branch on it, don't try/catch.
-- **Validate at the boundary.** Per-route `body`/`query`/`params`/`headers`/`response` is any Standard Schema (zod/valibot/arktype) or `@nifrajs/schema`'s `t`; invalid input → structured `400` before the handler runs.
+- **Validate at the boundary.** Per-route `body`/`query`/`params`/`headers`/`response` is any Standard Schema (zod/valibot/arktype) or `@nifrajs/schema`'s `t`; invalid input → structured `422` before the handler runs.
 - **Secure by default.** Body-size cap, `requestTimeoutMs` + `c.signal`, graceful shutdown, redacting logger, same-origin `redirect()`, constant-time secret comparison, fail-closed middleware.
 - **Money** in integer minor units; **time** parsed to absolute UTC at the boundary.
 - Throwing a `Response` anywhere in the lifecycle is control flow (returned as-is), not an error.
@@ -4411,6 +4411,61 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/cache
+
+Typed KV cache for nifra — **TTL**, **stale-while-revalidate**, **tag invalidation**, and **single-flight
+stampede protection** on a **pluggable store** (in-memory by default; bring CF KV / Redis for a shared
+cache). **Dependency-free**; runs on Bun/Node/Deno/Workers.
+
+```ts
+import { createCache } from "@nifrajs/cache"
+
+const cache = createCache({ defaultTtlMs: 30_000 })
+
+// Cache-aside in a loader — one DB hit per key per TTL, even under a stampede:
+export async function loader({ params }) {
+  const user = await cache.wrap(
+    `user:${params.id}`,
+    () => db.users.find(params.id),
+    { ttlMs: 30_000, swrMs: 60_000, tags: [`user:${params.id}`] },
+  )
+  return { user }
+}
+
+// On write, drop everything tagged for that user:
+await cache.invalidateTag(`user:${id}`)
+```
+
+## Semantics
+
+- **`wrap(key, loader, opts)`** — returns the cached value, or runs `loader`, stores, and returns it.
+  - **Fresh** (`now < staleAt`): the cached value, no loader call.
+  - **Stale-but-live** (`staleAt ≤ now < expiresAt`, i.e. within `swrMs`): the stale value is returned
+    **immediately** while a **background** refresh runs (deduped). Latency stays flat; data self-heals.
+  - **Miss/expired**: awaits `loader`. Concurrent misses for the same key share **one** call (no stampede).
+  - A throwing `loader` is **not** cached (and in the background path goes to `onError`, never rejects the caller).
+- **`set` / `get` / `has` / `delete`**, **`invalidateTag(tag)`**, **`clear()`**.
+- TTL: `ttlMs` (→ stale) + optional `swrMs` (→ served-stale window) + optional `tags`.
+
+## Stores
+
+The default `MemoryCache` is in-process with lazy expiry, a tag index, and an optional LRU cap
+(`new MemoryCache({ maxEntries: 10_000 })`). For a cache shared across instances, implement `CacheStore`
+(`get` / `set` / `delete` / `invalidateTag` / `clear`) over CF KV, Redis, etc.:
+
+```ts
+const cache = createCache({ store: new RedisCacheStore(redis) })
+```
+
+On **Cloudflare Workers** the in-memory cache is per-isolate and short-lived — back it with **CF KV** (or
+the Cache API) via a `CacheStore` for anything that should survive across requests/instances.
+
+## API
+
+- `createCache(options?)` → `Cache` — `{ store?, defaultTtlMs?, now?, onError? }`.
+- `cache.wrap(key, loader, { ttlMs?, swrMs?, tags? })` · `get` · `has` · `set` · `delete` · `invalidateTag` · `clear`.
+- `MemoryCache({ maxEntries?, now? })` — the default store; implement `CacheStore` for your own.
+
 ## @nifrajs/cli
 
 The `nifra` CLI — zero-config dev/build/start for a nifra app, plus the agent surfaces (`nifra context`,
@@ -4611,7 +4666,7 @@ export type App = typeof app // hand this to @nifrajs/client for end-to-end type
   surface — handlers lift over unchanged.
 - **Validation at the boundary.** Per-route `body`/`query` is any
   [Standard Schema](https://standardschema.dev) (zod/valibot/arktype, or `@nifrajs/schema`'s
-  `t`); invalid input is rejected with a structured `400` before the handler runs.
+  `t`); invalid input is rejected with a structured `422` before the handler runs.
 - **Lifecycle middleware.** `derive`/`decorate` extend the typed context;
   `onRequest`/`beforeHandle`/`afterHandle`/`onResponse`/`onError` run around handlers;
   `use(middleware)` applies a bundle.
@@ -4942,6 +4997,89 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/jobs
+
+Typed background jobs for nifra — enqueue work off the request path, run it with **retries + exponential
+backoff + dead-lettering** on a **pluggable store**. The async companion to [`@nifrajs/cron`](../cron)
+(cron schedules; jobs does the deferred work — email, webhooks, image processing). **Dependency-free.**
+
+```ts
+import { createQueue } from "@nifrajs/jobs"
+import { t } from "@nifrajs/schema"
+
+const q = createQueue()
+
+const email = q.define("send-email", {
+  input: t.object({ to: t.string(), subject: t.string() }), // validated at enqueue (the trust boundary)
+  retries: { attempts: 5 },                                 // 5 tries, exponential backoff, then dead-letter
+  async handler({ to, subject }, ctx) {
+    await send(to, subject) // ctx = { id, name, attempt }
+  },
+})
+
+// In a route handler — enqueue and return immediately:
+await email.enqueue({ to: "a@b.com", subject: "Welcome" })
+await email.enqueue({ to: "b@b.com", subject: "Later" }, { delayMs: 60_000 }) // run in 1 min
+
+// Start the worker on a long-running server (Bun/Node/Deno):
+const worker = q.start({ concurrency: 4 })
+// graceful shutdown: await worker.stop()
+```
+
+`enqueue` is typed against the handler's payload, and `input` (any [Standard Schema](https://standardschema.dev)
+validator — `@nifrajs/schema`'s `t`, Zod, Valibot, …) validates it before it's stored, so a bad payload
+fails at the call site, not three retries later.
+
+## Retries
+
+Per-job: `retries: number` (attempts) or `{ attempts, backoff }`. A handler that throws is routed to
+`onError`, then retried with the backoff delay; after the last attempt it's **dead-lettered**, not lost.
+
+```ts
+import { exponentialBackoff, fixedBackoff } from "@nifrajs/jobs"
+
+q.define("flaky", { retries: { attempts: 3, backoff: fixedBackoff(5_000) }, handler })
+createQueue({ backoff: exponentialBackoff({ baseMs: 500, maxMs: 60_000, jitter: 0.2 }) }) // queue default
+```
+
+## Stores
+
+The default `MemoryJobStore` is single-process — correct for dev and a single server, but not durable and
+not multi-worker. Implement the `JobStore` interface (`enqueue` / `lease` / `complete` / `retry` /
+`deadLetter` / `counts`) over Redis/Postgres for durability or horizontal workers:
+
+```ts
+const q = createQueue({ store: new RedisJobStore(redis) })
+```
+
+Leasing is at-least-once: a leased job is hidden for `leaseMs`; a worker that dies mid-job releases it
+back automatically. Make handlers **idempotent**.
+
+## Cloudflare Workers
+
+Workers has no long-lived process, so don't call `start()`. Back the queue with a durable store and a
+[CF Queue](https://developers.cloudflare.com/queues/), enqueue via the producer binding, and drain from
+the consumer:
+
+```ts
+export default {
+  async queue(_batch, env) {
+    const q = createQueue({ store: new D1JobStore(env.DB) })
+    await q.process() // one round; the platform schedules invocations
+  },
+}
+```
+
+## API
+
+- `createQueue(options?)` → `Queue` — `{ store?, onError?, now?, defaultAttempts?, backoff? }`.
+- `queue.define(name, { handler, input?, retries? })` → typed `JobHandle` with `.enqueue(payload, { delayMs? | runAt? })`.
+- `queue.enqueue(name, payload, options?)` — enqueue by name.
+- `queue.start({ concurrency?, pollIntervalMs?, leaseMs? })` → `Worker` (`.stop()` drains gracefully).
+- `queue.process()` — run one poll round (for Workers / custom drivers). `queue.drain()` — process until empty.
+- `queue.counts()` → `{ pending, active, dead }`. `queue.store` — the underlying store.
+- Stores: `MemoryJobStore`. Backoff: `exponentialBackoff`, `fixedBackoff`, `noBackoff`.
+
 ## @nifrajs/middleware
 
 Composable, dependency-light middleware for [nifra](../../README.md) — CORS, security headers, body
@@ -5258,6 +5396,85 @@ one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
 done-gate, or `nifra mcp` to give the agent live project tools.
 
+## @nifrajs/storage
+
+Blob storage for nifra — one `StorageAdapter` interface, several adapters. The **persistence half of
+[`@nifrajs/uploads`](../uploads)**: `uploads` decides what's allowed (MIME, size, signed URLs, EXIF
+stripping); `storage` puts the bytes somewhere. **Dependency-free.**
+
+```ts
+import { FileStorage } from "@nifrajs/storage"
+
+const storage = new FileStorage("./uploads")
+await storage.put("avatars/u1.png", bytes, { contentType: "image/png" })
+
+const object = await storage.get("avatars/u1.png") // { body, size, contentType?, metadata? } | null
+await storage.delete("avatars/u1.png")
+const keys = await storage.list({ prefix: "avatars/" })
+```
+
+## Adapters
+
+| Adapter | Use | Notes |
+|---|---|---|
+| `MemoryStorage` | dev / tests | not durable, not shared across instances |
+| `FileStorage(root)` | a long-running server (Bun/Node/Deno) | bytes-only: `contentType` inferred from the extension, custom metadata not persisted |
+| `R2Storage(env.BUCKET)` | the edge (Cloudflare R2) | round-trips `contentType` + metadata; binding typed structurally (no `@cloudflare/workers-types`) |
+
+Implement `StorageAdapter` (`put` / `get` / `delete` / `exists` / `list`) for **S3 / GCS / anything else** —
+the same five methods, and your routes don't change.
+
+## Key safety
+
+Keys are POSIX-ish relative paths (`avatars/u1.png`). **Every** adapter rejects unsafe keys — absolute
+paths, `..` traversal, NUL bytes, backslashes — via `assertSafeKey`, so a `FileStorage` key can never
+escape its root and a key valid in one adapter is valid in all.
+
+```ts
+import { assertSafeKey, StorageKeyError } from "@nifrajs/storage"
+```
+
+## API
+
+- `new MemoryStorage()` · `new FileStorage(root)` · `new R2Storage(bucket)`.
+- `put(key, data, { contentType?, metadata? })` — `data` is `Uint8Array | ArrayBuffer | string`.
+- `get(key)` → `{ body, size, contentType?, metadata? } | null` · `delete(key)` · `exists(key)` · `list({ prefix?, limit? })`.
+- `assertSafeKey(key)` / `StorageKeyError` · `toBytes(data)`.
+
+## @nifrajs/testing
+
+Testing helpers for nifra apps. [`@nifrajs/client`](../client)'s **`testClient`** is already the typed,
+no-network in-process request client (nifra's supertest / `inject`). This package adds what it doesn't: a
+**cookie jar** and a **cookie-persisting `testSession`**, so a login → authenticated-request flow tests as
+easily as a single request.
+
+```ts
+import { testSession } from "@nifrajs/testing"
+import { app } from "../src/app"
+
+const { client, cookies } = testSession<typeof app>(app)
+
+await client.auth.login.post({ email, password }) // Set-Cookie captured into the jar
+const me = await client.me.get()                   // Cookie sent automatically
+expect(me.ok && me.data.id).toBeDefined()
+expect(cookies.get("sid")).toBeDefined()           // inspect the jar
+
+await client.auth.logout.post()                    // a Max-Age=0 Set-Cookie clears it
+expect(cookies.get("sid")).toBeUndefined()
+```
+
+Same in-process client as `testClient` — the app's own `fetch`, no server/port/network, the full real
+lifecycle (validation, middleware, contracts, auth) and end-to-end types from `App`. The only addition is
+that every call carries and captures cookies via a shared jar.
+
+## API
+
+- `testSession<App>(app, { origin?, cookies? })` → `{ client: Treaty<App>, cookies: CookieJar }`.
+- `cookieJar()` → `CookieJar` — `header()` · `applyTo(headers)` · `store(response)` · `set` · `get` · `clear` · `size`.
+  Honours removal (`Max-Age=0` / past `Expires`); other cookie attributes are ignored (in-process, same-origin).
+
+For a **stateless** request (no cookies), use `testClient` from `@nifrajs/client` directly.
+
 ## @nifrajs/uploads
 
 File-upload hardening for nifra — magic-byte MIME detection, size + type validation, short-TTL signed download URLs, and EXIF/metadata stripping. Dependency-free, edge-safe.
@@ -5590,6 +5807,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `betterAuth`, `BetterAuthLike`, `BetterAuthOptions`, `getSession`, `requireSession`, `RequireSessionOptions`, `SessionOf`
 
+## @nifrajs/cache
+
+`Cache`, `CacheOptions`, `CacheStore`, `createCache`, `MemoryCache`, `MemoryCacheOptions`, `SetOptions`, `StoredEntry`, `WrapOptions`
+
 ## @nifrajs/client
 
 `ActionArgs`, `ActionData`, `ApiError`, `ApiProxy`, `client`, `ClientOptions`, `FetchFn`, `inProcessClient`, `Jsonify`, `LoaderArgs`, `LoaderData`, `RegistryOf`, `Result`, `testClient`, `Treaty`, `TreatyFromRegistry`
@@ -5626,6 +5847,10 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 `batch`, `BindableElement`, `BindableRoot`, `bindScope`, `computed`, `effect`, `island`, `IslandContext`, `IslandHost`, `IslandScope`, `IslandSetup`, `islandState`, `mountIslands`, `signal`, `Signal`
 
+## @nifrajs/jobs
+
+`Backoff`, `createQueue`, `EnqueueOptions`, `exponentialBackoff`, `ExponentialOptions`, `fixedBackoff`, `JobContext`, `JobCounts`, `JobDefinition`, `JobError`, `JobHandle`, `JobHandler`, `JobStore`, `JobValidationError`, `MemoryJobStore`, `noBackoff`, `Queue`, `QueueOptions`, `RetryPolicy`, `StandardResult`, `StandardSchemaV1`, `StoredJob`, `Worker`, `WorkerOptions`
+
 ## @nifrajs/mcp
 
 `bridgeScript`, `createMcpServer`, `CreateMcpServerOptions`, `defineMcpTool`, `DefineMcpToolOptions`, `defineMcpWidget`, `DefineMcpWidgetOptions`, `McpAppBridge`, `McpHttpOptions`, `McpServer`, `McpToolHandlerResult`, `McpUiIntent`, `McpWidget`, `respondMcpHttp`, `uiResourceMeta`, `widgetDocument`
@@ -5648,7 +5873,15 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/schema
 
-`fromTypeBox`, `NifraSchema`, `OpenAPIDocument`, `OpenAPIInfo`, `registerFormat`, `t`, `toOpenAPI`
+`decodeCursor`, `encodeCursor`, `fromTypeBox`, `NifraSchema`, `OpenAPIDocument`, `OpenAPIInfo`, `Page`, `paginate`, `registerFormat`, `t`, `toOpenAPI`
+
+## @nifrajs/storage
+
+`assertSafeKey`, `FileStorage`, `ListOptions`, `MemoryStorage`, `PutOptions`, `R2BucketLike`, `R2ObjectLike`, `R2Storage`, `StorageAdapter`, `StorageData`, `StorageKeyError`, `StorageObject`, `toBytes`
+
+## @nifrajs/testing
+
+`AppLike`, `cookieJar`, `CookieJar`, `testSession`, `TestSession`, `TestSessionOptions`
 
 ## @nifrajs/uploads
 

package/docs/types.json

@@ -569,7 +569,7 @@
     "name": "CacheOptions",
     "kind": "interface",
     "package": "@nifrajs/middleware",
-    "signature": "export interface CacheOptions {\n    readonly store: ResponseCacheStore;\n    /** Time to live in milliseconds. */\n    readonly ttlMs: number;\n    /** Methods cached. Default `[\"GET\", \"HEAD\"]`. */\n    readonly methods?: readonly string[];\n    /** Status predicate. Default: `200` only. */\n    readonly status?: (status: number) => boolean;\n    /** Header names included in the cache key and emitted in `Vary`. */\n    readonly vary?: readonly string[];\n    /** Custom cache key. Receives the normalized `vary` headers through the request itself. */\n    readonly key?: (request: Request) => string;\n    /** Maximum response bytes to store. Default `1_000_000`. Larger responses pass through. */\n    readonly maxBytes?: number;\n    /** Respect request `Cache-Control: no-cache/no-store`. Default `true`. */\n    readonly respectRequestCacheControl?: boolean;\n    /** Respect response `Cache-Control: private/no-store`. Default `true`. */\n    readonly respectResponseCacheControl?: boolean;\n    /** Cache responses with `Set-Cookie`. Default `false`. */\n    readonly cacheSetCookie?: boolean;\n    /** Response header for cache status. Default `\"x-nifra-cache\"`; set `false` to disable. */\n    readonly cacheStatusHeader?: string | false;\n}"
+    "signature": "export interface CacheOptions {\n    readonly store: ResponseCacheStore;\n    /** Time to live in milliseconds. */\n    readonly ttlMs: number;\n    /** Methods cached. Default `[\"GET\", \"HEAD\"]`. */\n    readonly methods?: readonly string[];\n    /** Status predicate. Default: `200` only. */\n    readonly status?: (status: number) => boolean;\n    /** Header names included in the cache key and emitted in `Vary`. */\n    readonly vary?: readonly string[];\n    /** Custom cache key. Receives the normalized `vary` headers through the request itself. */\n    readonly key?: (request: Request) => string;\n    /** Maximum response bytes to store. Default `1_000_000`. Larger responses pass through. */\n    readonly maxBytes?: number;\n    /** Respect request `Cache-Control: no-cache/no-store`. Default `true`. */\n    readonly respectRequestCacheControl?: boolean;\n    /** Respect response `Cache-Control: private/no-store`. Default `true`. */\n    readonly respectResponseCacheControl?: boolean;\n    /** Cache responses with `Set-Cookie`. Default `false`. */\n    readonly cacheSetCookie?: boolean;\n    /** Cache responses to requests bearing `Authorization` or `Cookie` even when the response is not\n     * explicitly `Cache-Control: public` (or `s-maxage`). Default `false`: a shared cache must not store a\n     * personalized response (RFC 9111 §3.5), or it would be replayed to other users. Leave this off unless\n     * the cached route is genuinely the same for every caller. */\n    readonly cacheAuthenticated?: boolean;\n    /** Response header for cache status. Default `\"x-nifra-cache\"`; set `false` to disable. */\n    readonly cacheStatusHeader?: string | false;\n}"
   },
   {
     "name": "CacheStore",
@@ -1414,8 +1414,8 @@
     "name": "docsTools",
     "kind": "function",
     "package": "@nifrajs/cli",
-    "signature": "export declare function docsTools(loadDocs: () => Promise<string | undefined>, loadExamples: () => Promise<Example[] | undefined>): McpTool[];",
-    "doc": "/** Build `nifra_docs` + `nifra_example` over injected corpus loaders. */"
+    "signature": "export declare function docsTools(loadDocs: () => Promise<string | undefined>, loadExamples: () => Promise<Example[] | undefined>, loadTypes: () => Promise<TypeEntry[] | undefined>): McpTool[];",
+    "doc": "/** Build `nifra_docs` + `nifra_example` + `nifra_types` over injected corpus loaders. */"
   },
   {
     "name": "DoctorAppliedFix",
@@ -2168,8 +2168,7 @@
     "name": "idempotency",
     "kind": "function",
     "package": "@nifrajs/middleware",
-    "signature": "export declare function idempotency(options: IdempotencyOptions): Middleware;",
-    "doc": "/**\n * Idempotency-key middleware. Apply with `app.use(idempotency({ store }))`.\n *\n * **`Set-Cookie` is intentionally not cached or replayed** — a cookie set on the first request is\n * session-specific, so replaying it to a different caller (key collision or abuse) would leak/fixate a\n * session. Cache the body + status + the rest of the headers; let auth cookies re-issue per request.\n *\n * Caching buffers the response body, so apply this to JSON/API routes, not streaming SSR responses.\n */"
+    "signature": "export declare function idempotency(options: IdempotencyOptions): Middleware;"
   },
   {
     "name": "IdempotencyClaim",
@@ -2181,7 +2180,7 @@
     "name": "IdempotencyOptions",
     "kind": "interface",
     "package": "@nifrajs/middleware",
-    "signature": "export interface IdempotencyOptions {\n    /** Where claims + cached responses live. `MemoryIdempotencyStore` for dev; a shared store in production. */\n    readonly store: IdempotencyStore;\n    /** Header carrying the key. Default `\"idempotency-key\"`. */\n    readonly header?: string;\n    /** Methods the guard applies to. Default `[\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]` (unsafe methods). */\n    readonly methods?: readonly string[];\n    /** How long a completed response is replayable, in ms. Default 24h. */\n    readonly ttlMs?: number;\n    /** How long the in-flight lock survives a crashed handler, in ms. Default 60s. */\n    readonly lockTtlMs?: number;\n    /** Max response bytes to cache. A larger response is returned but **not** stored. Default 1 MiB. */\n    readonly maxBytes?: number;\n    /** Whether a response should be cached for replay. Default: status `< 500` (don't replay transient 5xx). */\n    readonly shouldCache?: (response: Response) => boolean;\n}"
+    "signature": "export interface IdempotencyOptions {\n    /** Where claims + cached responses live. `MemoryIdempotencyStore` for dev; a shared store in production. */\n    readonly store: IdempotencyStore;\n    /** Header carrying the key. Default `\"idempotency-key\"`. */\n    readonly header?: string;\n    /** Methods the guard applies to. Default `[\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]` (unsafe methods). */\n    readonly methods?: readonly string[];\n    /** How long a completed response is replayable, in ms. Default 24h. */\n    readonly ttlMs?: number;\n    /** How long the in-flight lock survives a crashed handler, in ms. Default 60s. */\n    readonly lockTtlMs?: number;\n    /** Max response bytes to cache. A larger response is returned but **not** stored. Default 1 MiB. */\n    readonly maxBytes?: number;\n    /** Whether a response should be cached for replay. Default: status `< 500` (don't replay transient 5xx). */\n    readonly shouldCache?: (response: Response) => boolean;\n    /**\n     * Derive the store key from the request. Default: the `header` value **scoped by method + path**, so the\n     * same key on a different endpoint can't collide. Return a **principal-scoped** key (e.g.\n     * `` `${userId}:${req.headers.get(\"idempotency-key\")}` ``) so one user can't replay another's stored\n     * response on a shared key. Return `null`/`\"\"` to skip dedupe for this request.\n     */\n    readonly key?: (req: Request, header: string) => string | null;\n}"
   },
   {
     "name": "IdempotencyRecord",
@@ -2873,6 +2872,13 @@
     "signature": "export declare function loadReactDomServer(resolve?: ResolveSync | undefined): Promise<ReactDomServer>;",
     "doc": "/**\n * Load `react-dom/server`, preferring the app-root-resolved copy under the Bun runtime. Exported for unit\n * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can\n * inject a stub that succeeds (re-root branch) or throws (fallback branch) to cover both deterministically\n * without depending on the machine's node_modules layout.\n */"
   },
+  {
+    "name": "loadTypesCorpus",
+    "kind": "function",
+    "package": "@nifrajs/cli",
+    "signature": "export declare function loadTypesCorpus(): Promise<TypeEntry[] | undefined>;",
+    "doc": "/** Load the bundled type corpus (`docs/types.json`), resolved relative to this module so it works from\n * `src/` (dev) and `dist/` (published) alike. */"
+  },
   {
     "name": "Locale",
     "kind": "type",
@@ -2906,6 +2912,13 @@
     "package": "@nifrajs/middleware",
     "signature": "export interface LoggerOptions {\n    /** Sink for each line. Default: `console.log(JSON.stringify(fields))`. Route to your own logger here. */\n    readonly log?: (fields: RequestLogFields) => void;\n}"
   },
+  {
+    "name": "lookupType",
+    "kind": "function",
+    "package": "@nifrajs/cli",
+    "signature": "export declare function lookupType(types: readonly TypeEntry[], name: string): TypeEntry[];",
+    "doc": "/** Exact (case-insensitive) name lookup — returns every declaration with that name (a name can exist in\n * more than one package). */"
+  },
   {
     "name": "Manifest",
     "kind": "interface",
@@ -4262,6 +4275,13 @@
     "signature": "export declare function renderSizeReport(report: SizeReport): string;",
     "doc": "/**\n * Render a {@link SizeReport} as a terse aligned table (biggest first) with a totals row — the text\n * `nifra build --report` prints. Pure (string in, string out) so the formatting is unit-testable.\n */"
   },
+  {
+    "name": "renderTypesResult",
+    "kind": "function",
+    "package": "@nifrajs/cli",
+    "signature": "export declare function renderTypesResult(types: readonly TypeEntry[], name: string | undefined, query: string | undefined, limit: number): string;",
+    "doc": "/**\n * Render the tool result. `name` → the exact declaration(s); else `query` → the top matches; else a\n * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),\n * so this is the complete answer — there is no need to read a `.d.ts` file.\n */"
+  },
   {
     "name": "reproduciblePath",
     "kind": "function",
@@ -4948,6 +4968,12 @@
     "package": "@nifrajs/cli",
     "signature": "export interface ScoredSection extends DocSection {\n    readonly score: number;\n}"
   },
+  {
+    "name": "ScoredType",
+    "kind": "interface",
+    "package": "@nifrajs/cli",
+    "signature": "export interface ScoredType extends TypeEntry {\n    readonly score: number;\n}"
+  },
   {
     "name": "ScriptDescriptor",
     "kind": "interface",
@@ -4995,6 +5021,13 @@
     "signature": "export interface SearchTermGroup {\n    readonly term: string;\n    readonly variants: readonly string[];\n}",
     "doc": "/**\n * Tiny deterministic query expansion for the agent-facing docs/example search tools.\n *\n * This is intentionally not \"semantic search\": the corpora are small, curated, and bundled with the\n * package. A few framework-specific aliases plus safe prefix matching cover the common human/agent\n * wording drift (\"authentication\" vs \"auth\", \"ws\" vs \"websocket\") without adding dependencies,\n * model calls, or nondeterministic ranking.\n */"
   },
+  {
+    "name": "searchTypes",
+    "kind": "function",
+    "package": "@nifrajs/cli",
+    "signature": "export declare function searchTypes(types: readonly TypeEntry[], query: string, limit: number): ScoredType[];",
+    "doc": "/** Keyword-score types: a term in the name is worth far more than one in the signature/doc body. */"
+  },
   {
     "name": "secretBytes",
     "kind": "function",
@@ -5079,7 +5112,7 @@
     "name": "Server",
     "kind": "class",
     "package": "@nifrajs/core",
-    "signature": "export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {\n    private readonly router;\n    /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */\n    private readonly wsRouter;\n    private wsRouteCount;\n    /** In-process pub/sub backing `ws.subscribe(topic)` + `app.publish(topic, data)` (single-instance).\n     * Created by the first `app.ws()` via the `@nifrajs/core/ws` runtime — `undefined` until then, so a\n     * no-WebSocket app never constructs (or bundles) it. */\n    private topics;\n    private readonly routeList;\n    private readonly maxBodyBytes;\n    private readonly requestTimeoutMs;\n    private readonly gracefulSignals;\n    private readonly logger;\n    private bunServer;\n    private readonly derives;\n    private readonly decorations;\n    private readonly beforeHandleHooks;\n    private readonly afterHandleHooks;\n    private readonly onErrorHooks;\n    private readonly aroundHooks;\n    private readonly onRequestHooks;\n    private readonly onResponseHooks;\n    private readonly responseRequests;\n    /** Names of plugins/middleware already applied via `use` — for idempotent dedupe. */\n    private readonly appliedPlugins;\n    constructor(options?: ServerOptions);\n    /** Add a per-request, computed context extension for subsequent routes. */\n    derive<D extends object>(fn: (context: Context & Ctx) => MaybePromise<D>): Server<R, Ctx & D>;\n    /** Add a static context value for subsequent routes. */\n    decorate<const K extends string, V>(key: K, value: V): Server<R, Ctx & Record<K, V>>;\n    /**\n     * Run before routing on the raw request. Return a `Response` to short-circuit, or a replacement\n     * `Request` to continue routing with a rewritten method/URL/headers. Global.\n     */\n    onRequest(fn: (req: Request) => MaybePromise<OnRequestResult>): this;\n    /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */\n    beforeHandle(fn: (context: Context & Ctx) => MaybePromise<unknown>): this;\n    /**\n     * Wrap the matched route lifecycle for subsequent routes. This is intentionally generic over the\n     * route output, so wrappers like async context storage do not force Node's direct JSON path through\n     * a Web `Response`. The first registered wrapper is outermost.\n     */\n    around(fn: <T>(context: Context & Ctx, next: () => MaybePromise<T>) => MaybePromise<T>): this;\n    /** Transform the handler's result before it is serialized. Order-scoped. */\n    afterHandle(fn: (result: unknown, context: Context & Ctx) => MaybePromise<unknown>): this;\n    /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */\n    onError(fn: (error: unknown, context: Context & Ctx) => MaybePromise<unknown>): this;\n    /** Transform every outgoing response — success, error, 404, 405, short-circuit. Global. */\n    onResponse(fn: (response: Response, req: Request) => MaybePromise<Response>): this;\n    /**\n     * Apply a type-**identity** plugin ({@link IdentityPlugin}, from {@link defineIdentityPlugin}) — it\n     * registers routes/hooks but doesn't change the types, so this returns `this` with the route registry\n     * and context fully intact. This overload exists specifically so a *named* identity plugin (e.g.\n     * `@nifrajs/better-auth`) threads the registry: its `& { pluginName }` intersection would otherwise\n     * defeat the generic inference of the transforming overload below and collapse the result to `any`.\n     */\n    use(plugin: IdentityPlugin): this;\n    /**\n     * Apply a **plugin function** — `(app) => app`, typically built with {@link definePlugin}. It's\n     * called with `this` and its result is returned, so an inline plugin's `derive`/`decorate` thread\n     * the added context to handlers defined after `use` (the overload is generic over the concrete\n     * `this`). A named plugin already applied is skipped (idempotent dedupe).\n     */\n    use<Out extends AnyServer>(plugin: (app: this) => Out): Out;\n    /**\n     * Apply a {@link Middleware} bundle — wire each hook it provides to its lifecycle point. Returns\n     * `this` (no context-type merging); call it before the routes its `beforeHandle`/`afterHandle`\n     * should cover (those are order-scoped; `onRequest`/`onResponse` are global). A named bundle already\n     * applied is skipped (idempotent).\n     */\n    use(mw: Middleware): this;\n    get<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"GET\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    get<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"GET\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    post<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"POST\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    post<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"POST\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    put<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"PUT\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    put<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"PUT\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    patch<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"PATCH\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    patch<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"PATCH\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    delete<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"DELETE\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    delete<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"DELETE\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    /**\n     * Register a **WebSocket** route. The connection upgrades on a `GET` to `path` carrying\n     * `Upgrade: websocket`; the optional `handler.upgrade(c)` runs in the request context first and may\n     * reject (return a `Response`) or seed per-connection `ws.data`. WebSockets are served by the\n     * adapter (`listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler`) — not by bare `app.fetch`, which\n     * has no socket (a WS path through `app.fetch` is a normal HTTP response).\n     *\n     *   app.ws(\"/chat\", { open: (ws) => ws.send(\"hi\"), message: (ws, data) => ws.send(data) })\n     */\n    ws<Data = unknown, Schema extends StandardSchemaV1 | undefined = undefined>(path: string, handler: WebSocketHandler<Data, EnvOf<Ctx>, Schema>): this;\n    /**\n     * Broadcast `data` to every WebSocket connection subscribed to `topic` (via `ws.subscribe(topic)`).\n     * In-process and **single-instance** (see {@link TopicRegistry}) — a multi-instance deploy must bridge\n     * an external fan-out (Redis, a Durable Object) to this. A no-op when nobody is subscribed.\n     */\n    publish(topic: string, data: string | ArrayBufferView | ArrayBuffer): void;\n    private route;\n    /**\n     * Low-level route registration shared by the inline builder and `implement()`.\n     * Captures the server's current `derive`/`decorate` chain into the route — this\n     * is the \"compiled\", order-scoped per-route chain.\n     */\n    register(method: Method, path: string, schema: RouteSchema | undefined, handler: (context: never) => unknown): void;\n    /**\n     * Enumerate the registered routes (method, path, input schemas), in registration\n     * order. Powers `toOpenAPI` and other introspection; the router trie itself no\n     * longer holds the original patterns.\n     */\n    routes(): ReadonlyArray<RouteDescriptor>;\n    /**\n     * Resolve a `Request` to a `Response` — the whole lifecycle, testable without a port. The\n     * optional `platform` carries edge inputs (`env`, `waitUntil`); edge adapters pass it, and\n     * Bun/Node/Deno omit it (then `c.env` is `undefined` and `c.waitUntil` runs fire-and-forget).\n     */\n    fetch(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<Response>;\n    private fetchSource;\n    /**\n     * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` — the\n     * `@nifrajs/node` adapter serializes the returned primitives straight to the socket, skipping the undici\n     * `Response` build + body drain (the bulk of the Node bridge cost, measured ≈4µs/req). A handler that\n     * returns a `Response`, an error/short-circuit, or any registered `onResponse` hook falls back to the\n     * full Web path (`{ kind: \"response\" }`), so behavior is identical — only the common JSON-data case is\n     * faster. Same lifecycle as {@link fetch} (body cap, validation, hooks all run); only the final\n     * render differs.\n     */\n    resolveNode(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<NodeServeOutcome>;\n    resolveNodeSource(source: RequestSource, platform?: Platform<EnvOf<Ctx>>): MaybePromise<NodeServeOutcome>;\n    /**\n     * Resolve a WebSocket upgrade — the seam every serving adapter uses. Returns `pass` (not a WS\n     * upgrade for a registered route → handle as normal HTTP), `reject` (a WS route matched but\n     * `upgrade()` rejected, or the path was malformed → return `response`), or `upgrade` (perform the\n     * runtime upgrade, then dispatch the native socket's events to `handler`, seeding `ws.data` with\n     * `data`). Runs the route's `upgrade(c)` guard in a real request context. Synchronous unless\n     * `upgrade()` is async; a throw rejects with a flat 500 (no detail leaked).\n     */\n    resolveWebSocketUpgrade(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<WebSocketUpgradeOutcome>;\n    /** Bun `fetch` when WS routes exist: try a WS upgrade first, else run the normal HTTP lifecycle.\n     * `undefined` ⇒ Bun owns the upgraded socket; a `Response` ⇒ a normal reply or a rejected upgrade.\n     * (The socket dispatch itself lives in `ws-bun.ts`, loaded via `@nifrajs/core/ws`.) */\n    private bunFetchWithWebSocket;\n    /**\n     * The shared lifecycle, generic over how the final value is rendered: `finalize` turns a handler's\n     * result + `set` into the output `T` (`toResponse` → a Web `Response`; `toNodeOutcome` → node-direct\n     * primitives), `wrapResponse` lifts an early/error `Response` into that same `T`, and `onTimeout`\n     * produces the 503. The Web `fetch` and `resolveNode` are thin callers over this one routing +\n     * context + lifecycle implementation — no duplication across the trust boundary.\n     */\n    private dispatch;\n    /**\n     * onRequest short-circuit path. Synchronous as long as every hook returns synchronously (the\n     * common case — e.g. CORS returning `undefined` for a non-preflight request): an `async` version\n     * here put EVERY request of any app with one onRequest hook onto the promise machinery, profiled\n     * at ~13% of a realistic request. The first hook that returns a Promise hands the REMAINING\n     * hooks to the async continuation; behavior is identical.\n     */\n    private runWithOnRequest;\n    /** Async tail of {@link runWithOnRequest}: applies the first awaited hook's outcome, then runs\n     * the remaining hooks (awaiting freely — we're already async here). */\n    private continueOnRequest;\n    private takeResponseRequest;\n    /**\n     * Route → build context → run. Synchronous through to the handler for a **bare** route\n     * ({@link RouteEntry.bare}), so a sync handler produces its result with zero promise allocations;\n     * routes with validation/hooks keep the full async {@link runLifecycle}, unchanged.\n     */\n    private routeAndRun;\n    /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so\n     * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */\n    private runContextlessBare;\n    private contextlessBareError;\n    /**\n     * The synchronous fast path for a {@link RouteEntry.bare} route: apply static decorations, call the\n     * handler, render the result — **no `await`** unless the handler itself returns a promise. It mirrors\n     * the bare slice of {@link runLifecycle} (which a bare route would otherwise no-op through) and shares\n     * {@link logRequestError}; a bare route has no `onError` hooks, so error handling is fully synchronous\n     * (a thrown `Response` is control flow; anything else is a logged flat 500). This is where nifra skips\n     * the per-request async-frame tax — the same win codegen routers get, but without `eval`.\n     */\n    private runBare;\n    /** Bare-route error rendering — identical to {@link runLifecycle}'s catch minus the (absent) onError\n     * loop: a thrown `Response` is returned as deliberate control flow; anything else is logged + 500. */\n    /**\n     * Build a route's fused Web lane (see {@link RouteEntry.fusedWeb}). Composition happens once at\n     * registration; the returned closure is what every request to the route runs. Behavior is\n     * byte-identical to the generic `runBare`/`runContextlessBare` + `toResponse` pair — same\n     * decoration order, same error routing (thrown `Response` = control flow; anything else logs and\n     * 500s), same respond semantics (the lifecycle parity suite pins it).\n     */\n    private buildFusedWeb;\n    private bareError;\n    private runWithAround;\n    private runAround;\n    private runBodyOnly;\n    /** Validate + run the handler for the bodyOnly path — shared by the inline fast path and the\n     * streaming fallback. A method (not per-request closures) so the hot path allocates nothing\n     * beyond the one `.then` continuation. */\n    private finishBodyOnly;\n    private applyBodyValidation;\n    private runQueryOnly;\n    /** Validate-result → set `ctx.query` → run handler. A method (not a per-request closure), the\n     * query analogue of {@link applyBodyValidation}. */\n    private applyQueryValidation;\n    /**\n     * Thread the response through each global `onResponse` hook. Stays SYNCHRONOUS until a hook\n     * actually returns a Promise — an `async` version forced a promise + microtask on EVERY response\n     * of any app with an onResponse hook (cors/securityHeaders/etag/timing all use onResponse), the\n     * same ~13%/req tax the onRequest walk was de-async'd to avoid. The first async hook hands the\n     * rest to {@link continueOnResponse}.\n     */\n    private applyOnResponse;\n    /** Async tail of {@link applyOnResponse}: runs the remaining hooks once one has gone async. */\n    private continueOnResponse;\n    /**\n     * Bound the response time. On timeout we abort `ctx.signal` (so cancellation-aware\n     * handlers can bail) and return 503; the in-flight work keeps running but its\n     * result is discarded — JS can't forcibly cancel a promise.\n     */\n    private withTimeout;\n    /**\n     * The post-match lifecycle: validate → derive → beforeHandle → handler → afterHandle, with onError.\n     * Generic over the render: a success value goes through `finalize(result, set)` (a Web `Response`, or\n     * node-direct primitives); an early/error `Response` (validation, thrown, 500) through `wrapResponse`.\n     */\n    private runLifecycle;\n    private handleLifecycleError;\n    /** Log an unhandled request error to the (redacting) logger — shared by {@link runLifecycle} and the\n     * bare fast path ({@link bareError}) so both record the same fields. Never throws; never leaks. */\n    private logRequestError;\n    private readAndValidateBody;\n    /**\n     * Read the body as text, capped at `maxBodyBytes`. Rejects (`null`) on a\n     * `Content-Length` over the cap *before* buffering, and aborts mid-stream once the\n     * running byte count exceeds it — so a lying or absent length can't force us to\n     * buffer an oversized payload.\n     *\n     * Fast path: when a non-chunked request carries a `Content-Length` within the cap,\n     * a native `req.json()` is already bounded — under HTTP/1.1 + HTTP/2 framing the\n     * runtime delivers at most `Content-Length` bytes — so we skip the manual stream\n     * loop and a separate text decode. It trusts the wire\n     * *framing*, not the header value: nifra only ever receives framed Requests from the\n     * runtime's HTTP server, never a hand-built one with a mismatched length. Chunked or\n     * length-less bodies fall through to the streaming byte-cap guard below.\n     */\n    private readBoundedJson;\n    /**\n     * Start a `Bun.serve` instance bound to `port` (use `0` for an ephemeral port).\n     *\n     * `reusePort` sets `SO_REUSEPORT` so **multiple processes can bind the same port** and the kernel\n     * load-balances connections across them — the standard way to use every core (Bun is\n     * single-threaded per process). Spawn one process per core, each calling\n     * `app.listen(PORT, { reusePort: true })`; see `examples/cluster.ts`. Every process must opt in,\n     * and all of them must be the same app. Linux balances ~evenly; macOS accepts the flag but may\n     * favor one socket (fine for dev, measure on Linux for production numbers).\n     */\n    listen(port: number, options?: {\n        readonly reusePort?: boolean;\n    }): RunningServer;\n    /**\n     * Gracefully stop: wait for in-flight requests to finish (up to `drainMs`), then\n     * issue a single terminal stop — graceful if everything drained, forced if\n     * stragglers remain. Safe to call when not listening.\n     *\n     * The Bun semantics: poll `pendingRequests` (awaiting\n     * `stop()`'s promise drops in-flight requests), and decide graceful-vs-forced in\n     * ONE call (Bun can't escalate an already-graceful `stop()` to a forced close).\n     * New connections may be accepted during the drain window; in a real deploy the\n     * load balancer has already stopped routing here, and `drainMs` bounds it.\n     */\n    stop({ drainMs }?: {\n        drainMs?: number;\n    }): Promise<void>;\n    private installSignalHandlers;\n}",
+    "signature": "export declare class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {\n    private readonly router;\n    /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */\n    private readonly wsRouter;\n    private wsRouteCount;\n    /** In-process pub/sub backing `ws.subscribe(topic)` + `app.publish(topic, data)` (single-instance).\n     * Created by the first `app.ws()` via the `@nifrajs/core/ws` runtime — `undefined` until then, so a\n     * no-WebSocket app never constructs (or bundles) it. */\n    private topics;\n    private readonly routeList;\n    private readonly maxBodyBytes;\n    private readonly wsMaxPayloadBytes;\n    private readonly requestTimeoutMs;\n    private readonly gracefulSignals;\n    private readonly logger;\n    private bunServer;\n    private readonly derives;\n    private readonly decorations;\n    private readonly beforeHandleHooks;\n    private readonly afterHandleHooks;\n    private readonly onErrorHooks;\n    private readonly aroundHooks;\n    private readonly onRequestHooks;\n    private readonly onResponseHooks;\n    private readonly responseRequests;\n    /** Names of plugins/middleware already applied via `use` — for idempotent dedupe. */\n    private readonly appliedPlugins;\n    constructor(options?: ServerOptions);\n    /** Add a per-request, computed context extension for subsequent routes. */\n    derive<D extends object>(fn: (context: Context & Ctx) => MaybePromise<D>): Server<R, Ctx & D>;\n    /** Add a static context value for subsequent routes. */\n    decorate<const K extends string, V>(key: K, value: V): Server<R, Ctx & Record<K, V>>;\n    /**\n     * Run before routing on the raw request. Return a `Response` to short-circuit, or a replacement\n     * `Request` to continue routing with a rewritten method/URL/headers. Global.\n     */\n    onRequest(fn: (req: Request) => MaybePromise<OnRequestResult>): this;\n    /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */\n    beforeHandle(fn: (context: Context & Ctx) => MaybePromise<unknown>): this;\n    /**\n     * Wrap the matched route lifecycle for subsequent routes. This is intentionally generic over the\n     * route output, so wrappers like async context storage do not force Node's direct JSON path through\n     * a Web `Response`. The first registered wrapper is outermost.\n     */\n    around(fn: <T>(context: Context & Ctx, next: () => MaybePromise<T>) => MaybePromise<T>): this;\n    /** Transform the handler's result before it is serialized. Order-scoped. */\n    afterHandle(fn: (result: unknown, context: Context & Ctx) => MaybePromise<unknown>): this;\n    /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */\n    onError(fn: (error: unknown, context: Context & Ctx) => MaybePromise<unknown>): this;\n    /** Transform every outgoing response — success, error, 404, 405, short-circuit. Global. */\n    onResponse(fn: (response: Response, req: Request) => MaybePromise<Response>): this;\n    /**\n     * Apply a type-**identity** plugin ({@link IdentityPlugin}, from {@link defineIdentityPlugin}) — it\n     * registers routes/hooks but doesn't change the types, so this returns `this` with the route registry\n     * and context fully intact. This overload exists specifically so a *named* identity plugin (e.g.\n     * `@nifrajs/better-auth`) threads the registry: its `& { pluginName }` intersection would otherwise\n     * defeat the generic inference of the transforming overload below and collapse the result to `any`.\n     */\n    use(plugin: IdentityPlugin): this;\n    /**\n     * Apply a **plugin function** — `(app) => app`, typically built with {@link definePlugin}. It's\n     * called with `this` and its result is returned, so an inline plugin's `derive`/`decorate` thread\n     * the added context to handlers defined after `use` (the overload is generic over the concrete\n     * `this`). A named plugin already applied is skipped (idempotent dedupe).\n     */\n    use<Out extends AnyServer>(plugin: (app: this) => Out): Out;\n    /**\n     * Apply a {@link Middleware} bundle — wire each hook it provides to its lifecycle point. Returns\n     * `this` (no context-type merging); call it before the routes its `beforeHandle`/`afterHandle`\n     * should cover (those are order-scoped; `onRequest`/`onResponse` are global). A named bundle already\n     * applied is skipped (idempotent).\n     */\n    use(mw: Middleware): this;\n    get<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"GET\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    get<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"GET\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    post<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"POST\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    post<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"POST\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    put<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"PUT\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    put<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"PUT\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    patch<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"PATCH\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    patch<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"PATCH\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    delete<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(path: Path, schema: S, handler: H): Server<AddRoute<R, \"DELETE\", Path, RouteInfoFor<Path, S, OutputOf<H>>>, Ctx>;\n    delete<Path extends string, H extends Handler<Path, RouteSchema, Ctx>>(path: Path, handler: H): Server<AddRoute<R, \"DELETE\", Path, RouteInfoFor<Path, Record<never, never>, OutputOf<H>>>, Ctx>;\n    /**\n     * Register a **WebSocket** route. The connection upgrades on a `GET` to `path` carrying\n     * `Upgrade: websocket`; the optional `handler.upgrade(c)` runs in the request context first and may\n     * reject (return a `Response`) or seed per-connection `ws.data`. WebSockets are served by the\n     * adapter (`listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler`) — not by bare `app.fetch`, which\n     * has no socket (a WS path through `app.fetch` is a normal HTTP response).\n     *\n     *   app.ws(\"/chat\", { open: (ws) => ws.send(\"hi\"), message: (ws, data) => ws.send(data) })\n     */\n    ws<Data = unknown, Schema extends StandardSchemaV1 | undefined = undefined>(path: string, handler: WebSocketHandler<Data, EnvOf<Ctx>, Schema>): this;\n    /**\n     * Broadcast `data` to every WebSocket connection subscribed to `topic` (via `ws.subscribe(topic)`).\n     * In-process and **single-instance** (see {@link TopicRegistry}) — a multi-instance deploy must bridge\n     * an external fan-out (Redis, a Durable Object) to this. A no-op when nobody is subscribed.\n     */\n    publish(topic: string, data: string | ArrayBufferView | ArrayBuffer): void;\n    private route;\n    /**\n     * Low-level route registration shared by the inline builder and `implement()`.\n     * Captures the server's current `derive`/`decorate` chain into the route — this\n     * is the \"compiled\", order-scoped per-route chain.\n     */\n    register(method: Method, path: string, schema: RouteSchema | undefined, handler: (context: never) => unknown): void;\n    /**\n     * Enumerate the registered routes (method, path, input schemas), in registration\n     * order. Powers `toOpenAPI` and other introspection; the router trie itself no\n     * longer holds the original patterns.\n     */\n    routes(): ReadonlyArray<RouteDescriptor>;\n    /**\n     * Resolve a `Request` to a `Response` — the whole lifecycle, testable without a port. The\n     * optional `platform` carries edge inputs (`env`, `waitUntil`); edge adapters pass it, and\n     * Bun/Node/Deno omit it (then `c.env` is `undefined` and `c.waitUntil` runs fire-and-forget).\n     */\n    fetch(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<Response>;\n    private fetchSource;\n    /**\n     * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` — the\n     * `@nifrajs/node` adapter serializes the returned primitives straight to the socket, skipping the undici\n     * `Response` build + body drain (the bulk of the Node bridge cost, measured ≈4µs/req). A handler that\n     * returns a `Response`, an error/short-circuit, or any registered `onResponse` hook falls back to the\n     * full Web path (`{ kind: \"response\" }`), so behavior is identical — only the common JSON-data case is\n     * faster. Same lifecycle as {@link fetch} (body cap, validation, hooks all run); only the final\n     * render differs.\n     */\n    resolveNode(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<NodeServeOutcome>;\n    resolveNodeSource(source: RequestSource, platform?: Platform<EnvOf<Ctx>>): MaybePromise<NodeServeOutcome>;\n    /**\n     * Resolve a WebSocket upgrade — the seam every serving adapter uses. Returns `pass` (not a WS\n     * upgrade for a registered route → handle as normal HTTP), `reject` (a WS route matched but\n     * `upgrade()` rejected, or the path was malformed → return `response`), or `upgrade` (perform the\n     * runtime upgrade, then dispatch the native socket's events to `handler`, seeding `ws.data` with\n     * `data`). Runs the route's `upgrade(c)` guard in a real request context. Synchronous unless\n     * `upgrade()` is async; a throw rejects with a flat 500 (no detail leaked).\n     */\n    resolveWebSocketUpgrade(req: Request, platform?: Platform<EnvOf<Ctx>>): MaybePromise<WebSocketUpgradeOutcome>;\n    /** Bun `fetch` when WS routes exist: try a WS upgrade first, else run the normal HTTP lifecycle.\n     * `undefined` ⇒ Bun owns the upgraded socket; a `Response` ⇒ a normal reply or a rejected upgrade.\n     * (The socket dispatch itself lives in `ws-bun.ts`, loaded via `@nifrajs/core/ws`.) */\n    private bunFetchWithWebSocket;\n    /**\n     * The shared lifecycle, generic over how the final value is rendered: `finalize` turns a handler's\n     * result + `set` into the output `T` (`toResponse` → a Web `Response`; `toNodeOutcome` → node-direct\n     * primitives), `wrapResponse` lifts an early/error `Response` into that same `T`, and `onTimeout`\n     * produces the 503. The Web `fetch` and `resolveNode` are thin callers over this one routing +\n     * context + lifecycle implementation — no duplication across the trust boundary.\n     */\n    private dispatch;\n    /**\n     * onRequest short-circuit path. Synchronous as long as every hook returns synchronously (the\n     * common case — e.g. CORS returning `undefined` for a non-preflight request): an `async` version\n     * here put EVERY request of any app with one onRequest hook onto the promise machinery, profiled\n     * at ~13% of a realistic request. The first hook that returns a Promise hands the REMAINING\n     * hooks to the async continuation; behavior is identical.\n     */\n    private runWithOnRequest;\n    /** Async tail of {@link runWithOnRequest}: applies the first awaited hook's outcome, then runs\n     * the remaining hooks (awaiting freely — we're already async here). */\n    private continueOnRequest;\n    private takeResponseRequest;\n    /**\n     * Route → build context → run. Synchronous through to the handler for a **bare** route\n     * ({@link RouteEntry.bare}), so a sync handler produces its result with zero promise allocations;\n     * routes with validation/hooks keep the full async {@link runLifecycle}, unchanged.\n     */\n    private routeAndRun;\n    /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so\n     * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */\n    private runContextlessBare;\n    private contextlessBareError;\n    /**\n     * The synchronous fast path for a {@link RouteEntry.bare} route: apply static decorations, call the\n     * handler, render the result — **no `await`** unless the handler itself returns a promise. It mirrors\n     * the bare slice of {@link runLifecycle} (which a bare route would otherwise no-op through) and shares\n     * {@link logRequestError}; a bare route has no `onError` hooks, so error handling is fully synchronous\n     * (a thrown `Response` is control flow; anything else is a logged flat 500). This is where nifra skips\n     * the per-request async-frame tax — the same win codegen routers get, but without `eval`.\n     */\n    private runBare;\n    /** Bare-route error rendering — identical to {@link runLifecycle}'s catch minus the (absent) onError\n     * loop: a thrown `Response` is returned as deliberate control flow; anything else is logged + 500. */\n    /**\n     * Build a route's fused Web lane (see {@link RouteEntry.fusedWeb}). Composition happens once at\n     * registration; the returned closure is what every request to the route runs. Behavior is\n     * byte-identical to the generic `runBare`/`runContextlessBare` + `toResponse` pair — same\n     * decoration order, same error routing (thrown `Response` = control flow; anything else logs and\n     * 500s), same respond semantics (the lifecycle parity suite pins it).\n     */\n    private buildFusedWeb;\n    private bareError;\n    private runWithAround;\n    private runAround;\n    private runBodyOnly;\n    /** Validate + run the handler for the bodyOnly path — shared by the inline fast path and the\n     * streaming fallback. A method (not per-request closures) so the hot path allocates nothing\n     * beyond the one `.then` continuation. */\n    private finishBodyOnly;\n    private applyBodyValidation;\n    private runQueryOnly;\n    /** Validate-result → set `ctx.query` → run handler. A method (not a per-request closure), the\n     * query analogue of {@link applyBodyValidation}. */\n    private applyQueryValidation;\n    /**\n     * Thread the response through each global `onResponse` hook. Stays SYNCHRONOUS until a hook\n     * actually returns a Promise — an `async` version forced a promise + microtask on EVERY response\n     * of any app with an onResponse hook (cors/securityHeaders/etag/timing all use onResponse), the\n     * same ~13%/req tax the onRequest walk was de-async'd to avoid. The first async hook hands the\n     * rest to {@link continueOnResponse}.\n     */\n    private applyOnResponse;\n    /** Async tail of {@link applyOnResponse}: runs the remaining hooks once one has gone async. */\n    private continueOnResponse;\n    /**\n     * Bound the response time. On timeout we abort `ctx.signal` (so cancellation-aware\n     * handlers can bail) and return 503; the in-flight work keeps running but its\n     * result is discarded — JS can't forcibly cancel a promise.\n     */\n    private withTimeout;\n    /**\n     * The post-match lifecycle: validate → derive → beforeHandle → handler → afterHandle, with onError.\n     * Generic over the render: a success value goes through `finalize(result, set)` (a Web `Response`, or\n     * node-direct primitives); an early/error `Response` (validation, thrown, 500) through `wrapResponse`.\n     */\n    private runLifecycle;\n    private handleLifecycleError;\n    /** Log an unhandled request error to the (redacting) logger — shared by {@link runLifecycle} and the\n     * bare fast path ({@link bareError}) so both record the same fields. Never throws; never leaks. */\n    private logRequestError;\n    private readAndValidateBody;\n    /**\n     * Read the body as text, capped at `maxBodyBytes`. Rejects (`null`) on a\n     * `Content-Length` over the cap *before* buffering, and aborts mid-stream once the\n     * running byte count exceeds it — so a lying or absent length can't force us to\n     * buffer an oversized payload.\n     *\n     * Fast path: when a non-chunked request carries a `Content-Length` within the cap,\n     * a native `req.json()` is already bounded — under HTTP/1.1 + HTTP/2 framing the\n     * runtime delivers at most `Content-Length` bytes — so we skip the manual stream\n     * loop and a separate text decode. It trusts the wire\n     * *framing*, not the header value: nifra only ever receives framed Requests from the\n     * runtime's HTTP server, never a hand-built one with a mismatched length. Chunked or\n     * length-less bodies fall through to the streaming byte-cap guard below.\n     */\n    private readBoundedJson;\n    /**\n     * Start a `Bun.serve` instance bound to `port` (use `0` for an ephemeral port).\n     *\n     * `reusePort` sets `SO_REUSEPORT` so **multiple processes can bind the same port** and the kernel\n     * load-balances connections across them — the standard way to use every core (Bun is\n     * single-threaded per process). Spawn one process per core, each calling\n     * `app.listen(PORT, { reusePort: true })`; see `examples/cluster.ts`. Every process must opt in,\n     * and all of them must be the same app. Linux balances ~evenly; macOS accepts the flag but may\n     * favor one socket (fine for dev, measure on Linux for production numbers).\n     */\n    listen(port: number, options?: {\n        readonly reusePort?: boolean;\n    }): RunningServer;\n    /**\n     * Gracefully stop: wait for in-flight requests to finish (up to `drainMs`), then\n     * issue a single terminal stop — graceful if everything drained, forced if\n     * stragglers remain. Safe to call when not listening.\n     *\n     * The Bun semantics: poll `pendingRequests` (awaiting\n     * `stop()`'s promise drops in-flight requests), and decide graceful-vs-forced in\n     * ONE call (Bun can't escalate an already-graceful `stop()` to a forced close).\n     * New connections may be accepted during the drain window; in a real deploy the\n     * load balancer has already stopped routing here, and `drainMs` bounds it.\n     */\n    stop({ drainMs }?: {\n        drainMs?: number;\n    }): Promise<void>;\n    private installSignalHandlers;\n}",
     "doc": "/**\n * The inline server. Routes are chainable and fully type-inferred. `derive`/\n * `decorate` extend the handler context (`Ctx`) for routes defined *after* them,\n * with full types; `Ctx` is server-only and never touches the client registry.\n *\n *   app.decorate(\"db\", db).derive((c) => ({ user: auth(c) }))\n *      .get(\"/me\", (c) => c.user)            // c.user + c.db are typed\n */"
   },
   {
@@ -5127,7 +5160,7 @@
     "name": "ServerOptions",
     "kind": "interface",
     "package": "@nifrajs/core",
-    "signature": "export interface ServerOptions {\n    /**\n     * Max request body size (bytes), enforced **only when a route declares a body schema** — the cap\n     * lives in the schema-validated read path. Default 1_000_000.\n     *\n     * A route WITHOUT a body schema (raw body, file upload, BYO-validation) that reads `c.req` directly\n     * is not auto-bounded — use **`c.boundedBody(maxBytes?)`** / **`c.boundedJson(maxBytes?)`**, which\n     * apply this same cap (override per route by passing `maxBytes` — larger for an upload endpoint,\n     * smaller to tighten one).\n     */\n    readonly maxBodyBytes?: number;\n    /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */\n    readonly requestTimeoutMs?: number;\n    /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */\n    readonly gracefulSignals?: boolean;\n    /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */\n    readonly logger?: Logger;\n}"
+    "signature": "export interface ServerOptions {\n    /**\n     * Max request body size (bytes), enforced **only when a route declares a body schema** — the cap\n     * lives in the schema-validated read path. Default 1_000_000.\n     *\n     * A route WITHOUT a body schema (raw body, file upload, BYO-validation) that reads `c.req` directly\n     * is not auto-bounded — use **`c.boundedBody(maxBytes?)`** / **`c.boundedJson(maxBytes?)`**, which\n     * apply this same cap (override per route by passing `maxBytes` — larger for an upload endpoint,\n     * smaller to tighten one).\n     */\n    readonly maxBodyBytes?: number;\n    /** Max inbound WebSocket message size (bytes) when `listen()`ing on Bun — frames over this are rejected\n     * by the runtime before reaching your handler (so a huge frame can't be JSON-parsed into memory).\n     * Default: `maxBodyBytes` (1 MB). */\n    readonly wsMaxPayloadBytes?: number;\n    /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */\n    readonly requestTimeoutMs?: number;\n    /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */\n    readonly gracefulSignals?: boolean;\n    /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */\n    readonly logger?: Logger;\n}"
   },
   {
     "name": "ServeStaticOptions",
@@ -5854,6 +5887,13 @@
     "signature": "export declare function tsTypeOf(schema: unknown, depth?: number): string;",
     "doc": "/**\n * Render a JSON Schema as a compact TypeScript-like type (`{ id: string, name?: string }`) — the\n * shape agents already think in, at a fraction of the raw JSON Schema's tokens (~70-80% smaller).\n * Anything the renderer doesn't model falls back to the raw JSON for that subtree, so the output\n * is always faithful, just not always minimal.\n */"
   },
+  {
+    "name": "TypeEntry",
+    "kind": "interface",
+    "package": "@nifrajs/cli",
+    "signature": "export interface TypeEntry {\n    readonly name: string;\n    readonly kind: \"interface\" | \"type\" | \"class\" | \"function\" | \"enum\" | \"const\";\n    readonly package: string;\n    /** The literal declaration text from the `.d.ts` — a clean signature, no implementation. */\n    readonly signature: string;\n    /** The declaration's JSDoc block, if any. */\n    readonly doc?: string;\n}",
+    "doc": "/**\n * `nifra_types` — the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`\n * (written into this package by `bun run gen:llms`): each entry's `signature` is the literal declaration\n * parsed from the package's BUILT `.d.ts` with the TS compiler — a clean signature, never prose, never\n * truncated. So an agent that needs the precise shape of a type (`RateLimitStore`, `RouteSchema`, a\n * function signature) gets the authoritative source here and never has to read a `.d.ts` file.\n *\n * Lookup by `name` is exact (case-insensitive); `query` keyword-scores over the name (heavy) + the\n * signature/doc body; no args → a per-package index of the available type names.\n */"
+  },
   {
     "name": "UI_EXTENSION_KEY",
     "kind": "const",
@@ -6260,6 +6300,13 @@
     "signature": "export declare function walkSource(cwd: string, visit: (rel: string, content: string) => void): Promise<void>;",
     "doc": "/** Walk the project's `.ts`/`.tsx` source (skipping deps/build/tests), calling `visit` per file.\n * Exported so `nifra doctor` ({@link ./doctor.ts}) scans the same source surface as `nifra check`. */"
   },
+  {
+    "name": "WarmWorker",
+    "kind": "class",
+    "package": "@nifrajs/cli",
+    "signature": "export declare class WarmWorker {\n    readonly fingerprint: string;\n    private readonly label;\n    private readonly proc;\n    private readonly pending;\n    private stdoutBuffer;\n    private stderrBuffer;\n    private nextId;\n    private closed;\n    constructor(child: \"mcp-run\" | \"mcp-render\", cwd: string, fingerprint: string, label: string);\n    stop(): void;\n    request(input: unknown, signal?: AbortSignal): Promise<string>;\n    private readStdout;\n    private readStderr;\n    private handleLine;\n}",
+    "doc": "/** A persistent `mcp-run`/`mcp-render` `--worker` subprocess: the backend/web app is loaded ONCE and\n * reused across newline-delimited `{ id, input }` requests, replying `{ id, output }`. The same machinery\n * powers both `nifra_run warm` and `nifra_render warm` — `child` selects which engine, `label` shapes the\n * cancellation message. The owning handler ({@link createWarmHandler}) fingerprints the source tree and\n * replaces the worker when a file changes, so warm reuse never serves a stale result. Exported for the\n * concurrency test that proves a single per-request cancel doesn't tear down the shared worker. */"
+  },
   {
     "name": "wasmImageBackend",
     "kind": "function",
@@ -6311,7 +6358,7 @@
     "name": "WebSocketHandler",
     "kind": "interface",
     "package": "@nifrajs/core",
-    "signature": "export interface WebSocketHandler<Data = unknown, Env = unknown, Schema extends StandardSchemaV1 | undefined = undefined> {\n    /**\n     * Cross-site WebSocket hijacking (CSWSH) guard — checked BEFORE `upgrade()`. A browser does not\n     * apply CORS to WebSocket handshakes and DOES send the page's cookies, so without an Origin check\n     * any site can open an authenticated socket to your app. Set this to lock the route to known\n     * origins: a string allow-list (exact `Origin` header match) or a predicate. A request whose\n     * `Origin` doesn't match (or is absent, for the allow-list form) is rejected with `403` before any\n     * per-connection work. Omit for no built-in check (same as today — then enforce it yourself in\n     * `upgrade()`). Non-browser clients can spoof `Origin`, so this is a browser-CSWSH defense, not\n     * authentication — pair it with auth in `upgrade()`.\n     */\n    allowedOrigins?: ReadonlyArray<string> | ((origin: string | null) => boolean);\n    /**\n     * Runs in the HTTP request context **before** the upgrade (and after {@link allowedOrigins}) — the\n     * place to authenticate or rate-limit. Return the initial per-connection `data` (→ `ws.data`), or a\n     * `Response` to **reject** the upgrade (the client never connects). Omit to accept with\n     * `data: undefined`. A thrown error rejects with a flat 500.\n     */\n    upgrade?(c: WebSocketContext<Env>): MaybePromise<Data | Response>;\n    /**\n     * Contract-first messages: a Standard Schema (`t`, zod, valibot, …) validating each **inbound** frame.\n     * Text frames are parsed as JSON first. When set, `message` receives the validated, typed value; a\n     * non-JSON or schema-invalid frame is routed to `onInvalidMessage` (or dropped if that's omitted).\n     */\n    messageSchema?: Schema;\n    open?(ws: NifraWebSocket<Data>): MaybePromise<void>;\n    message?(ws: NifraWebSocket<Data>, data: WsMessageInput<Schema>): MaybePromise<void>;\n    /** Inbound frame that failed JSON parse or `messageSchema` validation (only fires when a schema is\n     * set). `raw` is the original frame; `issues` are the Standard Schema issues (one synthetic issue for\n     * a JSON parse failure). Omit to silently drop invalid frames. */\n    onInvalidMessage?(ws: NifraWebSocket<Data>, issues: ReadonlyArray<StandardIssue>, raw: WebSocketData): MaybePromise<void>;\n    close?(ws: NifraWebSocket<Data>, code: number, reason: string): MaybePromise<void>;\n    error?(ws: NifraWebSocket<Data>, error: unknown): MaybePromise<void>;\n}",
+    "signature": "export interface WebSocketHandler<Data = unknown, Env = unknown, Schema extends StandardSchemaV1 | undefined = undefined> {\n    /**\n     * Cross-site WebSocket hijacking (CSWSH) guard — checked BEFORE `upgrade()`. A browser does not\n     * apply CORS to WebSocket handshakes and DOES send the page's cookies, so without an Origin check\n     * any site can open an authenticated socket to your app. Set this to lock the route to known\n     * origins: a string allow-list (exact `Origin` header match) or a predicate. A request whose\n     * `Origin` doesn't match (or is absent, for the allow-list form) is rejected with `403` before any\n     * per-connection work.\n     *\n     * **When omitted, the default is same-origin:** a cross-origin BROWSER handshake (an `Origin` header\n     * whose host differs from the request's) is rejected with `403`. Non-browser clients (no `Origin`) and\n     * same-origin browsers pass. Set this to allow specific cross-origin clients, or `() => true` for a\n     * genuinely public socket. Non-browser clients can spoof `Origin`, so this is a browser-CSWSH defense,\n     * not authentication — pair it with auth in `upgrade()`.\n     */\n    allowedOrigins?: ReadonlyArray<string> | ((origin: string | null) => boolean);\n    /**\n     * Runs in the HTTP request context **before** the upgrade (and after {@link allowedOrigins}) — the\n     * place to authenticate or rate-limit. Return the initial per-connection `data` (→ `ws.data`), or a\n     * `Response` to **reject** the upgrade (the client never connects). Omit to accept with\n     * `data: undefined`. A thrown error rejects with a flat 500.\n     */\n    upgrade?(c: WebSocketContext<Env>): MaybePromise<Data | Response>;\n    /**\n     * Contract-first messages: a Standard Schema (`t`, zod, valibot, …) validating each **inbound** frame.\n     * Text frames are parsed as JSON first. When set, `message` receives the validated, typed value; a\n     * non-JSON or schema-invalid frame is routed to `onInvalidMessage` (or dropped if that's omitted).\n     */\n    messageSchema?: Schema;\n    open?(ws: NifraWebSocket<Data>): MaybePromise<void>;\n    message?(ws: NifraWebSocket<Data>, data: WsMessageInput<Schema>): MaybePromise<void>;\n    /** Inbound frame that failed JSON parse or `messageSchema` validation (only fires when a schema is\n     * set). `raw` is the original frame; `issues` are the Standard Schema issues (one synthetic issue for\n     * a JSON parse failure). Omit to silently drop invalid frames. */\n    onInvalidMessage?(ws: NifraWebSocket<Data>, issues: ReadonlyArray<StandardIssue>, raw: WebSocketData): MaybePromise<void>;\n    close?(ws: NifraWebSocket<Data>, code: number, reason: string): MaybePromise<void>;\n    error?(ws: NifraWebSocket<Data>, error: unknown): MaybePromise<void>;\n}",
     "doc": "/** A WebSocket route's lifecycle. All callbacks optional; only `message` is needed for an echo. */"
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The nifra CLI — zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -41,12 +41,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "1.0.0",
-    "@nifrajs/mcp": "1.0.0",
-    "@nifrajs/runner": "1.0.0",
-    "@nifrajs/schema": "1.0.0",
-    "@nifrajs/web": "1.0.0",
-    "create-nifra": "1.0.0"
+    "@nifrajs/client": "1.2.0",
+    "@nifrajs/mcp": "1.2.0",
+    "@nifrajs/runner": "1.2.0",
+    "@nifrajs/schema": "1.2.0",
+    "@nifrajs/web": "1.2.0",
+    "create-nifra": "1.2.0"
   },
   "repository": {
     "type": "git",

package/src/cli.ts

@@ -82,7 +82,7 @@ Port: \`dev\` and \`start\` share the default ${DEFAULT_DEV_PORT}. Override with
 \`PORT\` env var (\`--port\` wins over \`PORT\`, which wins over the default).`
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const CLI_VERSION = "1.0.0"
+const CLI_VERSION = "1.2.0"
 
 // A render adapter + nifra server are opaque to the CLI (it just forwards them); cast at the seam.
 const asAdapter = (v: unknown): RenderAdapter => v as RenderAdapter

package/src/mcp-http.ts

@@ -26,7 +26,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "1.0.0"
+const VERSION = "1.2.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 const DOCS_HEALTH =
   "nifra docs MCP — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call). Tools: nifra_docs, nifra_example."