create-nifra 2.1.0 → 2.3.0

package/README.md

@@ -11,11 +11,11 @@ bun create nifra my-app
 
 `--template <name>` (default `api`):
 
-- **`api`** — a typed nifra server (`src/app.ts` + `src/index.ts`) with an example test and
+- **`api`** - a typed nifra server (`src/app.ts` + `src/index.ts`) with an example test and
   `dev`/`start`/`test`/`typecheck` scripts.
-- **`site`** — a nifra + React SSR site, one source deployable to Cloudflare Pages, Node, Deno, or
+- **`site`** - a nifra + React SSR site, one source deployable to Cloudflare Pages, Node, Deno, or
   Vercel Edge.
-- **`isr`** — a nifra + React app with **Incremental Static Regeneration** on Cloudflare Workers + KV
+- **`isr`** - a nifra + React app with **Incremental Static Regeneration** on Cloudflare Workers + KV
   (pages cached + served stale-while-revalidate; on-demand purge endpoint).
 
 ```sh
@@ -34,7 +34,7 @@ MIT.
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/agent-files.d.ts

@@ -2,33 +2,33 @@
  * 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
+ *   .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
+ * 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
+ * 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
+ * otherwise fetches the package that actually provides the `nifra` command - robust across every
  * template and for any existing app.
  */
 /** 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 declare const MCP_SERVER_COMMAND: "bunx";
 /**
- * The `@nifrajs/cli` version the launch command pins to — DERIVED at load time from this package's own
+ * 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 —
+ * 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.
  *
@@ -39,11 +39,11 @@ export declare const MCP_SERVER_COMMAND: "bunx";
  *
  * 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`
+ * 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.
+ * at its scaffold-time version until `nifra init-agents` is re-run - an acceptable, deterministic trade.
  */
 export declare const MCP_CLI_VERSION: string;
 export declare const MCP_SERVER_ARGS: readonly [`@nifrajs/cli@${string}`, "mcp"];
@@ -56,16 +56,16 @@ export interface McpServerConfig {
 export interface McpConfig {
     readonly mcpServers: Readonly<Record<string, McpServerConfig>>;
 }
-/** The one canonical MCP config object both registries serialize — the anti-drift seam. */
+/** The one canonical MCP config object both registries serialize - the anti-drift seam. */
 export declare const MCP_CONFIG: McpConfig;
 /** 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 declare function mcpJson(): string;
 /**
- * `CLAUDE.md` — Claude Code reads this automatically. It is deliberately NOT a copy of `AGENTS.md`:
+ * `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
+ * 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 declare function claudeMd(): string;

package/dist/agent-files.js

@@ -2,23 +2,23 @@
  * 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
+ *   .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
+ * 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
+ * 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
+ * otherwise fetches the package that actually provides the `nifra` command - robust across every
  * template and for any existing app.
  */
 import { readFileSync } from "node:fs";
@@ -26,10 +26,10 @@ import { readFileSync } from "node:fs";
  * the package is named explicitly rather than relying on the bare `nifra` bin. */
 export const MCP_SERVER_COMMAND = "bunx";
 /**
- * The `@nifrajs/cli` version the launch command pins to — DERIVED at load time from this package's own
+ * 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 —
+ * 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.
  *
@@ -40,15 +40,15 @@ export const MCP_SERVER_COMMAND = "bunx";
  *
  * 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`
+ * 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.
+ * at its scaffold-time version until `nifra init-agents` is re-run - an acceptable, deterministic trade.
  */
 export const MCP_CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 export const MCP_SERVER_ARGS = [`@nifrajs/cli@${MCP_CLI_VERSION}`, "mcp"];
-/** The one canonical MCP config object both registries serialize — the anti-drift seam. */
+/** The one canonical MCP config object both registries serialize - the anti-drift seam. */
 export const MCP_CONFIG = {
     mcpServers: {
         nifra: { command: MCP_SERVER_COMMAND, args: [...MCP_SERVER_ARGS] },
@@ -60,31 +60,31 @@ export function mcpJson() {
     return `${JSON.stringify(MCP_CONFIG, null, 2)}\n`;
 }
 /**
- * `CLAUDE.md` — Claude Code reads this automatically. It is deliberately NOT a copy of `AGENTS.md`:
+ * `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
+ * 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() {
     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
+\`${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
+- \`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_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.
+  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:
+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
 `;
@@ -97,16 +97,16 @@ the gotchas — lives in \`AGENTS.md\`, imported here so it stays the single sou
 export function agentsMcpSection() {
     return `## MCP server
 
-This project ships a **nifra MCP server** — launch it with \`${MCP_SERVER_COMMAND} ${MCP_SERVER_ARGS.join(" ")}\`. It's registered for
+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
+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
+- \`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.)`;
 }
 /** The standalone files this module fully owns (whole-file generators). AGENTS.md is handled separately

package/dist/agents.d.ts

@@ -1,8 +1,8 @@
 /**
- * Generate the `AGENTS.md` a scaffolded app ships with — the conventions file read by coding agents
+ * Generate the `AGENTS.md` a scaffolded app ships with - the conventions file read by coding agents
  * (Claude Code, Cursor, …). It encodes nifra's non-obvious rules so an agent writes correct code from
  * the first prompt: validate at the boundary, the never-throwing client, `app.fetch` as the universal
- * entry, and (for full-stack apps) the one gotcha that bites everyone — never top-level-import
+ * entry, and (for full-stack apps) the one gotcha that bites everyone - never top-level-import
  * server-only code into a route module. Tailored per template so the paths + commands are real.
  */
 import type { AuthChoice } from "./auth.js";
@@ -12,9 +12,9 @@ export interface AgentsMdOptions {
     readonly template: TemplateName;
     readonly framework: Framework;
     readonly name: string;
-    /** Drizzle preset, when scaffolded with `--db` — adds a Database section. */
+    /** Drizzle preset, when scaffolded with `--db` - adds a Database section. */
     readonly db?: DbChoice;
-    /** Auth preset, when scaffolded with `--auth` — adds an Authentication section. */
+    /** Auth preset, when scaffolded with `--auth` - adds an Authentication section. */
     readonly auth?: AuthChoice;
 }
 /** Build the full `AGENTS.md` for a freshly scaffolded app. */

package/dist/agents.js

@@ -1,8 +1,8 @@
 /**
- * Generate the `AGENTS.md` a scaffolded app ships with — the conventions file read by coding agents
+ * Generate the `AGENTS.md` a scaffolded app ships with - the conventions file read by coding agents
  * (Claude Code, Cursor, …). It encodes nifra's non-obvious rules so an agent writes correct code from
  * the first prompt: validate at the boundary, the never-throwing client, `app.fetch` as the universal
- * entry, and (for full-stack apps) the one gotcha that bites everyone — never top-level-import
+ * entry, and (for full-stack apps) the one gotcha that bites everyone - never top-level-import
  * server-only code into a route module. Tailored per template so the paths + commands are real.
  */
 import { agentsMcpSection } from "./agent-files.js";
@@ -14,7 +14,7 @@ const FRAMEWORK_LABEL = {
     preact: "Preact",
     svelte: "Svelte",
 };
-/** Shared backend rules — every template is, at its core, a nifra `server()`. */
+/** Shared backend rules - every template is, at its core, a nifra `server()`. */
 const API_RULES = `## The backend: \`server()\`
 
 \`\`\`ts
@@ -39,54 +39,54 @@ export type App = typeof app
 Rules an agent must follow:
 
 - **Validate every input at the boundary.** The route schema slots are \`{ body, query }\` (plus
-  \`response\`, below) — use \`t\` from \`@nifrajs/schema\` (installed) or any Standard Schema (zod, valibot).
+  \`response\`, below) - use \`t\` from \`@nifrajs/schema\` (installed) or any Standard Schema (zod, valibot).
   Read the typed, already-validated \`c.body\` / \`c.query\` (invalid input was rejected with a 422 before the
-  handler ran). **Never** hand-parse \`await c.req.json()\` and poke at properties — that's the bug class the
+  handler ran). **Never** hand-parse \`await c.req.json()\` and poke at properties - that's the bug class the
   schema exists to remove.
 - **Path params are NOT a schema slot.** \`:id\` etc. are inferred from the path literal as \`string\` and
   read via \`c.params.id\`; there is no \`params\` (or \`headers\`) key in the route schema. Validate a param's
-  shape inside the handler (a length/format check), not via \`{ params: ... }\` — that's a type error.
+  shape inside the handler (a length/format check), not via \`{ params: ... }\` - that's a type error.
 - **Lock the output shape with \`response\` (no drift).** Add \`{ response: t.object({...}) }\` to a route:
   the handler's return is type-checked against it, and the typed client sees exactly that shape. One
-  contract, both sides — the frontend physically can't drift from the backend's output.
+  contract, both sides - the frontend physically can't drift from the backend's output.
 - **Data-or-error routes: set the status with \`c.set.status\`, then read the error off \`res.error\` (NOT \`res.data\`).**
   The typed client maps \`res.ok\` to the HTTP status. A route that does \`c.set.status = 404; return { ok: false,
   error: "not_found" }\` arrives at the client as \`res.ok === false\`, \`res.data === null\`, and the body on
   \`res.error\` (\`res.error.error === "not_found"\`). So branch on \`res.ok\` FIRST, then read \`res.data\` on success
-  or \`res.error\` on failure — never assert a 4xx onto \`res.data\`. Declaring the error arm in \`response\`
+  or \`res.error\` on failure - never assert a 4xx onto \`res.data\`. Declaring the error arm in \`response\`
   (\`t.union([Item, t.object({ ok: t.literal(false), error: t.string() })])\`) documents the shape and keeps the
   success \`res.data\` precise, but a 4xx still surfaces via \`res.error\`. Do NOT return a raw \`Response\` just to
   set an error status.
 - **Raw \`Response\` is for redirects / streams / files** (\`Response.redirect(url, 302)\`, a file body, an
   SSE stream). The typed client infers \`res.data: never\` on such a route and \`nifra check\` emits a
-  non-blocking \`response-route\` warning — both are EXPECTED there, not defects.
-- **\`app.fetch(request)\` is the whole app** — \`(Request) => Response | Promise<Response>\`. Tests drive it
+  non-blocking \`response-route\` warning - both are EXPECTED there, not defects.
+- **\`app.fetch(request)\` is the whole app** - \`(Request) => Response | Promise<Response>\`. Tests drive it
   directly (\`await app.fetch(new Request("http://x/users/1"))\`); no server needs to be running.
 - **Don't reach for a heavy ORM/HTTP layer.** Routing, validation, cookies, and the typed client are
   built in. Parameterize DB queries; use \`timingSafeEqual\` (or WebCrypto) for secret comparison.
-- **Cross-cutting concerns — use \`@nifrajs/middleware\`, don't hand-roll.** Rate limiting (\`429\` +
+- **Cross-cutting concerns - use \`@nifrajs/middleware\`, don't hand-roll.** Rate limiting (\`429\` +
   \`Retry-After\`), CORS, security headers, body limits, auth (\`bearer\`/\`apiKey\`/\`basicAuth\`/\`jwt\`), CSRF,
-  IP restriction, response caching, compression — all \`app.use(...)\` plugins in \`@nifrajs/middleware\`.
+  IP restriction, response caching, compression - all \`app.use(...)\` plugins in \`@nifrajs/middleware\`.
   Call \`nifra_docs("middleware")\` for the full list + usage before building one of these by hand.
 
-## The client is typed + never throws — ALWAYS use it for internal API calls
+## The client is typed + never throws - ALWAYS use it for internal API calls
 
 \`\`\`ts
 import { client } from "@nifrajs/client"
-import type { app } from "./app"          // type-only import — server code never ships to the client
+import type { app } from "./app"          // type-only import - server code never ships to the client
 
 const api = client<typeof app>("https://api.example.com")
 const res = await api.users({ id: "42" }).get()
-if (res.ok) res.data            // typed from the route's return type — zero codegen
+if (res.ok) res.data            // typed from the route's return type - zero codegen
 else res.error                  // errors are returned, never thrown
 \`\`\`
 
-**Never hand-roll \`fetch\` + ad-hoc response types for this app's own API** — that's exactly how a screen
+**Never hand-roll \`fetch\` + ad-hoc response types for this app's own API** - that's exactly how a screen
 drifts from the backend. \`client<typeof app>\` derives both the request inputs and \`res.data\` from the
 route types, so \`tsc\` (and \`nifra build\`) catch any mismatch the moment a route changes. When building a
 page that calls the API, reach for the client first.
 `;
-/** File-routing + the server-only gotcha — only for full-stack (site/isr) templates. */
+/** File-routing + the server-only gotcha - only for full-stack (site/isr) templates. */
 function webRules(framework) {
     const label = FRAMEWORK_LABEL[framework];
     return `## The frontend: file routing + loaders (${label})
@@ -96,7 +96,7 @@ function webRules(framework) {
 - A route file may export: \`default\` (the page component), \`loader\` (server-only data), \`action\`
   (server-only mutation), and \`meta\` (head tags). The \`loader\` returns data typed straight into the page.
 - **The \`server()\` backend is IN-PROCESS, not a public HTTP surface.** Loaders/actions call it through
-  \`ctx.api\` (the typed client — no network) during SSR; there is no \`GET /your-route\` endpoint on the page
+  \`ctx.api\` (the typed client - no network) during SSR; there is no \`GET /your-route\` endpoint on the page
   server to curl. Build features through loaders/actions + the typed client, not direct HTTP calls.
 - Swap UI frameworks by changing one import (\`@nifrajs/web-${framework}\` → another adapter); your route,
   loader, and action code do not change.
@@ -108,10 +108,10 @@ function webRules(framework) {
 ## ⚠️ The one rule that bites everyone: never import server-only code at a route's top level
 
 A route module's \`loader\`/\`action\` run **only on the server**, but the module is **also bundled for the
-browser** (for the component) — and the loader is *not* stripped. So a top-level
+browser** (for the component) - and the loader is *not* stripped. So a top-level
 \`import db from "./db"\` (or anything touching \`process.env\`, secrets, \`node:\` APIs) ships server code to
 the client and crashes hydration. Reach server resources through \`ctx.api\` / \`ctx.env\` (injected via
-\`createWebApp\`) inside the loader instead — never as a top-level import in a \`routes/\` file.
+\`createWebApp\`) inside the loader instead - never as a top-level import in a \`routes/\` file.
 `;
 }
 /** Per-ORM body of the DB rules: the query idiom, schema location, and migrate story all differ. */
@@ -133,11 +133,11 @@ singleton \`PrismaClient\`).
       c.db.note.create({ data: { title: c.body.title } }),
     )
   \`\`\`
-- **Migrations:** edit \`prisma/schema.prisma\`, then \`bun run db:migrate\` (\`prisma migrate dev\` — creates +
+- **Migrations:** edit \`prisma/schema.prisma\`, then \`bun run db:migrate\` (\`prisma migrate dev\` - creates +
   applies the migration and regenerates the client). \`bun run db:studio\` opens a DB browser.`;
     }
     if (orm === "kysely") {
-        return `A Kysely typed query builder is wired in \`db/\`: \`db/schema.ts\` (the DB-shape interface — keep it in
+        return `A Kysely typed query builder is wired in \`db/\`: \`db/schema.ts\` (the DB-shape interface - keep it in
 sync with your migrations) + \`db/index.ts\` (the typed client). You own the migrations (\`db/migrations/\`,
 run by \`db/migrate.ts\`).
 
@@ -176,25 +176,25 @@ typed client).
 - **Migrations:** edit \`db/schema.ts\`, then \`bun run db:generate\` (writes SQL to \`db/migrations\`) +
   \`bun run db:migrate\` (applies it). \`bun run db:studio\` opens a DB browser.`;
 }
-/** DB rules — only when scaffolded with `--db`. Teaches the wired data layer + the `c.db` seam. */
+/** DB rules - only when scaffolded with `--db`. Teaches the wired data layer + the `c.db` seam. */
 function dbRules(db) {
     const p = DB_PRESETS[db];
     return `## Database (${p.label})
 
 ${dbRulesBody(p.orm)} ${p.note}
 
-- **Query is fully typed** — types flow from the schema/model; \`c.db\` is typed end to end.
-- **Never top-level-import \`db\` into a \`routes/\` page file** — it's server-only; reach it via \`c.db\` on
+- **Query is fully typed** - types flow from the schema/model; \`c.db\` is typed end to end.
+- **Never top-level-import \`db\` into a \`routes/\` page file** - it's server-only; reach it via \`c.db\` on
   the backend (or \`ctx.api\` from a loader). A top-level import ships it to the browser and breaks the build.`;
 }
-/** Auth rules — only when scaffolded with `--auth`. Teaches the better-auth mount + the typed guards. */
+/** Auth rules - only when scaffolded with `--auth`. Teaches the better-auth mount + the typed guards. */
 function authRules(_auth) {
     return `## Authentication (better-auth)
 
 better-auth is configured in \`auth.ts\` (email/password + sessions, backed by your scaffolded database via
 its ORM adapter). nifra mounts it and gives you typed session guards via \`@nifrajs/better-auth\`.
 
-- **Mount it once** on the backend — it serves every auth endpoint under \`/api/auth/*\`:
+- **Mount it once** on the backend - it serves every auth endpoint under \`/api/auth/*\`:
   \`\`\`ts
   import { server } from "@nifrajs/core/server"
   import { betterAuth } from "@nifrajs/better-auth"
@@ -204,7 +204,7 @@ its ORM adapter). nifra mounts it and gives you typed session guards via \`@nifr
 - **Generate the auth tables** once, and after changing the config: \`bunx @better-auth/cli@latest generate\`
   writes them into your schema (\`db/schema.ts\` for Drizzle, \`prisma/schema.prisma\` for Prisma); then
   \`bun run db:migrate\`.
-- **Read / require a session** with the typed guards (pass the raw \`Request\` — \`c.req\` in a handler, or a
+- **Read / require a session** with the typed guards (pass the raw \`Request\` - \`c.req\` in a handler, or a
   loader's \`request\`):
   \`\`\`ts
   import { getSession, requireSession } from "@nifrajs/better-auth"
@@ -214,74 +214,74 @@ its ORM adapter). nifra mounts it and gives you typed session guards via \`@nifr
     return { id: user.id }
   })
   \`\`\`
-- \`auth\` is **server-only** — never import it into a \`routes/\` page, and keep \`BETTER_AUTH_SECRET\` in \`.env\`.`;
+- \`auth\` is **server-only** - never import it into a \`routes/\` page, and keep \`BETTER_AUTH_SECRET\` in \`.env\`.`;
 }
 const SECURITY_RULES = `## Production defaults (don't ship the happy path only)
 
-- **Dependencies: install current, never pin from memory.** Your training data lags npm by months — do
+- **Dependencies: install current, never pin from memory.** Your training data lags npm by months - do
   not hand-write a version range or reach for a remembered (often deprecated or vulnerable) API. Add a
-  dependency with \`bun add <pkg>\` so it resolves the **latest stable**, then use *that* version's API —
+  dependency with \`bun add <pkg>\` so it resolves the **latest stable**, then use *that* version's API -
   if unsure of a signature, read \`node_modules/<pkg>\`'s types or run \`bun pm view <pkg> version\`, don't
   guess. Never **downgrade** versions already in \`package.json\` (especially the pinned \`@nifrajs/*\` ones).
 - Validate at every trust boundary (above). Reject unknown fields and out-of-range values.
 - Constant-time comparison for secrets/tokens/HMACs (\`timingSafeEqual\` or WebCrypto), never \`===\`.
-- Verify ownership/permission on any resource a handler reads or mutates — auth'd ≠ authorized.
+- Verify ownership/permission on any resource a handler reads or mutates - auth'd ≠ authorized.
 - Idempotency on retryable side effects (webhooks, payments): short-circuit on a repeated key.
 - Money in integer minor units; timestamps as UTC; parse client dates at the boundary.
 - No secrets/PII in logs or error responses.
 `;
 const COMMANDS = {
-    api: `- \`bun install\` — install dependencies
-- \`bun run dev\` — run the API (watch mode)
-- \`bun test\` — drive \`app.fetch\` directly; no server required
-- \`nifra check\` — typecheck + typed-client lint (run before you call work done)`,
-    site: `- \`bun install\` — install dependencies
-- \`nifra dev\` — true-HMR dev server
-- \`nifra build\` — complete Bun deploy (server + content-hashed client assets)
-- \`nifra start\` — run the generated Bun server — pairs with \`nifra build\`
-- \`nifra check\` — typecheck + typed-client lint (run before you call work done)
+    api: `- \`bun install\` - install dependencies
+- \`bun run dev\` - run the API (watch mode)
+- \`bun test\` - drive \`app.fetch\` directly; no server required
+- \`nifra check\` - typecheck + typed-client lint (run before you call work done)`,
+    site: `- \`bun install\` - install dependencies
+- \`nifra dev\` - true-HMR dev server
+- \`nifra build\` - complete Bun deploy (server + content-hashed client assets)
+- \`nifra start\` - run the generated Bun server - pairs with \`nifra build\`
+- \`nifra check\` - typecheck + typed-client lint (run before you call work done)
 
   For a local production run use \`nifra build && nifra start\` (or \`bun run build:bun && bun run start\`). NOTE:
   the bare \`bun run build\` script targets **Cloudflare Pages for DEPLOY** (emits \`dist/\`, a different layout)
-  — it does NOT pair with \`nifra start\`/\`bun run start\` (which serve \`dist-bun/\`). Don't mix the two.`,
-    isr: `- \`bun install\` — install dependencies
-- \`nifra dev\` — true-HMR dev server
-- \`nifra build\` — complete Bun deploy (server + content-hashed client assets)
-- \`nifra start\` — run the generated Bun server (SSR + ISR cache) — pairs with \`nifra build\`
-- \`nifra check\` — typecheck + typed-client lint (run before you call work done)
+  - it does NOT pair with \`nifra start\`/\`bun run start\` (which serve \`dist-bun/\`). Don't mix the two.`,
+    isr: `- \`bun install\` - install dependencies
+- \`nifra dev\` - true-HMR dev server
+- \`nifra build\` - complete Bun deploy (server + content-hashed client assets)
+- \`nifra start\` - run the generated Bun server (SSR + ISR cache) - pairs with \`nifra build\`
+- \`nifra check\` - typecheck + typed-client lint (run before you call work done)
 
   For a local production run use \`nifra build && nifra start\`. NOTE: the bare \`bun run build\` script targets
-  **Cloudflare Pages for DEPLOY** (\`dist/\`) and does NOT pair with \`nifra start\` — don't mix the two.`,
-    fullstack: `- \`bun install\` — install dependencies
-- \`bun run dev\` — run the API (watch mode); \`src/index.ts\` also starts the job worker (\`queue.start()\`)
-- \`bun test\` — drives \`app.fetch\` directly (pagination, jobs via \`queue.drain()\`, cache, storage); no server required
-- \`bun run typecheck\` — run before you call work done
+  **Cloudflare Pages for DEPLOY** (\`dist/\`) and does NOT pair with \`nifra start\` - don't mix the two.`,
+    fullstack: `- \`bun install\` - install dependencies
+- \`bun run dev\` - run the API (watch mode); \`src/index.ts\` also starts the job worker (\`queue.start()\`)
+- \`bun test\` - drives \`app.fetch\` directly (pagination, jobs via \`queue.drain()\`, cache, storage); no server required
+- \`bun run typecheck\` - run before you call work done
 
   Wired: cursor pagination (\`t.pageQuery\`/\`t.paginated\`/\`paginate\`), background jobs (\`@nifrajs/jobs\`),
   a TTL cache (\`@nifrajs/cache\`), blob storage (\`@nifrajs/storage\`). Swap the in-memory \`notes\` store for
   your DB, and the memory cache/job/storage adapters for shared ones (Redis / CF KV / R2) when multi-process.`,
 };
-/** The agent's stop condition — what makes the anti-drift guarantees actually fire. */
-const DONE = `## Definition of done — run \`nifra check\`
+/** The agent's stop condition - what makes the anti-drift guarantees actually fire. */
+const DONE = `## Definition of done - run \`nifra check\`
 
-Before considering any change complete, run **\`nifra check\`**. It (1) typechecks — the frontend↔backend
+Before considering any change complete, run **\`nifra check\`**. It (1) typechecks - the frontend↔backend
 contract is compiler-enforced, so the typed client deriving \`res.data\` from your routes turns any
 mismatch into an error; (2) flags any hand-rolled \`fetch()\` to this app's own API (which bypasses that
 check); and (3) flags a server-only import (a DB driver, \`node:\`/\`bun:\`, \`./db\`) at the top level of a
-\`routes/\` page — that ships server code to the browser. Use \`nifra check --json\` for machine-readable
-diagnostics. A failing \`nifra check\` means the work isn't done — fix it, don't ship around it.`;
+\`routes/\` page - that ships server code to the browser. Use \`nifra check --json\` for machine-readable
+diagnostics. A failing \`nifra check\` means the work isn't done - fix it, don't ship around it.`;
 /** Build the full `AGENTS.md` for a freshly scaffolded app. */
 export function agentsMd(opts) {
     const isWeb = opts.template === "site" || opts.template === "isr";
     const what = isWeb
-        ? `a full-stack nifra app — a typed \`server()\` backend plus file-routed, server-rendered ${FRAMEWORK_LABEL[opts.framework]} pages`
-        : `a nifra API — a typed, contract-first \`server()\` backend`;
+        ? `a full-stack nifra app - a typed \`server()\` backend plus file-routed, server-rendered ${FRAMEWORK_LABEL[opts.framework]} pages`
+        : `a nifra API - a typed, contract-first \`server()\` backend`;
     // Each entry is a self-contained markdown block; join with a blank line between blocks. The web-rules
-    // block is empty for API templates — dropped before joining so there's no doubled blank line.
+    // block is empty for API templates - dropped before joining so there's no doubled blank line.
     const blocks = [
-        `# AGENTS.md — ${opts.name}\n\nGuidance for AI coding agents working in this repo. This is ${what}. nifra is Bun-native, Web-standard, and framework-agnostic; the same app runs on Bun, Node, Deno, and the edge.`,
+        `# AGENTS.md - ${opts.name}\n\nGuidance for AI coding agents working in this repo. This is ${what}. nifra is Bun-native, Web-standard, and framework-agnostic; the same app runs on Bun, Node, Deno, and the edge.`,
         `## Commands\n\n${COMMANDS[opts.template]}`,
-        // Surface the MCP early — an agent that learns the typechecked tools exist (and that `nifra check`
+        // Surface the MCP early - an agent that learns the typechecked tools exist (and that `nifra check`
         // is the done-gate) up front will reach for them instead of writing nifra from stale memory.
         agentsMcpSection(),
         API_RULES.trim(),
@@ -290,7 +290,7 @@ export function agentsMd(opts) {
         isWeb ? webRules(opts.framework).trim() : "",
         SECURITY_RULES.trim(),
         DONE,
-        "## Full reference\n\nThe complete, machine-readable API + docs live in **`llms-full.txt`** (served at the nifra site root). When you need an exact signature or a feature you haven't used, read that rather than guessing — it inlines every doc page and the export index.",
+        "## Full reference\n\nThe complete, machine-readable API + docs live in **`llms-full.txt`** (served at the nifra site root). When you need an exact signature or a feature you haven't used, read that rather than guessing - it inlines every doc page and the export index.",
     ];
     return `${blocks.filter(Boolean).join("\n\n")}\n`;
 }

package/dist/auth.d.ts

@@ -1,5 +1,5 @@
 /**
- * `--auth better-auth` — wire authentication into a scaffolded app, the same "bundle the right tool,
+ * `--auth better-auth` - wire authentication into a scaffolded app, the same "bundle the right tool,
  * correctly" move as `--db`. nifra owns the *mount* (`@nifrajs/better-auth` plugs better-auth's handler
  * into a `server()` and gives typed `getSession`/`requireSession` guards); better-auth owns the auth
  * logic. Auth needs a database, so this composes with `--db`: the generated `auth.ts` reuses the client
@@ -7,7 +7,7 @@
  * agent then runs `bunx @better-auth/cli generate` to add the auth tables and migrates.
  *
  * `--auth` therefore requires `--db` (the CLI enforces it). better-auth's clean adapters cover Drizzle
- * and Prisma; Kysely is rejected (it has no drop-in adapter — wire better-auth's own dialect manually).
+ * and Prisma; Kysely is rejected (it has no drop-in adapter - wire better-auth's own dialect manually).
  * One preset today: `better-auth`.
  */
 import { type DbChoice } from "./db.js";

package/dist/auth.js

@@ -1,5 +1,5 @@
 /**
- * `--auth better-auth` — wire authentication into a scaffolded app, the same "bundle the right tool,
+ * `--auth better-auth` - wire authentication into a scaffolded app, the same "bundle the right tool,
  * correctly" move as `--db`. nifra owns the *mount* (`@nifrajs/better-auth` plugs better-auth's handler
  * into a `server()` and gives typed `getSession`/`requireSession` guards); better-auth owns the auth
  * logic. Auth needs a database, so this composes with `--db`: the generated `auth.ts` reuses the client
@@ -7,14 +7,14 @@
  * agent then runs `bunx @better-auth/cli generate` to add the auth tables and migrates.
  *
  * `--auth` therefore requires `--db` (the CLI enforces it). better-auth's clean adapters cover Drizzle
- * and Prisma; Kysely is rejected (it has no drop-in adapter — wire better-auth's own dialect manually).
+ * and Prisma; Kysely is rejected (it has no drop-in adapter - wire better-auth's own dialect manually).
  * One preset today: `better-auth`.
  */
 import { appendFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { DB_PRESETS } from "./db.js";
 export const AUTH_CHOICES = ["better-auth"];
-/** ORMs better-auth wires via a drop-in adapter. Kysely is excluded — see {@link assertAuthableDb}. */
+/** ORMs better-auth wires via a drop-in adapter. Kysely is excluded - see {@link assertAuthableDb}. */
 const AUTHABLE_ORMS = new Set(["drizzle", "prisma"]);
 /**
  * Guard `--auth` against a DB whose ORM has no clean better-auth adapter. Throws an actionable error
@@ -31,9 +31,9 @@ export function assertAuthableDb(db) {
 export const AUTH_PRESETS = {
     "better-auth": {
         label: "better-auth",
-        note: "email/password + sessions, mounted at /api/auth/* — add OAuth providers in auth.ts.",
+        note: "email/password + sessions, mounted at /api/auth/* - add OAuth providers in auth.ts.",
         // @nifrajs/better-auth mounts it; better-auth is the implementation (peer-installed alongside).
-        deps: { "@nifrajs/better-auth": "^2.1.0", "better-auth": "^1.2.0" },
+        deps: { "@nifrajs/better-auth": "^2.3.0", "better-auth": "^1.2.0" },
     },
 };
 /** The better-auth `database` adapter expression + its import line, for the scaffolded DB's ORM. */
@@ -54,7 +54,7 @@ function adapterFor(db) {
         database: `drizzleAdapter(db, { provider: "${provider}" })`,
     };
 }
-/** The generated `auth.ts` — a better-auth instance backed by the scaffolded DB client. */
+/** The generated `auth.ts` - a better-auth instance backed by the scaffolded DB client. */
 function authModule(db) {
     const { importLine, database } = adapterFor(db);
     return `import { betterAuth as createBetterAuth } from "better-auth"
@@ -67,7 +67,7 @@ import { db } from "./db"
 export const auth = createBetterAuth({
   database: ${database},
   emailAndPassword: { enabled: true },
-  // Set in .env — generate a strong value: openssl rand -base64 32
+  // Set in .env - generate a strong value: openssl rand -base64 32
   secret: process.env.BETTER_AUTH_SECRET,
   baseURL: process.env.BETTER_AUTH_URL,
 })
@@ -76,7 +76,7 @@ export type Auth = typeof auth
 `;
 }
 const ENV = `
-# better-auth — REQUIRED. Generate a 32+ char secret: openssl rand -base64 32
+# better-auth - REQUIRED. Generate a 32+ char secret: openssl rand -base64 32
 BETTER_AUTH_SECRET="change-me-before-production"
 BETTER_AUTH_URL="http://localhost:3000"
 `;