@flaredev/cli 0.4.0 → 0.5.0

package/templates/app/lib/suggest.ts

@@ -0,0 +1,35 @@
+import { slugify, type StoredField } from "@flaredev/core";
+
+/**
+ * Values a form can make up for itself.
+ *
+ * A unique code — a SKU, a slug, a reference — is the shop's business, not something
+ * worth typing by hand, but it isn't something to impose either: these are offered
+ * behind a button, and whatever comes out can be typed over.
+ *
+ * Only unique, unformatted strings get one. An email or a URL is unique too, and
+ * inventing one would be nonsense.
+ */
+export function canSuggest(field: StoredField): boolean {
+  return field.kind === "string" && field.unique === true && (field.format === undefined || field.format === "slug");
+}
+
+/** Four digits, so two products added in the same minute don't collide. */
+const tail = () => String(Math.floor(Math.random() * 10_000)).padStart(4, "0");
+
+/**
+ * A code for `key`, derived from what's been typed so far.
+ *
+ * "Brushed steel desk lamp" gives the slug `brushed-steel-desk-lamp` and the SKU
+ * `BRU-4821` — recognisable at a glance in a list, which is the whole point of a code
+ * someone reads out over a counter.
+ */
+export function suggestValue(key: string, field: StoredField, title: string): string {
+  const source = title.trim();
+  const format = field.kind === "string" ? field.format : undefined;
+  if (format === "slug" || /slug/i.test(key)) {
+    return source ? slugify(source) : `item-${tail()}`;
+  }
+  const letters = source.replace(/[^A-Za-z0-9]/g, "").slice(0, 3).toUpperCase();
+  return `${letters || "REF"}-${tail()}`;
+}

package/templates/app/lib/usage.ts

@@ -0,0 +1,32 @@
+import { cached, TTL } from "@/lib/cache";
+import { storage } from "@/lib/storage";
+
+/**
+ * How much this app has put in R2.
+ *
+ * Listing a bucket is a Class A operation — the expensive kind — so it is cached for an
+ * hour. A bucket with more objects than one listing returns is reported as far as the
+ * cap and no further, because walking a million keys to draw one number would cost more
+ * than the number is worth.
+ */
+const MAX_KEYS = 1_000;
+
+export const storedBytes = cached(
+  async (): Promise<{ files: number; bytes: number; capped: boolean }> => {
+    try {
+      if (!storage.bucket.list) return { files: 0, bytes: 0, capped: false };
+      const listed = await storage.bucket.list({ limit: MAX_KEYS });
+      const objects = listed.objects ?? [];
+      return {
+        files: objects.length,
+        bytes: objects.reduce((sum, object) => sum + (object.size ?? 0), 0),
+        capped: Boolean(listed.truncated),
+      };
+    } catch {
+      // No bucket bound, or no permission to list it: report nothing rather than fail.
+      return { files: 0, bytes: 0, capped: false };
+    }
+  },
+  ["flare", "stored-bytes"],
+  { revalidate: TTL.long },
+);

package/templates/locks/package-lock.json

@@ -4973,9 +4973,9 @@
       }
     },
     "node_modules/@vitejs/plugin-rsc/node_modules/magic-string": {
-      "version": "1.4.1",
-      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.1.tgz",
-      "integrity": "sha512-8lyCu36ErXR0J9uaGKlKQoiLZKmtI63YGLE8G2o9jyRPdr4X47LusSOwgOJOzcVtp81fTAAjxR7BwKz682Jhow==",
+      "version": "1.4.2",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.2.tgz",
+      "integrity": "sha512-vG+rjFRj1PqdIBozIxAGMjPlOhaVe+GXpbttY/iSK7rGcJRMlwNJO7dcUwmUqkymsFLJiNGI06t4D7Fr7yRC9g==",
       "devOptional": true,
       "license": "MIT",
       "dependencies": {
@@ -6253,9 +6253,9 @@
       }
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.437",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.437.tgz",
-      "integrity": "sha512-1z60R0Nb+kYPnGUrQ6PvMjTVINDGMfqQZ/mI5FJIHvTotlA6noI+YJWakbjaFM+qhLXg9WnK3RUeYSO5ixSHJA==",
+      "version": "1.5.438",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.438.tgz",
+      "integrity": "sha512-AN9xMU1hJiT65LkCUPL1DZm5TCbOPb2Qsm5pYwFLEXp6/qj9SdT4yMiqs7Qqstwvkn1zF7l36SRGt+s6XcJ0FA==",
       "license": "ISC",
       "peer": true
     },
@@ -7124,9 +7124,9 @@
       "license": "MIT"
     },
     "node_modules/node-releases": {
-      "version": "2.0.56",
-      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.56.tgz",
-      "integrity": "sha512-x0InOIyzgdk+eyaWaRJFH5snEtiImgBgblZ2CyPrLmqqcuMQkEvcDPHbzqbD8eDsSeJbVOjn+crzyzHaM4D+/A==",
+      "version": "2.0.57",
+      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.57.tgz",
+      "integrity": "sha512-kQK9LGGFiHtrWiNhZtA7Qbw17AQz+dmsEKODRIVTXA9+e5MS/2gZEBhYJt13GrAz5/IOZKddH/0Z3TP/Zgo+yw==",
       "license": "MIT",
       "peer": true,
       "engines": {

package/templates/locks/pnpm-lock.yaml

@@ -2640,8 +2640,8 @@ packages:
       sqlite3:
         optional: true
 
-  electron-to-chromium@1.5.437:
-    resolution: {integrity: sha512-1z60R0Nb+kYPnGUrQ6PvMjTVINDGMfqQZ/mI5FJIHvTotlA6noI+YJWakbjaFM+qhLXg9WnK3RUeYSO5ixSHJA==}
+  electron-to-chromium@1.5.438:
+    resolution: {integrity: sha512-AN9xMU1hJiT65LkCUPL1DZm5TCbOPb2Qsm5pYwFLEXp6/qj9SdT4yMiqs7Qqstwvkn1zF7l36SRGt+s6XcJ0FA==}
 
   emoji-regex-xs@2.0.1:
     resolution: {integrity: sha512-1QFuh8l7LqUcKe24LsPUNzjrzJQ7pgRwp1QMcZ5MX6mFplk2zQ08NVCM84++1cveaUUYtcCYHmeFEuNg16sU4g==}
@@ -2950,8 +2950,8 @@ packages:
   magic-string@0.30.21:
     resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
 
-  magic-string@1.4.1:
-    resolution: {integrity: sha512-8lyCu36ErXR0J9uaGKlKQoiLZKmtI63YGLE8G2o9jyRPdr4X47LusSOwgOJOzcVtp81fTAAjxR7BwKz682Jhow==}
+  magic-string@1.4.2:
+    resolution: {integrity: sha512-vG+rjFRj1PqdIBozIxAGMjPlOhaVe+GXpbttY/iSK7rGcJRMlwNJO7dcUwmUqkymsFLJiNGI06t4D7Fr7yRC9g==}
 
   merge-stream@2.0.0:
     resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
@@ -3039,8 +3039,8 @@ packages:
   neo-async@2.6.2:
     resolution: {integrity: sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==}
 
-  node-releases@2.0.56:
-    resolution: {integrity: sha512-x0InOIyzgdk+eyaWaRJFH5snEtiImgBgblZ2CyPrLmqqcuMQkEvcDPHbzqbD8eDsSeJbVOjn+crzyzHaM4D+/A==}
+  node-releases@2.0.57:
+    resolution: {integrity: sha512-kQK9LGGFiHtrWiNhZtA7Qbw17AQz+dmsEKODRIVTXA9+e5MS/2gZEBhYJt13GrAz5/IOZKddH/0Z3TP/Zgo+yw==}
     engines: {node: '>=18'}
 
   obug@3.0.0:
@@ -5214,7 +5214,7 @@ snapshots:
       '@rolldown/pluginutils': 1.0.1
       es-module-lexer: 2.3.2
       estree-walker: 3.0.3
-      magic-string: 1.4.1
+      magic-string: 1.4.2
       obug: 3.0.0
       react: 19.3.0
       react-dom: 19.3.0(react@19.3.0)
@@ -5388,8 +5388,8 @@ snapshots:
     dependencies:
       baseline-browser-mapping: 2.11.25
       caniuse-lite: 1.0.30001810
-      electron-to-chromium: 1.5.437
-      node-releases: 2.0.56
+      electron-to-chromium: 1.5.438
+      node-releases: 2.0.57
       update-browserslist-db: 1.3.3(browserslist@4.29.0)
 
   buffer-from@1.1.2: {}
@@ -5459,7 +5459,7 @@ snapshots:
     optionalDependencies:
       kysely: 0.29.6
 
-  electron-to-chromium@1.5.437: {}
+  electron-to-chromium@1.5.438: {}
 
   emoji-regex-xs@2.0.1: {}
 
@@ -5780,7 +5780,7 @@ snapshots:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.6.0
 
-  magic-string@1.4.1:
+  magic-string@1.4.2:
     dependencies:
       '@jridgewell/sourcemap-codec': 1.6.0
 
@@ -5827,7 +5827,7 @@ snapshots:
 
   neo-async@2.6.2: {}
 
-  node-releases@2.0.56: {}
+  node-releases@2.0.57: {}
 
   obug@3.0.0: {}
 

package/templates/locks/yarn.lock

@@ -2879,9 +2879,9 @@ magic-string@^0.30.11, magic-string@^0.30.21:
     "@jridgewell/sourcemap-codec" "^1.5.5"
 
 magic-string@^1.2.3:
-  version "1.4.1"
-  resolved "https://registry.yarnpkg.com/magic-string/-/magic-string-1.4.1.tgz#d0f91b82cd286a8a8de14f4254ccbf1d7e07f55e"
-  integrity sha512-8lyCu36ErXR0J9uaGKlKQoiLZKmtI63YGLE8G2o9jyRPdr4X47LusSOwgOJOzcVtp81fTAAjxR7BwKz682Jhow==
+  version "1.4.2"
+  resolved "https://registry.yarnpkg.com/magic-string/-/magic-string-1.4.2.tgz#508aef4aac7319496dc074ec60ea511c49daf138"
+  integrity sha512-vG+rjFRj1PqdIBozIxAGMjPlOhaVe+GXpbttY/iSK7rGcJRMlwNJO7dcUwmUqkymsFLJiNGI06t4D7Fr7yRC9g==
   dependencies:
     "@jridgewell/sourcemap-codec" "^1.6.0"
 

package/templates/next/.env.example

@@ -0,0 +1,21 @@
+# Postgres, from your Neon project (Dashboard → Connection string).
+DATABASE_URL=
+
+# Sessions and signed upload URLs. Generate with: openssl rand -base64 32
+BETTER_AUTH_SECRET=
+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=
+
+# Optional. Rate limits and anything that has to be true across every instance.
+UPSTASH_REDIS_REST_URL=
+UPSTASH_REDIS_REST_TOKEN=
+
+# Optional. Without these, email is printed to the console instead of sent.
+RESEND_API_KEY=
+MAIL_FROM=

package/templates/next/README.md

@@ -0,0 +1,16 @@
+# __APP_NAME__
+
+A [Flare](https://flare-docs.codetotech.com) app on Next.js, Postgres and Prisma.
+
+```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 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.
+
+Docs: https://flare-docs.codetotech.com

package/templates/next/app/api/health/route.ts

@@ -0,0 +1,7 @@
+import { prisma } from "@/lib/db";
+
+/** Is the app up, and can it reach the database? */
+export async function GET() {
+  const rows = (await prisma.$queryRaw`select 1 as ok`) as { ok: number }[];
+  return Response.json({ ok: true, database: rows[0]?.ok === 1 });
+}

package/templates/next/app/dashboard/account/password/page.tsx

@@ -0,0 +1,19 @@
+import { Password } from "@/components/account/sections";
+import { prisma } from "@/lib/db";
+import { requireSession } from "@/lib/session";
+
+export const metadata = { title: "Password" };
+
+/** Whether this person signs in with a password at all: social and passkey accounts have none. */
+async function hasPassword(userId: string) {
+  const credential = await prisma.account.findFirst({
+    where: { userId, providerId: "credential" },
+    select: { id: true },
+  });
+  return Boolean(credential);
+}
+
+export default async function PasswordPage() {
+  const { user } = await requireSession("/dashboard/account/password");
+  return <Password hasPassword={await hasPassword(user.id)} email={user.email} />;
+}

package/templates/next/app/dashboard/account/security/page.tsx

@@ -0,0 +1,31 @@
+import { ConnectedAccounts, Passkeys, TwoFactor } from "@/components/account/sections";
+import { prisma } from "@/lib/db";
+import { enabledSocialProviders } from "@/lib/auth";
+import { authConfig, twoFactorAvailable } from "@/lib/auth-config";
+import { requireSession } from "@/lib/session";
+
+export const metadata = { title: "Security" };
+
+/** Two-factor, passkeys and the accounts you can sign in with. */
+export default async function SecurityPage() {
+  const { user } = await requireSession("/dashboard/account/security");
+  const credential = await prisma.account.findFirst({
+    where: { userId: user.id, providerId: "credential" },
+    select: { id: true },
+  });
+  const providers = enabledSocialProviders();
+
+  return (
+    <>
+      {twoFactorAvailable && (
+        <TwoFactor
+          enabled={Boolean((user as { twoFactorEnabled?: boolean | null }).twoFactorEnabled)}
+          hasPassword={Boolean(credential)}
+          methods={authConfig.twoFactor}
+        />
+      )}
+      {authConfig.passkeys && <Passkeys />}
+      {providers.length > 0 && <ConnectedAccounts providers={providers} />}
+    </>
+  );
+}

package/templates/next/app/dashboard/actions.ts

@@ -0,0 +1,277 @@
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { createObjectKey, fileKeyPrefix, fileMaxBytes, matchesContentType, mimeTypesFor, type FileField } from "@flaredev/core";
+import type { FieldIssue } from "@flaredev/core/server";
+import { diffFields, recordAudit } from "@/lib/audit";
+import { listViews, MAX_VIEWS } from "@/lib/views";
+import { prisma } from "@/lib/db";
+import { toCsv } from "@/lib/csv";
+import { storage } from "@/lib/storage";
+import { can, storedFields, type PolicyAction, type Resource } from "@flaredev/core";
+import { resourcePath, dashboardSession, dashboardStore, policyFor } from "@/lib/dashboard";
+
+export type ActionResult<T = unknown> =
+  | { ok: true; data: T }
+  | { ok: false; status: number; error: string; issues?: FieldIssue[]; field?: string };
+
+const forbidden = (message = "You don't have access to this."): ActionResult<never> => ({ ok: false, status: 403, error: message });
+
+/** Session + policy check for one action on one resource. */
+async function allowed(resourceName: string, action: PolicyAction): Promise<ActionResult<never> | undefined> {
+  const { allowed: inAdmin, role } = await dashboardSession();
+  if (!inAdmin) return forbidden();
+  if (!can(policyFor(resourceName), role, action)) return forbidden(`Your role can't ${action} this record.`);
+}
+
+/**
+ * Take a deleted record's uploads out of storage.
+ *
+ * The row is gone, so nothing can point at those objects again, and an app that never
+ * removes them pays to keep files no one can reach. A failure here is swallowed on
+ * purpose: the record is already deleted, and a stray object is a smaller problem than
+ * an action that reports failure after having done the work.
+ */
+async function removeUploads(resource: Resource, record: Record<string, unknown> | null | undefined): Promise<void> {
+  if (!record) return;
+  for (const [key, def] of storedFields(resource)) {
+    if (def.kind !== "file") continue;
+    const value = record[key];
+    if (typeof value === "string" && value) await storage.delete(value).catch(() => undefined);
+  }
+}
+
+export async function deleteRecordAction(resourceName: string, id: string): Promise<ActionResult<{ id: string }>> {
+  const denied = await allowed(resourceName, "delete");
+  if (denied) return denied;
+
+  const store = dashboardStore(resourceName);
+  const existing = await store.get(id);
+  const result = await store.delete(id);
+  if (result.ok) {
+    await removeUploads(store.resource, existing.ok ? existing.data : null);
+    await recordAudit({
+      action: "delete",
+      resource: resourceName,
+      recordId: id,
+      recordLabel: existing.ok ? recordTitle(store.resource, existing.data) : null,
+    });
+    revalidatePath(resourcePath(store.resource));
+  }
+  return result;
+}
+
+/** What to call a record in the audit log: its title field, falling back to its id. */
+function recordTitle(resource: { titleField: string }, record: Record<string, unknown>): string {
+  const value = record[resource.titleField];
+  return typeof value === "string" && value ? value : String(record.id ?? "");
+}
+
+/** How many rows one export may fetch: enough for a spreadsheet, not enough to exhaust the Worker. */
+const EXPORT_LIMIT = 50_000;
+const EXPORT_PAGE = 500;
+
+export async function deleteManyAction(resourceName: string, ids: string[]): Promise<ActionResult<{ deleted: number; failed: number }>> {
+  const denied = await allowed(resourceName, "delete");
+  if (denied) return denied;
+  if (ids.length === 0) return { ok: true, data: { deleted: 0, failed: 0 } };
+  if (ids.length > 500) return { ok: false, status: 400, error: "That's more than 500 records. Delete them in smaller batches." };
+
+  const store = dashboardStore(resourceName);
+  // One at a time, through the store: deleting a record runs its policy, its hooks and
+  // its cache invalidation, and a row that refuses to go (a foreign key still pointing
+  // at it) shouldn't take the rest of the batch with it.
+  let deleted = 0;
+  let failed = 0;
+  const hasFiles = storedFields(store.resource).some(([, def]) => def.kind === "file");
+  for (const id of ids) {
+    // Only read the record first when there's an upload to clean up afterwards.
+    const existing = hasFiles ? await store.get(id) : null;
+    const result = await store.delete(id);
+    if (result.ok) {
+      deleted++;
+      if (existing?.ok) await removeUploads(store.resource, existing.data);
+    } else failed++;
+  }
+  if (deleted > 0) {
+    await recordAudit({ action: "bulk-delete", resource: resourceName, changes: { deleted, failed } });
+    revalidatePath(resourcePath(store.resource));
+  }
+  return { ok: true, data: { deleted, failed } };
+}
+
+/**
+ * Every record matching the current search and filters, as CSV.
+ *
+ * Read through the same store the table uses, so the export shows exactly what the
+ * person can see — their policy, their filters, their sort.
+ */
+export async function exportRecordsAction(resourceName: string, query: string): Promise<ActionResult<{ csv: string; rows: number; truncated: boolean }>> {
+  const denied = await allowed(resourceName, "read");
+  if (denied) return denied;
+
+  const store = dashboardStore(resourceName);
+  const fields = storedFields(store.resource).filter(([, def]) => def.kind !== "file");
+  const columns = [["id", "Id"] as const, ...fields.map(([key, def]) => [key, def.label] as const), ["createdAt", "Created"] as const];
+
+  const rows: Record<string, unknown>[] = [];
+  let truncated = false;
+  for (let page = 1; rows.length < EXPORT_LIMIT; page++) {
+    const params = new URLSearchParams(query);
+    params.set("page", String(page));
+    params.set("perPage", String(EXPORT_PAGE));
+    const result = await store.list(params);
+    if (!result.ok) return result;
+    rows.push(...result.data.data);
+    if (page >= result.data.meta.totalPages) break;
+    if (rows.length >= EXPORT_LIMIT) {
+      truncated = true;
+      break;
+    }
+  }
+
+  const csv = toCsv(rows, columns.map(([key, label]) => ({ key, label })));
+  return { ok: true, data: { csv, rows: rows.length, truncated } };
+}
+
+/** Keep the table's current query as a named view, for this person. */
+export async function saveViewAction(resourceName: string, name: string, query: string): Promise<ActionResult<{ id: string }>> {
+  const denied = await allowed(resourceName, "read");
+  if (denied) return denied;
+  const { session } = await dashboardSession();
+  if (!session) return { ok: false, status: 401, error: "Sign in to save a view." };
+
+  const label = name.trim().slice(0, 60);
+  if (!label) return { ok: false, status: 400, error: "Give the view a name." };
+  const existing = await listViews(resourceName);
+  if (existing.length >= MAX_VIEWS) {
+    return { ok: false, status: 400, error: `That's ${MAX_VIEWS} views for ${resourceName}. Delete one first.` };
+  }
+
+  const row = await prisma.savedView.create({
+    data: { userId: session.user.id, resource: resourceName, name: label, query: query.replace(/^\?/, "").slice(0, 2000) },
+    select: { id: true },
+  });
+  revalidatePath("/dashboard", "layout");
+  return { ok: true, data: { id: row.id } };
+}
+
+/** Views belong to the person who saved them, so only they can remove one. */
+export async function deleteViewAction(id: string): Promise<ActionResult<{ id: string }>> {
+  const { session } = await dashboardSession();
+  if (!session) return { ok: false, status: 401, error: "Sign in first." };
+  await prisma.savedView.deleteMany({ where: { id, userId: session.user.id } });
+  revalidatePath("/dashboard", "layout");
+  return { ok: true, data: { id } };
+}
+
+export async function createRecordAction(resourceName: string, input: unknown): Promise<ActionResult<Record<string, unknown>>> {
+  const denied = await allowed(resourceName, "create");
+  if (denied) return denied;
+
+  const store = dashboardStore(resourceName);
+  const result = await store.create(input);
+  if (result.ok) {
+    await recordAudit({
+      action: "create",
+      resource: resourceName,
+      recordId: String(result.data.id),
+      recordLabel: recordTitle(store.resource, result.data),
+      changes: diffFields(null, result.data),
+    });
+    revalidatePath(resourcePath(store.resource));
+  }
+  return result;
+}
+
+export async function updateRecordAction(resourceName: string, id: string, input: unknown): Promise<ActionResult<Record<string, unknown>>> {
+  const denied = await allowed(resourceName, "update");
+  if (denied) return denied;
+
+  const store = dashboardStore(resourceName);
+  const before = await store.get(id);
+  const result = await store.update(id, input);
+  if (result.ok) {
+    await recordAudit({
+      action: "update",
+      resource: resourceName,
+      recordId: id,
+      recordLabel: recordTitle(store.resource, result.data),
+      changes: diffFields(before.ok ? before.data : null, result.data),
+    });
+    revalidatePath(resourcePath(store.resource));
+  }
+  return result;
+}
+
+/** The file field `fieldKey` of a resource, or a failure when it doesn't exist. */
+function fileField(
+  resourceName: string,
+  fieldKey: string,
+): { failure: ActionResult<never> } | { field: FileField & { label: string }; prefix: string } {
+  const { resource } = dashboardStore(resourceName);
+  const field = resource.fields[fieldKey];
+  if (!field || field.kind !== "file") {
+    return { failure: { ok: false, status: 400, error: `${resourceName} has no file field "${fieldKey}".` } };
+  }
+  return { field, prefix: fileKeyPrefix(resource, fieldKey) };
+}
+
+/**
+ * A short-lived signed URL for uploading to a `file:[…]` field. The declared type and
+ * size are checked against the descriptor before signing, so a browser can't widen
+ * what the field accepts; the storage route then checks the bytes really are that type.
+ */
+export async function createUploadUrlAction(
+  resourceName: string,
+  fieldKey: string,
+  file: { name: string; type: string; size: number },
+): Promise<ActionResult<{ url: string; key: string }>> {
+  // Uploading is part of creating or editing a record, so either permission is enough.
+  const deniedCreate = await allowed(resourceName, "create");
+  const deniedUpdate = await allowed(resourceName, "update");
+  if (deniedCreate && deniedUpdate) return deniedUpdate;
+
+  const target = fileField(resourceName, fieldKey);
+  if ("failure" in target) return target.failure;
+  const { field, prefix } = target;
+
+  const contentTypes = mimeTypesFor(field.accept);
+  if (!matchesContentType(file.type || "application/octet-stream", contentTypes)) {
+    return { ok: false, status: 415, error: `${field.label} accepts ${field.accept.join(", ")} files.`, field: fieldKey };
+  }
+  const maxBytes = fileMaxBytes(field);
+  if (file.size > maxBytes) {
+    return { ok: false, status: 413, error: `${field.label} must be ${Math.round(maxBytes / 1024 / 1024)} MB or smaller.`, field: fieldKey };
+  }
+
+  const upload = await storage.createUploadUrl({ key: createObjectKey(file.name, prefix), contentTypes, maxBytes });
+  return { ok: true, data: { url: upload.url, key: upload.key } };
+}
+
+/**
+ * A short-lived URL for viewing a file stored in a `file:[…]` field. Only keys under that
+ * field's prefix are signed, and only for roles that can work with the resource, so a
+ * guessed or borrowed key can't be read through a resource the role can't see.
+ */
+export async function createReadUrlAction(
+  resourceName: string,
+  fieldKey: string,
+  key: string,
+  /**
+   * Serve the file as a download with this name instead of showing it in the tab. Object
+   * keys carry an id to keep them unique, so without this a download arrives called
+   * `3f1c…-invoice.pdf` — pass the name the record holds.
+   */
+  downloadAs?: string,
+): Promise<ActionResult<{ url: string }>> {
+  const denied = await allowed(resourceName, "read");
+  // Someone creating or editing a record can view what they just uploaded.
+  if (denied && (await allowed(resourceName, "create")) && (await allowed(resourceName, "update"))) return denied;
+
+  const target = fileField(resourceName, fieldKey);
+  if ("failure" in target) return target.failure;
+  if (!key.startsWith(target.prefix)) return { ok: false, status: 403, error: "That file doesn't belong to this field.", field: fieldKey };
+
+  return { ok: true, data: { url: await storage.createReadUrl({ key, downloadAs: downloadAs || undefined }) } };
+}

package/templates/next/app/dashboard/layout.tsx

@@ -0,0 +1,64 @@
+import { cookies } from "next/headers";
+import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
+import { Toaster } from "@/components/ui/sonner";
+import { DashboardHeader, type Notice, type Theme } from "@/components/dashboard/dashboard-header";
+import { DashboardSidebar } from "@/components/dashboard/dashboard-sidebar";
+import { prisma } from "@/lib/db";
+import { authConfig, twoFactorAvailable } from "@/lib/auth-config";
+import { dashboardLinks } from "@/lib/dashboard-nav";
+import { ADMIN_ROLES, visibleResources } from "@/lib/dashboard";
+import { requireSession } from "@/lib/session";
+import { listViews } from "@/lib/views";
+
+/**
+ * The frame around every signed-in page: the app's resources in the sidebar, the
+ * account menu in the header and in the sidebar's footer.
+ *
+ * Everyone signed in gets a dashboard. What's in it depends on the policies: the
+ * sidebar lists only the resources this person may read, and the sections that manage
+ * the app itself are for ADMIN_ROLES (lib/dashboard.ts).
+ */
+export default async function DashboardLayout({ children }: { children: React.ReactNode }) {
+  const { user } = await requireSession("/dashboard");
+  const jar = await cookies();
+  const theme = (jar.get("flare-theme")?.value ?? "system") as Theme;
+  const collapsed = jar.get("sidebar_state")?.value === "false";
+  const role = (user as { role?: string | null }).role ?? "";
+
+  const views = await listViews();
+  const resources = (await visibleResources()).map((resource) => ({
+    name: resource.name,
+    pluralLabel: resource.pluralLabel,
+    slug: resource.slug,
+    icon: resource.icon,
+    group: resource.group,
+    views: views.filter((view) => view.resource === resource.name).map(({ id, name, query }) => ({ id, name, query })),
+  }));
+
+  // What the bell has to say: the things about this account that aren't done yet.
+  const passkeys = await prisma.passkey.count({ where: { userId: user.id } });
+  const notices: Notice[] = [
+    ...(user.emailVerified
+      ? []
+      : [{ id: "verify-email", title: "Verify your email address", description: "We'll send a new link or code.", href: "/verify-email", tone: "warning" as const }]),
+    ...(twoFactorAvailable && !(user as { twoFactorEnabled?: boolean | null }).twoFactorEnabled
+      ? [{ id: "two-factor", title: "Turn on two-factor authentication", description: "A second step after your password.", href: "/dashboard/account/security" }]
+      : []),
+    ...(authConfig.passkeys && passkeys === 0
+      ? [{ id: "passkey", title: "Add a passkey", description: "Sign in with Face ID, Touch ID or Windows Hello.", href: "/dashboard/account/security" }]
+      : []),
+  ];
+
+  const account = { name: user.name, email: user.email, image: (user as { image?: string | null }).image };
+
+  return (
+    <SidebarProvider defaultOpen={!collapsed}>
+      <DashboardSidebar appName="__APP_NAME__" resources={resources} links={dashboardLinks} isAdmin={ADMIN_ROLES.includes(role)} user={account} />
+      <SidebarInset>
+        <DashboardHeader user={account} initialTheme={theme} notices={notices} />
+        <main className="flex flex-1 flex-col gap-6 p-4 md:p-6 lg:p-8">{children}</main>
+      </SidebarInset>
+      <Toaster theme={theme} />
+    </SidebarProvider>
+  );
+}