@flaredev/cli 0.12.1 → 0.13.0

package/dist/index.js

@@ -371,8 +371,13 @@ var NEXT_DEPENDENCIES = {
   // protocol. Vercel refuses to build it. A pin is only worth having if it is moved when
   // one of these lands, so treat a critical against this line as a release of its own.
   next: "16.3.8",
-  "@prisma/client": "7.10.0",
-  "@prisma/adapter-pg": "7.10.0",
+  // Prisma 7, pinned exactly and deliberately. `prisma@latest` is 8.0.0-rc — a release
+  // candidate — and Prisma's own update notifier prints "npm i @prisma/client@latest"
+  // inside `prisma migrate` output, so an app that follows that advice lands on a
+  // prerelease. The three move together or not at all; a client newer than the CLI that
+  // generated it is the mismatch that shows up as a runtime error, not a build one.
+  "@prisma/client": "7.10.1",
+  "@prisma/adapter-pg": "7.10.1",
   pg: "^8.16.3",
   "@upstash/redis": "^1.36.0",
   "@better-auth/prisma-adapter": "1.7.17",
@@ -381,7 +386,9 @@ var NEXT_DEPENDENCIES = {
   dotenv: "^17.2.3"
 };
 var NEXT_DEV_DEPENDENCIES = {
-  prisma: "7.10.0",
+  // Matches @prisma/client and @prisma/adapter-pg above. See the note there before
+  // moving it: the newest 7.x, not `latest`, which is an 8.0 release candidate.
+  prisma: "7.10.1",
   // Runs seeds: the generated Prisma client is TypeScript a bundler compiles.
   tsx: "^4.23.13",
   // `flare deploy` and `npm run deploy`. Local rather than global, so the deploy works
@@ -407,7 +414,11 @@ var CLOUDFLARE_ONLY = [
   ".dev.vars.example",
   "worker-configuration.d.ts",
   // The engine's Drizzle adapter; the Next.js overlay brings prisma-rows.ts instead.
-  "lib/resource/drizzle-rows.ts"
+  "lib/resource/drizzle-rows.ts",
+  // Estimates Workers, D1 and R2 bills from Cloudflare's own price sheet — numbers that
+  // mean nothing to an app on Vercel and Neon, so a Next.js app doesn't get the page.
+  "app/dashboard/costs",
+  "components/dashboard/cost-estimator.tsx"
 ];
 
 // src/stack.ts
@@ -512,6 +523,9 @@ function installArgs(pm) {
 
 // src/commands/create.ts
 var SEED_ADMIN = { email: "admin@example.com", password: "Password", name: "Admin" };
+function toAppTitle(name) {
+  return name.split("-").map((word) => word ? word[0].toUpperCase() + word.slice(1) : word).join(" ");
+}
 var ALLOW_BUILDS = [
   "'@prisma/engines': false",
   "esbuild: true",
@@ -561,13 +575,14 @@ function createApp(target, options2 = {}) {
   const compatibilityDate = options2.compatibilityDate ?? COMPATIBILITY_DATE;
   const files = copyTemplate(join4(templatesDir, "app"), dir, {
     APP_NAME: name,
+    APP_TITLE: toAppTitle(name),
     COMPAT_DATE: compatibilityDate,
     PM: packageManager,
     THEME: theme,
     SIGNUP: signup
   });
   if (stack === "next") {
-    copyTemplate(join4(templatesDir, "next"), dir, { APP_NAME: name, PM: packageManager, THEME: theme, SIGNUP: signup });
+    copyTemplate(join4(templatesDir, "next"), dir, { APP_NAME: name, APP_TITLE: toAppTitle(name), PM: packageManager, THEME: theme, SIGNUP: signup });
     for (const path of CLOUDFLARE_ONLY) rmSync(join4(dir, path), { recursive: true, force: true });
   }
   writeFileSync3(join4(dir, "lib", "auth-config.ts"), renderAuthConfig(authMethods, authProviders, signup));
@@ -603,10 +618,15 @@ storage/
       start: "next start",
       deploy: "vercel deploy --prod",
       "db:generate": "prisma generate",
-      "db:migrate": "prisma migrate dev",
+      // Thin aliases for the flare commands, so the scripts and the printed steps
+      // can never say different things. `flare migrate` is `prisma migrate dev`
+      // plus `prisma generate` — the generate is not optional; Prisma 7 removed
+      // generator runs from `migrate dev`, and a client without the new model
+      // fails the very next command, usually `flare seed:resource`.
+      "db:migrate": "flare migrate",
       // An account to sign in with, so the app is reachable the moment the tables
       // exist. Safe to run twice: --skip-existing makes a second run a no-op.
-      "db:seed": `flare user:add ${SEED_ADMIN.email} --password ${SEED_ADMIN.password} --name ${SEED_ADMIN.name} --role admin --skip-existing`,
+      "db:seed": "flare db:seed",
       "db:studio": "prisma studio"
     } : {
       dev: "flare dev",
@@ -683,23 +703,27 @@ function printNextSteps(result, installed) {
   const pm = result.packageManager;
   const database = result.stack === "next" ? [
     ["docker compose up -d", "Postgres, on the address .env already has"],
-    [`${pm} run db:migrate`, "create the tables"],
-    [`${pm} run db:seed`, "an account to sign in with"]
+    ["npx flare migrate", "create the tables"],
+    ["npx flare db:seed", "an account to sign in with"]
   ] : [];
   const commands = [
     [`cd ${rel}`, "your new app"],
     ...installed ? [] : [[`${pm} install`, "dependencies first"]],
     ...database,
-    [`${pm} run dev`, "http://localhost:3000"],
+    ["npx flare dev", "http://localhost:3000"]
+  ];
+  const firstResource = [
     ["npx flare gen resource Contact", "a table, API and admin screens"],
+    ["npx flare migrate", "create its table"],
     ["npx flare seed:resource Contact 1000", "fill it with sample rows"]
   ];
-  const width = Math.max(...commands.map(([command]) => command.length)) + 2;
-  const steps = commands.map(([command, note2]) => `${pc.cyan(command.padEnd(width))}${pc.dim(note2)}`);
-  prompts.note(steps.join("\n"), "Next");
+  const width = Math.max(...[...commands, ...firstResource].map(([command]) => command.length)) + 2;
+  const line = ([command, note2]) => `${pc.cyan(command.padEnd(width))}${pc.dim(note2)}`;
+  prompts.note(commands.map(line).join("\n"), "Next");
+  prompts.note(firstResource.map(line).join("\n"), "Your first resource");
   const storage = storageSetupSteps(result.storage, result.stack, { local: true });
   if (storage.length > 0) {
-    prompts.note(storage.map((line) => line.startsWith("http") ? pc.cyan(line) : line).join("\n"), `Uploads \xB7 ${result.storage}`);
+    prompts.note(storage.map((line2) => line2.startsWith("http") ? pc.cyan(line2) : line2).join("\n"), `Uploads \xB7 ${result.storage}`);
   }
   if (result.stack === "next") {
     prompts.note(
@@ -2696,12 +2720,20 @@ async function migrate(options2 = {}) {
   const appRoot = findAppRoot(options2.cwd ?? process.cwd());
   const log2 = options2.log ?? ((message) => console.log(message));
   if (readStack(appRoot) === "next") {
+    const prisma = resolveBin(appRoot, "prisma", "prisma");
+    if (options2.deploy) {
+      log2(`${pc6.cyan("prisma")} migrate deploy`);
+      return runNode([prisma, "migrate", "deploy"], appRoot);
+    }
     if (options2.remote) {
-      log2(pc6.dim("On Next.js, `--remote` is whichever database DATABASE_URL points at."));
+      log2(pc6.dim("On Next.js, the database is whichever one DATABASE_URL points at."));
     }
-    const prisma = resolveBin(appRoot, "prisma", "prisma");
-    log2(`${pc6.cyan("prisma")} migrate deploy`);
-    return runNode([prisma, "migrate", "deploy"], appRoot);
+    const args = ["migrate", "dev", ...options2.name ? ["--name", options2.name] : []];
+    log2(`${pc6.cyan("prisma")} ${args.join(" ")}`);
+    const code = await runNode([prisma, ...args], appRoot);
+    if (code !== 0) return code;
+    log2(`${pc6.cyan("prisma")} generate`);
+    return runNode([prisma, "generate"], appRoot);
   }
   const { db, target, wrangler } = context(options2);
   const result = await runWrangler(wrangler, ["d1", "migrations", "apply", db.binding, ...target], appRoot);
@@ -2928,6 +2960,51 @@ function checkTemplateVersion(installed, cli) {
     fix: "Update the app's dependencies, then `flare update` to take the template changes you want."
   } : { check: "Flare version", verdict: "warn", detail: `app has @flaredev/core ${installed}, which is newer than this CLI (${cli}).`, fix: "Update the CLI." };
 }
+function installedVersion(appRoot, name) {
+  const path = join14(appRoot, "node_modules", ...name.split("/"), "package.json");
+  if (!existsSync15(path)) return void 0;
+  try {
+    return JSON.parse(readFileSync10(path, "utf8")).version;
+  } catch {
+    return void 0;
+  }
+}
+var PRISMA_PACKAGES = ["prisma", "@prisma/client", "@prisma/adapter-pg"];
+function checkPrismaVersions(versions) {
+  const found = Object.entries(versions).filter(([, version]) => version !== void 0);
+  if (found.length === 0) {
+    return { check: "Prisma", verdict: "skip", detail: "Prisma is not installed yet.", fix: "Install dependencies." };
+  }
+  const majors = new Set(found.map(([, version]) => version.split(".")[0]));
+  if (majors.size > 1) {
+    return {
+      check: "Prisma",
+      verdict: "fail",
+      detail: `the Prisma packages disagree on a major: ${found.map(([name, version]) => `${name} ${version}`).join(", ")}.`,
+      fix: "Set all three to the same version. A client the installed CLI did not generate fails on the first query, not at build."
+    };
+  }
+  const [major] = [...majors];
+  if (major !== "7") {
+    const prerelease = found.find(([, version]) => version.includes("-"));
+    return {
+      check: "Prisma",
+      verdict: "fail",
+      detail: `the app is on Prisma ${major}${prerelease ? ` (${prerelease[1]}, a prerelease)` : ""}; Flare generates for 7.`,
+      fix: "Pin prisma, @prisma/client and @prisma/adapter-pg to the same 7.x. `prisma@latest` is an 8.0 release candidate, so ask for the version by number."
+    };
+  }
+  const distinct = new Set(found.map(([, version]) => version));
+  if (distinct.size > 1) {
+    return {
+      check: "Prisma",
+      verdict: "warn",
+      detail: `Prisma 7, but at mixed versions: ${found.map(([name, version]) => `${name} ${version}`).join(", ")}.`,
+      fix: "Match them. They are released together and are only tested together."
+    };
+  }
+  return { check: "Prisma", verdict: "ok", detail: `Prisma ${[...distinct][0]}, all three in step.` };
+}
 function checkRateLimitBackend(declared, configured, stack) {
   if (declared.length === 0) return { check: "Rate limits", verdict: "ok", detail: "none declared." };
   const list2 = declared.map((entry) => `${entry.resource}.${entry.action} ${entry.spec}`).join(", ");
@@ -2964,6 +3041,9 @@ async function diagnose(options2 = {}) {
   }
   findings.push({ check: "Stack", verdict: "ok", detail: stack === "next" ? "Next.js (Prisma, Postgres)." : "Cloudflare (vinext, D1, Drizzle)." });
   findings.push(checkTemplateVersion(installedCoreVersion(appRoot), FLARE_VERSION2));
+  if (stack === "next") {
+    findings.push(checkPrismaVersions(Object.fromEntries(PRISMA_PACKAGES.map((name) => [name, installedVersion(appRoot, name)]))));
+  }
   findings.push(checkEnv(appRoot, stack));
   findings.push(checkBindings(appRoot, stack));
   let resources = [];
@@ -3214,7 +3294,7 @@ async function addUser(email, options2 = {}) {
 async function addOnD1(appRoot, rows, options2, log2) {
   if (options2.role) {
     const roles = await listRoles(options2);
-    if (roles && !roles.includes(options2.role)) {
+    if (roles && roles.length > 0 && !roles.includes(options2.role)) {
       log2(pc9.red(`No role "${options2.role}" is registered. Known roles: ${roles.join(", ") || "none"}.`));
       log2(pc9.dim(`Register it with: flare role:add ${options2.role}${options2.remote ? " --remote" : ""}`));
       return 1;
@@ -6004,7 +6084,7 @@ ${problems.map((problem) => `  ${problem}`).join("\n")}`);
     }
     if (renamed.length) {
       log2(`${pc17.cyan("prisma")} migrate dev --name ${name}_rename`);
-      const applied = await runNodeCapturing([prisma, "migrate", "dev", "--skip-generate", "--name", `${name}_rename`], appRoot);
+      const applied = await runNodeCapturing([prisma, "migrate", "dev", "--name", `${name}_rename`], appRoot);
       if (applied.code !== 0) {
         throw new Error(`The rename migration could not be applied:
 ${applied.output.trim()}`);
@@ -6283,7 +6363,7 @@ import { existsSync as existsSync25, mkdirSync as mkdirSync12, readFileSync as r
 import { dirname as dirname12, join as join25, relative as relative2 } from "path";
 import pc20 from "picocolors";
 var TRACKED = ["app", "lib", "components"];
-var PER_APP = /__APP_NAME__|__PM__|__THEME__|__COMPAT_DATE__/;
+var PER_APP = /__APP_NAME__|__APP_TITLE__|__PM__|__THEME__|__COMPAT_DATE__/;
 var WRITTEN_PER_APP = /* @__PURE__ */ new Set(["lib/auth-config.ts"]);
 var prunedOn = (path, stack) => stack === "next" && CLOUDFLARE_ONLY.some((only) => path === only || path.startsWith(`${only}/`));
 function upstreamFile(path, stack) {
@@ -7802,7 +7882,7 @@ function createCli() {
       printNextSteps(result, installed);
     }
   );
-  cli.command("gen <generator> [name] [second]", `Generate code. Generators: ${GENERATORS.join(", ")}`).option("--fields <fields>", "resource: fields, e.g. 'name:string, email:string!, status:enum(lead,customer)' (single quotes: bash treats ! in double quotes as history)").option("--group <name>", "resource: sidebar heading to file it under, e.g. Sales").option("--icon <name>", "resource: lucide icon for the sidebar, e.g. users").option("--soft-delete", "resource: keep deleted rows and hide them, with a Trash view in the dashboard").option("--method <verb>", "endpoint: GET (default), POST, PATCH, PUT or DELETE").option("--action <action>", "endpoint: policy action to require (read, create, update, delete)").option("--record", "endpoint: put it under one record, /api/<resource>/[id]/<name>").option("--force", "resource/policy/billing/security: overwrite hand-edited generated blocks").option("--from-schema", "migration: diff the current tables instead of a blank migration (Cloudflare only)").example("flare gen migration add_phone --from-schema         # Cloudflare: diff the Drizzle tables").example("flare gen migration add_phone                       # Next.js: prisma migrate dev, refusing a drop").option("--roles <roles>", "policy: roles allowed to read, create and update, e.g. admin,staff").option("--delete-roles <roles>", "policy: roles allowed to delete (default: the first --roles entry)").option("--own <field>", "policy: confine each user to rows whose field holds their id, e.g. --own userId").option("--own-except <roles>", "policy: roles that see every row despite --own, e.g. admin").option("--provider <provider>", "billing: payment provider (default: stripe)").option("--mode <mode>", "billing: subscriptions (the default; includes one-time checkout)").option("--skip-install", "billing/apikeys: write files without adding the dependency").option("--skip-migration", "billing/security/apikeys: skip generating the schema migration").example("flare gen resource Contact --fields 'name:string, email:string!, company:belongsTo(Company)?'").example("flare gen resource Invoice --fields 'number:string!' --soft-delete   # a delete goes to the Trash").example("flare gen endpoint Order publish --method POST --record").example("flare gen migration backfill_contact_status").example("flare gen migration add_phone_to_contacts --from-schema").example("flare gen policy Invoice --roles admin,staff --delete-roles admin").example("flare gen policy Invoice --roles staff --own userId --own-except admin   # each user sees only their own").example("flare gen billing --provider stripe --mode subscriptions").example("flare gen security").example("flare gen apikeys                                   # API keys for cron jobs, scripts and mobile apps").example("flare gen apikeys                                     # bearer keys for crons, scripts and mobile apps").action(
+  cli.command("gen <generator> [name] [second]", `Generate code. Generators: ${GENERATORS.join(", ")}`).option("--fields <fields>", "resource: fields, e.g. 'name:string, email:string!, status:enum(lead,customer)' (single quotes: bash treats ! in double quotes as history)").option("--group <name>", "resource: sidebar heading to file it under, e.g. Sales").option("--icon <name>", "resource: lucide icon for the sidebar, e.g. users").option("--soft-delete", "resource: keep deleted rows and hide them, with a Trash view in the dashboard").option("--method <verb>", "endpoint: GET (default), POST, PATCH, PUT or DELETE").option("--action <action>", "endpoint: policy action to require (read, create, update, delete)").option("--record", "endpoint: put it under one record, /api/<resource>/[id]/<name>").option("--force", "resource/policy/billing/security: overwrite hand-edited generated blocks").option("--from-schema", "migration: diff the current tables instead of a blank migration; on Next.js, also apply declared renames").example("flare gen migration add_phone --from-schema         # Cloudflare: diff the Drizzle tables").example("flare gen migration add_phone                       # Next.js: prisma migrate dev, refusing a drop").option("--roles <roles>", "policy: roles allowed to read, create and update, e.g. admin,staff").option("--delete-roles <roles>", "policy: roles allowed to delete (default: the first --roles entry)").option("--own <field>", "policy: confine each user to rows whose field holds their id, e.g. --own userId").option("--own-except <roles>", "policy: roles that see every row despite --own, e.g. admin").option("--provider <provider>", "billing: payment provider (default: stripe)").option("--mode <mode>", "billing: subscriptions (the default; includes one-time checkout)").option("--skip-install", "billing/apikeys: write files without adding the dependency").option("--skip-migration", "billing/security/apikeys: skip generating the schema migration").example("flare gen resource Contact --fields 'name:string, email:string!, company:belongsTo(Company)?'").example("flare gen resource Invoice --fields 'number:string!' --soft-delete   # a delete goes to the Trash").example("flare gen endpoint Order publish --method POST --record").example("flare gen migration backfill_contact_status").example("flare gen migration add_phone_to_contacts --from-schema").example("flare gen policy Invoice --roles admin,staff --delete-roles admin").example("flare gen policy Invoice --roles staff --own userId --own-except admin   # each user sees only their own").example("flare gen billing --provider stripe --mode subscriptions").example("flare gen security").example("flare gen apikeys                                   # API keys for cron jobs, scripts and mobile apps").example("flare gen apikeys                                     # bearer keys for crons, scripts and mobile apps").action(
     async (generator, name, second, options2) => {
       if (generator === "billing")
         return genBilling({ provider: options2.provider, mode: options2.mode, force: options2.force, skipInstall: options2.skipInstall, skipMigration: options2.skipMigration });
@@ -7864,10 +7944,10 @@ function createCli() {
     "migrate",
     perStack(
       "Apply pending D1 migrations (local database unless --remote)",
-      "Apply pending Prisma migrations to the database in DATABASE_URL (prisma migrate deploy)",
-      "Apply pending migrations: D1 on the Cloudflare stack, Prisma on the Next.js one"
+      "Make the database match the schema: prisma migrate dev + prisma generate (--deploy: apply committed migrations only)",
+      "Make the database match the schema: D1 migrations on Cloudflare; prisma migrate dev + generate on Next.js"
     )
-  ).option("--remote", cloudflareOnly("Target the deployed database")).option("--env <name>", cloudflareOnly("Wrangler environment")).option("--database <binding>", cloudflareOnly("D1 binding, when the app has several")).action(async (options2) => {
+  ).option("--remote", cloudflareOnly("Target the deployed database")).option("--env <name>", cloudflareOnly("Wrangler environment")).option("--database <binding>", cloudflareOnly("D1 binding, when the app has several")).option("--name <name>", "Next.js: name the migration, so Prisma doesn't have to ask").option("--deploy", "Next.js: apply committed migrations and invent nothing (CI, production)").example("flare migrate                      # local, writes a migration if the schema changed").example("flare migrate --deploy             # production: apply what is committed, nothing else").action(async (options2) => {
     process.exitCode = await migrate(options2);
   });
   cli.command(
@@ -7926,6 +8006,15 @@ function createCli() {
   cli.command("sync-types", "Regenerate schema, routes, clients, and validators from resource descriptors; report drift").option("--check", "Change nothing; exit 1 if anything is out of sync (CI)").option("--force", "Overwrite generated blocks that were edited by hand").action(async (options2) => {
     process.exitCode = await syncTypes(options2);
   });
+  cli.command("db:seed", "Seed the development admin account (admin@example.com / Password, role admin)").option("--remote", "Against the deployed database rather than the local one (Cloudflare)").example("flare db:seed").action(async (options2) => {
+    process.exitCode = await addUser(SEED_ADMIN.email, {
+      password: SEED_ADMIN.password,
+      name: SEED_ADMIN.name,
+      role: "admin",
+      skipExisting: true,
+      remote: options2.remote
+    });
+  });
   cli.command("user:add <email>", "Create an account from the command line (the way in when signup is closed)").option("--role <role>", "Role to give them, e.g. admin").option("--password <password>", "Their password (generated and printed when omitted)").option("--name <name>", "Display name (default: the part before the @)").option("--remote", "Against the deployed database rather than the local one").option("--env <name>", "Wrangler environment").option("--skip-existing", "Succeed quietly if the account is already there (for seeds)").example("flare user:add ada@example.com --role admin").action(
     async (email, options2) => {
       process.exitCode = await addUser(email, options2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flaredev/cli",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "The flare command-line tool: create, generate, migrate, and deploy Flare apps",
   "license": "MIT",
   "author": "Muke Johnbaptist",
@@ -41,7 +41,7 @@
     "jiti": "^2.7.0",
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
-    "@flaredev/core": "0.12.1"
+    "@flaredev/core": "0.13.0"
   },
   "engines": {
     "node": ">=22"

package/templates/app/README.md

@@ -1,4 +1,4 @@
-# __APP_NAME__
+# __APP_TITLE__
 
 A [Flare](https://flare-docs.codetotech.com) app running on Cloudflare Workers via vinext.
 

package/templates/app/_gitignore

@@ -1,4 +1,11 @@
 node_modules
+
+# Prisma's generated client (Next.js stack). Generated output, not source: it is
+# rewritten by `prisma generate` on every install (postinstall) and on every build, so
+# committing it means hundreds of generated files in your diffs and a stale client the
+# moment someone changes the schema without regenerating.
+lib/generated/
+
 .env*
 !.env.example
 .dev.vars*

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

@@ -55,9 +55,9 @@ export default async function DashboardLayout({ children }: { children: React.Re
 
   return (
     <SidebarProvider defaultOpen={!collapsed}>
-      <DashboardSidebar appName="__APP_NAME__" resources={resources} links={dashboardLinks} isAdmin={ADMIN_ROLES.includes(role)} user={account} />
+      <DashboardSidebar appName="__APP_TITLE__" resources={resources} links={dashboardLinks} isAdmin={ADMIN_ROLES.includes(role)} user={account} />
       <SidebarInset>
-        <DashboardHeader user={account} initialTheme={theme} notices={notices} />
+        <DashboardHeader user={account} initialTheme={theme} notices={notices} isAdmin={ADMIN_ROLES.includes(role)} />
         <main className="flex flex-1 flex-col gap-6 p-4 md:p-6 lg:p-8">{children}</main>
       </SidebarInset>
       <Toaster theme={theme} />

package/templates/app/app/dashboard/page.tsx

@@ -1,24 +1,33 @@
 import Link from "next/link";
-import { count, eq } from "drizzle-orm";
-import { ArrowRightIcon, CheckCircle2Icon, CircleIcon, PlusIcon } from "lucide-react";
+import { count, eq, gte } from "drizzle-orm";
+import { ArrowRightIcon, CheckCircle2Icon, CircleIcon, PlusIcon, UsersIcon } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
-import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from "@/components/ui/empty";
 import { PageHeader } from "@/components/dashboard/page-header";
 import { resourceIcon } from "@/components/dashboard/resource-icon";
 import { StatCards, type Stat } from "@/components/dashboard/stat-card";
 import { getDb } from "@/db";
-import { passkey } from "@/db/auth-schema";
+import { passkey, user as userTable } from "@/db/auth-schema";
 import { authConfig, twoFactorAvailable } from "@/lib/auth-config";
-import { adminPermissions, resourcePath, resourceStats, trend, visibleResources } from "@/lib/dashboard";
+import { ADMIN_ROLES, adminPermissions, dashboardSession, resourcePath, resourceStats, trend, visibleResources } from "@/lib/dashboard";
 import { requireSession } from "@/lib/session";
 
 export const metadata = { title: "Dashboard" };
 
+/** The three commands that turn an empty app into one with data, with the stack's real steps. */
+const FIRST_RESOURCE_STEPS = [
+  { command: "npx flare gen resource Contact --fields 'name:string, email:email!'", note: "the table, API and admin screens" },
+  { command: "npx flare migrate", note: "create its table" },
+  { command: "npx flare seed:resource Contact 1000", note: "fill it with sample rows" },
+];
+
 /** The first thing you see when you sign in: how much data there is, and what's left to set up. */
 export default async function DashboardPage() {
   const { user } = await requireSession("/dashboard");
+  const { role } = await dashboardSession();
+  const isAdmin = role !== null && ADMIN_ROLES.includes(role);
   const resources = await visibleResources();
+  const week = new Date(Date.now() - 7 * 86_400_000);
 
   const cards = await Promise.all(
     resources.map(async (resource) => {
@@ -28,16 +37,46 @@ export default async function DashboardPage() {
     }),
   );
 
-  const stats: Stat[] = cards.slice(0, 4).map(({ resource, total, recent }) => ({
-    label: resource.pluralLabel,
-    value: total,
-    hint: recent.current > 0 ? `${recent.current.toLocaleString()} this week` : "none this week",
-    change: trend(recent.current, recent.previous),
-    icon: resourceIcon(resource.icon),
-    href: resourcePath(resource),
-  }));
+  // The one table every app has from its first sign-in. Admin only, because it links to
+  // the accounts page, which is.
+  const db = getDb();
+  const [people, peopleThisWeek] = isAdmin
+    ? await Promise.all([
+        db
+          .select({ n: count() })
+          .from(userTable)
+          .then(([row]) => row?.n ?? 0),
+        db
+          .select({ n: count() })
+          .from(userTable)
+          .where(gte(userTable.createdAt, week))
+          .then(([row]) => row?.n ?? 0),
+      ])
+    : [0, 0];
+
+  const stats: Stat[] = [
+    ...(isAdmin
+      ? [
+          {
+            label: "Users",
+            value: people,
+            hint: peopleThisWeek > 0 ? `${peopleThisWeek.toLocaleString()} this week` : "none this week",
+            icon: UsersIcon,
+            href: "/dashboard/users",
+          } satisfies Stat,
+        ]
+      : []),
+    ...cards.slice(0, isAdmin ? 3 : 4).map(({ resource, total, recent }) => ({
+      label: resource.pluralLabel,
+      value: total,
+      hint: recent.current > 0 ? `${recent.current.toLocaleString()} this week` : "none this week",
+      change: trend(recent.current, recent.previous),
+      icon: resourceIcon(resource.icon),
+      href: resourcePath(resource),
+    })),
+  ];
 
-  const [{ passkeys } = { passkeys: 0 }] = await getDb().select({ passkeys: count() }).from(passkey).where(eq(passkey.userId, user.id));
+  const [{ passkeys } = { passkeys: 0 }] = await db.select({ passkeys: count() }).from(passkey).where(eq(passkey.userId, user.id));
   const twoFactorOn = Boolean((user as { twoFactorEnabled?: boolean | null }).twoFactorEnabled);
   const steps = [
     { done: user.emailVerified, label: "Verify your email address", href: "/verify-email" },
@@ -50,31 +89,67 @@ export default async function DashboardPage() {
     <>
       <PageHeader
         title={`Welcome${user.name ? `, ${user.name.split(" ")[0]}` : ""}`}
-        description={resources.length > 0 ? "Everything in your app, and how it's moving." : "Your app is running. Add a resource to fill this page."}
+        description={resources.length > 0 ? "Everything in your app, and how it's moving." : "Your app is running. Add a resource and this page fills in."}
       />
 
       <StatCards stats={stats} />
 
       {resources.length === 0 && (
-        <Empty className="rounded-xl border border-dashed">
-          <EmptyHeader>
-            <EmptyTitle>No resources yet</EmptyTitle>
-            <EmptyDescription>
-              Generate one with <code>flare gen resource Contact --fields &quot;name:string, email:string&quot;</code>, then fill it with{" "}
-              <code>flare seed:resource Contact --count 1000</code>.
-            </EmptyDescription>
-          </EmptyHeader>
-        </Empty>
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-base">Add your first resource</CardTitle>
+            <CardDescription>
+              A resource is a table, its API and its admin screens, generated from one line. Three commands from a terminal in this
+              app:
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="flex flex-col">
+            {FIRST_RESOURCE_STEPS.map((step, index) => (
+              <div key={step.command} className="flex flex-wrap items-baseline gap-x-3 gap-y-1 border-b py-3 last:border-b-0 last:pb-0">
+                <span className="grid size-6 shrink-0 translate-y-0.5 place-items-center rounded-full bg-muted text-xs font-medium text-muted-foreground">
+                  {index + 1}
+                </span>
+                <code className="rounded bg-muted px-2 py-1 font-mono text-[13px]">{step.command}</code>
+                <span className="text-xs text-muted-foreground">{step.note}</span>
+              </div>
+            ))}
+            <p className="mt-4 text-xs text-muted-foreground">
+              Then refresh this page: the sidebar, these cards and the admin screens are already wired to it.
+            </p>
+          </CardContent>
+        </Card>
       )}
 
       <div className="grid gap-6 lg:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
-        {cards.length > 0 && (
+        {(cards.length > 0 || isAdmin) && (
           <Card>
             <CardHeader>
               <CardTitle className="text-base">Your data</CardTitle>
-              <CardDescription>Every resource you can see.</CardDescription>
+              <CardDescription>Every table in the app, and who it belongs to.</CardDescription>
             </CardHeader>
             <CardContent className="flex flex-col">
+              {isAdmin && (
+                <div className="flex items-center gap-3 border-b py-3 last:border-b-0 last:pb-0">
+                  <span className="grid size-9 shrink-0 place-items-center rounded-md bg-muted text-muted-foreground">
+                    <UsersIcon className="size-4.5" />
+                  </span>
+                  <div className="flex min-w-0 flex-col">
+                    <Link href="/dashboard/users" className="truncate text-sm font-medium hover:underline">
+                      Users
+                    </Link>
+                    <span className="text-xs text-muted-foreground">
+                      {people.toLocaleString()} {people === 1 ? "account" : "accounts"}
+                    </span>
+                  </div>
+                  <div className="ml-auto flex items-center gap-1">
+                    <Button variant="ghost" size="icon" aria-label="Open users" asChild>
+                      <Link href="/dashboard/users">
+                        <ArrowRightIcon />
+                      </Link>
+                    </Button>
+                  </div>
+                </div>
+              )}
               {cards.map(({ resource, total, permissions }) => {
                 const Icon = resourceIcon(resource.icon);
                 return (

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

@@ -0,0 +1,86 @@
+"use server";
+
+import { headers } from "next/headers";
+import { revalidatePath } from "next/cache";
+import { auth } from "@/lib/auth";
+import { dashboardSession } from "@/lib/dashboard";
+
+/**
+ * Managing accounts, through Better Auth's admin API.
+ *
+ * The same `admin` plugin that gives users a role also enforces who may call these:
+ * only roles in its `adminRoles` (see lib/auth.ts — "admin" out of the box). The check
+ * here is only for a clean sentence; the API would refuse anyway, which means these
+ * actions are exactly as powerful as the `flare user:add` / `flare user:role` commands
+ * and no more.
+ */
+
+export type UserActionResult = { ok: true } | { ok: false; error: string };
+
+function failed(error: unknown): UserActionResult {
+  const message = error instanceof Error ? error.message : String(error);
+  // Better Auth's refusal for a non-admin caller, said in this page's words.
+  if (/not.*(allowed|permitted)|unauthorized|forbidden/i.test(message)) {
+    return { ok: false, error: "Only an admin can manage accounts." };
+  }
+  return { ok: false, error: message || "That didn't work." };
+}
+
+async function signedIn(): Promise<UserActionResult | undefined> {
+  const { session } = await dashboardSession();
+  if (!session) return { ok: false, error: "You're signed out." };
+}
+
+/** Make an account, exactly as `flare user:add` would: usable immediately. */
+export async function createUserAction(input: { name: string; email: string; password: string; role: string }): Promise<UserActionResult> {
+  const out = await signedIn();
+  if (out) return out;
+  const role = input.role.trim() || "user";
+  if (!/^[a-z][a-z0-9_-]{0,31}$/.test(role)) {
+    return { ok: false, error: "A role is lowercase letters, digits, _ or -, e.g. admin or support-agent." };
+  }
+  try {
+    await auth.api.createUser({
+      body: { name: input.name.trim(), email: input.email.trim(), password: input.password, role: role as "user" },
+      headers: await headers(),
+    });
+  } catch (error) {
+    return failed(error);
+  }
+  revalidatePath("/dashboard/users");
+  return { ok: true };
+}
+
+/** Change what someone is allowed to do. Takes effect on their next request. */
+export async function setRoleAction(input: { userId: string; role: string }): Promise<UserActionResult> {
+  const out = await signedIn();
+  if (out) return out;
+  const role = input.role.trim();
+  if (!/^[a-z][a-z0-9_-]{0,31}$/.test(role)) {
+    return { ok: false, error: "A role is lowercase letters, digits, _ or -, e.g. admin or support-agent." };
+  }
+  try {
+    await auth.api.setRole({ body: { userId: input.userId, role: role as "user" }, headers: await headers() });
+  } catch (error) {
+    return failed(error);
+  }
+  revalidatePath("/dashboard/users");
+  return { ok: true };
+}
+
+/** A banned account keeps its data and loses its way in; unban restores it. */
+export async function setBannedAction(input: { userId: string; banned: boolean }): Promise<UserActionResult> {
+  const out = await signedIn();
+  if (out) return out;
+  try {
+    if (input.banned) {
+      await auth.api.banUser({ body: { userId: input.userId }, headers: await headers() });
+    } else {
+      await auth.api.unbanUser({ body: { userId: input.userId }, headers: await headers() });
+    }
+  } catch (error) {
+    return failed(error);
+  }
+  revalidatePath("/dashboard/users");
+  return { ok: true };
+}