create-nifra 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# create-nifra
+
+Scaffold a new [nifra](../../README.md) app.
+
+```sh
+bun create nifra my-app
+# or:  npm create nifra my-app
+```
+
+## Templates
+
+`--template <name>` (default `api`):
+
+- **`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
+  Vercel Edge.
+- **`isr`** — a nifra + React app with **Incremental Static Regeneration** on Cloudflare Workers + KV
+  (pages cached + served stale-while-revalidate; on-demand purge endpoint).
+
+```sh
+bun create nifra my-app --template isr
+```
+
+Then:
+
+```sh
+cd my-app
+bun install
+bun run dev
+```
+
+MIT.

package/dist/agents.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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
+ * server-only code into a route module. Tailored per template so the paths + commands are real.
+ */
+import type { AuthChoice } from "./auth.js";
+import type { Framework, TemplateName } from "./cli.js";
+import { type DbChoice } from "./db.js";
+export interface AgentsMdOptions {
+    readonly template: TemplateName;
+    readonly framework: Framework;
+    readonly name: string;
+    /** Drizzle preset, when scaffolded with `--db` — adds a Database section. */
+    readonly db?: DbChoice;
+    /** Auth preset, when scaffolded with `--auth` — adds an Authentication section. */
+    readonly auth?: AuthChoice;
+}
+/** Build the full `AGENTS.md` for a freshly scaffolded app. */
+export declare function agentsMd(opts: AgentsMdOptions): string;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,EAAc,KAAK,QAAQ,EAAiB,MAAM,SAAS,CAAA;AAgPlE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAA;IACtB,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;CAC3B;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAoBtD"}

package/dist/agents.js

@@ -0,0 +1,259 @@
+/**
+ * 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
+ * server-only code into a route module. Tailored per template so the paths + commands are real.
+ */
+import { DB_PRESETS } from "./db.js";
+const FRAMEWORK_LABEL = {
+    react: "React",
+    solid: "Solid",
+    vue: "Vue",
+    preact: "Preact",
+    svelte: "Svelte",
+};
+/** Shared backend rules — every template is, at its core, a nifra `server()`. */
+const API_RULES = `## The backend: \`server()\`
+
+\`\`\`ts
+import { server } from "@nifrajs/core"
+import { t } from "@nifrajs/schema"
+
+export const app = server()
+  .get("/users/:id", { response: t.object({ id: t.string() }) }, (c) => ({ id: c.params.id }))
+  .post(
+    "/users",
+    // body validates the input; response LOCKS the output shape (the contract).
+    { body: t.object({ name: t.string() }), response: t.object({ id: t.string(), name: t.string() }) },
+    (c) => {
+      // c.body is VALIDATED + TYPED. Invalid input was already rejected with a 400 before this ran.
+      return { id: crypto.randomUUID(), name: c.body.name }
+    },
+  )
+
+export type App = typeof app
+\`\`\`
+
+Rules an agent must follow:
+
+- **Validate every input at the boundary.** Pass a schema (\`{ body, query, params, headers }\`) on any
+  route that reads untrusted input — use \`t\` from \`@nifrajs/schema\` or any Standard Schema (zod, valibot).
+  Then read \`c.body\` / \`c.query\` / \`c.params\`, which are typed and already validated. **Never** hand-parse
+  \`await c.req.json()\` and poke at properties — that's the bug class the schema exists to remove.
+- **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.
+- **Return values, not boilerplate.** Returning a plain object/array/string sends JSON. Return a
+  \`Response\` for full control, or \`new Response(..., { status })\` for errors. Prefer explicit error
+  shapes (\`{ ok: false, error: "slot_unavailable" }\`) with the right status over generic 500s.
+- **\`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.
+
+## 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
+
+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
+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
+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. */
+function webRules(framework) {
+    const label = FRAMEWORK_LABEL[framework];
+    return `## The frontend: file routing + loaders (${label})
+
+- Routes live in \`routes/\`. \`index.tsx\` → \`/\`, \`[id].tsx\` → \`/:id\`, \`_layout.tsx\` wraps a subtree,
+  \`_404.tsx\` / \`_error.tsx\` are the fallbacks.
+- 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.
+- Swap UI frameworks by changing one import (\`@nifrajs/web-${framework}\` → another adapter); your route,
+  loader, and action code do not change.
+- **Loaders \`throw redirect(url)\`, actions \`return redirect(url)\`.** Loader redirects abort the
+  render server-side; action redirects return a response so client form submits get \`X-Nifra-Redirect\`
+  and navigate without a full reload. Throwing in an action or returning in a loader is a silent bug
+  that produces a false "operation failed" error on the client.
+
+## ⚠️ 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
+\`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.
+`;
+}
+/** Per-ORM body of the DB rules: the query idiom, schema location, and migrate story all differ. */
+function dbRulesBody(orm) {
+    if (orm === "prisma") {
+        return `A Prisma data layer is wired: \`prisma/schema.prisma\` (a starter \`Note\` model) + \`db/index.ts\` (a
+singleton \`PrismaClient\`).
+
+- **Wire it into the backend once**, then read \`c.db\` in handlers:
+  \`\`\`ts
+  import { server } from "@nifrajs/core"
+  import { t } from "@nifrajs/schema"
+  import { db } from "./db"
+
+  export const app = server()
+    .decorate("db", db)
+    .get("/notes", async (c) => c.db.note.findMany({ where: { deletedAt: null } }))
+    .post("/notes", { body: t.object({ title: t.string({ minLength: 1 }) }) }, async (c) =>
+      c.db.note.create({ data: { title: c.body.title } }),
+    )
+  \`\`\`
+- **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
+sync with your migrations) + \`db/index.ts\` (the typed client). You own the migrations (\`db/migrations/\`,
+run by \`db/migrate.ts\`).
+
+- **Wire it into the backend once**, then read \`c.db\` in handlers:
+  \`\`\`ts
+  import { server } from "@nifrajs/core"
+  import { t } from "@nifrajs/schema"
+  import { db } from "./db"
+
+  export const app = server()
+    .decorate("db", db)
+    .get("/notes", async (c) =>
+      c.db.selectFrom("notes").selectAll().where("deleted_at", "is", null).execute())
+    .post("/notes", { body: t.object({ title: t.string({ minLength: 1 }) }) }, async (c) =>
+      c.db.insertInto("notes").values({ title: c.body.title }).returningAll().executeTakeFirstOrThrow())
+  \`\`\`
+- **Migrations:** add a file to \`db/migrations/\` (copy the \`0001_create_notes.ts\` shape), update the
+  \`db/schema.ts\` interface to match, then \`bun run db:migrate\`.`;
+    }
+    return `A Drizzle data layer is wired in \`db/\`: \`db/schema.ts\` (a starter \`notes\` table) + \`db/index.ts\` (the
+typed client).
+
+- **Wire it into the backend once**, then read \`c.db\` in handlers:
+  \`\`\`ts
+  import { server } from "@nifrajs/core"
+  import { t } from "@nifrajs/schema"
+  import { db, notes } from "./db"
+
+  export const app = server()
+    .decorate("db", db)
+    .get("/notes", async (c) => c.db.select().from(notes))
+    .post("/notes", { body: t.object({ title: t.string({ minLength: 1 }) }) }, async (c) =>
+      (await c.db.insert(notes).values({ title: c.body.title }).returning())[0],
+    )
+  \`\`\`
+- **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. */
+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
+  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. */
+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/*\`:
+  \`\`\`ts
+  import { server } from "@nifrajs/core"
+  import { betterAuth } from "@nifrajs/better-auth"
+  import { auth } from "./auth"
+  export const app = server().use(betterAuth(auth))
+  \`\`\`
+- **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
+  loader's \`request\`):
+  \`\`\`ts
+  import { getSession, requireSession } from "@nifrajs/better-auth"
+  app.get("/me", async (c) => (await getSession(auth, c.req))?.user ?? null)
+  app.get("/account", async (c) => {
+    const { user } = await requireSession(auth, c.req) // throws a 401 Response when signed out
+    return { id: user.id }
+  })
+  \`\`\`
+- \`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
+  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 —
+  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.
+- 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\` — content-hashed client bundle + manifest
+- \`nifra start\` — serve the built app (SSR)
+- \`nifra check\` — typecheck + typed-client lint (run before you call work done)`,
+    isr: `- \`bun install\` — install dependencies
+- \`nifra dev\` — true-HMR dev server
+- \`nifra build\` — build for your deploy target
+- \`nifra start\` — serve the built app (SSR + ISR cache)
+- \`nifra check\` — typecheck + typed-client lint (run before you call work done)`,
+};
+/** 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
+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.`;
+/** 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`;
+    // 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.
+    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.`,
+        `## Commands\n\n${COMMANDS[opts.template]}`,
+        API_RULES.trim(),
+        opts.db !== undefined ? dbRules(opts.db) : "",
+        opts.auth !== undefined ? authRules(opts.auth) : "",
+        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.",
+    ];
+    return `${blocks.filter(Boolean).join("\n\n")}\n`;
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

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

package/dist/auth.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `--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
+ * from `./db` via better-auth's adapter for the chosen ORM (`drizzleAdapter` / `prismaAdapter`). The
+ * 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).
+ * One preset today: `better-auth`.
+ */
+import { type DbChoice } from "./db.js";
+export declare const AUTH_CHOICES: readonly ["better-auth"];
+export type AuthChoice = (typeof AUTH_CHOICES)[number];
+/**
+ * Guard `--auth` against a DB whose ORM has no clean better-auth adapter. Throws an actionable error
+ * for Kysely (passing a raw dialect to better-auth is manual wiring we won't fake-scaffold). Called by
+ * the CLI before scaffolding so the failure is early and explains the fix.
+ */
+export declare function assertAuthableDb(db: DbChoice): void;
+export interface AuthPreset {
+    readonly label: string;
+    readonly note: string;
+    readonly deps: Readonly<Record<string, string>>;
+}
+export declare const AUTH_PRESETS: Readonly<Record<AuthChoice, AuthPreset>>;
+/** Write `auth.ts` and append the auth env vars to the (db-preset-created) `.env.example`. */
+export declare function writeAuthFiles(target: string, _auth: AuthChoice, db: DbChoice): Promise<void>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAc,KAAK,QAAQ,EAAY,MAAM,SAAS,CAAA;AAE7D,eAAO,MAAM,YAAY,0BAA2B,CAAA;AACpD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAKtD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,CAQnD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAChD;AAED,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAOjE,CAAA;AAiDD,8FAA8F;AAC9F,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,QAAQ,GACX,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/auth.js

@@ -0,0 +1,90 @@
+/**
+ * `--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
+ * from `./db` via better-auth's adapter for the chosen ORM (`drizzleAdapter` / `prismaAdapter`). The
+ * 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).
+ * 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}. */
+const AUTHABLE_ORMS = new Set(["drizzle", "prisma"]);
+/**
+ * Guard `--auth` against a DB whose ORM has no clean better-auth adapter. Throws an actionable error
+ * for Kysely (passing a raw dialect to better-auth is manual wiring we won't fake-scaffold). Called by
+ * the CLI before scaffolding so the failure is early and explains the fix.
+ */
+export function assertAuthableDb(db) {
+    const { orm } = DB_PRESETS[db];
+    if (!AUTHABLE_ORMS.has(orm)) {
+        throw new Error(`--auth better-auth doesn't scaffold for --db ${db} (${orm} has no drop-in better-auth adapter). ` +
+            "Use a drizzle-* or prisma-* preset, or wire better-auth's database dialect manually in auth.ts.");
+    }
+}
+export const AUTH_PRESETS = {
+    "better-auth": {
+        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": "^0.1.0", "better-auth": "^1.2.0" },
+    },
+};
+/** The better-auth `database` adapter expression + its import line, for the scaffolded DB's ORM. */
+function adapterFor(db) {
+    const { orm, dialect } = DB_PRESETS[db];
+    if (orm === "prisma") {
+        // Prisma's adapter `provider` is the datasource name ("postgresql"), not Drizzle's "pg".
+        const provider = dialect === "postgres" ? "postgresql" : "sqlite";
+        return {
+            importLine: `import { prismaAdapter } from "better-auth/adapters/prisma"`,
+            database: `prismaAdapter(db, { provider: "${provider}" })`,
+        };
+    }
+    // Drizzle (the only other authable ORM; Kysely is rejected upstream by assertAuthableDb).
+    const provider = dialect === "postgres" ? "pg" : "sqlite";
+    return {
+        importLine: `import { drizzleAdapter } from "better-auth/adapters/drizzle"`,
+        database: `drizzleAdapter(db, { provider: "${provider}" })`,
+    };
+}
+/** 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"
+${importLine}
+import { db } from "./db"
+
+// better-auth stores users + sessions in your database (the same one in db/). After editing the config
+// (e.g. adding OAuth providers), generate its tables: \`bunx @better-auth/cli generate\` writes the auth
+// schema for your ORM, then \`bun run db:migrate\` applies it.
+export const auth = createBetterAuth({
+  database: ${database},
+  emailAndPassword: { enabled: true },
+  // Set in .env — generate a strong value: openssl rand -base64 32
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: process.env.BETTER_AUTH_URL,
+})
+
+export type Auth = typeof auth
+`;
+}
+const ENV = `
+# 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"
+`;
+/** Write `auth.ts` and append the auth env vars to the (db-preset-created) `.env.example`. */
+export async function writeAuthFiles(target, _auth, db) {
+    assertAuthableDb(db); // defensive: the CLI already checks, but never emit a broken adapter import
+    await writeFile(join(target, "auth.ts"), authModule(db));
+    // .env.example already exists (the DB preset wrote it; `--auth` requires `--db`); append, don't clobber.
+    await appendFile(join(target, ".env.example"), ENV);
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,UAAU,EAA2B,MAAM,SAAS,CAAA;AAE7D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,aAAa,CAAU,CAAA;AAGpD,uGAAuG;AACvG,MAAM,aAAa,GAAqB,IAAI,GAAG,CAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAA;AAE3E;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAY;IAC3C,MAAM,EAAE,GAAG,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC,CAAA;IAC9B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,gDAAgD,EAAE,KAAK,GAAG,wCAAwC;YAChG,iGAAiG,CACpG,CAAA;IACH,CAAC;AACH,CAAC;AAQD,MAAM,CAAC,MAAM,YAAY,GAA6C;IACpE,aAAa,EAAE;QACb,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,qFAAqF;QAC3F,gGAAgG;QAChG,IAAI,EAAE,EAAE,sBAAsB,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE;KACpE;CACF,CAAA;AAED,oGAAoG;AACpG,SAAS,UAAU,CAAC,EAAY;IAC9B,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC,CAAA;IACvC,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;QACrB,yFAAyF;QACzF,MAAM,QAAQ,GAAG,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAA;QACjE,OAAO;YACL,UAAU,EAAE,6DAA6D;YACzE,QAAQ,EAAE,kCAAkC,QAAQ,MAAM;SAC3D,CAAA;IACH,CAAC;IACD,0FAA0F;IAC1F,MAAM,QAAQ,GAAG,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAA;IACzD,OAAO;QACL,UAAU,EAAE,+DAA+D;QAC3E,QAAQ,EAAE,mCAAmC,QAAQ,MAAM;KAC5D,CAAA;AACH,CAAC;AAED,2FAA2F;AAC3F,SAAS,UAAU,CAAC,EAAY;IAC9B,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC,CAAA;IAC/C,OAAO;EACP,UAAU;;;;;;;cAOE,QAAQ;;;;;;;;CAQrB,CAAA;AACD,CAAC;AAED,MAAM,GAAG,GAAG;;;;CAIX,CAAA;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,KAAiB,EACjB,EAAY;IAEZ,gBAAgB,CAAC,EAAE,CAAC,CAAA,CAAC,4EAA4E;IACjG,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAA;IACxD,yGAAyG;IACzG,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,GAAG,CAAC,CAAA;AACrD,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { type AuthChoice } from "./auth.js";
+import { type DbChoice } from "./db.js";
+declare const TEMPLATES: {
+    readonly api: "../template";
+    readonly site: "../template-site";
+    readonly isr: "../template-isr";
+};
+export type TemplateName = keyof typeof TEMPLATES;
+/** Frontend frameworks the `site` template can scaffold. React is the default (`template-site`); the
+ * rest live in `template-site-<framework>` siblings — same multi-target deploy story, different adapter
+ * + routes. */
+declare const FRAMEWORKS: readonly ["react", "preact", "vue", "solid", "svelte"];
+export type Framework = (typeof FRAMEWORKS)[number];
+/**
+ * Deploy targets for the multi-target `site` template. Every target's build + server entry already ships
+ * in the template; choosing one repoints the canonical `build`/`deploy` scripts at it (the per-target
+ * `build:*` scripts stay, so you can still switch). nifra never runs the deploy or enters credentials —
+ * `deploy` shells out to the vendor CLI you've authed yourself.
+ */
+interface DeployPreset {
+    readonly label: string;
+    readonly build: string;
+    /** `deploy` script; `NAME` is replaced with the app directory name. */
+    readonly deploy: string;
+    readonly steps: readonly string[];
+}
+/**
+ * Build a GitHub Actions workflow that builds on every push/PR and deploys `target` on a push to `main`.
+ * Reuses the canonical `bun run build` (the deploy preset repoints it), then runs the target's official
+ * deploy mechanism. Exported for unit tests. Throws on an unknown target.
+ */
+export declare function githubDeployWorkflow(target: string, appName: string): string;
+export interface ScaffoldOptions {
+    /** Destination directory. */
+    readonly target: string;
+    /** Template to copy. Default `"api"`. */
+    readonly template?: TemplateName;
+    /** Frontend framework (site template only). Default `"react"`. */
+    readonly framework?: string;
+    /** Deploy target (site template only) — repoints the default `build`/`deploy` scripts. */
+    readonly deploy?: string;
+    /** Emit a CI deploy workflow for the chosen `--deploy` target. Only `"github"` today. */
+    readonly ci?: string;
+    /** Wire a data layer: `drizzle-{libsql,postgres,sqlite}` | `prisma-{postgres,sqlite}` | `kysely-postgres`. */
+    readonly db?: string;
+    /** Wire authentication: `better-auth` (requires `--db` — auth needs a database). */
+    readonly auth?: string;
+    /** Allow scaffolding into a non-empty directory (copies template, overwrites collisions). */
+    readonly force?: boolean;
+    /** Path to a local nifra monorepo — replaces `@nifrajs/*` semver deps with `file:` refs so
+     *  the app runs against the local source before the packages are published to npm. */
+    readonly link?: string;
+}
+export interface ScaffoldResult {
+    readonly name: string;
+    readonly template: TemplateName;
+    readonly framework?: Framework;
+    readonly deploy?: DeployPreset;
+    /** The CI provider a workflow was generated for, when `--ci` was passed. */
+    readonly ci?: "github";
+    /** Repo secrets the generated workflow needs (for the next-steps message). */
+    readonly ciSecrets?: readonly string[];
+    /** The Drizzle preset wired in, when `--db` was passed. */
+    readonly db?: DbChoice;
+    /** The auth preset wired in, when `--auth` was passed. */
+    readonly auth?: AuthChoice;
+    /** Local nifra monorepo path when `--link` was used; undefined when using published packages. */
+    readonly link?: string;
+}
+/**
+ * Copy a template into `target` and finalize it (gitignore rename, package name, optional deploy preset).
+ * Throws on: unknown template, `--deploy` with a non-site template, unknown deploy target, or an existing
+ * destination. Pure enough to unit-test (no argv, no process.exit).
+ */
+export declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
+interface ParsedArgs {
+    readonly target?: string;
+    readonly template?: TemplateName;
+    readonly framework?: string;
+    readonly deploy?: string;
+    readonly ci?: string;
+    readonly db?: string;
+    readonly auth?: string;
+    readonly force?: boolean;
+    readonly link?: string;
+}
+/** Parse `[dir] [--template|-t <t>] [--framework|-f <fw>] [--deploy|-d <target>] [--ci|-c github]
+ *  [--db <preset>] [--auth <preset>] [--force] [--link <path>]`.
+ * `--framework`/`--deploy`/`--ci` all default the template to `site`. */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/**
+ * Run the CLI for `argv` and return the exit code + the message to print — no `process.exit`, `console`,
+ * or `process.argv`, so the whole flow (parse → scaffold → next-steps) is unit-testable in-process.
+ */
+export declare function run(argv: readonly string[]): Promise<{
+    code: 0 | 1;
+    message: string;
+}>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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