@flaredev/cli 0.11.0 → 0.12.0

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/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,48 @@ 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.
  *
@@ -183,6 +227,17 @@ 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." });
@@ -192,12 +247,20 @@ export const auth = betterAuth({
     // 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/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,8 +166,9 @@ 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, owner) {
@@ -135,13 +177,14 @@ export function prismaRows(delegate: PrismaDelegate, client: unknown): ResourceR
       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;

package/templates/next/lib/storage/disk.ts

@@ -0,0 +1,128 @@
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { Readable } from "node:stream";
+import type { StorageBucket, StorageObjectBody } from "@flaredev/core";
+
+/**
+ * Files on the local disk, the way Laravel's `local` disk works.
+ *
+ * For development without Docker, and for a single-server deployment where a volume is
+ * simpler than a bucket. It is not for anything that scales horizontally: two instances
+ * do not share a filesystem, and the second one serves 404s for everything the first
+ * one wrote.
+ *
+ * Bytes are served through this app's `/api/storage` route like R2's are, so a file is
+ * still private and still behind whatever policy issued the URL. Nothing is published
+ * by putting it here.
+ */
+
+export interface DiskOptions {
+  /**
+   * Where the files go, relative to the project root unless absolute.
+   * Default `storage/app` — Laravel's name for the same thing.
+   */
+  dir?: string;
+}
+
+/**
+ * The content type is kept beside the object rather than guessed from its extension.
+ *
+ * A key is whatever `createObjectKey` was given, and people upload files called
+ * `report` and `IMG_0421`. Guessing would serve those as a download instead of showing
+ * them, and would be wrong rather than merely unhelpful for anything renamed. The
+ * sidecar lives in a parallel tree so it can never collide with a real key — somebody
+ * does, eventually, upload a file called `photo.png.meta`.
+ */
+interface Meta {
+  contentType?: string;
+}
+
+export function diskBucket(options: DiskOptions = {}): StorageBucket {
+  const root = resolve(options.dir ?? join(process.cwd(), "storage", "app"));
+  const objects = join(root, "objects");
+  const metas = join(root, "meta");
+
+  /**
+   * A key as a path under `base`, confined to it.
+   *
+   * `createStorage` already rejects `..` and leading slashes before a key reaches a
+   * bucket. This is the second lock on the same door: a bucket is a public function and
+   * a path traversal here reads any file the process can.
+   */
+  const pathFor = (base: string, key: string, suffix = "") => {
+    const full = resolve(join(base, key + suffix));
+    if (full !== base && !full.startsWith(base + sep)) throw new Error(`Refusing to touch "${key}": it escapes the storage directory.`);
+    return full;
+  };
+
+  const write = async (file: string, data: Buffer | string) => {
+    try {
+      await mkdir(dirname(file), { recursive: true });
+      await writeFile(file, data);
+    } catch (error) {
+      // The one failure worth explaining. A serverless host gives you a read-only
+      // filesystem, so this driver cannot work there at all — and `EROFS` on a path
+      // nobody chose is a puzzling way to find that out, usually in production.
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "EROFS" || code === "EACCES" || code === "EPERM") {
+        throw new Error(
+          `The disk driver cannot write to ${root} (${code}). A serverless host — Vercel, Lambda, Workers — ` +
+            "has no writable filesystem that survives a request, so set STORAGE_DRIVER to r2, cloudinary or " +
+            "uploadthing for anything deployed there. Disk is for local development and for a server you own.",
+        );
+      }
+      throw error;
+    }
+  };
+
+  return {
+    async get(key: string): Promise<StorageObjectBody | null> {
+      const file = pathFor(objects, key);
+      let size: number;
+      let mtimeMs: number;
+      try {
+        const info = await stat(file);
+        if (!info.isFile()) return null;
+        size = info.size;
+        mtimeMs = info.mtimeMs;
+      } catch {
+        return null;
+      }
+
+      let meta: Meta = {};
+      try {
+        meta = JSON.parse(await readFile(pathFor(metas, key, ".json"), "utf8")) as Meta;
+      } catch {
+        // Written before the sidecar existed, or removed by hand. The object is still
+        // the thing being asked for, so serve it as bytes rather than refusing.
+      }
+
+      return {
+        // Node's stream, as the web stream the route writes to the response.
+        body: Readable.toWeb(createReadStream(file)) as ReadableStream,
+        size,
+        // Strong enough for a cache: a write changes one or the other.
+        httpEtag: `"${size.toString(16)}-${Math.floor(mtimeMs).toString(16)}"`,
+        httpMetadata: { contentType: meta.contentType },
+      };
+    },
+
+    async put(key, value, putOptions) {
+      // The route hands over a stream of known length, already capped by the field's
+      // maxBytes and checked against its declared type.
+      const body = value === null ? Buffer.alloc(0) : Buffer.from(await new Response(value as BodyInit).arrayBuffer());
+      await write(pathFor(objects, key), body);
+      const contentType = putOptions?.httpMetadata?.contentType;
+      if (contentType) await write(pathFor(metas, key, ".json"), JSON.stringify({ contentType } satisfies Meta));
+    },
+
+    async delete(keys) {
+      for (const key of [keys].flat()) {
+        // `force` so deleting what was never there is the success it describes.
+        await rm(pathFor(objects, key), { force: true });
+        await rm(pathFor(metas, key, ".json"), { force: true });
+      }
+    },
+  };
+}