@flaredev/cli 0.10.0 → 0.12.0

package/templates/next/.env.example

@@ -1,20 +1,36 @@
-# Postgres, from your Neon project (Dashboard → Connection string).
-DATABASE_URL=
+# Copy to .env. `flare create` already wrote one with a secret and the local service
+# addresses below, so this file is here for the values you change when you deploy.
+#
+# Two ways to run the services this app needs:
+#
+#   With Docker     docker compose up -d     — Postgres, MinIO and Redis on your machine.
+#                                              The values below already match it.
+#   Without Docker  Neon, Cloudflare R2 and Upstash. Replace the values below with theirs.
+#
+# Nothing in the app knows which you chose: MinIO speaks S3 like R2, and the Redis proxy
+# speaks Upstash's REST protocol.
+
+# Postgres. Docker: the compose file. Hosted: Neon (Dashboard -> Connection string),
+# pooled rather than direct.
+DATABASE_URL=postgresql://flare:flare@127.0.0.1:5432/app
 
 # Sessions and signed upload URLs. Generate with: openssl rand -base64 32
 BETTER_AUTH_SECRET=
+# A bare origin: no trailing slash, or every sign-in returns 403.
 BETTER_AUTH_URL=http://localhost:3000
 
-# File uploads, on an R2 bucket (Cloudflare → R2 → Manage API tokens).
-# R2 serves what it stores for free, which is why it's here rather than Blob storage.
-R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
-R2_BUCKET=
-R2_ACCESS_KEY_ID=
-R2_SECRET_ACCESS_KEY=
+# File uploads. Docker: MinIO, below. Hosted: an R2 bucket (Cloudflare -> R2 -> Manage
+# API tokens). R2 serves what it stores for free, which is why it is here rather than
+# Blob storage.
+R2_ENDPOINT=http://127.0.0.1:9000
+R2_BUCKET=app-uploads
+R2_ACCESS_KEY_ID=flare
+R2_SECRET_ACCESS_KEY=flare-secret-123
 
 # Optional. Rate limits and anything that has to be true across every instance.
-UPSTASH_REDIS_REST_URL=
-UPSTASH_REDIS_REST_TOKEN=
+# Docker: the serverless-redis-http proxy. Hosted: Upstash.
+UPSTASH_REDIS_REST_URL=http://127.0.0.1:8079
+UPSTASH_REDIS_REST_TOKEN=flare-local-token
 
 # Optional. Without these, email is printed to the console instead of sent.
 RESEND_API_KEY=

package/templates/next/README.md

@@ -2,15 +2,47 @@
 
 A [Flare](https://flare-docs.codetotech.com) app on Next.js, Postgres and Prisma.
 
+## Local development
+
 ```bash
 cp .env.example .env       # DATABASE_URL and BETTER_AUTH_SECRET, at least
-__PM__ run db:migrate      # prisma migrate dev: write and apply a migration
+__PM__ run db:migrate      # prisma migrate dev: write and apply a migration locally
+__PM__ run db:seed         # run seed files in seeds/
 __PM__ run dev             # start the dev server on http://localhost:3000
-__PM__ run build           # production build
-__PM__ run deploy          # deploy to Vercel
 ```
 
 After `flare gen resource`, run `__PM__ run db:migrate` to turn the new models
 in `prisma/schema/resources.prisma` into a migration.
 
+## Deploying to Vercel
+
+Vercel builds on its own machines, but **does not touch your database during deployment**. A newly provisioned Postgres database starts empty; attempting to sign up or sign in before applying migrations will fail with `500 Internal Server Error`.
+
+Apply migrations and initial seeds once from your local machine against your production database:
+
+```bash
+# 1. Apply existing migrations to production (runs prisma migrate deploy)
+DATABASE_URL="<your POSTGRES_PRISMA_URL>" npx flare migrate
+
+# 2. Seed initial data (if needed)
+DATABASE_URL="<your POSTGRES_PRISMA_URL>" __PM__ run db:seed
+```
+
+### Production Database Notes:
+- **`POSTGRES_PRISMA_URL` vs `DATABASE_URL`**: Vercel Postgres integration defines `POSTGRES_PRISMA_URL`. Flare and Prisma look for `DATABASE_URL`. Pass it inline as shown above rather than rewriting your local `.env`.
+- **Do not run `prisma migrate dev` against production**: Cloud databases reject creating shadow databases. Use `npx flare migrate` (`prisma migrate deploy`) or `npx prisma db push`.
+- **`BETTER_AUTH_URL`**: Set without a trailing slash (e.g. `https://myapp.vercel.app`) to avoid 403 origin mismatch errors.
+
+Full guide: https://flare-docs.codetotech.com/guides/vercel-deployment/
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `__PM__ run dev` | Start dev server on http://localhost:3000 |
+| `__PM__ run build` | Generate Prisma client and create production Next.js build |
+| `__PM__ run deploy` | Deploy to Vercel (`vercel deploy --prod`) |
+| `__PM__ run db:migrate` | Create and apply migrations locally (`prisma migrate dev`) |
+| `__PM__ run db:seed` | Run seed scripts in `seeds/` |
+
 Docs: https://flare-docs.codetotech.com

package/templates/next/docker-compose.yml

@@ -0,0 +1,74 @@
+# The services this app expects, running on your machine.
+#
+#   docker compose up -d
+#
+# Without Docker you point the same variables at hosted services instead — Neon for
+# Postgres, Cloudflare R2 for uploads, Upstash for Redis. Nothing in the app knows the
+# difference: MinIO speaks S3 like R2 does, and the Redis proxy speaks Upstash's REST
+# protocol, so `lib/storage.ts` and `lib/redis.ts` are the same code either way.
+#
+# `.env.example` already holds the values that match this file.
+
+services:
+  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_USER: flare
+      POSTGRES_PASSWORD: flare
+      POSTGRES_DB: app
+    ports: ["5432:5432"]
+    volumes: [postgres-data:/var/lib/postgresql/data]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flare -d app"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # R2 speaks S3, and so does MinIO, which is how file uploads work locally without a
+  # Cloudflare account.
+  #
+  # bitnamilegacy, pinned: bitnami/minio stopped publishing tags, and both minio/minio on
+  # Docker Hub and quay.io now refuse an anonymous pull. This archived tag still works and
+  # creates the bucket on startup, so there is no setup step after `up`.
+  minio:
+    image: bitnamilegacy/minio:2025.7.23-debian-12-r5
+    environment:
+      MINIO_ROOT_USER: flare
+      MINIO_ROOT_PASSWORD: flare-secret-123
+      MINIO_DEFAULT_BUCKETS: app-uploads
+    # 9000 is the S3 API, 9001 the web console (http://localhost:9001).
+    ports: ["9000:9000", "9001:9001"]
+    volumes: [minio-data:/bitnami/minio/data]
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://127.0.0.1:9000/minio/health/live"]
+      interval: 5s
+      timeout: 5s
+      retries: 20
+
+  redis:
+    image: redis:8-alpine
+    # Not published: only the proxy below talks to it, and the app never speaks RESP.
+    expose: ["6379"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # `@upstash/redis` is a REST client, not a socket client, so it cannot talk to the Redis
+  # above directly. This proxy speaks Upstash's REST protocol in front of it, which keeps
+  # `lib/redis.ts` identical whether you are on your laptop or on Upstash.
+  redis-http:
+    image: hiett/serverless-redis-http:latest
+    environment:
+      SRH_MODE: env
+      SRH_TOKEN: flare-local-token
+      SRH_CONNECTION_STRING: redis://redis:6379
+    ports: ["8079:80"]
+    depends_on:
+      redis:
+        condition: service_healthy
+
+volumes:
+  postgres-data:
+  minio-data:

package/templates/next/lib/auth.ts

@@ -1,4 +1,6 @@
 import { after } from "next/server";
+import { cookies } from "next/headers";
+import { INVITE_COOKIE, invitationAllows, spendInvitation } from "./invitations";
 import { passkey } from "@better-auth/passkey";
 import { prismaAdapter } from "@better-auth/prisma-adapter";
 import { betterAuth } from "better-auth";
@@ -107,6 +109,86 @@ async function guardPassword(path: string, body: Record<string, unknown> | undef
   }
 }
 
+/**
+ * Whether this account may be created at all — `authConfig.signup`.
+ *
+ * Checked where the user row is written rather than on each sign-up route, because there
+ * are four ways to end up with a new account (a password sign-up, a magic link, an email
+ * code, a social callback) and gating them one by one is how one gets missed.
+ *
+ * **The first account is always allowed.** An app nobody can sign into cannot be set up,
+ * and in `invite` mode there would be nobody to issue the invitation. Everybody after
+ * them goes through this; the first account also becomes the admin (see below).
+ */
+async function assertSignUpAllowed(email: string): Promise<void> {
+  if (authConfig.signup === "open") return;
+  if ((await prisma.user.findFirst({ select: { id: true } })) === null) return;
+
+  if (authConfig.signup === "closed") {
+    throw new APIError("FORBIDDEN", { message: "This app is not accepting new accounts." });
+  }
+
+  // `invite`: the token was put in a cookie when the invitation link was opened.
+  const token = (await cookies()).get(INVITE_COOKIE)?.value;
+  if (!(await invitationAllows(token, email))) {
+    throw new APIError("FORBIDDEN", { message: "You need an invitation to create an account here." });
+  }
+}
+
+/**
+ * Spend the invitation this sign-up used, once the account exists.
+ *
+ * Separate from the check because the account does not exist yet when the check runs: an
+ * invitation has to survive a sign-up that fails validation, and only be used up by one
+ * that worked.
+ */
+async function spendUsedInvitation(): Promise<void> {
+  if (authConfig.signup !== "invite") return;
+  const jar = await cookies();
+  const token = jar.get(INVITE_COOKIE)?.value;
+  if (!token) return;
+  await spendInvitation(token);
+  jar.delete(INVITE_COOKIE);
+}
+
+/**
+ * The first account to exist becomes the admin.
+ *
+ * Generated resources are admin-only, so without this a fresh app has a database, an API
+ * and a dashboard that nobody can reach — and the usual fix for that is to open
+ * everything up, which is how an admin panel ends up on the internet. The person running
+ * sign-up on an empty database is the person setting the app up.
+ *
+ * Done here rather than in `databaseHooks.user.create`, because the admin plugin already
+ * registers one of those (`{ role: defaultRole, ...user }`) and Better Auth does not merge
+ * the two — a second one is silently never called. This runs after the row exists and
+ * states the rule in SQL, which no plugin can quietly win.
+ *
+ * Everyone after them keeps the plugin's default role, and no role reaches an admin-only
+ * resource until you grant one with `flare user:role them@example.com admin`.
+ *
+ * Two people signing up in the same instant would both see two rows and neither would be
+ * promoted, leaving an app with no admin. It needs a brand-new app and millisecond timing,
+ * and `flare user:role you@example.com admin` fixes it, so this stays the simple rule
+ * rather than a transaction nobody can read.
+ */
+let adminSettled = false;
+
+async function promoteFirstUser() {
+  if (adminSettled) return;
+  // Two rows is all it takes to answer "is there exactly one?".
+  const rows = await prisma.user.findMany({ select: { id: true, role: true }, take: 2 });
+  if (rows.length !== 1) {
+    // Nobody yet: the next sign-up asks again. More than one: the question is settled.
+    adminSettled = rows.length > 1;
+    return;
+  }
+  if (rows[0]!.role !== "admin") {
+    await prisma.user.update({ where: { id: rows[0]!.id }, data: { role: "admin" } });
+  }
+  adminSettled = true;
+}
+
 export const auth = betterAuth({
   appName: "__APP_NAME__",
   secret: process.env.BETTER_AUTH_SECRET,
@@ -145,16 +227,40 @@ export const auth = betterAuth({
     // verification email doesn't hold the sign-up request open.
     backgroundTasks: { handler: (promise: Promise<unknown>) => after(() => promise) },
   },
+  databaseHooks: {
+    user: {
+      create: {
+        // The one place every sign-up passes through, whichever route it came in on.
+        before: async (user: { email: string }) => {
+          await assertSignUpAllowed(user.email);
+          return { data: user };
+        },
+      },
+    },
+  },
   hooks: {
     before: createAuthMiddleware(async (ctx) => {
       if (disabledPath(ctx.path)) throw new APIError("NOT_FOUND", { message: "This sign-in method isn't enabled." });
       await guardPassword(ctx.path, ctx.body as Record<string, unknown> | undefined);
     }),
+    // Any route can be the one that creates the first user — a password sign-up, a magic
+    // link, a social callback — so this asks after all of them rather than guessing which.
+    after: createAuthMiddleware(async () => {
+      await promoteFirstUser();
+      await spendUsedInvitation();
+    }),
   },
   plugins: [
-    // Adds user.role (default "user") and admin APIs. The /admin area allows ADMIN_ROLES (lib/admin.ts).
+    // Adds user.role (default "user") and admin APIs. The dashboard allows ADMIN_ROLES (lib/dashboard.ts).
     admin({ defaultRole: "user", adminRoles: ["admin"] }),
-    magicLink({ sendMagicLink: ({ email, url }) => sendMagicLink({ email, url }), expiresIn: 5 * 60, disableSignUp: false }),
+    // disableSignUp follows the mode: a magic link to an address with no account would
+    // otherwise create one, which is a sign-up through a side door. In `invite` mode the
+    // link is still how an invited person signs *in* — they have an account by then.
+    magicLink({
+      sendMagicLink: ({ email, url }) => sendMagicLink({ email, url }),
+      expiresIn: 5 * 60,
+      disableSignUp: authConfig.signup !== "open",
+    }),
     emailOTP({ sendVerificationOTP: (data) => sendEmailCode(data), otpLength: 6, expiresIn: 5 * 60, allowedAttempts: 5 }),
     twoFactor({
       issuer: "__APP_NAME__",

package/templates/next/lib/dashboard.ts

@@ -80,7 +80,9 @@ export function dashboardStore(name: string): ResourceStore {
   if (!store) {
     store = createResourceStore({
       resource: entry.resource,
-      rows: prismaRows(entry.delegate, prisma),
+      // The descriptor goes in so the store can translate enum values both ways:
+      // Prisma's client speaks member names, so the column's "A+" is "A_2b" to it.
+      rows: prismaRows(entry.delegate, prisma, entry.resource),
       // The admin is not exempt from ownership. A policy that confines staff to their own
       // rows has to mean the same thing here as it does over the API, or the dashboard is
       // a way around it.

package/templates/next/lib/db.ts

@@ -1,5 +1,9 @@
 import { PrismaPg } from "@prisma/adapter-pg";
-import { PrismaClient } from "@/lib/generated/prisma/client";
+// Relative, not "@/lib/generated/prisma/client". The alias is resolved by the bundler,
+// and `flare seed` runs this file through tsx instead, which does not resolve it under
+// `moduleResolution: "bundler"` — the seed died on its first import before reaching the
+// database. The generated client lives inside lib/ anyway, so this is the shorter path.
+import { PrismaClient } from "./generated/prisma/client";
 
 /**
  * The Prisma client, one per process.

package/templates/next/lib/invitations.ts

@@ -0,0 +1,119 @@
+// This file is yours.
+//
+// Flare copies the code that turns a resource descriptor into a working endpoint into
+// your app rather than hiding it in node_modules, for the same reason shadcn/ui copies
+// a component: you cannot fix, read or reason about what you cannot see.
+//
+// `flare diff` shows how your copy differs from the version Flare ships, and
+// `flare update` applies the parts you choose. Neither runs unless you ask.
+
+/**
+ * Invitations, for an app whose sign-up is `invite` (see lib/auth-config.ts) — the
+ * Prisma half.
+ *
+ * **They live in the `Verification` model**, which Better Auth already has and already
+ * uses for exactly this shape of thing: a single-use token with an expiry. Reusing it
+ * means invitations need no model of their own and so no migration — an app switching to
+ * `invite` changes one line in auth-config.ts and nothing else.
+ *
+ * Rows are keyed `invite:<hash>`. Only the hash is stored, never the token itself, for the
+ * same reason a password is not: a leaked database should not be a pile of working
+ * invitations.
+ */
+import { prisma } from "@/lib/db";
+
+/** How long an invitation is good for, unless you say otherwise. */
+export const DEFAULT_INVITE_DAYS = 7;
+
+/** The cookie an opened invitation link leaves behind, for the sign-up that follows. */
+export const INVITE_COOKIE = "flare_invite";
+
+/** How long that cookie lives: long enough to fill in a form, not long enough to forget. */
+export const INVITE_COOKIE_MAX_AGE = 60 * 60;
+
+const KEY_PREFIX = "invite:";
+
+/** WebCrypto, so this file does not depend on which runtime it is loaded in. */
+const randomToken = () => {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+
+/** Only the hash is stored, so a copy of the table is not a pile of working invitations. */
+async function hash(token: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+const key = async (token: string) => `${KEY_PREFIX}${await hash(token)}`;
+
+/** What an invitation is for: one address, or anybody who has the link. */
+export type InviteFor = { email: string } | { anyone: true };
+
+/** An invitation. The token is returned once and never stored. */
+export interface CreatedInvitation {
+  token: string;
+  expiresAt: Date;
+  /** Who it is for, or null when anybody with the link may use it. */
+  email: string | null;
+}
+
+/** Create one. The returned token is the only copy. */
+export async function createInvitation(options: { for: InviteFor; days?: number }): Promise<CreatedInvitation> {
+  const token = randomToken();
+  const email = "email" in options.for ? options.for.email.trim().toLowerCase() : null;
+  const expiresAt = new Date(Date.now() + (options.days ?? DEFAULT_INVITE_DAYS) * 86_400_000);
+  await prisma.verification.create({
+    // `*` rather than an empty string, so "for anybody" is a value and not a mistake.
+    data: { identifier: await key(token), value: email ?? "*", expiresAt },
+  });
+  return { token, expiresAt, email };
+}
+
+/** The link to send somebody, given the app's own origin. */
+export const invitationLink = (baseUrl: string, token: string) => `${baseUrl.replace(/\/$/, "")}/invite/${token}`;
+
+/**
+ * Whether this token is a live invitation for this email address.
+ *
+ * Checked, not spent: the account does not exist yet when this is asked, and an
+ * invitation should survive a sign-up that fails validation.
+ */
+export async function invitationAllows(token: string | undefined, email: string): Promise<boolean> {
+  if (!token) return false;
+  const row = await prisma.verification.findFirst({ where: { identifier: await key(token) } });
+  if (!row) return false;
+  if (row.expiresAt.getTime() <= Date.now()) return false;
+  // An invitation addressed to somebody is for them alone; `*` is for whoever has the link.
+  return row.value === "*" || row.value === email.trim().toLowerCase();
+}
+
+/** Spend it, so the link cannot be used again. Called once the account exists. */
+export async function spendInvitation(token: string | undefined): Promise<void> {
+  if (!token) return;
+  await prisma.verification.deleteMany({ where: { identifier: await key(token) } });
+}
+
+/** Invitations an admin can see: live ones, newest first. Never the tokens. */
+export async function listInvitations(): Promise<{ id: string; email: string | null; expiresAt: Date; createdAt: Date }[]> {
+  const rows = await prisma.verification.findMany({
+    where: { identifier: { startsWith: KEY_PREFIX }, expiresAt: { gt: new Date() } },
+    orderBy: { createdAt: "desc" },
+  });
+  return rows.map((row) => ({ id: row.id, email: row.value === "*" ? null : row.value, expiresAt: row.expiresAt, createdAt: row.createdAt }));
+}
+
+/** Revoke one by its row id, so a link sent to the wrong address stops working. */
+export async function revokeInvitation(id: string): Promise<void> {
+  await prisma.verification.deleteMany({ where: { id } });
+}
+
+/**
+ * Drop invitations that have expired.
+ *
+ * Only rows under the `invite:` prefix — the rest of this table is Better Auth's, and
+ * deleting its tokens would sign people out and break magic links.
+ */
+export async function pruneInvitations(): Promise<void> {
+  await prisma.verification.deleteMany({ where: { identifier: { startsWith: KEY_PREFIX }, expiresAt: { lt: new Date() } } });
+}

package/templates/next/lib/rate-limit.ts

@@ -0,0 +1,83 @@
+// This file is yours.
+//
+// Flare copies the code that turns a resource descriptor into a working endpoint into
+// your app rather than hiding it in node_modules, for the same reason shadcn/ui copies
+// a component: you cannot fix, read or reason about what you cannot see.
+//
+// `flare diff` shows how your copy differs from the version Flare ships, and
+// `flare update` applies the parts you choose. Neither runs unless you ask.
+
+/**
+ * Where a resource's rate limits are counted — the Next.js half.
+ *
+ * A descriptor says `rateLimit: { create: "10/min" }`; the generated route asks here
+ * whether this call is within it. The counter is Redis: `INCR` then `EXPIRE` on the first
+ * call of a window, which is two round trips at most and exact across every instance —
+ * the reason lib/redis.ts exists.
+ *
+ * **If Redis is not configured, nothing is limited.** Say so loudly once rather than
+ * failing every request: a serverless function that refuses to serve is worse than one
+ * that logs that a limit is not being enforced, and `flare doctor` reports it as a
+ * problem. Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.
+ */
+import { fixedWindow, rateLimitKey, type Rate, type RateLimitDecision } from "@flaredev/core";
+import { redis } from "@/lib/redis";
+
+/** Allowed, with no count kept — what an unconfigured limiter answers. */
+const UNLIMITED: RateLimitDecision = { allowed: true, remaining: Number.MAX_SAFE_INTEGER, retryAfter: 0 };
+
+let warned = false;
+
+/**
+ * Count one call and say whether it was within the limit.
+ *
+ * `caller` is the signed-in account's id where there is one and the client IP otherwise,
+ * so a limit is per person rather than per everyone behind one connection.
+ */
+export async function checkRateLimit(
+  resource: string,
+  action: string,
+  caller: string,
+  rate: Rate,
+): Promise<RateLimitDecision> {
+  // Captured in a local, because the narrowing from this check does not reach inside the
+  // callback below — the closure is called later, so TypeScript is right to doubt it.
+  const client = redis;
+  if (!client) {
+    if (!warned) {
+      warned = true;
+      console.warn(
+        "[flare] A resource declares a rateLimit, but Upstash Redis is not configured, so nothing is being limited. " +
+          "Set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN (flare doctor will show you).",
+      );
+    }
+    return UNLIMITED;
+  }
+
+  const key = `flare:rate:${rateLimitKey(resource, action, caller)}`;
+  try {
+    return await fixedWindow(rate, async (windowSeconds) => {
+      const count = await client.incr(key);
+      // Only the call that opened the window sets the expiry, so a busy key's window is
+      // not pushed forward on every hit — that would make the limit unbounded.
+      if (count === 1) {
+        await client.expire(key, windowSeconds);
+        return { count, ttl: windowSeconds };
+      }
+      const ttl = await client.ttl(key);
+      // A key with no expiry (a crash between INCR and EXPIRE) would otherwise count for
+      // ever; give it one and treat this window as full-length.
+      if (ttl < 0) {
+        await client.expire(key, windowSeconds);
+        return { count, ttl: windowSeconds };
+      }
+      return { count, ttl };
+    });
+  } catch (error) {
+    // A counter that is unreachable must not take the endpoint down with it. Letting the
+    // call through is the safer failure: the alternative is an outage in the limiter
+    // becoming an outage in the app.
+    console.error("[flare] rate limit counter failed, allowing the request:", error);
+    return UNLIMITED;
+  }
+}

package/templates/next/lib/resource/prisma-rows.ts

@@ -20,6 +20,7 @@
  * package can't depend on one. The delegate is described structurally instead, which is
  * also what makes it easy to test without a database.
  */
+import { enumTranslations, storedFields, type EnumTranslation, type Resource } from "@flaredev/core";
 import type { ConstraintHit, ResourceRows, Row, RowsQuery } from "./rows";
 
 /**
@@ -79,10 +80,46 @@ function fromIndexName(name: string): string {
   return match ? match[1]! : name;
 }
 
-export function prismaRows(delegate: PrismaDelegate, client: unknown): ResourceRows {
+/**
+ * Prisma's client speaks enum *member* names, not the values stored in the column.
+ *
+ * `A+` cannot be an identifier, so the schema declares the member `A_2b` with
+ * `@map("A+")`. The map applies to Postgres: the column holds `A+`, and the generated
+ * client still hands back `A_2b` and insists on it when writing. Left alone, the admin
+ * shows `A_2b`, the validators reject it because the descriptor says the value is `A+`,
+ * and a create fails outright.
+ *
+ * So values are translated at this boundary, and nothing above it has to know. A
+ * resource whose options are all identifiers already — `draft`, `published`, which is
+ * most of them — gets no translation table and pays nothing.
+ */
+function translate(row: Row, enums: Record<string, EnumTranslation>, direction: "toValue" | "toMember"): Row {
+  let copy: Row | undefined;
+  for (const key of Object.keys(enums)) {
+    const current = row[key];
+    if (typeof current !== "string") continue;
+    const mapped = enums[key]![direction][current];
+    // An unknown member is left as it is rather than blanked: a value written before an
+    // option was removed should still be visible in the admin, not silently become null.
+    if (mapped === undefined || mapped === current) continue;
+    copy ??= { ...row };
+    copy[key] = mapped;
+  }
+  return copy ?? row;
+}
+
+export function prismaRows(delegate: PrismaDelegate, client: unknown, resource?: Resource): ResourceRows {
+  // Built once per store rather than per row. Without a descriptor there is nothing to
+  // translate, which keeps the old two-argument call working.
+  const enums = resource ? enumTranslations(storedFields(resource)) : {};
+  const hasEnums = Object.keys(enums).length > 0;
+  const toValue = (row: Row): Row => (hasEnums ? translate(row, enums, "toValue") : row);
+  const toMember = (row: Row): Row => (hasEnums ? translate(row, enums, "toMember") : row);
   /** The search and filter half of a where clause — everything but the cursor. */
   function matching(query: Pick<RowsQuery, "search" | "filters" | "deleted">): Record<string, unknown> {
-    const where: Record<string, unknown> = { ...query.filters };
+    // A filter on an enum field arrives as the value the user sees, and has to reach
+    // Prisma as the member name.
+    const where: Record<string, unknown> = hasEnums ? { ...toMember(query.filters as Row) } : { ...query.filters };
     // A soft-deleting resource hides its deleted rows. Set on the query rather than in
     // `filters` because "only" is `not: null`, which the filter shape cannot say.
     if (query.deleted === "exclude") where.deletedAt = null;
@@ -106,18 +143,22 @@ export function prismaRows(delegate: PrismaDelegate, client: unknown): ResourceR
         // Postgres compares a timestamp against a Date, not the number the cursor
         // carried. Without this, paging past the first page of a date-sorted list fails
         // with "Expected DateTime, provided Int".
-        const value = isDate && (typeof query.cursor.value === "number" || typeof query.cursor.value === "string") ? new Date(query.cursor.value) : query.cursor.value;
+        let value = isDate && (typeof query.cursor.value === "number" || typeof query.cursor.value === "string") ? new Date(query.cursor.value) : query.cursor.value;
+        // Paging over an enum column: the cursor carries the value the row was handed
+        // out with, and Prisma compares member names.
+        if (hasEnums && enums[field] && typeof value === "string") value = enums[field]!.toMember[value] ?? value;
         // (sort, id) as one comparison, so rows sharing a sort value are neither skipped
         // nor repeated. AND-ed with the filters rather than replacing them.
         const keyset = [{ [field]: { [op]: value } }, { AND: [{ [field]: value }, { id: { [op]: id } }] }];
         where.AND = [...((where.AND as unknown[]) ?? []), { OR: keyset }];
       }
-      return delegate.findMany({
+      const rows = await delegate.findMany({
         where,
         orderBy: [{ [query.sort.field]: query.sort.direction }, { id: query.sort.direction }],
         take: query.limit,
         ...(query.offset ? { skip: query.offset } : {}),
       });
+      return hasEnums ? rows.map(toValue) : rows;
     },
 
     countUpTo(query, limit) {
@@ -125,22 +166,25 @@ export function prismaRows(delegate: PrismaDelegate, client: unknown): ResourceR
       return delegate.count({ where: matching(query), take: limit });
     },
 
-    byId(id) {
-      return delegate.findUnique({ where: { id } });
+    async byId(id) {
+      const row = await delegate.findUnique({ where: { id } });
+      return row ? toValue(row) : row;
     },
 
-    async titles(ids, titleField) {
-      const rows = await delegate.findMany({ where: { id: { in: ids } }, select: { id: true, [titleField]: true } });
+    async titles(ids, titleField, owner) {
+      const where = owner ? { id: { in: ids }, [owner.field]: owner.value } : { id: { in: ids } };
+      const rows = await delegate.findMany({ where, select: { id: true, [titleField]: true } });
       return rows.map((row) => ({ id: String(row.id), title: row[titleField] }));
     },
 
-    insert(values) {
-      return delegate.create({ data: values });
+    async insert(values) {
+      return toValue(await delegate.create({ data: hasEnums ? toMember(values as Row) : values }));
     },
 
     async update(id, values) {
       try {
-        return await delegate.update({ where: { id }, data: values });
+        const row = await delegate.update({ where: { id }, data: hasEnums ? toMember(values as Row) : values });
+        return toValue(row);
       } catch (error) {
         if (codeOf(error) === NOT_FOUND) return null;
         throw error;