create-nifra 3.5.0 → 4.0.2

package/src/agent-files.ts

@@ -1,25 +1,24 @@
 /**
- * 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:
+ * The canonical generators for the agent files an app ships. `AGENTS.md` is the single source of agent
+ * guidance; every other agent's file is a thin pointer to it, so no two copies can drift:
  *
- *   .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
+ *   AGENTS.md                         - the guidance (read natively by Codex, Cursor, Copilot and others)
+ *   CLAUDE.md                         - Claude Code: `@AGENTS.md` import
+ *   GEMINI.md                         - Gemini CLI: `@./AGENTS.md` import
+ *   .cursor/rules/nifra.mdc           - Cursor: an always-applied rule pointing at AGENTS.md
+ *   .github/copilot-instructions.md   - GitHub Copilot: points at AGENTS.md
+ *   .mcp.json, .cursor/mcp.json       - the nifra MCP server, registered for Claude Code and Cursor
  *
- * 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.
+ * Both `create-nifra` (scaffold time) and `@nifrajs/cli`'s `nifra init-agents` (retrofit an existing app)
+ * import these, so the 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.
+ * `@nifrajs/cli` package, 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 in an
+ * app that does not carry `@nifrajs/cli`. Naming the bin-owning package resolves the locally-installed
+ * bin when present and otherwise fetches the package that actually provides the `nifra` command.
  */
 
 import { readFileSync } from "node:fs"
@@ -47,7 +46,8 @@ export const MCP_SERVER_COMMAND = "bunx" as const
  * 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.
+ * at its scaffold-time version until `nifra init-agents --sync-mcp` re-pins it to the nifra the project
+ * installs - an acceptable, deterministic trade.
  */
 export const MCP_CLI_VERSION: string = (
   JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
@@ -80,35 +80,27 @@ 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`.
- */
+const POINTER_INTRO =
+  "This project's agent guidance - commands, the project structure, the rules, and the nifra MCP server - lives in AGENTS.md, the single source every agent reads."
+
+/** `CLAUDE.md`: Claude Code expands the `@AGENTS.md` import in place. */
 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
-`
+  return `# CLAUDE.md\n\n${POINTER_INTRO}\n\n@AGENTS.md\n`
+}
+
+/** `GEMINI.md`: Gemini CLI expands `@./AGENTS.md` imports in its context files. */
+export function geminiMd(): string {
+  return `# GEMINI.md\n\n${POINTER_INTRO}\n\n@./AGENTS.md\n`
+}
+
+/** `.cursor/rules/nifra.mdc`: an always-applied Cursor rule; `@AGENTS.md` attaches the file. */
+export function cursorRule(): string {
+  return `---\ndescription: nifra project guidance\nalwaysApply: true\n---\n\n${POINTER_INTRO} Read it before changing code:\n\n@AGENTS.md\n`
+}
+
+/** `.github/copilot-instructions.md`: Copilot has no import syntax, so this names the file. */
+export function copilotInstructions(): string {
+  return `${POINTER_INTRO} Read AGENTS.md at the repository root before changing code, and follow it.\n`
 }
 
 /**
@@ -132,6 +124,44 @@ project + the installed version, so they beat training-data recall:
   failing check means it isn't done. (\`nifra check --json\` in a terminal does the same.)`
 }
 
+/**
+ * The "## Project structure" section of a web app's `AGENTS.md`: the zones the build enforces. Shared so
+ * a scaffolded app and one `nifra init-agents` retrofits teach the same rules.
+ */
+export function agentsStructureSection(): string {
+  return `${STRUCTURE_HEADING}
+
+Every file a build loads belongs to one side, and the build refuses an import that crosses the wrong
+way - it fails naming the import chain rather than shipping server code to the browser.
+
+| Where | Holds | Reaches the browser |
+|---|---|---|
+| \`routes/x.tsx\` (\`.svelte\`, \`.vue\`, \`.mdx\`) | a page: the component, \`meta\` | yes |
+| \`routes/x.backend.ts\` | that page's \`loader\`, \`action\`, \`loaderOutput\`, \`actionOutput\`, \`middleware\` | never |
+| \`frontend/\` | components, hooks, browser-only code | yes |
+| \`backend/\` | \`app.ts\` (the API), \`framework.ts\`, the database, auth, secrets | never |
+| \`shared/\` | schemas, types and pure helpers both sides import | yes |
+| \`public/\` | static files served as they are | yes |
+
+A file outside those folders joins a side with a \`.frontend.ts\`, \`.backend.ts\` or \`.shared.ts\` suffix.
+
+- **A route is two files.** \`routes/blog/[slug].tsx\` renders; \`routes/blog/[slug].backend.ts\` loads.
+  A server-only export (\`loader\`, \`action\`, ...) in the \`.tsx\` file is a build error.
+- **Frontend code never imports backend code** - not \`backend/\`, not a \`.backend.ts\` file, not a
+  database driver or \`node:\` built-in. Data reaches a page only as its loader's return value.
+- **Every loader and action declares what it sends**: \`export const loaderOutput = t.object({ ... })\`
+  (and \`actionOutput\`). Only what the schema declares reaches the browser, and a loader without one
+  is refused.
+- **Type a route with its generated \`./+types/<name>\`**: \`import type { Route } from "./+types/[slug]"\`
+  gives \`Route.LoaderArgs\` (with the typed \`api\`) in the backend half and \`Route.ComponentProps\` in
+  the page. \`nifra dev\`, \`nifra build\`, \`nifra check\` and \`nifra types\` write them.
+- **Secrets stay in \`backend/\`.** A value only the server may see is read there (\`process.env\`), never
+  in a frontend file; a build that finds what looks like a credential in browser output fails.`
+}
+
+/** The heading `nifra init-agents` looks for before appending {@link agentsStructureSection}. */
+export const STRUCTURE_HEADING = "## Project structure"
+
 /** 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 {
@@ -142,8 +172,20 @@ export interface AgentFileSpec {
 }
 
 /** 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. */
+ * because create-nifra builds it from `agents.ts` and the retrofit command appends sections 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 GEMINI_MD_PATH = "GEMINI.md"
+export const CURSOR_RULE_PATH = ".cursor/rules/nifra.mdc"
+export const COPILOT_INSTRUCTIONS_PATH = ".github/copilot-instructions.md"
 export const AGENTS_MD_PATH = "AGENTS.md"
+
+/** Every agent's pointer to `AGENTS.md`, in the order they are written and reported. */
+export const AGENT_POINTERS: readonly { readonly path: string; readonly content: () => string }[] =
+  [
+    { path: CLAUDE_MD_PATH, content: claudeMd },
+    { path: GEMINI_MD_PATH, content: geminiMd },
+    { path: CURSOR_RULE_PATH, content: cursorRule },
+    { path: COPILOT_INSTRUCTIONS_PATH, content: copilotInstructions },
+  ]

package/template/README.md

@@ -15,16 +15,22 @@ rate-limit store intentionally refuses production unless `NIFRA_ALLOW_MEMORY_RAT
 shared store for a multi-instance deployment. If you add cookie sessions, install the signed CSRF
 middleware and keep authenticated mutation routes covered by both authenticated and CSRF assurance.
 
-- `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.
+Server code lives in `backend/`, the same folder a site keeps its backend in, so pages can be added
+later without moving anything:
 
-Add a typed client from `typeof app`:
+- `backend/app.ts` - exports `backend`, your API: it composes the route modules (exported without
+  `listen`, so tests drive it via `backend.fetch`). `nifra contracts` and `nifra sdk` read it from
+  here.
+- `backend/routes.ts` - the routes.
+- `backend/index.ts` - boots the server.
+- `backend/app.test.ts` - an example test.
+
+Add a typed client from `typeof backend`:
 
 ```ts
 import { client } from "@nifrajs/client"
-import type { App } from "./src/app.ts"
+import type { Backend } from "./backend/app.ts"
 
-const api = client<App>("http://localhost:3000")
+const api = client<Backend>("http://localhost:3000")
 const { data } = await api.users({ id: "42" }).get()
 ```

package/template/{src → backend}/app.test.ts

@@ -1,10 +1,10 @@
 import { testClient } from "@nifrajs/client"
 import { expect, test } from "bun:test"
-import { app } from "./app.ts"
+import { backend } from "./app.ts"
 
 // The typed in-process client: no server, no port, the full real lifecycle (validation,
 // middleware), and `res.data` typed from the route's schemas. Calls never throw - branch on `ok`.
-const api = testClient<typeof app>(app)
+const api = testClient<typeof backend>(backend)
 
 test("GET /users/:id echoes the id", async () => {
   const res = await api.users({ id: "42" }).get()

package/template/{src → backend}/app.ts

@@ -1,4 +1,5 @@
 import { server } from "@nifrajs/core/server"
+import { responseContract } from "@nifrajs/core/response-contract"
 import {
   MemoryStore,
   cors,
@@ -8,7 +9,10 @@ import {
 } from "@nifrajs/middleware"
 import { routes } from "./routes.ts"
 
-/** Your app. Exported (without `listen`) so tests can drive it via the in-process test client. */
+/**
+ * Your API. Every `nifra` command finds it here (`backend/app.ts` exporting `backend`), and it is
+ * exported without `listen` so tests can drive it in-process.
+ */
 
 // Composition only: this module merges route modules and registers none of its own.
 //
@@ -24,10 +28,11 @@ const rateStore = new MemoryStore({
   allowInProduction: process.env.NIFRA_ALLOW_MEMORY_RATE_LIMIT === "true",
 })
 
-export const app = server({
+export const backend = server({
   requestTimeoutMs: 30_000,
   admission: createAdmissionController({ maxInFlight: 128, maxQueue: 0 }),
 })
+  .use(responseContract("enforce"))
   .use(securityHeaders())
   .use(
     cors({
@@ -38,4 +43,4 @@ export const app = server({
   .use(rateLimit({ store: rateStore, max: 120, windowMs: 60_000 }))
   .merge(routes)
 
-export type App = typeof app
+export type Backend = typeof backend

package/template/{src → backend}/index.ts

@@ -1,5 +1,5 @@
-import { app } from "./app.ts"
+import { backend } from "./app.ts"
 
 const port = Number(process.env.PORT ?? 3000)
-app.listen(port)
+backend.listen(port)
 console.log(`▲ nifra listening on http://localhost:${port}`)

package/template/{src → backend}/routes.ts

@@ -3,7 +3,7 @@ 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.
+// `client<Backend>(baseUrl)` in a frontend) - no codegen step.
 const EchoInput = t.object({ message: t.string({ minLength: 1 }) })
 const EchoReply = t.object({ echoed: t.string() })
 

package/template/nifra.assurance.ts

@@ -11,10 +11,10 @@
  * 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"
+import { backend } from "./backend/app.ts"
 
 export default defineAssuranceConfig({
-  source: app,
+  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.
@@ -34,19 +34,21 @@ export default defineAssuranceConfig({
       // 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.
+      // Shared starter catalog: an absent database integration is optional, but any matching
+      // import still grants its capabilities. Remove optional for seams this app owns.
       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"] },
+        { specifier: "./read.ts", capabilities: ["db.read"], optional: true },
+        { specifier: "./write.ts", capabilities: ["db.write"], optional: true },
+        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "pg", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "postgres", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "mysql2", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "kysely", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"], optional: true },
       ],
       // 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" }`.

package/template/package.json

@@ -4,20 +4,20 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "bun --watch run src/index.ts",
-    "start": "bun run src/index.ts",
+    "dev": "bun --watch run backend/index.ts",
+    "start": "bun run backend/index.ts",
     "check": "nifra check && nifra assure",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nifrajs/client": "^3.5.0",
-    "@nifrajs/core": "^3.5.0",
-    "@nifrajs/middleware": "^3.5.0",
-    "@nifrajs/schema": "^3.5.0"
+    "@nifrajs/client": "^4.0.2",
+    "@nifrajs/core": "^4.0.2",
+    "@nifrajs/middleware": "^4.0.2",
+    "@nifrajs/schema": "^4.0.2"
   },
   "devDependencies": {
-    "@nifrajs/cli": "^3.5.0",
+    "@nifrajs/cli": "^4.0.2",
     "@types/bun": "latest",
     "typescript": "^6.0.3"
   }

package/template/tsconfig.json

@@ -12,5 +12,5 @@
     "types": ["bun"],
     "skipLibCheck": true
   },
-  "include": ["src/**/*"]
+  "include": ["backend/**/*"]
 }

package/template-batteries/README.md

@@ -24,19 +24,23 @@ rate-limit store intentionally refuses production unless `NIFRA_ALLOW_MEMORY_RAT
 shared store for a multi-instance deployment. If you add cookie sessions, install the signed CSRF
 middleware and keep authenticated mutation routes covered by both authenticated and CSRF assurance.
 
-- `src/app.ts` - routes + the `notes` domain, exported (without `listen`) so tests drive it via `app.fetch`.
-- `src/index.ts` - boots the server and starts the job worker (`queue.start()`).
-- `src/app.test.ts` - exercises pagination, the background job (`queue.drain()`), the cache, and storage.
+- `backend/app.ts` - exports `backend`, your API: it composes the route modules (exported without
+  `listen`, so tests drive it via `backend.fetch`). `nifra contracts` and `nifra sdk` read it from
+  here.
+- `backend/notes.ts` - the `notes` domain: routes, the job queue, the cache and storage.
+- `backend/index.ts` - boots the server and starts the job worker (`queue.start()`).
+- `backend/app.test.ts` - exercises pagination, the background job (`queue.drain()`), the cache, and
+  storage.
 
 Swap the in-memory `notes` array for your database, the `MemoryStorage` for `FileStorage`/`R2Storage`, and
 the default in-memory cache/job stores for shared (Redis / CF KV) ones when you go multi-process.
 
-Add a typed client from `typeof app`:
+Add a typed client from `typeof backend`:
 
 ```ts
 import { client } from "@nifrajs/client"
-import type { App } from "./src/app.ts"
+import type { Backend } from "./backend/app.ts"
 
-const api = client<App>("http://localhost:3000")
+const api = client<Backend>("http://localhost:3000")
 const { data } = await api.notes.get({ query: { limit: 20 } })
 ```

package/template-batteries/{src → backend}/app.test.ts

@@ -1,14 +1,18 @@
 import { expect, test } from "bun:test"
-import { app, queue, wasIndexed } from "./app.ts"
+import { backend, queue, wasIndexed } from "./app.ts"
+
+// `listen()` tells the app who is calling; a bare `backend.fetch` does not, and `rateLimit()` refuses a
+// request it cannot attribute. Each test request therefore arrives from a local peer, as it would
+// through a socket.
+const send = (path: string, init?: RequestInit) =>
+  backend.fetch(new Request(`http://localhost${path}`, init), { clientIp: "127.0.0.1" })
 
 const post = (body: unknown) =>
-  app.fetch(
-    new Request("http://localhost/notes", {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-    }),
-  )
+  send("/notes", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  })
 
 test("create + background index job", async () => {
   const res = await post({ title: "first", body: "hello" })
@@ -28,40 +32,36 @@ test("cursor pagination walks every page", async () => {
   await post({ title: "b", body: "" })
   await post({ title: "c", body: "" })
 
-  const first = (await (
-    await app.fetch(new Request("http://localhost/notes?limit=2"))
-  ).json()) as Page
+  const first = (await (await send("/notes?limit=2")).json()) as Page
   expect(first.items).toHaveLength(2)
   expect(first.nextCursor).not.toBeNull()
 
-  const url = `http://localhost/notes?limit=2&cursor=${encodeURIComponent(first.nextCursor ?? "")}`
-  const second = (await (await app.fetch(new Request(url))).json()) as Page
+  const cursor = encodeURIComponent(first.nextCursor ?? "")
+  const second = (await (await send(`/notes?limit=2&cursor=${cursor}`)).json()) as Page
   expect(second.items.length).toBeGreaterThan(0)
 })
 
 test("limit over the cap is a 422", async () => {
-  const res = await app.fetch(new Request("http://localhost/notes?limit=999"))
+  const res = await send("/notes?limit=999")
   expect(res.status).toBe(422)
 })
 
 test("get one is served (and cached); missing is 404", async () => {
   const created = (await (await post({ title: "cached", body: "x" })).json()) as { id: number }
-  const hit = await app.fetch(new Request(`http://localhost/notes/${created.id}`))
+  const hit = await send(`/notes/${created.id}`)
   expect(((await hit.json()) as { id: number }).id).toBe(created.id)
 
-  const miss = await app.fetch(new Request("http://localhost/notes/999999"))
+  const miss = await send("/notes/999999")
   expect(miss.status).toBe(404)
 })
 
 test("attachment round-trips through storage", async () => {
   const created = (await (await post({ title: "with-file", body: "x" })).json()) as { id: number }
-  const res = await app.fetch(
-    new Request(`http://localhost/notes/${created.id}/attachment`, {
-      method: "PUT",
-      headers: { "content-type": "text/plain" },
-      body: "hello bytes",
-    }),
-  )
+  const res = await send(`/notes/${created.id}/attachment`, {
+    method: "PUT",
+    headers: { "content-type": "text/plain" },
+    body: "hello bytes",
+  })
   expect(res.status).toBe(201)
   expect(((await res.json()) as { bytes: number }).bytes).toBe("hello bytes".length)
 })

package/template-batteries/{src → backend}/app.ts

@@ -1,3 +1,4 @@
+import { responseContract } from "@nifrajs/core/response-contract"
 import { server } from "@nifrajs/core/server"
 import {
   cors,
@@ -8,7 +9,10 @@ import {
 } from "@nifrajs/middleware"
 import { noteRoutes } from "./notes.ts"
 
-/** Your app. Exported (without `listen`) so tests can drive it via the in-process test client. */
+/**
+ * Your API. Every `nifra` command finds it here (`backend/app.ts` exporting `backend`), and it is
+ * exported without `listen` so tests can drive it in-process.
+ */
 
 // Composition only: this module merges route modules and registers none of its own.
 //
@@ -22,10 +26,11 @@ const rateStore = new MemoryStore({
   allowInProduction: process.env.NIFRA_ALLOW_MEMORY_RATE_LIMIT === "true",
 })
 
-export const app = server({
+export const backend = server({
   requestTimeoutMs: 30_000,
   admission: createAdmissionController({ maxInFlight: 128, maxQueue: 0 }),
 })
+  .use(responseContract("enforce"))
   .use(securityHeaders())
   .use(
     cors({
@@ -36,7 +41,7 @@ export const app = server({
   .use(rateLimit({ store: rateStore, max: 120, windowMs: 60_000 }))
   .merge(noteRoutes)
 
-export type App = typeof app
+export type Backend = typeof backend
 
 export type { Note } from "./notes.ts"
 // Re-exported so `index.ts` can start the worker and `app.test.ts` can inspect it, without either

package/template-batteries/{src → backend}/index.ts

@@ -1,4 +1,4 @@
-import { app, queue } from "./app.ts"
+import { backend, queue } from "./app.ts"
 
 // Start the in-process job worker (leases due jobs, runs them with retries/backoff). On Cloudflare
 // Workers, drive a durable store from a CF Queues consumer with `queue.process()` instead - see the
@@ -6,5 +6,5 @@ import { app, queue } from "./app.ts"
 queue.start()
 
 const port = Number(process.env.PORT ?? 3000)
-app.listen(port)
+backend.listen(port)
 console.log(`▲ nifra full-stack app on http://localhost:${port}`)

package/template-batteries/{src → backend}/notes.ts

@@ -10,7 +10,7 @@ import { MemoryStorage } from "@nifrajs/storage"
 //
 // A full-stack starter: cursor pagination (@nifrajs/schema), background jobs (@nifrajs/jobs), a typed
 // cache (@nifrajs/cache), and blob storage (@nifrajs/storage) - over an in-memory "notes" store you'd
-// swap for your database. Everything is exported so `app.test.ts` can drive it via `app.fetch`.
+// swap for your database. Everything is exported so `app.test.ts` can drive it via `backend.fetch`.
 
 export interface Note {
   id: number

package/template-batteries/nifra.assurance.ts

@@ -9,10 +9,10 @@
  * an exemption you get by leaving the rule off is one nobody ever sees.
  */
 import { defineAssuranceConfig, NIFRA_ASSURANCE } from "@nifrajs/core/assurance"
-import { app } from "./src/app.ts"
+import { backend } from "./backend/app.ts"
 
 export default defineAssuranceConfig({
-  source: app,
+  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.
@@ -32,19 +32,21 @@ export default defineAssuranceConfig({
       // 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.
+      // Shared starter catalog: an absent database integration is optional, but any matching
+      // import still grants its capabilities. Remove optional for seams this app owns.
       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"] },
+        { specifier: "./read.ts", capabilities: ["db.read"], optional: true },
+        { specifier: "./write.ts", capabilities: ["db.write"], optional: true },
+        { specifier: "bun:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "node:sqlite", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "pg", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "postgres", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "mysql2", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "kysely", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "drizzle-orm/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@libsql/*", capabilities: ["db.read", "db.write"], optional: true },
+        { specifier: "@prisma/client", capabilities: ["db.read", "db.write"], optional: true },
       ],
       // 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" }`.

package/template-batteries/package.json

@@ -4,22 +4,23 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "dev": "bun --watch run src/index.ts",
-    "start": "bun run src/index.ts",
+    "dev": "bun --watch run backend/index.ts",
+    "start": "bun run backend/index.ts",
     "check": "nifra check && nifra assure",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nifrajs/cache": "^3.5.0",
-    "@nifrajs/client": "^3.5.0",
-    "@nifrajs/core": "^3.5.0",
-    "@nifrajs/jobs": "^3.5.0",
-    "@nifrajs/schema": "^3.5.0",
-    "@nifrajs/storage": "^3.5.0"
+    "@nifrajs/cache": "^4.0.2",
+    "@nifrajs/client": "^4.0.2",
+    "@nifrajs/core": "^4.0.2",
+    "@nifrajs/jobs": "^4.0.2",
+    "@nifrajs/middleware": "^4.0.2",
+    "@nifrajs/schema": "^4.0.2",
+    "@nifrajs/storage": "^4.0.2"
   },
   "devDependencies": {
-    "@nifrajs/cli": "^3.5.0",
+    "@nifrajs/cli": "^4.0.2",
     "@types/bun": "latest",
     "typescript": "^6.0.3"
   }