create-nifra 2.1.0 → 2.3.0

package/dist/scaffold/site.js

@@ -0,0 +1,99 @@
+/**
+ * Compose a site scaffold: shared base, generated files, framework overlay.
+ *
+ * A site is 26 files. Thirteen are the same whatever you render with - the Dockerfile, every server
+ * entry, the worker, the assurance config - eight are mechanical enough to emit from a model, and five
+ * are genuinely the framework's own. Keeping five copies of all 26 is what let `.vercel` reach four
+ * tsconfigs and not the fifth, and a Vercel comment reach one build entry and not the other four.
+ *
+ * The five that stay literal stay literal on purpose. `nifra.config.ts` explains why Solid wants a
+ * `solid` resolve condition and what `@preact/preset-vite` is; the routes are the app a user reads
+ * first. That prose belongs in a file you can open, not in a TypeScript string.
+ */
+import { cp, mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { frameworkSpec } from "./frameworks.js";
+import { BUILD_TARGETS, renderBuildFile } from "./site-build.js";
+import { renderFrameworkModule, renderPackageJson, renderTsconfig } from "./site-files.js";
+/**
+ * Files identical in every site scaffold, taken from the base directory.
+ *
+ * Listed rather than globbed: a glob would silently absorb a file someone adds to the base for one
+ * framework's benefit, which is the failure this is meant to end. Adding a shared file means saying so
+ * here, and `site-composition.test.ts` fails if this list and the directory disagree.
+ */
+export const SHARED_SITE_FILES = [
+    ".dockerignore",
+    "Dockerfile",
+    "_worker.ts",
+    "backend.ts",
+    "counter.ts",
+    "deno.json",
+    "gitignore",
+    "nifra.assurance.ts",
+    "server-bun.ts",
+    "server-deno.ts",
+    "server-node.ts",
+    "server-vercel.ts",
+    "wrangler.toml",
+];
+/** Files each framework supplies itself, relative to its overlay directory. */
+export const FRAMEWORK_SITE_FILES = ["README.md", "nifra.config.ts"];
+/** Route files, whose extension is the framework's own. */
+export const ROUTE_BASENAMES = ["_404", "_layout", "index"];
+/** Extension the framework's route files carry. */
+export function routeExtension(framework) {
+    if (framework.id === "svelte")
+        return "svelte";
+    if (framework.id === "vue")
+        return "vue";
+    return "tsx";
+}
+const here = dirname(fileURLToPath(import.meta.url));
+/** The base directory: the shared files plus React's own, which is also the React overlay. */
+export const SITE_BASE_DIR = join(here, "..", "..", "template-site");
+export function overlayDir(framework) {
+    return framework.id === "react"
+        ? SITE_BASE_DIR
+        : join(here, "..", "..", `template-site-${framework.id}`);
+}
+/** Every file a site scaffold emits, and the text it holds. Generated files only. */
+export function generatedSiteFiles(framework) {
+    const files = new Map();
+    for (const target of BUILD_TARGETS)
+        files.set(target.file, renderBuildFile(target, framework));
+    files.set("framework.ts", renderFrameworkModule(framework));
+    files.set("package.json", renderPackageJson(framework));
+    files.set("tsconfig.json", renderTsconfig(framework));
+    return files;
+}
+/**
+ * Write a complete site scaffold into `target`.
+ *
+ * Refusing an occupied destination is the default and is preserved deliberately: `cp`'s
+ * `errorOnExist` did that before this was generated, and losing it would turn a mistyped path into
+ * silent data loss in someone's working directory. `--force` is what `bun create nifra .` needs.
+ */
+export async function materializeSite(target, id, options = {}) {
+    const framework = frameworkSpec(id);
+    const overlay = overlayDir(framework);
+    const force = options.force === true;
+    const copy = (from, to) => cp(from, to, force ? { force: true } : { errorOnExist: true, force: false });
+    // `wx` fails when the file exists, which is the write-side equivalent of `errorOnExist`.
+    const emit = (to, contents) => writeFile(to, contents, force ? {} : { flag: "wx" });
+    await mkdir(join(target, "routes"), { recursive: true });
+    for (const file of SHARED_SITE_FILES)
+        await copy(join(SITE_BASE_DIR, file), join(target, file));
+    for (const [file, contents] of generatedSiteFiles(framework)) {
+        await emit(join(target, file), contents);
+    }
+    for (const file of FRAMEWORK_SITE_FILES)
+        await copy(join(overlay, file), join(target, file));
+    const extension = routeExtension(framework);
+    for (const base of ROUTE_BASENAMES) {
+        const name = join("routes", `${base}.${extension}`);
+        await copy(join(overlay, name), join(target, name));
+    }
+}
+//# sourceMappingURL=site.js.map

package/dist/scaffold/site.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-nifra",
-  "version": "2.1.0",
-  "description": "Scaffold a new nifra app — `bun create nifra <dir>`.",
+  "version": "2.3.0",
+  "description": "Scaffold a new nifra app - `bun create nifra <dir>`.",
   "keywords": [
     "bun",
     "typescript",
@@ -29,6 +29,7 @@
   },
   "files": [
     "dist",
+    "src/agent-files.ts",
     "template",
     "template-site",
     "template-site-vue",

package/src/agent-files.ts

@@ -0,0 +1,149 @@
+/**
+ * The canonical generators for the agent-discovery files an app ships so a coding agent auto-discovers
+ * the project's nifra MCP server and prefers it over writing nifra from memory:
+ *
+ *   .mcp.json          - Claude Code's project MCP registry  ({ mcpServers: { nifra: { command, args } } })
+ *   .cursor/mcp.json   - Cursor's MCP registry (same server config)
+ *   CLAUDE.md          - Claude's preamble (use the MCP first; gate on `nifra check`) + `@AGENTS.md` import
+ *   AGENTS.md "MCP"    - a section for non-Claude agents pointing at the same server
+ *
+ * Single source of truth: both `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents`
+ * (retrofit an existing app) import these, so the four files can never drift apart. This module is
+ * dependency-free (pure string + object generation) on purpose - `create-nifra` ships with no runtime
+ * deps, and `@nifrajs/cli` imports it as a workspace dependency.
+ *
+ * Why `bunx @nifrajs/cli mcp` (not `bunx nifra mcp`): the `nifra` binary is provided by the
+ * `@nifrajs/cli` package. A scaffolded `site` app carries `@nifrajs/cli` as a devDependency, so either
+ * spelling would resolve `node_modules/.bin/nifra` locally - BUT the `api`/`isr` templates do NOT carry
+ * `@nifrajs/cli`, and the bare npm package literally named `nifra` (this monorepo's `@nifrajs/web` shim)
+ * exposes NO `nifra` bin. So `bunx nifra mcp` would fetch the wrong package and fail there. Naming the
+ * bin-owning package, `bunx @nifrajs/cli mcp`, resolves the locally-installed bin when present and
+ * otherwise fetches the package that actually provides the `nifra` command - robust across every
+ * template and for any existing app.
+ */
+
+import { readFileSync } from "node:fs"
+
+/** The MCP launch command, shared by `.mcp.json` and `.cursor/mcp.json`. See the module header for why
+ * the package is named explicitly rather than relying on the bare `nifra` bin. */
+export const MCP_SERVER_COMMAND = "bunx" as const
+
+/**
+ * The `@nifrajs/cli` version the launch command pins to - DERIVED at load time from this package's own
+ * `version`, never hardcoded. `fixed` changeset versioning ([["@nifrajs/*", "create-nifra", "nifra"]] in
+ * `.changeset/config.json`) bumps `create-nifra` and `@nifrajs/cli` in lockstep, so `create-nifra@x`
+ * always means `@nifrajs/cli@x`. Deriving it here means a release bump has nothing to forget to update -
+ * there is no stale literal to drift (the 1.0.0 cut shipped a beta pin exactly this way). `check:publish`
+ * still asserts it equals `@nifrajs/cli`'s version as a belt-and-suspenders guard on the `fixed` link.
+ *
+ * Resolves correctly under BOTH export conditions: the `bun` export runs `src/agent-files.ts`
+ * (`../package.json` → the package root) and the tsc `default` export runs `dist/agent-files.js`
+ * (`../package.json` → the same root, since `dist/` sits beside the manifest). npm always ships a
+ * package's own `package.json`, so the read can't miss at install time.
+ *
+ * Why pin at all instead of `bunx @nifrajs/cli mcp`: `bunx` keys its cache on the exact version spec.
+ * An UNPINNED spec resolves to the `latest` tag once, then `bunx` reuses that cached copy on every
+ * later spawn WITHOUT re-checking the registry - so an editor that once launched an older `@nifrajs/cli`
+ * keeps respawning the stale binary even after a newer one is published (the MCP server silently runs
+ * old code). Pinning the exact version makes the version part of the cache key, so each release fetches
+ * fresh and a stale cache can never shadow it. The cost: an already-scaffolded app's `.mcp.json` freezes
+ * at its scaffold-time version until `nifra init-agents` is re-run - an acceptable, deterministic trade.
+ */
+export const MCP_CLI_VERSION: string = (
+  JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+    version: string
+  }
+).version
+export const MCP_SERVER_ARGS = [`@nifrajs/cli@${MCP_CLI_VERSION}`, "mcp"] as const
+
+/** The server entry registered under the `nifra` key in both Claude Code's and Cursor's MCP config. */
+export interface McpServerConfig {
+  readonly command: string
+  readonly args: readonly string[]
+}
+
+/** Claude Code / Cursor MCP config shape: a map of server name → launch config. */
+export interface McpConfig {
+  readonly mcpServers: Readonly<Record<string, McpServerConfig>>
+}
+
+/** The one canonical MCP config object both registries serialize - the anti-drift seam. */
+export const MCP_CONFIG: McpConfig = {
+  mcpServers: {
+    nifra: { command: MCP_SERVER_COMMAND, args: [...MCP_SERVER_ARGS] },
+  },
+}
+
+/** Serialize the canonical MCP config as the JSON written to `.mcp.json` and `.cursor/mcp.json`.
+ * Trailing newline so the file is POSIX-clean and diffs don't flag a missing EOL. */
+export function mcpJson(): string {
+  return `${JSON.stringify(MCP_CONFIG, null, 2)}\n`
+}
+
+/**
+ * `CLAUDE.md` - Claude Code reads this automatically. It is deliberately NOT a copy of `AGENTS.md`:
+ * a short preamble that (1) tells Claude this project ships a nifra MCP, registered in `.mcp.json`, and
+ * to PREFER it, and (2) pulls in the full cookbook with Claude Code's `@file` import directive on its
+ * own line - `@AGENTS.md` - so the conventions live in exactly one place and can't drift between the
+ * two files. Keep this short; the depth is in `AGENTS.md`.
+ */
+export function claudeMd(): string {
+  return `# CLAUDE.md
+
+This project ships a **nifra MCP server**, registered for Claude Code in \`.mcp.json\` (it launches with
+\`${MCP_SERVER_COMMAND} ${MCP_SERVER_ARGS.join(" ")}\`). **Prefer the MCP tools** over writing nifra from memory - they are
+typechecked against *this* project and this installed version, so they beat training-data recall:
+
+- \`nifra_docs\` / \`nifra_example\` - exact signatures + verified, compiling snippets. Reach for these
+  before hand-writing a route, a loader, or a client call; a remembered API is often stale or wrong.
+- \`nifra_context\` - this project's route index + conventions, so changes fit the existing surface.
+- \`nifra_types\` - the EXACT TypeScript of any \`@nifrajs/*\` symbol (e.g. \`nifra_types({ name: "RateLimitStore" })\`).
+  Call it for a precise type; **never read \`node_modules/@nifrajs/**/*.d.ts\`** - the tool is the authoritative, complete source.
+- **\`nifra_check\` is the done-gate.** Before declaring any change complete, run \`nifra_check\` (or
+  \`nifra check --json\` in a terminal). It typechecks the frontend↔backend contract and flags drift
+  (hand-rolled \`fetch()\` to this app's own API, server-only imports in \`routes/\`). A failing check
+  means the work isn't done - fix it, don't ship around it.
+
+The full nifra cookbook for this app - backend rules, the typed never-throwing client, file routing, and
+the gotchas - lives in \`AGENTS.md\`, imported here so it stays the single source of truth:
+
+@AGENTS.md
+`
+}
+
+/**
+ * The "## MCP server" section appended to a scaffolded (or retrofitted) `AGENTS.md`, so non-Claude
+ * agents (Cursor, and anything that reads `AGENTS.md`) also learn the MCP exists and what to prefer.
+ * Mirrors the CLAUDE.md preamble's guidance without the Claude-specific `@import`.
+ */
+export function agentsMcpSection(): string {
+  return `## MCP server
+
+This project ships a **nifra MCP server** - launch it with \`${MCP_SERVER_COMMAND} ${MCP_SERVER_ARGS.join(" ")}\`. It's registered for
+Claude Code in \`.mcp.json\` and for Cursor in \`.cursor/mcp.json\`; other agents can point their MCP client
+at that command. **Prefer its tools** over writing nifra from memory - they're typechecked against this
+project + the installed version, so they beat training-data recall:
+
+- \`nifra_docs\` / \`nifra_example\` - exact signatures + verified, compiling snippets.
+- \`nifra_context\` / \`nifra_routes\` - this project's route index + per-route schemas.
+- \`nifra_types\` - the EXACT TypeScript of any \`@nifrajs/*\` symbol (interface/type/function). Call it for a
+  precise type; **never read \`@nifrajs\` \`.d.ts\` files** - this is the authoritative, complete source.
+- \`nifra_check\` - the done-gate (typecheck + drift lints). Run it before calling work complete; a
+  failing check means it isn't done. (\`nifra check --json\` in a terminal does the same.)`
+}
+
+/** Identifies a generated agent-discovery file: where it goes (relative to the project root) and how to
+ * produce its content. `merge` is for files that augment an existing one (AGENTS.md) rather than own it. */
+export interface AgentFileSpec {
+  /** Path relative to the project root (POSIX-style; the caller joins onto the cwd). */
+  readonly path: string
+  /** A human label for the "wrote/skipped" report. */
+  readonly label: string
+}
+
+/** The standalone files this module fully owns (whole-file generators). AGENTS.md is handled separately
+ * because create-nifra builds it from `agents.ts` and the retrofit command appends a section to it. */
+export const MCP_JSON_PATH = ".mcp.json"
+export const CURSOR_MCP_JSON_PATH = ".cursor/mcp.json"
+export const CLAUDE_MD_PATH = "CLAUDE.md"
+export const AGENTS_MD_PATH = "AGENTS.md"

package/template/README.md

@@ -9,9 +9,9 @@ bun test           # run the tests
 bun run typecheck  # type-check
 ```
 
-- `src/app.ts` — your routes (exported without `listen`, so tests drive it via `app.fetch`).
-- `src/index.ts` — boots the server.
-- `src/app.test.ts` — an example test.
+- `src/app.ts` - your routes (exported without `listen`, so tests drive it via `app.fetch`).
+- `src/index.ts` - boots the server.
+- `src/app.test.ts` - an example test.
 
 Add a typed client from `typeof app`:
 

package/template/nifra.assurance.ts

@@ -0,0 +1,80 @@
+/**
+ * What this app's routes are required to PROVE, checked by `nifra assure` (and level L1 of
+ * `nifra levels`). Evidence is collected from the routes themselves - a `body` schema records
+ * `body-bounded`, an auth middleware records `authenticated` - so this file states the requirement
+ * and the framework reports whether the route actually carries it.
+ *
+ * The starter rules below are deliberately small and true of THIS app. Grow them as the app grows:
+ * once there is auth, add `NIFRA_ASSURANCE.AUTHENTICATED` to `mutation`, and every route that does
+ * not carry it fails the check rather than shipping.
+ *
+ * Rules are first-match-wins, so order matters: put narrow exemptions above the general rule.
+ */
+import { defineAssuranceConfig, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
+import { app } from "./src/app.ts"
+
+export default defineAssuranceConfig({
+  source: app,
+  // What each effect IS, so the policy below can be written about a CLASS of effect rather than a list
+  // of token names: `{ access: "write", zone: "domain" }` covers `payments.charge` the day someone adds
+  // it, where a rule naming `db.write` would not.
+  capabilities: {
+    definitions: [
+      { id: "db.read", zone: "domain", access: "read" },
+      { id: "db.write", zone: "domain", access: "write" },
+    ],
+    provenance: {
+      // Reaching one of these modules means holding the capabilities beside it, and `nifra check` fails
+      // any route that can reach further than it declared - so wiring a database into a handler and
+      // forgetting to say so is a failing check rather than something review has to catch.
+      //
+      // The first two are the seam `--db` scaffolds, split by access on purpose: reach is computed per
+      // MODULE, and a GET route may not declare a domain write, so a module that can reach both has GET
+      // routes with no legal declaration. Keeping reads and writes import-disjoint - at the seam and at
+      // the route modules - is what keeps every route's declaration equal to its reach. The drivers
+      // below are the backstop for code that goes around the seam; they grant both, because an import
+      // cannot tell a read from a write.
+      imports: [
+        { specifier: "./read.ts", capabilities: ["db.read"] },
+        { specifier: "./write.ts", capabilities: ["db.write"] },
+        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"] },
+        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"] },
+        { specifier: "pg", capabilities: ["db.read", "db.write"] },
+        { specifier: "postgres", capabilities: ["db.read", "db.write"] },
+        { specifier: "mysql2", capabilities: ["db.read", "db.write"] },
+        { specifier: "kysely", capabilities: ["db.read", "db.write"] },
+        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"] },
+        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"] },
+        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"] },
+        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"] },
+      ],
+      // Add a driver here to force every query through the seam, and the check will name any route that
+      // reaches around it: `{ specifier: "pg", reason: "query through db/read.ts or db/write.ts" }`.
+      forbiddenImports: [],
+    },
+  },
+  policy: {
+    rules: [
+      // Anything that writes business state must prove who asked. Matched on what the capability IS
+      // rather than on its name or its path, so a token introduced later - `payments.charge`,
+      // `orders.write` - is covered the day it is declared instead of the day someone remembers to
+      // widen this rule. A server function is a public POST endpoint like any other, so this is what
+      // stops one shipping unauthenticated.
+      {
+        name: "authenticated-write",
+        match: { access: "write", zone: "domain" },
+        require: [NIFRA_ASSURANCE.AUTHENTICATED],
+      },
+      // Anything that changes state must validate its input at the boundary. Adding a POST without a
+      // `body` schema fails this - which is the point: the check is what notices, not review.
+      {
+        name: "mutation",
+        match: { methods: ["POST", "PUT", "PATCH", "DELETE"] },
+        require: [NIFRA_ASSURANCE.BODY_BOUNDED],
+      },
+      // Reads carry no requirement yet. When some become private, split this into a public rule and
+      // an authenticated one rather than weakening the whole class.
+      { name: "read", match: { methods: ["GET"] }, require: [] },
+    ],
+  },
+})

package/template/package.json

@@ -6,15 +6,17 @@
   "scripts": {
     "dev": "bun --watch run src/index.ts",
     "start": "bun run src/index.ts",
+    "check": "nifra check && nifra assure",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.1.0",
-    "@nifrajs/core": "^2.1.0",
-    "@nifrajs/schema": "^2.1.0"
+    "@nifrajs/client": "^2.3.0",
+    "@nifrajs/core": "^2.3.0",
+    "@nifrajs/schema": "^2.3.0"
   },
   "devDependencies": {
+    "@nifrajs/cli": "^2.3.0",
     "@types/bun": "latest",
     "typescript": "^6.0.3"
   }

package/template/src/app.ts

@@ -1,17 +1,16 @@
 import { server } from "@nifrajs/core/server"
-import { t } from "@nifrajs/schema"
+import { routes } from "./routes.ts"
 
 /** Your app. Exported (without `listen`) so tests can drive it via the in-process test client. */
 
-// Contract-first: the schema validates the body at the boundary, types `c.body` in the
-// handler, types the response, and flows into the typed client (`testClient` in app.test.ts,
-// `client<App>(baseUrl)` in a frontend) - no codegen step.
-const EchoInput = t.object({ message: t.string({ minLength: 1 }) })
-const EchoReply = t.object({ echoed: t.string() })
-
-export const app = server()
-  .get("/", () => ({ hello: "nifra" }))
-  .get("/users/:id", (c) => ({ id: c.params.id }))
-  .post("/echo", { body: EchoInput, response: EchoReply }, (c) => ({ echoed: c.body.message }))
+// Composition only: this module merges route modules and registers none of its own.
+//
+// That is not a style preference. `nifra check` works out what a route can reach from the module that
+// REGISTERS it, following that module's imports - so a file that registers routes AND imports a
+// database gives every route in it database reach, and a GET route may not declare a domain write at
+// all. Keeping the root pure means each route's reach is its own module's, which is what lets the
+// capability declarations in `nifra.assurance.ts` stay true as the app grows. Add a feature as a
+// module, merge it here.
+export const app = server().merge(routes)
 
 export type App = typeof app

package/template/src/routes.ts

@@ -0,0 +1,13 @@
+import { server } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+
+// Contract-first: the schema validates the body at the boundary, types `c.body` in the
+// handler, types the response, and flows into the typed client (`testClient` in app.test.ts,
+// `client<App>(baseUrl)` in a frontend) - no codegen step.
+const EchoInput = t.object({ message: t.string({ minLength: 1 }) })
+const EchoReply = t.object({ echoed: t.string() })
+
+export const routes = server()
+  .get("/", () => ({ hello: "nifra" }))
+  .get("/users/:id", (c) => ({ id: c.params.id }))
+  .post("/echo", { body: EchoInput, response: EchoReply }, (c) => ({ echoed: c.body.message }))

package/template-isr/README.md

@@ -1,6 +1,6 @@
 # nifra + ISR
 
-A nifra + React app with **Incremental Static Regeneration** — pages are cached and served
+A nifra + React app with **Incremental Static Regeneration** - pages are cached and served
 stale-while-revalidate, backed by **Workers KV** in production (so the cache and on-demand purges hold
 across instances) and an in-memory store for local dev.
 

package/template-isr/backend.ts

@@ -1,17 +1,13 @@
 import { server } from "@nifrajs/core/server"
-import { t } from "@nifrajs/schema"
+import { page } from "./page"
 
-// Your backend contract — page loaders/actions call it in-process during SSR (no network). This demo
-// counts server renders so the ISR cache is observable: a cache HIT serves stored bytes (the loader
-// doesn't run, so the number holds), while a MISS or background REGENERATION runs it (it bumps).
-// Replace it with real data (KV/D1/Postgres/…); on the edge, reach bindings via `c.env`.
-let renders = 0
-
-export const backend = server().get(
-  "/page",
-  { response: t.object({ renders: t.number() }) },
-  () => {
-    renders += 1
-    return { renders }
-  },
-)
+// Your backend contract - page loaders/actions call it in-process during SSR (no network).
+// Composition only: this module merges route modules and registers none of its own.
+//
+// That is not a style preference. `nifra check` works out what a route can reach from the module that
+// REGISTERS it, following that module's imports - so a file that registers routes AND imports a
+// database gives every route in it database reach, and a GET route may not declare a domain write at
+// all. Keeping this file pure means each route's reach is its own module's, which is what lets the
+// capability declarations in `nifra.assurance.ts` stay true as the app grows. Add a feature as a
+// module, merge it here.
+export const backend = server().merge(page)

package/template-isr/nifra.assurance.ts

@@ -0,0 +1,81 @@
+/**
+ * What this app's routes are required to PROVE, checked by `nifra assure` (and level L1 of
+ * `nifra levels`). Evidence is collected from the routes themselves - a `body` schema records
+ * `body-bounded`, an auth middleware records `authenticated` - so this file states the requirement
+ * and the framework reports whether the route actually carries it.
+ *
+ * Page routes under `routes/` are not classified here; this is the backend contract those pages call.
+ *
+ * Rules are first-match-wins, so order matters: narrow exemptions go above the general rule, and each
+ * one is named and justified. An exemption you have to write down is one a reviewer can argue with;
+ * an exemption you get by leaving the rule off is one nobody ever sees.
+ */
+import { defineAssuranceConfig, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
+import { backend } from "./backend"
+
+export default defineAssuranceConfig({
+  source: backend,
+  // What each effect IS, so the policy below can be written about a CLASS of effect rather than a list
+  // of token names: `{ access: "write", zone: "domain" }` covers `payments.charge` the day someone adds
+  // it, where a rule naming `db.write` would not.
+  capabilities: {
+    definitions: [
+      { id: "db.read", zone: "domain", access: "read" },
+      { id: "db.write", zone: "domain", access: "write" },
+    ],
+    provenance: {
+      // Reaching one of these modules means holding the capabilities beside it, and `nifra check` fails
+      // any route that can reach further than it declared - so wiring a database into a handler and
+      // forgetting to say so is a failing check rather than something review has to catch.
+      //
+      // The first two are the seam `--db` scaffolds, split by access on purpose: reach is computed per
+      // MODULE, and a GET route may not declare a domain write, so a module that can reach both has GET
+      // routes with no legal declaration. Keeping reads and writes import-disjoint - at the seam and at
+      // the route modules - is what keeps every route's declaration equal to its reach. The drivers
+      // below are the backstop for code that goes around the seam; they grant both, because an import
+      // cannot tell a read from a write.
+      imports: [
+        { specifier: "./read.ts", capabilities: ["db.read"] },
+        { specifier: "./write.ts", capabilities: ["db.write"] },
+        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"] },
+        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"] },
+        { specifier: "pg", capabilities: ["db.read", "db.write"] },
+        { specifier: "postgres", capabilities: ["db.read", "db.write"] },
+        { specifier: "mysql2", capabilities: ["db.read", "db.write"] },
+        { specifier: "kysely", capabilities: ["db.read", "db.write"] },
+        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"] },
+        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"] },
+        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"] },
+        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"] },
+      ],
+      // Add a driver here to force every query through the seam, and the check will name any route that
+      // reaches around it: `{ specifier: "pg", reason: "query through db/read.ts or db/write.ts" }`.
+      forbiddenImports: [],
+    },
+  },
+  policy: {
+    rules: [
+      // Anything that writes business state must prove who asked. Matched on what the capability IS
+      // rather than on its name or its path, so a token introduced later - `payments.charge`,
+      // `orders.write` - is covered the day it is declared instead of the day someone remembers to
+      // widen this rule. A server function is a public POST endpoint like any other, so this is what
+      // stops one shipping unauthenticated.
+      {
+        name: "authenticated-write",
+        match: { access: "write", zone: "domain" },
+        require: [NIFRA_ASSURANCE.AUTHENTICATED],
+      },
+      // Anything that changes state must validate its input at the boundary. This demo is read-only,
+      // so the rule classifies nothing yet - which is the point: the first POST added to `page.ts`
+      // fails the check unless it bounds its body.
+      {
+        name: "mutation",
+        match: { methods: ["POST", "PUT", "PATCH", "DELETE"] },
+        require: [NIFRA_ASSURANCE.BODY_BOUNDED],
+      },
+      // Reads carry no requirement yet. When some become private, split this into a public rule and
+      // an authenticated one rather than weakening the whole class.
+      { name: "read", match: { methods: ["GET"] }, require: [] },
+    ],
+  },
+})

package/template-isr/package.json

@@ -6,19 +6,20 @@
   "scripts": {
     "build": "bun run build.ts",
     "dev": "bunx wrangler dev",
-    "dev:bun": "bun run server.ts"
+    "dev:bun": "bun run server.ts",
+    "check": "nifra check && nifra assure"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.1.0",
-    "@nifrajs/core": "^2.1.0",
-    "@nifrajs/schema": "^2.1.0",
-    "@nifrajs/web": "^2.1.0",
-    "@nifrajs/web-react": "^2.1.0",
+    "@nifrajs/client": "^2.3.0",
+    "@nifrajs/core": "^2.3.0",
+    "@nifrajs/schema": "^2.3.0",
+    "@nifrajs/web": "^2.3.0",
+    "@nifrajs/web-react": "^2.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@nifrajs/cli": "^2.1.0",
+    "@nifrajs/cli": "^2.3.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3"

package/template-isr/page.ts

@@ -0,0 +1,12 @@
+import { server } from "@nifrajs/core/server"
+import { t } from "@nifrajs/schema"
+
+// This demo counts server renders so the ISR cache is observable: a cache HIT serves stored bytes (the
+// loader doesn't run, so the number holds), while a MISS or background REGENERATION runs it (it bumps).
+// Replace it with real data (KV/D1/Postgres/…); on the edge, reach bindings via `c.env`.
+let renders = 0
+
+export const page = server().get("/page", { response: t.object({ renders: t.number() }) }, () => {
+  renders += 1
+  return { renders }
+})

package/template-isr/routes/_404.tsx

@@ -1,7 +1,7 @@
 export default function NotFound() {
   return (
     <section>
-      <h2>404 — not found</h2>
+      <h2>404 - not found</h2>
       <p>
         <a href="/">← home</a>
       </p>

package/template-isr/routes/_layout.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react"
 
-/** Root layout — rendered inside the document shell `renderPage` emits. */
+/** Root layout - rendered inside the document shell `renderPage` emits. */
 export default function Layout(props: { children?: ReactNode }) {
   return (
     <main

package/template-isr/routes/index.tsx

@@ -7,7 +7,7 @@ export const meta = {
 }
 
 // ISR: the `withISR` wrapper (worker.ts / server.ts) caches this page and serves it
-// stale-while-revalidate. `revalidate` is the freshness window in SECONDS — nifra emits it as the
+// stale-while-revalidate. `revalidate` is the freshness window in SECONDS - nifra emits it as the
 // `x-nifra-isr-revalidate` header, which the wrapper reads to set this page's TTL. Loader/meta are
 // pure annotated exports, so they tree-shake out of the client bundle.
 export const revalidate = 10
@@ -24,7 +24,7 @@ export default function Home(props: { data: LoaderData<typeof loader> }) {
         server renders: <b>{props.data.renders}</b>
       </p>
       <p>
-        Reload within {revalidate}s and this holds — you're served the cached page (response header{" "}
+        Reload within {revalidate}s and this holds - you're served the cached page (response header{" "}
         <code>x-nifra-isr: hit</code>). After the window, the next request gets the stale page
         instantly (<code>stale</code>) while a fresh copy regenerates behind it. Edit{" "}
         <code>routes/index.tsx</code> to begin.