@nifrajs/cli 1.0.0-beta.4 → 1.1.0

package/dist/types-search.js

@@ -0,0 +1,90 @@
+/**
+ * `nifra_types` — the EXACT TypeScript of every exported `@nifrajs/*` symbol. The corpus is `types.json`
+ * (written into this package by `bun run gen:llms`): each entry's `signature` is the literal declaration
+ * parsed from the package's BUILT `.d.ts` with the TS compiler — a clean signature, never prose, never
+ * truncated. So an agent that needs the precise shape of a type (`RateLimitStore`, `RouteSchema`, a
+ * function signature) gets the authoritative source here and never has to read a `.d.ts` file.
+ *
+ * Lookup by `name` is exact (case-insensitive); `query` keyword-scores over the name (heavy) + the
+ * signature/doc body; no args → a per-package index of the available type names.
+ */
+import { countBodyHits, queryTermGroups, tokenize, tokenSetHas } from "./search-terms.js";
+/** Exact (case-insensitive) name lookup — returns every declaration with that name (a name can exist in
+ * more than one package). */
+export function lookupType(types, name) {
+    const wanted = name.trim().toLowerCase();
+    return types.filter((t) => t.name.toLowerCase() === wanted);
+}
+/** Keyword-score types: a term in the name is worth far more than one in the signature/doc body. */
+export function searchTypes(types, query, limit) {
+    const terms = queryTermGroups(query);
+    if (terms.length === 0)
+        return [];
+    const scored = [];
+    for (const t of types) {
+        const nameTokens = new Set(tokenize(t.name));
+        const body = `${t.signature} ${t.doc ?? ""}`.toLowerCase();
+        let score = 0;
+        for (const term of terms) {
+            if (tokenSetHas(nameTokens, term))
+                score += 8;
+            score += countBodyHits(body, term, 4);
+        }
+        if (score > 0)
+            scored.push({ ...t, score });
+    }
+    return scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}
+function renderEntry(t) {
+    const head = `## ${t.name} — ${t.kind}, \`${t.package}\``;
+    const doc = t.doc ? `${t.doc}\n` : "";
+    return `${head}\n\n\`\`\`ts\n${doc}${t.signature}\n\`\`\``;
+}
+/**
+ * Render the tool result. `name` → the exact declaration(s); else `query` → the top matches; else a
+ * per-package index of type names. The signatures are authoritative (generated from the built `.d.ts`),
+ * so this is the complete answer — there is no need to read a `.d.ts` file.
+ */
+export function renderTypesResult(types, name, query, limit) {
+    if (name !== undefined && name.trim() !== "") {
+        const hits = lookupType(types, name);
+        if (hits.length === 0) {
+            return `No exported type named ${JSON.stringify(name)} in @nifrajs/*. Call nifra_types with a \`query\` (e.g. "rate limit") or no args for the per-package index of names.`;
+        }
+        return hits.map(renderEntry).join("\n\n---\n\n");
+    }
+    if (query !== undefined && query.trim() !== "") {
+        const matches = searchTypes(types, query, limit);
+        if (matches.length === 0) {
+            return `No types matched ${JSON.stringify(query)}. Try a broader term, pass an exact \`name\`, or call with no args for the index.`;
+        }
+        return matches.map(renderEntry).join("\n\n---\n\n");
+    }
+    const byPkg = new Map();
+    for (const t of types) {
+        const list = byPkg.get(t.package) ?? [];
+        list.push(t.name);
+        byPkg.set(t.package, list);
+    }
+    const index = [...byPkg.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([pkg, names]) => `- **${pkg}**: ${names.sort().join(", ")}`)
+        .join("\n");
+    return `# nifra types — index (${types.length} exported symbols; pass \`name\` for the exact declaration, or \`query\` to search)\n\nSignatures are generated from the built \`.d.ts\` — authoritative + complete. Use this instead of reading any \`.d.ts\` file.\n\n${index}`;
+}
+/** Load the bundled type corpus (`docs/types.json`), resolved relative to this module so it works from
+ * `src/` (dev) and `dist/` (published) alike. */
+export async function loadTypesCorpus() {
+    const url = new URL("../docs/types.json", import.meta.url);
+    try {
+        const text = await Bun.file(url).text();
+        if (text.length === 0)
+            return undefined;
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) && parsed.length > 0 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=types-search.js.map

package/dist/types-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-search.js","sourceRoot":"","sources":["../src/types-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAgBzF;6BAC6B;AAC7B,MAAM,UAAU,UAAU,CAAC,KAA2B,EAAE,IAAY;IAClE,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACxC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,CAAA;AAC7D,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,WAAW,CACzB,KAA2B,EAC3B,KAAa,EACb,KAAa;IAEb,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,CAAA;IACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACjC,MAAM,MAAM,GAAiB,EAAE,CAAA;IAC/B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,WAAW,EAAE,CAAA;QAC1D,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,WAAW,CAAC,UAAU,EAAE,IAAI,CAAC;gBAAE,KAAK,IAAI,CAAC,CAAA;YAC7C,KAAK,IAAI,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QACvC,CAAC;QACD,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAA;AACjG,CAAC;AAED,SAAS,WAAW,CAAC,CAAY;IAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,IAAI,CAAA;IACzD,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACrC,OAAO,GAAG,IAAI,iBAAiB,GAAG,GAAG,CAAC,CAAC,SAAS,UAAU,CAAA;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA2B,EAC3B,IAAwB,EACxB,KAAyB,EACzB,KAAa;IAEb,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QACpC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,sHAAsH,CAAA;QAC7K,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IAClD,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;QAChD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mFAAmF,CAAA;QACrI,CAAC;QACD,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;IACrD,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAA;IACzC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;QACvC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACjB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC5B,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;SAC/B,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,GAAG,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;SACjE,IAAI,CAAC,IAAI,CAAC,CAAA;IACb,OAAO,0BAA0B,KAAK,CAAC,MAAM,2NAA2N,KAAK,EAAE,CAAA;AACjR,CAAC;AAED;iDACiD;AACjD,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC1D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAA;QACvC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAA;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAgB,CAAA;QAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}

package/docs/examples.json

@@ -159,7 +159,7 @@
     "name": "IDENTITY",
     "topic": "Nifra — Plugins & middleware",
     "slug": "plugins",
-    "code": "import { defineIdentityPlugin, server } from \"@nifrajs/core\"\n\n// A plugin that registers routes/hooks but adds NO context type is a type-IDENTITY plugin.\n// defineIdentityPlugin keeps app.use()'s return type EXACTLY the caller's server, so routes added\n// after .use() keep their types — and the typed client derived from them stays intact.\nexport const audit = defineIdentityPlugin(\"audit\", (app) =>\n  app.onResponse((res) => res),\n)\n\n// /a AND /b stay fully typed across the .use():\nconst api = server().get(\"/a\", () => ({ a: 1 })).use(audit).get(\"/b\", () => ({ b: 2 }))"
+    "code": "import { defineRouterPlugin, server } from \"@nifrajs/core\"\n\n// A plugin that mounts routes/hooks but adds NO context type: defineRouterPlugin (the clearer name for\n// defineIdentityPlugin) keeps app.use()'s return type EXACTLY the caller's server, so routes added after\n// .use() stay typed — and the typed client derived from them stays intact.\nexport const scim = defineRouterPlugin(\"scim\", (app) => {\n  app.get(\"/scim/v2/Users\", () => ({ Resources: [] })) // mount as a SIDE EFFECT (a runtime-only route)\n  return app                                           // return the app unchanged → caller's registry preserved\n})\n\n// /a AND /b stay fully typed across the .use():\nconst api = server().get(\"/a\", () => ({ a: 1 })).use(scim).get(\"/b\", () => ({ b: 2 }))"
   },
   {
     "name": "JWT_BASIC",

package/docs/llms-full.txt

@@ -404,6 +404,19 @@ return makes the typed client infer `data: never`, so you silently lose drift
 detection for that route (`nifra check` flags it). `c.set` keeps your
 plain-object return fully typed.
 
+When you genuinely want a `Response` — an **error short-circuit** from a
+`derive` / `beforeHandle` (auth, rate limits) — `c.json(body, status?)`
+and `c.text(body, status?)` build one in a line:
+`throw c.json({ error: "unauthorized" }, 401)` instead of
+`new Response(JSON.stringify(…), { status: 401, headers: … })`. The second arg is a
+status number or a full `ResponseInit`, and both work whether you `return` or
+`throw` them. (In a route's happy path keep returning a plain object, as above, so the
+typed client stays in sync.)
+
+The request is on `c.req`, also available as `c.request` — the same name a
+page loader/action receives (which in turn also accepts `ctx.req`), so one name works
+in both places.
+
 ### Contract-first (defineContract + implement)
 
 For larger apps — or when the contract is shared across services — declare it with
@@ -1174,29 +1187,37 @@ app
 app.use((a) => a.decorate("db", db).derive((c) => ({ now: Date.now() })))
 ```
 
-### Route/hook plugins: keep types with defineIdentityPlugin
+### Route/hook plugins: keep types with defineRouterPlugin
 
 A plugin that registers routes or hooks but adds **no context type** — e.g. mounting an auth
-handler — should be built with `defineIdentityPlugin`, not `definePlugin`.
-It threads the app's _exact_ type through `use`, so the route registry (and the
-typed client derived from it) survives the plugin. A plain
-`definePlugin((app) => app)` infers `app` as
-`Server`, which collapses `use()`'s result — and your whole
-typed client — to `any`. `@nifrajs/better-auth` is built this way, so
+router — should be built with `defineRouterPlugin` (the clearer-named alias of
+`defineIdentityPlugin`), not `definePlugin`. It threads the app's
+_exact_ type through `use`, so the route registry (and the typed client derived
+from it) survives the plugin. Mount routes as a **side effect** then `return app`
+(registering with `.get`/`.post` directly would change the type away from the
+identity, so those routes run but aren't in the typed registry — the trade that keeps everything
+else typed).
+
+**Footgun:** reach for `definePlugin` here instead and a plain
+`definePlugin((app) => app.get(...))` infers `app` as
+`Server`, collapsing `use()`'s result — and your whole typed
+client — to `any`, with **no type error and no runtime error**.
+`@nifrajs/better-auth` is built with the identity form, so
 `server().use(betterAuth(auth)).get(...)` keeps every route typed.
 
 ```ts
-import { defineIdentityPlugin, server } from "@nifrajs/core"
+import { defineRouterPlugin, server } from "@nifrajs/core"
 
-// A plugin that registers routes/hooks but adds NO context type is a type-IDENTITY plugin.
-// defineIdentityPlugin keeps app.use()'s return type EXACTLY the caller's server, so routes added
-// after .use() keep their types — and the typed client derived from them stays intact.
-export const audit = defineIdentityPlugin("audit", (app) =>
-  app.onResponse((res) => res),
-)
+// A plugin that mounts routes/hooks but adds NO context type: defineRouterPlugin (the clearer name for
+// defineIdentityPlugin) keeps app.use()'s return type EXACTLY the caller's server, so routes added after
+// .use() stay typed — and the typed client derived from them stays intact.
+export const scim = defineRouterPlugin("scim", (app) => {
+  app.get("/scim/v2/Users", () => ({ Resources: [] })) // mount as a SIDE EFFECT (a runtime-only route)
+  return app                                           // return the app unchanged → caller's registry preserved
+})
 
 // /a AND /b stay fully typed across the .use():
-const api = server().get("/a", () => ({ a: 1 })).use(audit).get("/b", () => ({ b: 2 }))
+const api = server().get("/a", () => ({ a: 1 })).use(scim).get("/b", () => ({ b: 2 }))
 ```
 
 ### Lifecycle hooks
@@ -3030,6 +3051,42 @@ Vue, Solid, Svelte). Nifra dedupes the active adapter's runtime in build and dev
 [Dev & HMR](/docs/dev) and the `file:`-linked-package note in
 `AGENTS.md`.
 
+###
+`client` resolves to `never` (or `data: never`)
+
+The typed client is derived from your backend's type. Two things collapse it:
+
+-
+**
+A route returns a raw `Response`.
+**
+That route's `data` infers `never` (Nifra can't see the shape). Return a
+plain object and shape the response with `c.set` — reach for `c.json` /
+`c.text` only for an error short-circuit (`throw` from a
+`derive` / `beforeHandle`), not a route's happy path. See
+[API & typed client](/docs/api).
+
+-
+**A plugin widened the app's type.** A plugin that registers routes/hooks but whose return
+type isn't the concrete server (e.g. an untyped `app => app.onResponse(…)`)
+makes `.use()` return `Server` and the client loses your
+registry. Build it with `defineRouterPlugin(name, …)` (the clearer-named
+`defineIdentityPlugin`) so `.use()` returns your server unchanged and
+routes added after it stay typed. See
+[Plugins → keep types with defineRouterPlugin](/docs/plugins).
+
+`nifra check` flags the raw-`Response` case; the plugin case surfaces as a
+`never` client at the call site.
+
+####
+Call site rejects `{ query: {…} }`
+
+If `api.thing.get({ query: { … } })` errors, the route declares no
+`query` schema — its query types as `never`, so the client can't accept query
+params. The error reads out the fix; add a schema to the route:
+`.get("/thing", { query: z.object({ page: z.string() }) }, h)`. Then
+`c.query` is the validated type and the client accepts a typed `query`.
+
 ### Still stuck?
 
 Run `nifra check --json` as the done-gate — it surfaces the import-chain leaks,
@@ -4354,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`,
@@ -4885,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
@@ -5201,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.
@@ -5533,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`
@@ -5543,7 +5821,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/core
 
-`AnyServer`, `attachWebSocket`, `commonSecretPatterns`, `Context`, `ContextForOp`, `ContractShape`, `CookieOptions`, `defineContract`, `defineIdentityPlugin`, `definePlugin`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FRAMEWORK_NAME`, `FrameworkError`, `FrameworkName`, `Handler`, `HandlersFor`, `IdentityPlugin`, `implement`, `InferInput`, `InferOutput`, `jsonLogger`, `LogFields`, `Logger`, `Method`, `METHODS`, `Middleware`, `NifraPlugin`, `NifraWebSocket`, `NodeServeOutcome`, `OnRequestResult`, `OperationDef`, `Params`, `parseCookies`, `Platform`, `Prettify`, `redactLogFields`, `RedactOptions`, `Registry`, `RegistryFor`, `RegistryFromImpl`, `ResponseControls`, `ResponseDef`, `robots`, `RobotsOptions`, `RobotsRule`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `Router`, `RouterMatch`, `RouteSchema`, `RunningServer`, `ScheduledController`, `ScheduledHandler`, `serializeCookie`, `server`, `Server`, `ServerOptions`, `SignatureEncoding`, `signValue`, `silentLogger`, `sitemap`, `SitemapChangeFreq`, `SitemapEntry`, `SitemapOptions`, `sse`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `toFetchHandler`, `TopicRegistry`, `unsignValue`, `validateStandard`, `ValidationOutcome`, `verifyWebhook`, `VerifyWebhookOptions`, `Version`, `VERSION`, `WebhookFailureReason`, `WebhookProvider`, `WebhookResult`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`
+`AnyServer`, `attachWebSocket`, `commonSecretPatterns`, `Context`, `ContextForOp`, `ContractShape`, `CookieOptions`, `defineContract`, `defineIdentityPlugin`, `definePlugin`, `defineRouterPlugin`, `DurableObjectNamespaceLike`, `ExecutionContext`, `FRAMEWORK_NAME`, `FrameworkError`, `FrameworkName`, `Handler`, `HandlersFor`, `IdentityPlugin`, `implement`, `InferInput`, `InferOutput`, `jsonLogger`, `LogFields`, `Logger`, `Method`, `METHODS`, `Middleware`, `NifraPlugin`, `NifraWebSocket`, `NodeServeOutcome`, `OnRequestResult`, `OperationDef`, `Params`, `parseCookies`, `Platform`, `Prettify`, `redactLogFields`, `RedactOptions`, `Registry`, `RegistryFor`, `RegistryFromImpl`, `ResponseControls`, `ResponseDef`, `robots`, `RobotsOptions`, `RobotsRule`, `RouteConfigError`, `RouteConfigErrorCode`, `RouteDescriptor`, `RouteInfo`, `Router`, `RouterMatch`, `RouteSchema`, `RunningServer`, `ScheduledController`, `ScheduledHandler`, `serializeCookie`, `server`, `Server`, `ServerOptions`, `SignatureEncoding`, `signValue`, `silentLogger`, `sitemap`, `SitemapChangeFreq`, `SitemapEntry`, `SitemapOptions`, `sse`, `SSEContext`, `SSEInit`, `SSEMessage`, `SSEStream`, `StandardIssue`, `StandardResult`, `StandardSchemaV1`, `StandardTypes`, `StandardWebSocket`, `toFetchHandler`, `TopicRegistry`, `unsignValue`, `validateStandard`, `ValidationOutcome`, `verifyWebhook`, `VerifyWebhookOptions`, `Version`, `VERSION`, `WebhookFailureReason`, `WebhookProvider`, `WebhookResult`, `WebSocketContext`, `WebSocketData`, `WebSocketHandler`, `WebSocketUpgradeOutcome`
 
 ## @nifrajs/cron
 
@@ -5569,6 +5847,14 @@ 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`
+
 ## @nifrajs/middleware
 
 `apiKey`, `ApiKeyStaticOptions`, `ApiKeyVerifyOptions`, `appendTrailingSlash`, `AuthPlugin`, `basicAuth`, `BasicAuthPlugin`, `BasicAuthStaticOptions`, `BasicAuthVerifyOptions`, `bearer`, `BearerOptions`, `bodyLimit`, `BodyLimitOptions`, `buildOpenApiDocument`, `cache`, `cacheControl`, `CacheControlOptions`, `CachedResponse`, `CacheOptions`, `combine`, `Composable`, `compression`, `CompressionOptions`, `cors`, `CorsOptions`, `createCsrfToken`, `csrf`, `CsrfOptions`, `etag`, `ETagOptions`, `healthcheck`, `HealthcheckOptions`, `idempotency`, `IdempotencyClaim`, `IdempotencyOptions`, `IdempotencyRecord`, `IdempotencyStore`, `IpMatcher`, `ipRestriction`, `IpRestrictionOptions`, `jwk`, `JwkKey`, `jwks`, `JwksOptions`, `jwt`, `JwtAlgorithm`, `JwtClaims`, `JwtHeader`, `JwtKeyResolver`, `JwtOptions`, `JwtPlugin`, `JwtVerificationKey`, `language`, `LanguageMatch`, `LanguageOptions`, `logger`, `LoggerOptions`, `MemoryIdempotencyStore`, `MemoryIdempotencyStoreOptions`, `MemoryResponseCache`, `MemoryResponseCacheOptions`, `MemoryStore`, `MemoryStoreOptions`, `methodOverride`, `MethodOverrideOptions`, `namedCombine`, `openapi`, `OpenApiInfo`, `OpenApiOptions`, `OpenApiServer`, `OpenApiTag`, `OpenApiUiOptions`, `pickLanguage`, `poweredBy`, `PoweredByOptions`, `prettyJson`, `PrettyJsonOptions`, `rateLimit`, `RateLimitOptions`, `RateLimitResult`, `RateLimitStore`, `requestId`, `RequestIdOptions`, `RequestLogFields`, `responseCache`, `ResponseCacheStore`, `RouteLike`, `securityHeaders`, `SecurityHeadersOptions`, `SecurityRequirement`, `timing`, `TimingControls`, `TimingMetric`, `TimingOptions`, `TrailingSlashOptions`, `trimTrailingSlash`, `tryVerifyJwt`, `VerifiedJwt`, `verifyCsrfToken`, `verifyJwt`, `VerifyJwtOptions`, `VerifyJwtResult`
@@ -5587,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
 
@@ -5595,7 +5889,7 @@ done-gate, or `nifra mcp` to give the agent live project tools.
 
 ## @nifrajs/web
 
-`Action`, `ACTION_GLOBAL`, `apiKey`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumeratePrerenderedPaths`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `GetStaticPaths`, `hashQueryKey`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `Submission`, `SubmitOptions`, `withISR`
+`Action`, `ACTION_GLOBAL`, `apiKey`, `buildManifest`, `CachedResponse`, `CacheStore`, `canonical`, `clientEntry`, `ClientRouter`, `ClientRouterOptions`, `createClientRouter`, `createMatcher`, `createQueryClient`, `createWebApp`, `CreateWebAppOptions`, `DATA_GLOBAL`, `DATA_HEADER`, `DEFAULT_DEV_PORT`, `defer`, `Deferred`, `disableDraft`, `DRAFT_COOKIE`, `DraftCookieControls`, `enableDraft`, `EnableDraftOptions`, `enumeratePrerenderedPaths`, `enumerateStaticRoutes`, `Fetcher`, `FetcherState`, `FetchRouteData`, `filePathToPattern`, `filePathToPatterns`, `FontDisplay`, `fontFace`, `FontFace`, `fontPreload`, `FontPreloadInput`, `FontSource`, `generateClientEntry`, `GenerateClientEntryOptions`, `generateServerManifest`, `GenerateServerManifestOptions`, `GetStaticPaths`, `hashQueryKey`, `isDraftEnabled`, `ISR_REVALIDATE_HEADER`, `ISR_STATUS_HEADER`, `ISRApp`, `ISROptions`, `ISRPlatform`, `jsonLd`, `KVCacheStore`, `KVCacheStoreOptions`, `KVNamespaceLike`, `LayoutEntry`, `LinkDescriptor`, `Loader`, `LoaderContext`, `manifest`, `Manifest`, `MemoryCacheStore`, `MemoryCacheStoreOptions`, `mergeHeads`, `meta`, `Meta`, `MetaArgs`, `MetaInput`, `MountRouterOptions`, `openGraph`, `OpenGraphInput`, `PRE_HYDRATION_GUARD`, `QueryClient`, `QueryClientOptions`, `QueryHandle`, `QueryState`, `QueryStatus`, `redirect`, `REDIRECT_HEADER`, `RedirectOptions`, `RenderAdapter`, `RenderedPage`, `renderPage`, `RenderPageOptions`, `renderPageResult`, `RenderProps`, `resolveMeta`, `revalidate`, `REVALIDATE_HEADER`, `revalidateEndpoint`, `RevalidateEndpointOptions`, `RevalidateResult`, `ROUTE_GLOBAL`, `RouteEntry`, `RouteMatch`, `RouteModule`, `RoutePattern`, `RouterState`, `routeStyles`, `ScriptDescriptor`, `serializeData`, `ServerOnly`, `StaticPath`, `StaticPaths`, `StaticRoutes`, `styles`, `Submission`, `SubmitOptions`, `withISR`
 
 ## @nifrajs/web-preact