@flaredev/cli 0.13.0 → 0.14.0

package/templates/app/lib/permissions.ts

@@ -0,0 +1,105 @@
+import { revalidateTag } from "next/cache";
+import { and, asc, eq } from "drizzle-orm";
+import { withGrants, type PermissionGrant, type Policy, type PolicyAction } from "@flaredev/core";
+import { getDb } from "@/db";
+import { role as roleTable, rolePermission } from "@/db/flare-schema";
+import { user } from "@/db/auth-schema";
+import { policies } from "@/policies";
+import { cached, TTL } from "./cache";
+
+/**
+ * Permissions managed from the dashboard, on top of the policies in your code.
+ *
+ * `policies/*.policy.ts` is the floor and this only ever widens it — the reasoning is
+ * in `withGrants` (@flaredev/core), and the short version is that a row in a table must
+ * never be able to lock an app out or quietly restrict something the code left open.
+ *
+ * Everything here is cached under one tag and revalidated on every write, so a role
+ * change takes effect on the editor's next request rather than in a minute's time.
+ */
+
+export const GRANTS_TAG = "flare/permissions";
+
+/** The four things a role can be granted. "list" is read, so it is not one of them. */
+export const GRANTABLE: Exclude<PolicyAction, "list">[] = ["read", "create", "update", "delete"];
+
+const readGrants = cached(
+  async (): Promise<PermissionGrant[]> => {
+    const rows = await getDb()
+      .select({ role: rolePermission.role, resource: rolePermission.resource, action: rolePermission.action })
+      .from(rolePermission);
+    return rows as PermissionGrant[];
+  },
+  ["flare", "permissions"],
+  { tags: [GRANTS_TAG], revalidate: TTL.medium },
+);
+
+/** Every grant in the database. */
+export function allGrants(): Promise<PermissionGrant[]> {
+  return readGrants();
+}
+
+/** The policy in your code, before the dashboard's grants. */
+export function codePolicy(resourceName: string): Policy | undefined {
+  return (policies as Record<string, Policy | undefined>)[resourceName];
+}
+
+/**
+ * The policy actually enforced for a resource: the file, widened by the grants.
+ *
+ * Undefined when there is no policy file, which means the resource is open to every
+ * signed-in user — and grants on it do nothing. The roles screen says so.
+ */
+export async function effectivePolicy(resourceName: string): Promise<Policy | undefined> {
+  return withGrants(codePolicy(resourceName), resourceName, await allGrants());
+}
+
+/** Roles that exist, newest last. Registering one is what makes it offerable in the UI. */
+export async function listRoles(): Promise<{ name: string; label: string }[]> {
+  return getDb().select({ name: roleTable.name, label: roleTable.label }).from(roleTable).orderBy(asc(roleTable.createdAt));
+}
+
+/**
+ * Roles that accounts actually hold, registered or not.
+ *
+ * `flare user:role someone@example.com auditor` is a complete way to create a role —
+ * the string on the account is the role. If this screen only listed the `role` table it
+ * would hide the ones already in use, and you could not grant anything to them. So the
+ * two lists are merged, and holding a role is enough to appear.
+ */
+export async function rolesInUse(): Promise<string[]> {
+  const rows = await getDb().selectDistinct({ role: user.role }).from(user);
+  return rows.map((row) => row.role).filter((role): role is string => Boolean(role));
+}
+
+export async function createRole(name: string, label: string): Promise<void> {
+  await getDb().insert(roleTable).values({ name, label }).onConflictDoUpdate({ target: roleTable.name, set: { label } });
+  revalidateTag(GRANTS_TAG, { expire: 0 });
+}
+
+/**
+ * Forget a role.
+ *
+ * Its grants go with it — a grant naming a role nobody holds is noise that will outlive
+ * everyone who remembers what it was for. Accounts keep the role string they have;
+ * `can()` simply stops finding grants for it, and the policy file still decides.
+ */
+export async function deleteRole(name: string): Promise<void> {
+  const db = getDb();
+  await db.delete(rolePermission).where(eq(rolePermission.role, name));
+  await db.delete(roleTable).where(eq(roleTable.name, name));
+  revalidateTag(GRANTS_TAG, { expire: 0 });
+}
+
+/** Tick or untick one cell of the matrix. */
+export async function setGrant(role: string, resource: string, action: string, granted: boolean): Promise<void> {
+  const db = getDb();
+  if (granted) {
+    await db.insert(rolePermission).values({ role, resource, action }).onConflictDoNothing();
+  } else {
+    await db
+      .delete(rolePermission)
+      .where(and(eq(rolePermission.role, role), eq(rolePermission.resource, resource), eq(rolePermission.action, action)));
+  }
+  revalidateTag(GRANTS_TAG, { expire: 0 });
+}

package/templates/app/lib/stale-chunk.ts

@@ -0,0 +1,50 @@
+/**
+ * Telling "the code in this tab is out of date" apart from a real failure.
+ *
+ * A browser that has loaded one build and is handed another — you updated the app and
+ * it rebuilt, or you started a different Flare app on the same localhost port — can end
+ * up executing a module graph that no longer matches what the server is serving. The
+ * bundler says so in its own words:
+ *
+ *   "... was instantiated because it was required from module <file>, but the module
+ *    factory is not available."
+ *
+ * It reads like a crash in your code, and it is not: nothing is wrong with the app, the
+ * tab is simply holding stale JavaScript. It matters that the error boundary knows the
+ * difference, because the usual remedy — React's `reset()`, which re-renders the
+ * segment without a page load — cannot fix this one. The stale modules are still in
+ * memory afterwards. Only a real reload replaces them.
+ */
+
+/** Phrases every bundler in this family uses for "the code in this tab is out of date". */
+const STALE_CHUNK = [
+  "module factory is not available",
+  "chunkloaderror",
+  "loading chunk",
+  "loading css chunk",
+  "failed to fetch dynamically imported module",
+  "error loading dynamically imported module",
+  "importing a module script failed",
+];
+
+/** Whether this error means the tab's JavaScript is stale rather than the app is broken. */
+export function isStaleChunkError(error: unknown): boolean {
+  if (!error) return false;
+  const name = (error as { name?: unknown }).name;
+  if (typeof name === "string" && name.toLowerCase() === "chunkloaderror") return true;
+  const message = (error as { message?: unknown }).message;
+  if (typeof message !== "string") return false;
+  const haystack = message.toLowerCase();
+  return STALE_CHUNK.some((phrase) => haystack.includes(phrase));
+}
+
+/**
+ * Reload the page, bypassing the cached modules.
+ *
+ * `location.reload()` is enough for the common case, and is what the bundler's own
+ * advice amounts to. It is called from a click handler so the browser treats it as a
+ * user-initiated navigation rather than a redirect loop.
+ */
+export function hardReload(): void {
+  if (typeof window !== "undefined") window.location.reload();
+}

package/templates/app/migrations/0000_init.sql

@@ -108,6 +108,15 @@ CREATE TABLE `role` (
 	`created_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL
 );
 --> statement-breakpoint
+CREATE TABLE `role_permission` (
+	`id` text PRIMARY KEY NOT NULL,
+	`role` text NOT NULL,
+	`resource` text NOT NULL,
+	`action` text NOT NULL,
+	`created_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `role_permission_unique` ON `role_permission` (`role`,`resource`,`action`);--> statement-breakpoint
 CREATE TABLE `saved_view` (
 	`id` text PRIMARY KEY NOT NULL,
 	`user_id` text NOT NULL,

package/templates/app/migrations/meta/0000_snapshot.json

@@ -1,7 +1,7 @@
 {
   "version": "6",
   "dialect": "sqlite",
-  "id": "06909070-5897-4787-87c1-4e86bf5f98d3",
+  "id": "e643eb1a-d0d0-4191-83cf-68129224a23d",
   "prevId": "00000000-0000-0000-0000-000000000000",
   "tables": {
     "account": {
@@ -734,6 +734,62 @@
       "uniqueConstraints": {},
       "checkConstraints": {}
     },
+    "role_permission": {
+      "name": "role_permission",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "resource": {
+          "name": "resource",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "action": {
+          "name": "action",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": "(cast(unixepoch('subsecond') * 1000 as integer))"
+        }
+      },
+      "indexes": {
+        "role_permission_unique": {
+          "name": "role_permission_unique",
+          "columns": [
+            "role",
+            "resource",
+            "action"
+          ],
+          "isUnique": true
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
     "saved_view": {
       "name": "saved_view",
       "columns": {

package/templates/app/migrations/meta/_journal.json

@@ -5,7 +5,7 @@
     {
       "idx": 0,
       "version": "6",
-      "when": 1790112915429,
+      "when": 1794024182826,
       "tag": "0000_init",
       "breakpoints": true
     }

package/templates/locks/cloudflare/pnpm-lock.yaml

@@ -58,7 +58,7 @@ importers:
         version: 0.45.4(kysely@0.29.8)
       lucide-react:
         specifier: ^1.46.0
-        version: 1.69.0(@types/react@19.3.0)(react@19.3.1)
+        version: 1.70.0(@types/react@19.3.0)(react@19.3.1)
       radix-ui:
         specifier: ^1.6.7
         version: 1.8.1(@types/react-dom@19.3.0(@types/react@19.3.0))(@types/react@19.3.0)(react-dom@19.3.1(react@19.3.1))(react@19.3.1)
@@ -2527,8 +2527,8 @@ packages:
       sqlite3:
         optional: true
 
-  electron-to-chromium@1.5.477:
-    resolution: {integrity: sha512-PN++F4zWZoVDGWinxMnSCpVqKhqFOJfLXxdU8bYJKudAEsHL/XKVITOKWVbfMt1r276Mi9RDLU9VHx9uKJ4RMQ==}
+  electron-to-chromium@1.5.478:
+    resolution: {integrity: sha512-pftG+ma5Lm8O6/p45bhYT6StBN5ziQymaRzmCZwFl8DwWHKPPD93FdOmP1aqftcepolQYvrcyTLa17kE8Yf+jg==}
 
   emoji-regex-xs@2.0.1:
     resolution: {integrity: sha512-1QFuh8l7LqUcKe24LsPUNzjrzJQ7pgRwp1QMcZ5MX6mFplk2zQ08NVCM84++1cveaUUYtcCYHmeFEuNg16sU4g==}
@@ -2756,8 +2756,8 @@ packages:
   linebreak@1.1.0:
     resolution: {integrity: sha512-MHp03UImeVhB7XZtjd0E4n6+3xr5Dq/9xI/5FptGk5FrbDR3zagPa2DS6U8ks/3HjbKWG9Q1M2ufOzxV2qLYSQ==}
 
-  lucide-react@1.69.0:
-    resolution: {integrity: sha512-UTFECm4yEgkgMN0kfLuxWcmlk+4u02Jrqehgk3ZXRx/Ud68OpP7hjkp67bvkBHmIpMaZCIveF1QDYeupO7XmYQ==}
+  lucide-react@1.70.0:
+    resolution: {integrity: sha512-gCTPPN1MlQUBtUgdsUv+0CAUj+X8hifRUiRBw4E5v7lvDIOIpx0EZezdGQMSimS8pKA6esvullJub4GYr0mCHA==}
     peerDependencies:
       '@types/react': '*'
       react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
@@ -5185,7 +5185,7 @@ snapshots:
     dependencies:
       baseline-browser-mapping: 2.11.35
       caniuse-lite: 1.0.30001822
-      electron-to-chromium: 1.5.477
+      electron-to-chromium: 1.5.478
       node-releases: 2.0.63
       update-browserslist-db: 1.3.4(browserslist@4.29.5)
 
@@ -5256,7 +5256,7 @@ snapshots:
     optionalDependencies:
       kysely: 0.29.8
 
-  electron-to-chromium@1.5.477: {}
+  electron-to-chromium@1.5.478: {}
 
   emoji-regex-xs@2.0.1: {}
 
@@ -5495,7 +5495,7 @@ snapshots:
       base64-js: 0.0.8
       unicode-trie: 2.0.0
 
-  lucide-react@1.69.0(@types/react@19.3.0)(react@19.3.1):
+  lucide-react@1.70.0(@types/react@19.3.0)(react@19.3.1):
     dependencies:
       react: 19.3.1
     optionalDependencies:

package/templates/locks/next/pnpm-lock.yaml

@@ -3169,8 +3169,8 @@ packages:
     resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
     engines: {node: '>= 6'}
 
-  glob@13.0.6:
-    resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
+  glob@13.0.7:
+    resolution: {integrity: sha512-wfsFgXQ8A3SEI9XGf7Nl3Y9l7ffSrGh7SUCT7vU/2CzYPep9kjxAn1S40F9OPKxAMGCVl7HtNlJhrCJUeUq83g==}
     engines: {node: 18 || 20 || >=22}
 
   graceful-fs@4.2.11:
@@ -6412,7 +6412,7 @@ snapshots:
       async-sema: 3.1.1
       bindings: 1.5.0
       estree-walker: 2.0.2
-      glob: 13.0.6
+      glob: 13.0.7
       graceful-fs: 4.2.11
       node-gyp-build: 4.8.4
       picomatch: 4.0.7
@@ -7163,7 +7163,7 @@ snapshots:
     dependencies:
       is-glob: 4.0.3
 
-  glob@13.0.6:
+  glob@13.0.7:
     dependencies:
       minimatch: 10.2.6
       minipass: 7.1.3

package/templates/next/lib/dashboard.ts

@@ -4,6 +4,7 @@ import { allowedActions, can, columnName, ownershipFilter, type Policy, type Pol
 import { createResourceStore, prismaRows, type PrismaDelegate, type ResourceStore } from "@/lib/resource";
 import { prisma } from "@/lib/db";
 import { policies } from "@/policies";
+import { effectivePolicy } from "./permissions";
 import { resourceTables } from "@/resources/server";
 import { currentUser } from "./api";
 import { auth } from "./auth";
@@ -19,6 +20,13 @@ import { cached, resourceTag, revalidateResource, TTL } from "./cache";
 
 export const ADMIN_ROLES = ["admin", "staff"];
 
+/**
+ * The policy in your code, before the dashboard's grants.
+ *
+ * The store takes this one, because the half of a policy the store enforces is `own` —
+ * per-record ownership — which is a code decision and not something the roles screen
+ * can change. Role checks go through {@link effectivePolicy} instead.
+ */
 export function policyFor(resourceName: string): Policy | undefined {
   return (policies as Record<string, Policy | undefined>)[resourceName];
 }
@@ -27,7 +35,9 @@ export async function dashboardSession() {
   const session = await auth.api.getSession({ headers: await headers() });
   if (!session) return { session: null, role: null, allowed: false } as const;
   const role = (session.user as { role?: string | null }).role ?? null;
-  const readable = allResources().some((resource) => can(policyFor(resource.name), role, "read"));
+  const readable = (await Promise.all(allResources().map((resource) => effectivePolicy(resource.name)))).some((policy) =>
+    can(policy, role, "read"),
+  );
   return { session, role, allowed: (role !== null && ADMIN_ROLES.includes(role)) || readable } as const;
 }
 
@@ -46,7 +56,7 @@ export async function requireDashboard(returnTo = "/dashboard") {
  */
 export async function requireAccess(resource: Resource, action: PolicyAction) {
   const { session, role } = await requireDashboard(resourcePath(resource));
-  const policy = policyFor(resource.name);
+  const policy = await effectivePolicy(resource.name);
   if (!can(policy, role, action)) {
     redirect(action !== "read" && can(policy, role, "read") ? resourcePath(resource) : "/dashboard?error=forbidden");
   }
@@ -56,7 +66,7 @@ export async function requireAccess(resource: Resource, action: PolicyAction) {
 /** What the current user may do with a resource, for hiding actions they can't use. */
 export async function adminPermissions(resourceName: string) {
   const { role } = await dashboardSession();
-  return allowedActions(policyFor(resourceName), role);
+  return allowedActions(await effectivePolicy(resourceName), role);
 }
 
 /**
@@ -190,7 +200,8 @@ export function allResources(): Resource[] {
 /** Resources the current user may read, for the sidebar and dashboard. */
 export async function visibleResources(): Promise<Resource[]> {
   const { role } = await dashboardSession();
-  return allResources().filter((resource) => can(policyFor(resource.name), role, "read"));
+  const policies = await Promise.all(allResources().map((resource) => effectivePolicy(resource.name)));
+  return allResources().filter((resource, index) => can(policies[index], role, "read"));
 }
 
 export function resourcePath(resource: Resource, ...parts: string[]) {

package/templates/next/lib/permissions.ts

@@ -0,0 +1,100 @@
+import { revalidateTag } from "next/cache";
+import { withGrants, type PermissionGrant, type Policy, type PolicyAction } from "@flaredev/core";
+import { prisma } from "@/lib/db";
+import { policies } from "@/policies";
+import { cached, TTL } from "./cache";
+
+/**
+ * Permissions managed from the dashboard, on top of the policies in your code.
+ *
+ * `policies/*.policy.ts` is the floor and this only ever widens it — the reasoning is
+ * in `withGrants` (@flaredev/core), and the short version is that a row in a table must
+ * never be able to lock an app out or quietly restrict something the code left open.
+ *
+ * Everything here is cached under one tag and revalidated on every write, so a role
+ * change takes effect on the editor's next request rather than in a minute's time.
+ */
+
+export const GRANTS_TAG = "flare/permissions";
+
+/** The four things a role can be granted. "list" is read, so it is not one of them. */
+export const GRANTABLE: Exclude<PolicyAction, "list">[] = ["read", "create", "update", "delete"];
+
+const readGrants = cached(
+  async (): Promise<PermissionGrant[]> => {
+    const rows = await prisma.rolePermission.findMany({ select: { role: true, resource: true, action: true } });
+    return rows as PermissionGrant[];
+  },
+  ["flare", "permissions"],
+  { tags: [GRANTS_TAG], revalidate: TTL.medium },
+);
+
+/** Every grant in the database. */
+export function allGrants(): Promise<PermissionGrant[]> {
+  return readGrants();
+}
+
+/** The policy in your code, before the dashboard's grants. */
+export function codePolicy(resourceName: string): Policy | undefined {
+  return (policies as Record<string, Policy | undefined>)[resourceName];
+}
+
+/**
+ * The policy actually enforced for a resource: the file, widened by the grants.
+ *
+ * Undefined when there is no policy file, which means the resource is open to every
+ * signed-in user — and grants on it do nothing. The roles screen says so.
+ */
+export async function effectivePolicy(resourceName: string): Promise<Policy | undefined> {
+  return withGrants(codePolicy(resourceName), resourceName, await allGrants());
+}
+
+/** Roles that exist, newest last. Registering one is what makes it offerable in the UI. */
+export async function listRoles(): Promise<{ name: string; label: string }[]> {
+  const rows = await prisma.role.findMany({ orderBy: { createdAt: "asc" }, select: { name: true, label: true } });
+  return rows;
+}
+
+/**
+ * Roles that accounts actually hold, registered or not.
+ *
+ * `flare user:role someone@example.com auditor` is a complete way to create a role —
+ * the string on the account is the role. If this screen only listed the `role` table it
+ * would hide the ones already in use, and you could not grant anything to them. So the
+ * two lists are merged, and holding a role is enough to appear.
+ */
+export async function rolesInUse(): Promise<string[]> {
+  const rows = await prisma.user.findMany({ where: { role: { not: null } }, distinct: ["role"], select: { role: true } });
+  return rows.map((row) => row.role).filter((role): role is string => Boolean(role));
+}
+
+export async function createRole(name: string, label: string): Promise<void> {
+  await prisma.role.upsert({ where: { name }, update: { label }, create: { name, label } });
+  revalidateTag(GRANTS_TAG, { expire: 0 });
+}
+
+/**
+ * Forget a role.
+ *
+ * Its grants go with it — a grant naming a role nobody holds is noise that will outlive
+ * everyone who remembers what it was for. Accounts keep the role string they have;
+ * `can()` simply stops finding grants for it, and the policy file still decides.
+ */
+export async function deleteRole(name: string): Promise<void> {
+  await prisma.$transaction([prisma.rolePermission.deleteMany({ where: { role: name } }), prisma.role.delete({ where: { name } })]);
+  revalidateTag(GRANTS_TAG, { expire: 0 });
+}
+
+/** Tick or untick one cell of the matrix. */
+export async function setGrant(role: string, resource: string, action: string, granted: boolean): Promise<void> {
+  if (granted) {
+    await prisma.rolePermission.upsert({
+      where: { role_resource_action: { role, resource, action } },
+      update: {},
+      create: { role, resource, action },
+    });
+  } else {
+    await prisma.rolePermission.deleteMany({ where: { role, resource, action } });
+  }
+  revalidateTag(GRANTS_TAG, { expire: 0 });
+}

package/templates/next/prisma/schema/base.prisma

@@ -133,6 +133,37 @@ model TwoFactor {
 }
 
 /// Who changed what, written by the dashboard's actions.
+/// Roles a user can hold (`user.role` from Better Auth's admin plugin). Register them
+/// from the dashboard's Roles screen or with `flare role:add <name>`.
+model Role {
+  name      String   @id
+  label     String
+  createdAt DateTime @default(now()) @map("created_at")
+
+  @@map("role")
+}
+
+/// Permissions granted from the dashboard, on top of the policies in your code.
+///
+/// A row says "this role may do this to this resource". It can only ever *widen* what
+/// `policies/*.policy.ts` already allows — see `withGrants` in @flaredev/core. A
+/// resource with no policy file is open to every signed-in user, and no row here
+/// changes that; the roles screen says so rather than pretending otherwise.
+model RolePermission {
+  id        String   @id @default(uuid())
+  /// The role's name, as in the Role table and user.role.
+  role      String
+  /// The resource's descriptor name, e.g. "Invoice".
+  resource  String
+  /// "read", "create", "update" or "delete".
+  action    String
+  createdAt DateTime @default(now()) @map("created_at")
+
+  /// One row per cell of the matrix: ticking a box twice is the same tick.
+  @@unique([role, resource, action])
+  @@map("role_permission")
+}
+
 model AuditLog {
   id           String   @id @default(uuid())
   action       String