@nifrajs/cli 2.8.0 → 2.8.2

package/dist/scaffold.js

@@ -8,7 +8,7 @@
  * for vue/svelte/vanilla we return the correct PATH + the route-module contract and point at
  * `nifra_example` for the body, rather than hand-writing an SFC we can't typecheck here.
  */
-import { mkdir, writeFile } from "node:fs/promises";
+import { lstat, mkdir, realpath, writeFile } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
 const EXT = {
     react: "tsx",
@@ -100,6 +100,37 @@ function resolveInsideCwd(cwd, relativeFile) {
     }
     return target;
 }
+/** Lexical containment is not enough when an existing route directory is a symlink. Check every
+ * existing ancestor and its real path before scaffolding so an agent cannot redirect a write outside
+ * the selected project. The target itself is created with `wx`, so an existing target symlink is also
+ * never followed/overwritten. */
+async function assertNoSymlinkedAncestors(root, target) {
+    const rootPath = resolve(root);
+    const realRoot = await realpath(rootPath);
+    let current = dirname(target);
+    while (current !== rootPath) {
+        if (!current.startsWith(`${rootPath}${sep}`)) {
+            throw new Error(`refusing to write outside project root: ${target}`);
+        }
+        try {
+            if ((await lstat(current)).isSymbolicLink()) {
+                throw new Error(`refusing to write through symlinked directory: ${current}`);
+            }
+            const actual = await realpath(current);
+            if (actual !== realRoot && !actual.startsWith(`${realRoot}${sep}`)) {
+                throw new Error(`refusing to write outside project root through: ${current}`);
+            }
+        }
+        catch (err) {
+            if (err && typeof err === "object" && err.code === "ENOENT") {
+                current = dirname(current);
+                continue;
+            }
+            throw err;
+        }
+        current = dirname(current);
+    }
+}
 /** Write a scaffolded route stub when the framework has a verified ready-to-write body. The write is
  * intentionally conservative: it refuses non-JSX stubs (where we only return contract guidance) and
  * uses `wx`, so an agent cannot overwrite user work by accident. */
@@ -113,7 +144,9 @@ export async function writeScaffoldRoute(cwd, urlPath, framework) {
         };
     }
     const target = resolveInsideCwd(cwd, result.file);
+    await assertNoSymlinkedAncestors(cwd, target);
     await mkdir(dirname(target), { recursive: true });
+    await assertNoSymlinkedAncestors(cwd, target);
     try {
         await writeFile(target, result.content, { flag: "wx" });
     }

package/dist/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/docs/examples.json

@@ -105,7 +105,7 @@
     "name": "DUAL_API",
     "topic": "Nifra - Framework contract",
     "slug": "contract",
-    "code": "// TWO ways to handle a request - pick by who is calling.\nimport type { LoaderContext } from \"@nifrajs/web\"\n\n// (1) A page's own data + mutations → route exports. A PUBLIC POST is a route ACTION\n//     (routes/contact.tsx) - the browser POSTs the route's own URL, nifra runs `action`:\nexport async function action(ctx: LoaderContext) {\n  const form = await ctx.request.formData()        // the browser POSTed this route\n  return { ok: true, body: String(form.get(\"body\")) } // → props.actionData on re-render\n}\n\n// (2) ctx.api is the IN-PROCESS backend client (the inProcessClient(server) the app was given).\n//     It is LOADERS-ONLY: the SSR backend registers GET handlers, so a .post() to ctx.api 405s.\nexport async function loader(ctx: LoaderContext) {\n  // ✅ a GET in-process - no HTTP hop. (A .post() to ctx.api would 405; write an `action` instead.)\n  return { id: ctx.params.id }\n}\n\n// Rule of thumb: data INTO a page → loader + ctx.api (GET). A mutation FROM the browser\n// (a form/fetch POST) → an `action` export on the route. Don't `inProcessClient(api).post()`."
+    "code": "// TWO ways to handle a request - pick by who is calling.\nimport type { LoaderContext } from \"@nifrajs/web\"\n\n// (1) A page's own data + mutations → route exports. A PUBLIC POST is a route ACTION\n//     (routes/contact.tsx) - the browser POSTs the route's own URL, Nifra runs `action`:\nexport async function action(ctx: LoaderContext) {\n  const form = await ctx.request.formData()        // the browser POSTed this route\n  return { ok: true, body: String(form.get(\"body\")) } // → props.actionData on re-render\n}\n\n// (2) ctx.api is the IN-PROCESS backend client (the inProcessClient(server) the app was given).\n//     It is LOADERS-ONLY: the SSR backend registers GET handlers, so a .post() to ctx.api 405s.\nexport async function loader(ctx: LoaderContext) {\n  // ✅ a GET in-process - no HTTP hop. (A .post() to ctx.api would 405; write an `action` instead.)\n  return { id: ctx.params.id }\n}\n\n// Rule of thumb: data INTO a page → loader + ctx.api (GET). A mutation FROM the browser\n// (a form/fetch POST) → an `action` export on the route. Don't `inProcessClient(api).post()`."
   },
   {
     "name": "INLINE_SCRIPT",
@@ -183,7 +183,7 @@
     "name": "VITE_PROD",
     "topic": "Nifra - Dev & HMR",
     "slug": "dev",
-    "code": "// vite.config.ts - a Vite/Rollup PRODUCTION client build (the escape hatch, not the default).\n// Only reach for this when an app needs a Vite-only transform with no Bun equivalent; nifra's default\n// production bundler stays Bun (buildClient), which is faster and Bun-native.\nimport { viteLeakGuard } from \"@nifrajs/web/plugins/vite-leak-guard\"\n\nexport default {\n  build: {\n    // The SAME two client-leak guards nifra's Bun build runs - server-only code or a node: builtin\n    // reaching the browser fails the build, with the identical error message. A second production\n    // pipeline must not ship without them.\n    rollupOptions: { plugins: [viteLeakGuard()] },\n  },\n}"
+    "code": "// vite.config.ts - a Vite/Rollup PRODUCTION client build (the escape hatch, not the default).\n// Only reach for this when an app needs a Vite-only transform with no Bun equivalent; Nifra's default\n// production bundler stays Bun (buildClient), which is faster and Bun-native.\nimport { viteLeakGuard } from \"@nifrajs/web/plugins/vite-leak-guard\"\n\nexport default {\n  build: {\n    // The SAME two client-leak guards Nifra's Bun build runs - server-only code or a node: builtin\n    // reaching the browser fails the build, with the identical error message. A second production\n    // pipeline must not ship without them.\n    rollupOptions: { plugins: [viteLeakGuard()] },\n  },\n}"
   },
   {
     "name": "LAB",
@@ -297,7 +297,7 @@
     "name": "SHAPING",
     "topic": "Nifra - Plugins & middleware",
     "slug": "plugins",
-    "code": "import { server } from \"@nifrajs/core/server\"\nimport { methodOverride, trimTrailingSlash, language, timing, poweredBy, combine } from \"@nifrajs/middleware\"\n\nconst app = server()\n  .use(methodOverride())     // POST + X-HTTP-Method-Override → PUT/PATCH/DELETE (a real pre-routing request rewrite)\n  .use(trimTrailingSlash())  // canonicalize URLs: 308 redirect (or rewrite), same-origin only, conservative methods\n  .use(language({ supported: [\"en\", \"fr\"], defaultLanguage: \"en\" }))  // Accept-Language → c.language + Content-Language\n  .use(timing())             // Server-Timing header + typed c.timing marks/measures\n// poweredBy() is opt-in (nifra emits no X-Powered-By by default). combine(a, b, c) bundles several into one plugin."
+    "code": "import { server } from \"@nifrajs/core/server\"\nimport { methodOverride, trimTrailingSlash, language, timing, poweredBy, combine } from \"@nifrajs/middleware\"\n\nconst app = server()\n  .use(methodOverride())     // POST + X-HTTP-Method-Override → PUT/PATCH/DELETE (a real pre-routing request rewrite)\n  .use(trimTrailingSlash())  // canonicalize URLs: 308 redirect (or rewrite), same-origin only, conservative methods\n  .use(language({ supported: [\"en\", \"fr\"], defaultLanguage: \"en\" }))  // Accept-Language → c.language + Content-Language\n  .use(timing())             // Server-Timing header + typed c.timing marks/measures\n// poweredBy() is opt-in (Nifra emits no X-Powered-By by default). combine(a, b, c) bundles several into one plugin."
   },
   {
     "name": "BUILD",

package/docs/llms-full.txt

@@ -95,7 +95,7 @@ export default function Page(props: { data: LoaderData<typeof loader> }) {
 
 See the [benchmarks](/benchmarks) for how it performs.
 
-## Nifra vs. other frameworks
+## Nifra vs. other frameworks - the honest comparison
 
 > How Nifra compares to the full-stack frameworks (Next.js, Nuxt, SvelteKit, Remix, TanStack Start) - and, as a standalone backend, to Hono and Elysia. Five UI frameworks, five runtimes, end-to-end types, and an AI-agent toolchain no competitor ships.
 
@@ -193,8 +193,10 @@ regex), but a router is **~1% of a real request** - the time goes to middleware,
 context, and serialization. In the current matrix (median of 5 full runs) Nifra
 **tops the framework field on Bun** - level with Elysia on `GET /users/:id` at
 101% of the raw-runtime ceiling, 105% of Elysia on the validated `POST` - and
-**leads every framework on Deno** on both workloads. On **Node** it runs ahead of Elysia,
-Hono, and Express and within ~2% of Fastify. In the realistic shape (security headers + CORS +
+**leads every framework on Deno** on both workloads. On **Node** it
+**leads the framework field too** - ahead of Fastify by ~12% on the validated
+`POST` (96% of the raw-Node ceiling) and level-to-ahead on GET, with Elysia, Hono,
+and Express behind. In the realistic shape (security headers + CORS +
 bearer auth + cookies + validated query/body + a ~2.4 KB JSON response, measured with
 `oha`) Nifra runs at **103% of Elysia on GET and 108% on POST**. Treat benchmark
 rows as same-run evidence, not a permanent law of nature.
@@ -226,12 +228,22 @@ accurately:
 surface), `nifra_example` (snippets typechecked against the installed version - no
 hallucinated APIs), `nifra_scaffold` (URL → correct `routes/` file),
 `nifra_run` (verify via HTTP), and `nifra_check` (a drift gate that returns the
-fix).
+fix). One MCP, two transports: the docs tools are also hosted at `mcp.nifra.dev`
+(no checkout needed), while the project tools run only on your machine - your code never
+leaves it.
 
 -
 `llms.txt` + `llms-full.txt` served at the site root, an `AGENTS.md`
 in every scaffold, and a docs corpus that can't drift from the code.
 
+-
+`nifra assure` + `nifra levels` - a route-assurance gate: a policy file
+classifies every reflected route and CI fails naming exactly which evidence is missing
+(authentication on writes, validation, declared effects). Spectral lints the OpenAPI
+_document_ and Semgrep pattern-matches source text; neither sees the real route graph.
+This is what makes agent-written routes safe to merge - an agent (or a human) cannot ship an
+unauthenticated write past it.
+
 ### Where Nifra fits
 
 Reach for Nifra when you want:
@@ -748,7 +760,7 @@ export const addTodo = serverFn(
 )
 ```
 
-The second argument receives the validated input and the ordinary nifra `Context`:
+The second argument receives the validated input and the ordinary Nifra `Context`:
 `c.env`, `c.clientIp`, `c.budget`, cookies and the capability
 guard are all there, because this is a route.
 
@@ -1017,7 +1029,7 @@ const isr = withISR(app, { store, revalidate: 60, now: () => Date.now() })
 Bun.serve({ fetch: (req) => isr(req) })
 ```
 
-Set a route's freshness with `export const revalidate` (seconds) - nifra emits it as
+Set a route's freshness with `export const revalidate` (seconds) - Nifra emits it as
 the `x-nifra-isr-revalidate` header, which the wrapper reads to set that page's TTL.
 
 ```ts
@@ -1133,9 +1145,9 @@ route.
 
 ## Nifra - Hydration & pre-hydration forms
 
-> SSR pages become interactive after hydration. nifra keeps that gap safe: progressive-enhancement forms and links work before it, and a JS-only form's broken native submit is guarded automatically.
+> SSR pages become interactive after hydration. Nifra keeps that gap safe: progressive-enhancement forms and links work before it, and a JS-only form's broken native submit is guarded automatically.
 
-An SSR page is visible at once but interactive only after its island hydrates. nifra keeps
+An SSR page is visible at once but interactive only after its island hydrates. Nifra keeps
 that gap safe for you - you rarely have to think about it.
 
 ### Forms and links - nothing to do
@@ -1167,12 +1179,12 @@ async function onSubmit(e: FormEvent) {
 return <form onSubmit={onSubmit}>…</form>
 ```
 
-nifra blocks that native submit until hydration commits, so the worst case is a no-op click -
+Nifra blocks that native submit until hydration commits, so the worst case is a no-op click -
 never a broken navigation. It never touches a `method="post"` form or a GET form
 with a real action. Opt a form out with `data-native`:
 
 ```ts
-<form data-native>…</form>   {/* nifra won't guard it - native submit is intended */}
+<form data-native>…</form>   {/* Nifra won't guard it - native submit is intended */}
 ```
 
 ### Gate other JS on the signal
@@ -1385,9 +1397,9 @@ but the compiled frameworks use their native single-file format - **Svelte**
 package's Bun plugin (`@nifrajs/web-vue/plugin`, `@nifrajs/web-svelte/plugin`).
 
 ```ts
-<!-- routes/index.vue - a nifra route authored as a Vue Single-File Component -->
+<!-- routes/index.vue - a Nifra route authored as a Vue Single-File Component -->
 <script lang="ts">
-// The plain <script> carries nifra's route convention (server-only named exports):
+// The plain <script> carries Nifra's route convention (server-only named exports):
 export const meta = { title: "Home" }
 export async function loader({ api }) {
   const res = await api.count.get()
@@ -1396,7 +1408,7 @@ export async function loader({ api }) {
 </script>
 
 <script setup lang="ts">
-defineProps(["data"])          // nifra passes the loader data in as `data`
+defineProps(["data"])          // Nifra passes the loader data in as `data`
 </script>
 
 <template>
@@ -1757,7 +1769,7 @@ const app = server()
   .use(trimTrailingSlash())  // canonicalize URLs: 308 redirect (or rewrite), same-origin only, conservative methods
   .use(language({ supported: ["en", "fr"], defaultLanguage: "en" }))  // Accept-Language → c.language + Content-Language
   .use(timing())             // Server-Timing header + typed c.timing marks/measures
-// poweredBy() is opt-in (nifra emits no X-Powered-By by default). combine(a, b, c) bundles several into one plugin.
+// poweredBy() is opt-in (Nifra emits no X-Powered-By by default). combine(a, b, c) bundles several into one plugin.
 ```
 
 ### Security middleware
@@ -2244,7 +2256,7 @@ server function:
 
 On its own that is an assertion. What makes it load-bearing is the other half:
 `provenance.imports` maps a module specifier to the capabilities that reaching it
-implies, so nifra can compare what a route _says_ against what it _can do_.
+implies, so Nifra can compare what a route _says_ against what it _can do_.
 
 ```ts
 import { server } from "@nifrajs/core/server"
@@ -2491,7 +2503,7 @@ yourself. Nifra owns the _session_; you bring (or mount) the _who_.
 `@nifrajs/better-auth` bridges [Better Auth](https://better-auth.com) into
 nifra: `betterAuth(auth)` mounts its handler at `/api/auth/*` (GET + POST),
 so every endpoint - sign-in/up/out, OAuth callbacks, session, 2FA, magic links - is served by
-your nifra server. Read the session with `getSession(auth, request)` (typed
+your Nifra server. Read the session with `getSession(auth, request)` (typed
 `{ user, session } | null`) or guard a route with
 `requireSession(auth, request, options?)` (returns it, or throws a 401/redirect
 `Response`). It's declared **structurally** - no hard dependency on Better Auth, so
@@ -2572,7 +2584,7 @@ createWebApp({ /* … */ api: sessions })                  // inject the manager
 ### Guard a route
 
 `requireSession` / `requireUser` throw a `Response` (a 302 to
-`redirectTo`, or a 401) when the session is missing - nifra returns a thrown Response
+`redirectTo`, or a 401) when the session is missing - Nifra returns a thrown Response
 as-is, so the guard short-circuits the loader.
 
 ```ts
@@ -2583,7 +2595,7 @@ import { requireUser } from "@nifrajs/auth"   // browser-safe; OK to import in a
 export async function loader({ request, api }) {
   const sessions = api                       // the manager injected via createWebApp's `api`
   const session = await sessions.read(request)
-  // requireUser throws a 302 to /login when there's no session; nifra returns the thrown Response.
+  // requireUser throws a 302 to /login when there's no session; Nifra returns the thrown Response.
   const userId = requireUser(session, "userId", { redirectTo: "/login" })
   return { userId }
 }
@@ -2713,11 +2725,11 @@ const imgix: ImageLoader = ({ src, width, quality }) =>
   `https://my.imgix.net${src}?w=${width}&auto=format${quality ? `&q=${quality}` : ""}`
 ```
 
-### Self-hosting - nifra's own resize endpoint
+### Self-hosting - Nifra's own resize endpoint
 
 No CDN? `@nifrajs/image/server`'s `createImageHandler` is a self-hosted resize
 endpoint backed by `Bun.Image` (libjpeg-turbo / libspng / libwebp, decoded off-thread).
-Pair it with `selfHostedLoader` and nifra resizes your own images - no third party in the
+Pair it with `selfHostedLoader` and Nifra resizes your own images - no third party in the
 path.
 
 ```ts
@@ -2773,7 +2785,7 @@ decodes/resizes/encodes. Three official backends, all from `@nifrajs/image/backe
 
 -
 `sharpImageBackend(sharp)` - libvips for Node. You pass your `sharp` import
-(nifra keeps zero dependency on it, and you pin the version).
+(Nifra keeps zero dependency on it, and you pin the version).
 
 -
 `wasmImageBackend(codecs)` - pure-WASM decode/resize/encode you wire up (jSquash is
@@ -2787,7 +2799,7 @@ built in (it never decodes just to read dimensions).
 import { createImageHandler } from "@nifrajs/image/server"
 import { sharpImageBackend, wasmImageBackend } from "@nifrajs/image/backends"
 
-// Node - libvips via sharp. Pass your own import (nifra never depends on it):
+// Node - libvips via sharp. Pass your own import (Nifra never depends on it):
 import sharp from "sharp"
 createImageHandler({ backend: sharpImageBackend(sharp), root: "./public" })
 
@@ -3055,7 +3067,7 @@ export default toFetchHandler(app, {
 
 `app.ws(path, handler)` registers a WebSocket route. It mirrors
 `.get()`/`.post()` - chainable, with per-connection state typed
-through a generic - and runs on every runtime nifra serves: Bun, Deno, Node, and Cloudflare
+through a generic - and runs on every runtime Nifra serves: Bun, Deno, Node, and Cloudflare
 Workers.
 
 The WebSocket runtime ships as an opt-in plugin, so apps that never use it don’t bundle it.
@@ -3141,7 +3153,7 @@ escape hatch to the native socket
 Inbound frames arrive raw (`string | Uint8Array`) by default. Add a
 `messageSchema` - any
 [Standard Schema](https://standardschema.dev) (`t`, zod, valibot) - and
-nifra parses each frame as JSON, validates it, and hands `message` the typed
+Nifra parses each frame as JSON, validates it, and hands `message` the typed
 value; anything that fails goes to `onInvalidMessage` instead (so a malformed
 frame can never reach your handler).
 
@@ -3178,7 +3190,7 @@ Bun, Deno, and Node are long-lived processes, so this works directly on a single
 Across a load balancer, `app.publish` only reaches sockets on the same instance -
 bridge an external fan-out (Redis pub/sub, NATS, a queue) to broadcast across all of them. On
 **Cloudflare Workers**, a stateless isolate can’t broadcast across connections,
-so nifra ships a Durable Object hub: `createWebSocketHub(app)` holds the
+so Nifra ships a Durable Object hub: `createWebSocketHub(app)` holds the
 connections, and `toFetchHandler(app, { webSocketHub })` routes upgrades to it
 - then `ws.subscribe` / `app.publish` behave exactly as on Bun.
 
@@ -3434,7 +3446,7 @@ Deploy: `wrangler pages deploy dist` (Pages) or `wrangler deploy`
 `server.ts` to hand-write. (`create-nifra` scaffolds the conventions.)
 
 ```ts
-nifra dev      # true-HMR dev server (Vite middleware + nifra SSR) - http://localhost:4321
+nifra dev      # true-HMR dev server (Vite middleware + Nifra SSR) - http://localhost:4321
 nifra build    # full Bun deploy → dist/server.js + content-hashed dist/assets/ (default target: bun)
 nifra start    # run dist/server.js on Bun
 nifra build --target cf-pages  # also: node | deno | vercel | static; add --report for chunk sizes
@@ -3510,6 +3522,50 @@ Nifra ships an MCP server. It is not a documentation lookup bolted onto a framew
 can read the project, learn the real API, run actual requests against the backend it just
 edited, and finish with a report of what the change proved.
 
+### One MCP, two ways to connect
+
+There is one Nifra MCP. It reaches your agent over the two standard MCP transports, and which
+one you use is decided by a single question: **is the agent working inside a Nifra repo?**
+
+Local - `nifra mcp`
+
+Hosted - `mcp.nifra.dev`
+
+Transport
+stdio - the agent spawns it as a process
+HTTP - add one URL, nothing to install
+
+Runs
+on your machine, in your project
+on our infrastructure
+
+Sees
+your routes, schemas, and files - locally only, nothing leaves the machine
+only Nifra's published docs corpus - never your code
+
+Tools
+
+everything: project tools (`nifra_context`, `nifra_run`,
+`nifra_assure`, …) **plus** the docs tools
+
+docs tools only (`nifra_docs`, `nifra_example`,
+`nifra_types`, `nifra_learn`)
+
+Use when
+building or editing a Nifra app
+learning Nifra, or the client can't spawn processes (Claude.ai, ChatGPT)
+
+The project tools _must_ run where your code is - hosting them would mean uploading
+your source, which is exactly what this design refuses to do. And the local server does not
+proxy the hosted one for docs: the docs corpus ships inside the npm package, so the answers
+match **the Nifra version installed in your project**, work offline, and send nothing
+anywhere. This hosted-plus-local pairing is the same shape Supabase, Stripe, Sentry, and
+GitHub ship their MCP servers in, for the same reason: public knowledge can be hosted; tools
+that touch your own code and data run where that code lives.
+
+So: inside a Nifra repo, register the local server (it includes the docs tools - you never
+need both). Anywhere else, add the URL.
+
 ### Setup
 
 ```ts
@@ -3736,7 +3792,7 @@ const server = await createViteDevServer({
   routesDir,
   clientModule: "@nifrajs/web-react/client",
   plugins: [react()],                                // Vue: @vitejs/plugin-vue, Svelte: …, etc.
-  port: Number(Bun.env.PORT ?? 4321),                // nifra's default; --port / PORT override it
+  port: Number(Bun.env.PORT ?? 4321),                // Nifra's default; --port / PORT override it
   createApp: (clientEntry, importQuery) =>
     createWebApp({
       adapter: reactAdapter,
@@ -3906,13 +3962,13 @@ so `node:` builtins and `server-only` modules fail the build either way.
 
 ```ts
 // vite.config.ts - a Vite/Rollup PRODUCTION client build (the escape hatch, not the default).
-// Only reach for this when an app needs a Vite-only transform with no Bun equivalent; nifra's default
+// Only reach for this when an app needs a Vite-only transform with no Bun equivalent; Nifra's default
 // production bundler stays Bun (buildClient), which is faster and Bun-native.
 import { viteLeakGuard } from "@nifrajs/web/plugins/vite-leak-guard"
 
 export default {
   build: {
-    // The SAME two client-leak guards nifra's Bun build runs - server-only code or a node: builtin
+    // The SAME two client-leak guards Nifra's Bun build runs - server-only code or a node: builtin
     // reaching the browser fails the build, with the identical error message. A second production
     // pipeline must not ship without them.
     rollupOptions: { plugins: [viteLeakGuard()] },
@@ -4841,7 +4897,7 @@ call.
 import type { LoaderContext } from "@nifrajs/web"
 
 // (1) A page's own data + mutations → route exports. A PUBLIC POST is a route ACTION
-//     (routes/contact.tsx) - the browser POSTs the route's own URL, nifra runs `action`:
+//     (routes/contact.tsx) - the browser POSTs the route's own URL, Nifra runs `action`:
 export async function action(ctx: LoaderContext) {
   const form = await ctx.request.formData()        // the browser POSTed this route
   return { ok: true, body: String(form.get("body")) } // → props.actionData on re-render
@@ -5617,7 +5673,7 @@ await Bun.write("app/fonts.preloads.json", JSON.stringify(inter.preloads))
 Then wire the two outputs into your app:
 
 ```ts
-// app entry - bundled + content-hashed by nifra's CSS pipeline
+// app entry - bundled + content-hashed by Nifra's CSS pipeline
 import "./fonts.css"
 
 // root layout - preload the primary file (one less render-blocking round trip)
@@ -5686,6 +5742,102 @@ stylesheet can't redirect the download elsewhere - an SSRF gate), and caps each
 Filenames are derived only from validated tokens plus a content hash, so there's no path
 traversal.
 
+## Nifra - Integrations (Stripe, and any npm library)
+
+> Third-party libraries work in Nifra as-is - handlers are plain TypeScript. The Stripe recipe end-to-end: SDK calls in a route, constant-time webhook verification, and idempotent processing.
+
+The most important thing on this page: **you rarely need it**. A Nifra handler
+is plain TypeScript running on Bun, Node, Deno, or the edge - the npm ecosystem works
+as-is. Stripe, OpenAI, Resend, Drizzle, Prisma, AWS SDKs: import them and call them, the
+way their own documentation shows.
+
+### When you need nothing at all
+
+If a library is called from your code - an SDK, a database client, a date library - there is
+no integration step. It does not know or care that Nifra is serving the request. The one
+rule that still applies is Nifra's own: anything crossing a trust boundary (a request body,
+a webhook payload, a third-party response you act on) goes through a schema first.
+
+### The Stripe recipe
+
+Three parts, each already covered by something the framework ships.
+
+#### 1. Calling the SDK
+
+```ts
+// doc-check: skip - fragment: `env` and your price ids are your application's.
+import { server } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+import Stripe from "stripe"
+
+// The Stripe SDK, exactly as its own docs show it. No adapter, no wrapper, no plugin.
+const stripe = new Stripe(env.STRIPE_SECRET_KEY)
+
+export const billing = server().post(
+  "/api/checkout",
+  { body: t.object({ priceId: t.string({ minLength: 1 }) }) },
+  async (c) => {
+    const session = await stripe.checkout.sessions.create({
+      mode: "subscription",
+      line_items: [{ price: c.body.priceId, quantity: 1 }],
+      success_url: "https://app.example.com/billing?done=1",
+      cancel_url: "https://app.example.com/billing",
+    })
+    return { url: session.url }
+  },
+)
+```
+
+Ordinary route, ordinary SDK call. The body schema is doing real work: a checkout endpoint
+is a public POST, and `c.body.priceId` arrives validated and typed.
+
+#### 2. Receiving webhooks
+
+```ts
+// doc-check: skip - fragment: `app`, `env`, and `StripeEvent` are your application's.
+import { verifyWebhook } from "@nifrajs/core/webhook"
+
+app.post("/webhooks/stripe", async (c) => {
+  // Bounded raw-body read + constant-time HMAC check, BEFORE any parsing.
+  const r = await verifyWebhook(c.req, env.STRIPE_WEBHOOK_SECRET, { provider: "stripe" })
+  if (!r.ok) { c.set.status = 400; return { ok: false, error: r.reason } }
+
+  const event = StripeEvent.parse(JSON.parse(r.payload)) // validate at the trust boundary
+  // …fulfil the event…
+  return { ok: true }
+})
+```
+
+This is the part teams hand-roll incorrectly. `verifyWebhook` reads the raw body
+bounded (DoS guard), verifies the signature in constant time, checks the timestamp
+tolerance, and only then hands you the payload. Presets exist for Stripe and GitHub, and a
+generic header/encoding form covers any other provider - including key rotation via an
+array of secrets. Details in [security](/docs/security).
+
+#### 3. Processing exactly once
+
+```ts
+// doc-check: skip - fragment: `app` and `fulfil` are your application's.
+import { idempotency, MemoryIdempotencyStore } from "@nifrajs/middleware"
+
+// Stripe redelivers webhooks and clients retry checkouts. With the idempotency
+// middleware, a retried request with the same Idempotency-Key replays the FIRST
+// response - the side effect runs once. Use a shared store (Redis) in production.
+app.use(idempotency({ store: new MemoryIdempotencyStore() }))
+```
+
+Stripe redelivers; users double-click. The `idempotency` middleware replays the
+first response for a retried key instead of re-running the charge, and rejects a concurrent
+duplicate while the first is in flight.
+
+### When to write a plugin
+
+Reach for [a plugin](/docs/plugins) only when a library should participate in
+the framework itself: contribute typed context to every handler (`c.stripe`, a
+session, a tenant), mount routes of its own, or hook the request lifecycle. That is
+`definePlugin` - a few lines, typed end-to-end. For everything else, an import
+at the top of the file is the whole integration.
+
 ## Nifra 2.0 migration guide - upgrade from 1.x
 
 > Upgrade a Nifra 1.x application to 2.0: automated package and import moves, opt-in runtime plugins, client and web changes, external auth mounts, and release verification.
@@ -5700,7 +5852,7 @@ and import edits; this guide covers the structural changes it deliberately canno
 
 ```
 
-The command updates existing `@nifrajs/*`, `nifra`, and
+The command updates existing `@nifrajs/*`, `Nifra`, and
 `create-nifra` dependency ranges to `2.0.0` while preserving
 caret/tilde/exact style. It also replaces the removed `@nifrajs/budget` dependency
 with `@nifrajs/core` and moves its imports to
@@ -5723,7 +5875,7 @@ Only applications calling `app.resolveNode()` directly need to install it.
 
 ### 3. Use the lean package entry points
 
-The `@nifrajs/core` and `nifra` roots now expose the lean HTTP server
+The `@nifrajs/core` and `Nifra` roots now expose the lean HTTP server
 surface. Prefer `@nifrajs/core/server` for `server()`, and import
 contracts, assurance, capabilities, budgets, manifests, reflection, SSE, WebSockets, and
 other optional systems from their documented subpaths.
@@ -5877,7 +6029,7 @@ onto the route. The client then infers all of this for free.
 app.get("/users/:id", (req, res) => res.json({ id: req.params.id }))
 app.post("/users", express.json(), (req, res) => res.status(201).json(create(req.body)))
 
-// nifra - return the value (or a Response); c is Web-standard; the body is parsed + validated
+// Nifra - return the value (or a Response); c is Web-standard; the body is parsed + validated
 server()
   .get("/users/:id", (c) => ({ id: c.params.id }))
   .post("/users", { body: t.object({ name: t.string() }) }, (c) => create(c.body))
@@ -5893,7 +6045,7 @@ adds the typed client, schema validation, multi-runtime deploy, and (if you want
 // Hono
 app.get("/users/:id", (c) => c.json({ id: c.req.param("id") }))
 
-// nifra - nearly identical; params are a typed object, you return the value
+// Nifra - nearly identical; params are a typed object, you return the value
 server().get("/users/:id", (c) => ({ id: c.params.id }))
 ```
 
@@ -5975,7 +6127,7 @@ export default async function Page({ params }) {
   return <h1>{user.name}</h1>
 }
 
-// nifra - routes/users/[id].tsx
+// Nifra - routes/users/[id].tsx
 export async function loader({ params, api }: LoaderArgs<typeof backend>) {
   const res = await api.users({ id: params.id }).get()   // typed, in-process during SSR
   return { user: res.data }
@@ -5996,7 +6148,7 @@ example:
 // SvelteKit - +page.server.ts + +page.svelte
 export async function load({ params }) { return { post: await getPost(params.slug) } }
 
-// nifra - routes/blog/[slug].svelte (loader is a module export, page is the .svelte)
+// Nifra - routes/blog/[slug].svelte (loader is a module export, page is the .svelte)
 export async function loader({ params }) { return { post: await getPost(params.slug) } }
 ```
 
@@ -6007,7 +6159,7 @@ export async function loader({ params }) { return { post: await getPost(params.s
 app.
 
 -
-**Much faster SSR** - Nifra renders ~28× Next.js, ~7× Nuxt, ~4× SvelteKit/SolidStart on
+**Much faster SSR** - Nifra renders ~25× Next.js, ~7× Nuxt, ~4× SvelteKit/SolidStart on
 dynamic pages, with a fraction of the client JS. See [benchmarks](/benchmarks).
 
 -
@@ -6385,7 +6537,7 @@ export default defineAssuranceConfig({
 ```
 
 L4 requires an **explicit** executor. Invariant runs send deliberately hostile
-input, so nifra will not guess which app to point them at; a level that fuzzed your live
+input, so Nifra will not guess which app to point them at; a level that fuzzed your live
 server by default would be a footgun, and a skipped route is reported rather than passed over
 in silence.
 

package/docs/types.json

@@ -10821,14 +10821,14 @@
     "name": "VERSION",
     "kind": "const",
     "package": "@nifrajs/core",
-    "signature": "export declare const VERSION: \"2.8.0\";",
+    "signature": "export declare const VERSION: \"2.8.2\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {
     "name": "VERSION",
     "kind": "const",
     "package": "nifra",
-    "signature": "export declare const VERSION: \"2.8.0\";",
+    "signature": "export declare const VERSION: \"2.8.2\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {

package/package.json

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