@flaredev/cli 0.10.0 → 0.12.0

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 });
+      }
+    },
+  };
+}

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

@@ -0,0 +1,86 @@
+import { AwsClient } from "aws4fetch";
+import type { StorageBucket, StorageObjectBody } from "@flaredev/core";
+
+/**
+ * Files on R2, over its S3-compatible API — so this also drives any S3 that will take
+ * a signed request: MinIO in `docker compose`, Backblaze B2, S3 itself.
+ *
+ * R2 rather than Vercel Blob for one reason: R2 charges nothing to serve what it
+ * stores. On a file-heavy app that is the difference between a small bill and a large
+ * one, and it costs nothing to use from outside Cloudflare — see the cost guide.
+ *
+ * `aws4fetch` signs the requests; it is a few kilobytes and works in any runtime,
+ * unlike the AWS SDK. There is no `publicUrl`: the bucket is private, and reads are
+ * signed and proxied by this app so a policy still decides who may see a file.
+ */
+
+export interface R2Options {
+  endpoint: string;
+  bucket: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+}
+
+export function r2Bucket(options: R2Options): StorageBucket {
+  const client = new AwsClient({
+    accessKeyId: options.accessKeyId,
+    secretAccessKey: options.secretAccessKey,
+    service: "s3",
+    region: "auto",
+  });
+  const endpoint = `${options.endpoint}/${options.bucket}`;
+
+  /**
+   * A key as a URL path.
+   *
+   * Each segment is escaped on its own, so the slashes in "products/2026/09/a.png" stay
+   * slashes. Escaping the whole key would turn them into %2F, which is a different
+   * object name to S3 even where a particular server is forgiving about it.
+   */
+  const path = (key: string) => key.split("/").map(encodeURIComponent).join("/");
+
+  /** Raise a bucket error rather than letting a failed write look like a successful one. */
+  const ok = async (response: Response, doing: string, key: string): Promise<Response> => {
+    if (response.ok) return response;
+    const detail = await response.text().catch(() => "");
+    throw new Error(`Storage ${doing} failed for "${key}": ${response.status} ${detail.slice(0, 300)}`);
+  };
+
+  return {
+    async get(key: string): Promise<StorageObjectBody | null> {
+      const response = await client.fetch(`${endpoint}/${path(key)}`);
+      if (!response.ok || !response.body) return null;
+      return {
+        body: response.body,
+        httpMetadata: { contentType: response.headers.get("content-type") ?? undefined },
+        size: Number(response.headers.get("content-length") ?? 0),
+        // R2 returns the object's ETag quoted, which is what the header wants back.
+        httpEtag: response.headers.get("etag") ?? "",
+      };
+    },
+
+    async put(key, value, putOptions) {
+      // S3 needs a Content-Length, and a stream has no length to send — it answers
+      // "411 MissingContentLength" and stores nothing. Uploads are capped by the field's
+      // own maxBytes long before they reach here, so reading one into memory is safe and
+      // is what makes the length known.
+      //
+      // The length is set by hand rather than left to fetch. Next patches the global
+      // fetch, and in that runtime it does not derive content-length even from a buffered
+      // body — so S3 still answers 411 and stores nothing. Buffering everything through
+      // Response keeps one path for streams, buffers and strings alike.
+      const body = value === null ? new ArrayBuffer(0) : await new Response(value as BodyInit).arrayBuffer();
+      const headers: Record<string, string> = { "content-length": String(body.byteLength) };
+      if (putOptions?.httpMetadata?.contentType) headers["content-type"] = putOptions.httpMetadata.contentType;
+      await ok(await client.fetch(`${endpoint}/${path(key)}`, { method: "PUT", body, headers }), "upload", key);
+    },
+
+    async delete(keys) {
+      for (const key of [keys].flat()) {
+        const response = await client.fetch(`${endpoint}/${path(key)}`, { method: "DELETE" });
+        // S3 answers 204 for a key that was never there, which is the outcome we wanted.
+        if (response.status !== 404) await ok(response, "delete", key);
+      }
+    },
+  };
+}

package/templates/next/lib/storage.ts

@@ -1,81 +1,98 @@
-import { AwsClient } from "aws4fetch";
-import { createObjectKey, createStorage } from "@flaredev/core";
+import { createObjectKey, createStorage, type StorageBucket } from "@flaredev/core";
+import { cloudinaryBucket } from "./storage/cloudinary";
+import { diskBucket } from "./storage/disk";
+import { r2Bucket } from "./storage/r2";
+import { uploadThingBucket } from "./storage/uploadthing";
 
 /**
- * File storage on R2, over its S3-compatible API.
+ * Where uploaded files go.
  *
- * R2 rather than Vercel Blob for one reason: R2 charges nothing to serve what it
- * stores. On a file-heavy app that is the difference between a small bill and a large
- * one, and it costs nothing to use from outside Cloudflare — see the cost guide.
+ * One of four drivers, chosen by `STORAGE_DRIVER`. Everything above this line is the
+ * same whichever you pick — the `file` field, the upload widget, `createUploadUrl` and
+ * `createReadUrl` — because a driver only has to answer three questions: store these
+ * bytes, give them back, throw them away.
  *
- * `aws4fetch` signs the requests; it is a few kilobytes and works in any runtime, unlike
- * the AWS SDK. Everything above this — the upload widget, the signed-URL helpers, the
- * file field — is the same code the Cloudflare stack runs.
+ *   r2           S3-compatible: R2, MinIO, B2, S3. The default, and what
+ *                `docker compose up` gives you locally.
+ *   disk         The local filesystem, like Laravel's `local` disk. No account,
+ *                no network. One machine only.
+ *   cloudinary   A CDN with an image pipeline. Serves from res.cloudinary.com.
+ *   uploadthing  A CDN with an uploader. Serves from <app>.ufs.sh.
+ *
+ * The drivers are in `lib/storage/`, in your repository, and are ordinary files you can
+ * read and change. Adding a fifth means writing `get`, `put` and `delete` — see
+ * `lib/storage/disk.ts`, which is the shortest of them.
+ *
+ * ## Private by default, and what breaks that
+ *
+ * With `r2` or `disk`, a read URL is a short-lived signed token redeemed by
+ * `app/api/storage/route.ts`, so whoever issued it decided the viewer was allowed it.
+ *
+ * `cloudinary` and `uploadthing` are content delivery networks, and serving through
+ * this app would throw away the thing you are paying them for. So they hand back their
+ * own URL, which **anyone with the link can read, forever**. That is the normal way to
+ * use them and the wrong way to store a medical record. Set `STORAGE_PUBLIC=false` to
+ * keep every read signed and proxied, and they become ordinary private storage.
+ *
+ *   const { url } = await storage.createUploadUrl({
+ *     key: createObjectKey(file.name, `users/${user.id}`),
+ *     contentTypes: ["image/*", "application/pdf"],
+ *     maxBytes: 10 * 1024 * 1024,
+ *   });
+ *   // browser: fetch(url, { method: "PUT", body: file, headers: { "Content-Type": file.type } })
+ *
+ *   const src = await storage.createReadUrl({ key });
  */
-const client = new AwsClient({
-  accessKeyId: process.env.R2_ACCESS_KEY_ID ?? "",
-  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY ?? "",
-  service: "s3",
-  region: "auto",
-});
 
-const endpoint = `${process.env.R2_ENDPOINT ?? ""}/${process.env.R2_BUCKET ?? ""}`;
+type StorageDriver = "r2" | "disk" | "cloudinary" | "uploadthing";
 
-/**
- * A key as a URL path.
- *
- * Each segment is escaped on its own, so the slashes in "products/2026/09/a.png" stay
- * slashes. Escaping the whole key would turn them into %2F, which is a different object
- * name to S3 even where a particular server is forgiving about it.
- */
-const path = (key: string) => key.split("/").map(encodeURIComponent).join("/");
+const DRIVERS: StorageDriver[] = ["r2", "disk", "cloudinary", "uploadthing"];
 
-/** Raise a bucket error rather than letting a failed write look like a successful one. */
-async function ok(response: Response, doing: string, key: string): Promise<Response> {
-  if (response.ok) return response;
-  const detail = await response.text().catch(() => "");
-  throw new Error(`Storage ${doing} failed for "${key}": ${response.status} ${detail.slice(0, 300)}`);
+/** Required environment, named in the error rather than left as `undefined`. */
+function required(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`STORAGE_DRIVER is "${driver}" and needs ${name}, which is not set.`);
+  return value;
 }
 
-/** The bucket, shaped the way @flaredev/core expects, over plain HTTP calls. */
-const bucket = {
-  async get(key: string) {
-    const response = await client.fetch(`${endpoint}/${path(key)}`);
-    if (!response.ok || !response.body) return null;
-    return {
-      body: response.body,
-      httpMetadata: { contentType: response.headers.get("content-type") ?? undefined },
-      size: Number(response.headers.get("content-length") ?? 0),
-      // R2 returns the object's ETag quoted, which is what the header wants back.
-      httpEtag: response.headers.get("etag") ?? "",
-    };
-  },
-  async put(key: string, value: ReadableStream | ArrayBuffer | string | null, options?: { httpMetadata?: { contentType?: string } }) {
-    // S3 needs a Content-Length, and a stream has no length to send — it answers
-    // "411 MissingContentLength" and stores nothing. Uploads are capped by the field's
-    // own maxBytes long before they reach here, so reading one into memory is safe and
-    // is what makes the length known.
-    //
-    // The length is set by hand rather than left to fetch. Next patches the global
-    // fetch, and in that runtime it does not derive content-length even from a buffered
-    // body — so S3 still answers 411 and stores nothing. Buffering everything through
-    // Response keeps one path for streams, buffers and strings alike.
-    const body = value === null ? new ArrayBuffer(0) : await new Response(value as BodyInit).arrayBuffer();
-    const headers: Record<string, string> = { "content-length": String(body.byteLength) };
-    if (options?.httpMetadata?.contentType) headers["content-type"] = options.httpMetadata.contentType;
-    await ok(await client.fetch(`${endpoint}/${path(key)}`, { method: "PUT", body, headers }), "upload", key);
-  },
-  async delete(keys: string | string[]) {
-    for (const key of [keys].flat()) {
-      const response = await client.fetch(`${endpoint}/${path(key)}`, { method: "DELETE" });
-      // S3 answers 204 for a key that was never there, which is the outcome we wanted.
-      if (response.status !== 404) await ok(response, "delete", key);
-    }
-  },
-};
+const configured = (process.env.STORAGE_DRIVER ?? "r2").trim().toLowerCase();
+if (!DRIVERS.includes(configured as StorageDriver)) {
+  throw new Error(`Unknown STORAGE_DRIVER "${configured}". One of: ${DRIVERS.join(", ")}.`);
+}
+const driver = configured as StorageDriver;
+
+/** Public delivery is the point of a CDN, so it is on unless it is turned off. */
+const publicDelivery = process.env.STORAGE_PUBLIC !== "false";
+
+function selectBucket(): StorageBucket {
+  switch (driver) {
+    case "disk":
+      return diskBucket({ dir: process.env.STORAGE_DIR });
+    case "cloudinary":
+      return cloudinaryBucket({
+        cloudName: required("CLOUDINARY_CLOUD_NAME"),
+        apiKey: required("CLOUDINARY_API_KEY"),
+        apiSecret: required("CLOUDINARY_API_SECRET"),
+        publicDelivery,
+      });
+    case "uploadthing":
+      return uploadThingBucket({
+        token: required("UPLOADTHING_TOKEN"),
+        appId: required("UPLOADTHING_APP_ID"),
+        publicDelivery,
+      });
+    case "r2":
+      return r2Bucket({
+        endpoint: required("R2_ENDPOINT"),
+        bucket: required("R2_BUCKET"),
+        accessKeyId: required("R2_ACCESS_KEY_ID"),
+        secretAccessKey: required("R2_SECRET_ACCESS_KEY"),
+      });
+  }
+}
 
 export const storage = createStorage({
-  bucket,
+  bucket: selectBucket(),
   // Signing keys are derived from the auth secret with a storage-specific label.
   secret: process.env.BETTER_AUTH_SECRET ?? "",
 });

package/templates/next/lib/user-titles.ts

@@ -0,0 +1,49 @@
+// 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.
+
+/**
+ * Names for the accounts a `belongsTo("User")` field points at — the Prisma half.
+ *
+ * Better Auth owns the account table, so it is not a Flare resource and has no store to
+ * ask — but the admin still has to show "Ada Lovelace" where the column holds a uuid.
+ * This is the one place that reads it, and it reads two columns and no more.
+ *
+ * An account may have no name (a passkey-only sign-up, say), so the email stands in. It
+ * is the same fallback `/api/users` uses, so a record reads the same in the table, on
+ * the detail page and in the picker.
+ */
+import { prisma } from "@/lib/db";
+
+/** What the admin needs to treat Better Auth's account table as a relation target. */
+export const AUTH_USER_RELATION = {
+  name: "User",
+  label: "User",
+  pluralLabel: "Users",
+  slug: "users",
+  titleField: "name",
+} as const;
+
+/** id → display name, for the ids that exist. Unknown ids are simply absent. */
+export async function userTitles(ids: string[]): Promise<Record<string, string>> {
+  const wanted = [...new Set(ids.filter(Boolean))];
+  if (wanted.length === 0) return {};
+  const rows = await prisma.user.findMany({ where: { id: { in: wanted } }, select: { id: true, name: true, email: true } });
+  return Object.fromEntries(rows.map((row) => [row.id, row.name?.trim() || row.email]));
+}
+
+/**
+ * Whether anybody has an account yet.
+ *
+ * Asked by the sign-up page: the gate in lib/auth.ts always lets the *first* account
+ * through, whatever `authConfig.signup` says, because an app nobody can sign into cannot
+ * be set up. So "sign-up is closed" is only true once somebody exists.
+ */
+export async function anyAccountExists(): Promise<boolean> {
+  return (await prisma.user.findFirst({ select: { id: true } })) !== null;
+}