create-nifra 2.0.0 → 2.2.0

package/dist/auth.js

@@ -33,7 +33,7 @@ export const AUTH_PRESETS = {
         label: "better-auth",
         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.0.0", "better-auth": "^1.2.0" },
+        deps: { "@nifrajs/better-auth": "^2.2.0", "better-auth": "^1.2.0" },
     },
 };
 /** The better-auth `database` adapter expression + its import line, for the scaffolded DB's ORM. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nifra",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Scaffold a new nifra app — `bun create nifra <dir>`.",
   "keywords": [
     "bun",
@@ -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/package.json

@@ -10,9 +10,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.0.0",
-    "@nifrajs/core": "^2.0.0",
-    "@nifrajs/schema": "^2.0.0"
+    "@nifrajs/client": "^2.2.0",
+    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/schema": "^2.2.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/template-isr/package.json

@@ -9,16 +9,16 @@
     "dev:bun": "bun run server.ts"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.0.0",
-    "@nifrajs/core": "^2.0.0",
-    "@nifrajs/schema": "^2.0.0",
-    "@nifrajs/web": "^2.0.0",
-    "@nifrajs/web-react": "^2.0.0",
+    "@nifrajs/client": "^2.2.0",
+    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/schema": "^2.2.0",
+    "@nifrajs/web": "^2.2.0",
+    "@nifrajs/web-react": "^2.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@nifrajs/cli": "^2.0.0",
+    "@nifrajs/cli": "^2.2.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3"

package/template-site/package.json

@@ -17,20 +17,20 @@
     "deploy:vercel": "vercel deploy --prebuilt"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.0.0",
-    "@nifrajs/core": "^2.0.0",
-    "@nifrajs/schema": "^2.0.0",
-    "@nifrajs/deno": "^2.0.0",
-    "@nifrajs/node": "^2.0.0",
-    "@nifrajs/web": "^2.0.0",
-    "@nifrajs/web-react": "^2.0.0",
+    "@nifrajs/client": "^2.2.0",
+    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/schema": "^2.2.0",
+    "@nifrajs/deno": "^2.2.0",
+    "@nifrajs/node": "^2.2.0",
+    "@nifrajs/web": "^2.2.0",
+    "@nifrajs/web-react": "^2.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@nifrajs/cli": "^2.0.0",
+    "@nifrajs/cli": "^2.2.0",
     "@vitejs/plugin-react": "^4.3.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.0"

package/template-site-preact/package.json

@@ -17,18 +17,18 @@
     "deploy:vercel": "vercel deploy --prebuilt"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.0.0",
-    "@nifrajs/core": "^2.0.0",
-    "@nifrajs/schema": "^2.0.0",
-    "@nifrajs/deno": "^2.0.0",
-    "@nifrajs/node": "^2.0.0",
-    "@nifrajs/web": "^2.0.0",
-    "@nifrajs/web-preact": "^2.0.0",
+    "@nifrajs/client": "^2.2.0",
+    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/schema": "^2.2.0",
+    "@nifrajs/deno": "^2.2.0",
+    "@nifrajs/node": "^2.2.0",
+    "@nifrajs/web": "^2.2.0",
+    "@nifrajs/web-preact": "^2.2.0",
     "preact": "^10.25.0"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.9.0",
-    "@nifrajs/cli": "^2.0.0",
+    "@nifrajs/cli": "^2.2.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.0"
   }

package/template-site-solid/package.json

@@ -17,17 +17,17 @@
     "deploy:vercel": "vercel deploy --prebuilt"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.0.0",
-    "@nifrajs/core": "^2.0.0",
-    "@nifrajs/schema": "^2.0.0",
-    "@nifrajs/deno": "^2.0.0",
-    "@nifrajs/node": "^2.0.0",
-    "@nifrajs/web": "^2.0.0",
-    "@nifrajs/web-solid": "^2.0.0",
+    "@nifrajs/client": "^2.2.0",
+    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/schema": "^2.2.0",
+    "@nifrajs/deno": "^2.2.0",
+    "@nifrajs/node": "^2.2.0",
+    "@nifrajs/web": "^2.2.0",
+    "@nifrajs/web-solid": "^2.2.0",
     "solid-js": "^1.9.0"
   },
   "devDependencies": {
-    "@nifrajs/cli": "^2.0.0",
+    "@nifrajs/cli": "^2.2.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.0",
     "vite-plugin-solid": "^2.10.0"

package/template-site-svelte/package.json

@@ -17,18 +17,18 @@
     "deploy:vercel": "vercel deploy --prebuilt"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.0.0",
-    "@nifrajs/core": "^2.0.0",
-    "@nifrajs/schema": "^2.0.0",
-    "@nifrajs/deno": "^2.0.0",
-    "@nifrajs/node": "^2.0.0",
-    "@nifrajs/web": "^2.0.0",
-    "@nifrajs/web-svelte": "^2.0.0",
+    "@nifrajs/client": "^2.2.0",
+    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/schema": "^2.2.0",
+    "@nifrajs/deno": "^2.2.0",
+    "@nifrajs/node": "^2.2.0",
+    "@nifrajs/web": "^2.2.0",
+    "@nifrajs/web-svelte": "^2.2.0",
     "svelte": "^5.3.0"
   },
   "devDependencies": {
     "@sveltejs/vite-plugin-svelte": "^5.0.0",
-    "@nifrajs/cli": "^2.0.0",
+    "@nifrajs/cli": "^2.2.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.0"
   }

package/template-site-vue/package.json

@@ -17,17 +17,17 @@
     "deploy:vercel": "vercel deploy --prebuilt"
   },
   "dependencies": {
-    "@nifrajs/client": "^2.0.0",
-    "@nifrajs/core": "^2.0.0",
-    "@nifrajs/schema": "^2.0.0",
-    "@nifrajs/deno": "^2.0.0",
-    "@nifrajs/node": "^2.0.0",
-    "@nifrajs/web": "^2.0.0",
-    "@nifrajs/web-vue": "^2.0.0",
+    "@nifrajs/client": "^2.2.0",
+    "@nifrajs/core": "^2.2.0",
+    "@nifrajs/schema": "^2.2.0",
+    "@nifrajs/deno": "^2.2.0",
+    "@nifrajs/node": "^2.2.0",
+    "@nifrajs/web": "^2.2.0",
+    "@nifrajs/web-vue": "^2.2.0",
     "vue": "^3.5.0"
   },
   "devDependencies": {
-    "@nifrajs/cli": "^2.0.0",
+    "@nifrajs/cli": "^2.2.0",
     "@vitejs/plugin-vue": "^5.2.0",
     "@vue/compiler-sfc": "^3.5.0",
     "typescript": "^6.0.3",