@flaredev/cli 0.1.0

package/templates/app/lib/auth.ts

@@ -0,0 +1,44 @@
+import { env, waitUntil } from "cloudflare:workers";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "@better-auth/drizzle-adapter";
+import { nextCookies } from "better-auth/next-js";
+import { admin } from "better-auth/plugins/admin";
+import { hashPassword, verifyPassword } from "@flaredev/core";
+import { getDb, schema } from "@/db";
+
+/** Optional: set when serving from a custom domain (e.g. https://example.com). */
+const configuredURL = (env as { BETTER_AUTH_URL?: string }).BETTER_AUTH_URL;
+
+export const auth = betterAuth({
+  appName: "__APP_NAME__",
+  secret: env.BETTER_AUTH_SECRET,
+  // Without BETTER_AUTH_URL, accept local dev on any port and this app's workers.dev
+  // host. Cloudflare only routes hosts this Worker serves, so the allowlist can't be spoofed.
+  baseURL: configuredURL || {
+    allowedHosts: ["localhost:*", "127.0.0.1:*", "__APP_NAME__.*.workers.dev"],
+  },
+  database: drizzleAdapter(getDb(), { provider: "sqlite", schema }),
+  socialProviders: __SOCIAL_PROVIDERS__,
+  emailAndPassword: {
+    enabled: true,
+    // PBKDF2 via WebCrypto: the default scrypt exceeds Workers CPU limits.
+    password: { hash: hashPassword, verify: verifyPassword },
+  },
+  advanced: {
+    // Let emails and other deferred work finish after the response is sent.
+    backgroundTasks: { handler: waitUntil },
+  },
+  plugins: [
+    // Adds user.role (default "user") and admin APIs. The /admin area allows ADMIN_ROLES (lib/admin.ts).
+    admin({ defaultRole: "user", adminRoles: ["admin"] }),
+    // Must stay last: lets server actions set auth cookies.
+    nextCookies(),
+  ],
+});
+
+export type Session = typeof auth.$Infer.Session;
+
+/** OAuth providers with credentials configured, e.g. ["github"]. */
+export function enabledSocialProviders(): string[] {
+  return Object.keys(auth.options.socialProviders ?? {});
+}

package/templates/app/lib/cache.ts

@@ -0,0 +1,83 @@
+import { revalidateTag, unstable_cache } from "next/cache";
+import type { ChangeEvent } from "@flaredev/core/server";
+
+/**
+ * Caching for data you read far more often than you write.
+ *
+ * Only the **data cache** (Workers KV) is configured in `vite.config.ts`. It is
+ * what `cached()` below, `fetch()` and `"use cache"` write to. Shared by every
+ * colo and every isolate, so a value computed once is reused until it expires or
+ * its tag is revalidated.
+ *
+ * vinext's page-level CDN cache (the Workers Cache `cdn` adapter) is off until a
+ * vinext fix lands: in the current beta, pages that redirect break behind it.
+ *
+ * Nothing here caches per-user data: everything keyed by session belongs
+ * outside the cache, since these entries are shared between visitors.
+ */
+
+/** How long cached values stay fresh, in seconds. Pick the one that matches how stale you can stand. */
+export const TTL = {
+  /** Changes often, cheap to recompute: counts, dashboards. */
+  short: 60,
+  /** The usual case: lists and detail views behind a resource tag. */
+  medium: 5 * 60,
+  /** Rarely changes: settings, published content, reference tables. */
+  long: 60 * 60,
+} as const;
+
+/** Tag for everything derived from a resource, e.g. `resource/Deal`. */
+export const resourceTag = (resource: string) => `resource/${resource}`;
+
+/** Tag for one record, e.g. `resource/Deal/0f9…`. */
+export const recordTag = (resource: string, id: string) => `resource/${resource}/${id}`;
+
+/**
+ * The KV data cache silently ignores tags containing `:`, `\` or control
+ * characters — the entry is stored untagged, so no revalidation ever reaches
+ * it. Refuse them here instead, where the mistake is still visible.
+ */
+function checkTag(tag: string): string {
+  if (!tag || tag.length > 256 || /[\x00-\x1f\\:]/.test(tag)) {
+    throw new Error(`Cache tag "${tag}" can't be used: tags must be 1–256 characters without ":", "\\" or control characters.`);
+  }
+  return tag;
+}
+
+/**
+ * Cache the result of an async function in the data cache.
+ *
+ * `keyParts` identify the value (include every argument the result depends on);
+ * `tags` say what invalidates it. Cached functions must not read cookies,
+ * headers, or anything else request-specific — the value is shared.
+ *
+ * ```ts
+ * const openDeals = cached(
+ *   () => getDb().select({ total: count() }).from(deals).where(eq(deals.stage, "open")),
+ *   ["deals", "open-count"],
+ *   { tags: [resourceTag("Deal")] },
+ * );
+ * ```
+ */
+export function cached<Args extends unknown[], Value>(
+  fn: (...args: Args) => Promise<Value>,
+  keyParts: string[],
+  options: { tags?: string[]; revalidate?: number } = {},
+) {
+  return unstable_cache(fn, keyParts, {
+    revalidate: options.revalidate ?? TTL.medium,
+    tags: (options.tags ?? []).map(checkTag),
+  });
+}
+
+/**
+ * Drop everything cached for a resource (and for the record that changed).
+ * `lib/admin.ts` and `lib/api.ts` pass this to the store, so writes through the
+ * admin or the REST API invalidate without anyone remembering to call it.
+ */
+export function revalidateResource({ resource, action, id }: ChangeEvent) {
+  // { expire: 0 }: drop the entry now rather than serving it stale while it refreshes.
+  // A record someone just edited should never come back with its old values.
+  revalidateTag(resourceTag(resource), { expire: 0 });
+  if (action !== "create") revalidateTag(recordTag(resource, id), { expire: 0 });
+}

package/templates/app/lib/mail.ts

@@ -0,0 +1,36 @@
+import { env } from "cloudflare:workers";
+import { createMailer, renderTransactionalEmail, type TransactionalEmail } from "@flaredev/core";
+
+/**
+ * Transactional email via Resend.
+ *
+ * Without RESEND_API_KEY (e.g. local dev) emails are printed to the console
+ * instead of sent. MAIL_FROM must use a domain verified in Resend. The fallback
+ * sandbox sender only delivers to your own Resend account address.
+ */
+export const mailer = createMailer({
+  apiKey: env.RESEND_API_KEY,
+  from: env.MAIL_FROM || "__APP_NAME__ <onboarding@resend.dev>",
+});
+
+/**
+ * Render and send a transactional email. Resolves to `{ data, error }` and never throws for API errors.
+ *
+ *   const { error } = await sendTransactionalEmail({
+ *     to: user.email,
+ *     subject: "Your order has shipped",
+ *     heading: "On its way",
+ *     paragraphs: [`Order #${order.id} left our warehouse today.`],
+ *     action: { label: "Track order", url: `https://example.com/orders/${order.id}` },
+ *     idempotencyKey: `order-shipped/${order.id}`,
+ *   });
+ */
+export async function sendTransactionalEmail({
+  to,
+  subject,
+  idempotencyKey,
+  ...content
+}: Omit<TransactionalEmail, "appName"> & { to: string | string[]; subject: string; idempotencyKey?: string }) {
+  const { html, text } = renderTransactionalEmail({ appName: "__APP_NAME__", ...content });
+  return mailer.send({ to, subject, html, text, idempotencyKey });
+}

package/templates/app/lib/realtime.ts

@@ -0,0 +1,45 @@
+import {
+  realtimeHub,
+  type RealtimeAuthorize,
+  type RealtimeChannel,
+  type RealtimeChannelNamespace,
+} from "@flaredev/core/realtime/server";
+import { env } from "cloudflare:workers";
+import { auth } from "./auth";
+
+/**
+ * Who may open a realtime connection, per channel. `worker/index.ts` calls this for
+ * every `/realtime/<channel>/ws` upgrade, after rejecting cross-site origins.
+ *
+ * Default: any signed-in user may join any channel and receive events and
+ * presence; nobody may broadcast from the browser (server code publishes with
+ * `realtimeChannel(...).publish`). Tighten per channel as your app needs, e.g.
+ *
+ *   if (channel === "deals" && !["admin", "staff"].includes(role ?? "")) return false;
+ *   if (channel === `user-${session.user.id}`) return { send: true };
+ */
+export const authorizeRealtime: RealtimeAuthorize = async (request) => {
+  // disableRefresh: this runs outside a Next request, where refreshing the
+  // session cookie has nowhere to write it.
+  const session = await auth.api.getSession({ headers: request.headers, query: { disableRefresh: true } });
+  if (!session) return false;
+  return { send: false };
+};
+
+/** The FLARE_REALTIME binding. `env` is the worker runtime binding object; its type is app-generated. */
+function binding(): RealtimeChannelNamespace {
+  return (env as unknown as { FLARE_REALTIME: RealtimeChannelNamespace }).FLARE_REALTIME;
+}
+
+/**
+ * An RPC handle for a realtime channel that server code can publish to.
+ *
+ * ```ts
+ * // In a route handler or server action, after something the UI should
+ * // live-update on, await the RPC (DO stubs return promises):
+ * await realtimeChannel("deals").publish("deal.updated", { id, title });
+ * ```
+ */
+export function realtimeChannel(name: string): RealtimeChannel {
+  return realtimeHub(binding(), name);
+}

package/templates/app/lib/security.ts

@@ -0,0 +1,13 @@
+// Request protection for worker/index.ts. Security is off until you run
+// `flare gen security`, which rewrites the generated block below.
+// generated:start
+/** Minimal ExecutionContext surface worker/index.ts passes in. */
+export interface SecurityContext {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/** Security is not enabled yet: every request goes straight to the app. */
+export async function protect(_request: Request, _env: unknown, _ctx: SecurityContext, next: () => Promise<Response>): Promise<Response> {
+  return next();
+}
+// generated:end

package/templates/app/lib/session.ts

@@ -0,0 +1,24 @@
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { auth } from "./auth";
+
+/** The current session, or null. Validates against the database: use in server components, actions and route handlers. */
+export async function getSession() {
+  return auth.api.getSession({ headers: await headers() });
+}
+
+/** The current session; redirects to /sign-in (returning to `returnTo` afterwards) when signed out. */
+export async function requireSession(returnTo?: string) {
+  const session = await getSession();
+  if (!session) {
+    redirect(returnTo ? `/sign-in?next=${encodeURIComponent(returnTo)}` : "/sign-in");
+  }
+  return session;
+}
+
+/** Only allow same-site relative redirect targets, to avoid open redirects via `?next=`. */
+export function safeRedirectPath(value: unknown, fallback = "/dashboard"): string {
+  return typeof value === "string" && value.startsWith("/") && !value.startsWith("//") && !value.startsWith("/\\")
+    ? value
+    : fallback;
+}

package/templates/app/lib/storage.ts

@@ -0,0 +1,26 @@
+import { env } from "cloudflare:workers";
+import { createObjectKey, createStorage } from "@flaredev/core";
+
+/**
+ * File storage on the `STORAGE` R2 bucket.
+ *
+ * `createUploadUrl` / `createReadUrl` return short-lived signed URLs redeemed by
+ * `app/api/storage/route.ts`. A URL grants access to whoever holds it, so check
+ * that the current user may upload or view the object before issuing one.
+ *
+ *   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 });
+ */
+export const storage = createStorage({
+  bucket: env.STORAGE,
+  // Signing keys are derived from the auth secret with a storage-specific label.
+  secret: env.BETTER_AUTH_SECRET,
+});
+
+export { createObjectKey };

package/templates/app/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

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

@@ -0,0 +1,66 @@
+CREATE TABLE `account` (
+	`id` text PRIMARY KEY NOT NULL,
+	`account_id` text NOT NULL,
+	`provider_id` text NOT NULL,
+	`user_id` text NOT NULL,
+	`access_token` text,
+	`refresh_token` text,
+	`id_token` text,
+	`access_token_expires_at` integer,
+	`refresh_token_expires_at` integer,
+	`scope` text,
+	`password` text,
+	`created_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL,
+	`updated_at` integer NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `user`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE INDEX `account_userId_idx` ON `account` (`user_id`);--> statement-breakpoint
+CREATE TABLE `session` (
+	`id` text PRIMARY KEY NOT NULL,
+	`expires_at` integer NOT NULL,
+	`token` text NOT NULL,
+	`created_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL,
+	`updated_at` integer NOT NULL,
+	`ip_address` text,
+	`user_agent` text,
+	`user_id` text NOT NULL,
+	`impersonated_by` text,
+	FOREIGN KEY (`user_id`) REFERENCES `user`(`id`) ON UPDATE no action ON DELETE cascade
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `session_token_unique` ON `session` (`token`);--> statement-breakpoint
+CREATE INDEX `session_userId_idx` ON `session` (`user_id`);--> statement-breakpoint
+CREATE TABLE `user` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`email` text NOT NULL,
+	`email_verified` integer DEFAULT false NOT NULL,
+	`image` text,
+	`created_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL,
+	`role` text,
+	`banned` integer DEFAULT false,
+	`ban_reason` text,
+	`ban_expires` integer
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `user_email_unique` ON `user` (`email`);--> statement-breakpoint
+CREATE TABLE `verification` (
+	`id` text PRIMARY KEY NOT NULL,
+	`identifier` text NOT NULL,
+	`value` text NOT NULL,
+	`expires_at` integer NOT NULL,
+	`created_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL,
+	`updated_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `verification_identifier_idx` ON `verification` (`identifier`);--> statement-breakpoint
+CREATE TABLE `role` (
+	`name` text PRIMARY KEY NOT NULL,
+	`label` text NOT NULL,
+	`created_at` integer DEFAULT (cast(unixepoch('subsecond') * 1000 as integer)) NOT NULL
+);
+--> statement-breakpoint
+-- Built-in roles: lib/admin.ts lets both into /admin. Add more with `flare role:add`.
+INSERT INTO `role` (`name`, `label`) VALUES ('admin', 'Admin'), ('staff', 'Staff');