@flaredev/cli 0.2.0 → 0.4.0

package/templates/app/components/dashboard/table-selection.tsx

@@ -0,0 +1,185 @@
+"use client";
+
+import { createContext, useCallback, useContext, useMemo, useState, useTransition } from "react";
+import { useRouter } from "next/navigation";
+import { DownloadIcon, Trash2Icon, XIcon } from "lucide-react";
+import { toast } from "sonner";
+import { deleteManyAction } from "@/app/dashboard/actions";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Spinner } from "@/components/ui/spinner";
+import { toCsv } from "@/lib/csv";
+
+interface SelectionValue {
+  ids: string[];
+  selected: Set<string>;
+  toggle: (id: string) => void;
+  toggleAll: () => void;
+  clear: () => void;
+}
+
+const SelectionContext = createContext<SelectionValue | null>(null);
+
+function useSelection(): SelectionValue {
+  const value = useContext(SelectionContext);
+  if (!value) throw new Error("Selection components must be inside <TableSelection>.");
+  return value;
+}
+
+/**
+ * Selection for the rows on screen.
+ *
+ * Deliberately per page: a "select everything, all 40,000 of them" checkbox reads as
+ * harmless right up until the moment it isn't. To act on more than a page, filter down
+ * to what you mean first.
+ */
+export function TableSelection({ ids, children }: { ids: string[]; children: React.ReactNode }) {
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+
+  const toggle = useCallback((id: string) => {
+    setSelected((current) => {
+      const next = new Set(current);
+      if (!next.delete(id)) next.add(id);
+      return next;
+    });
+  }, []);
+
+  const toggleAll = useCallback(() => {
+    setSelected((current) => (current.size === ids.length ? new Set() : new Set(ids)));
+  }, [ids]);
+
+  const clear = useCallback(() => setSelected(new Set()), []);
+  const value = useMemo(() => ({ ids, selected, toggle, toggleAll, clear }), [ids, selected, toggle, toggleAll, clear]);
+
+  return <SelectionContext.Provider value={value}>{children}</SelectionContext.Provider>;
+}
+
+export function SelectAllCheckbox({ label }: { label: string }) {
+  const { ids, selected, toggleAll } = useSelection();
+  const all = ids.length > 0 && selected.size === ids.length;
+  return (
+    <Checkbox
+      checked={all ? true : selected.size > 0 ? "indeterminate" : false}
+      onCheckedChange={toggleAll}
+      aria-label={all ? `Clear selection` : `Select all ${label} on this page`}
+    />
+  );
+}
+
+export function RowCheckbox({ id, label }: { id: string; label: string }) {
+  const { selected, toggle } = useSelection();
+  return <Checkbox checked={selected.has(id)} onCheckedChange={() => toggle(id)} aria-label={`Select ${label}`} />;
+}
+
+/** Highlights the row while it's selected, so the checkbox isn't the only signal. */
+export function useRowSelected(id: string): boolean {
+  return useSelection().selected.has(id);
+}
+
+interface BarProps {
+  resourceName: string;
+  label: string;
+  pluralLabel: string;
+  canDelete: boolean;
+  /** Rows as they're shown, for exporting what's selected without another round trip. */
+  rows: Record<string, unknown>[];
+  columns: { key: string; label: string }[];
+}
+
+/**
+ * What you can do with the rows you've ticked. Appears only when something is selected,
+ * pinned to the bottom so it's reachable in a long table.
+ */
+export function SelectionBar({ resourceName, label, pluralLabel, canDelete, rows, columns }: BarProps) {
+  const { selected, clear } = useSelection();
+  const router = useRouter();
+  const [confirming, setConfirming] = useState(false);
+  const [pending, startTransition] = useTransition();
+  const count = selected.size;
+  if (count === 0) return null;
+
+  const noun = count === 1 ? label.toLowerCase() : pluralLabel.toLowerCase();
+
+  const exportSelected = () => {
+    const chosen = rows.filter((row) => selected.has(String(row.id)));
+    downloadCsv(`${resourceName.toLowerCase()}-selection.csv`, toCsv(chosen, columns));
+  };
+
+  const remove = () => {
+    startTransition(async () => {
+      const result = await deleteManyAction(resourceName, [...selected]);
+      setConfirming(false);
+      if (!result.ok) {
+        toast.error(result.error);
+        return;
+      }
+      const { deleted, failed } = result.data;
+      clear();
+      router.refresh();
+      if (failed > 0) toast.warning(`Deleted ${deleted}; ${failed} couldn't be deleted.`);
+      else toast.success(`Deleted ${deleted} ${deleted === 1 ? label.toLowerCase() : pluralLabel.toLowerCase()}.`);
+    });
+  };
+
+  return (
+    <>
+      <div className="sticky bottom-4 z-10 mx-auto flex w-fit items-center gap-2 rounded-full border bg-popover px-2 py-1.5 shadow-lg">
+        <span className="px-2 text-sm tabular-nums">
+          {count} {noun} selected
+        </span>
+        <Button variant="ghost" size="sm" onClick={exportSelected}>
+          <DownloadIcon data-icon="inline-start" />
+          Export
+        </Button>
+        {canDelete && (
+          <Button variant="ghost" size="sm" className="text-destructive hover:text-destructive" onClick={() => setConfirming(true)}>
+            <Trash2Icon data-icon="inline-start" />
+            Delete
+          </Button>
+        )}
+        <Button variant="ghost" size="icon" onClick={clear} aria-label="Clear selection">
+          <XIcon />
+        </Button>
+      </div>
+
+      <AlertDialog open={confirming} onOpenChange={setConfirming}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              Delete {count} {noun}?
+            </AlertDialogTitle>
+            <AlertDialogDescription>This can&apos;t be undone. Anything that belongs to them may be deleted too.</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={pending}>Keep them</AlertDialogCancel>
+            <AlertDialogAction onClick={(event) => { event.preventDefault(); remove(); }} disabled={pending}>
+              {pending && <Spinner data-icon="inline-start" />}
+              Delete {count}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  );
+}
+
+/** Hand the browser a file without a round trip to the server. */
+export function downloadCsv(filename: string, csv: string) {
+  // The BOM is what makes Excel read UTF-8 correctly.
+  const url = URL.createObjectURL(new Blob(["\ufeff" + csv], { type: "text/csv;charset=utf-8" }));
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = filename;
+  link.click();
+  URL.revokeObjectURL(url);
+}

package/templates/app/components/dashboard/traffic-chart.tsx

@@ -0,0 +1,32 @@
+import type { RequestPoint } from "@/lib/analytics";
+
+/**
+ * Requests a day, with the failing share in red.
+ *
+ * Bars in CSS rather than a charting library: seven numbers don't justify shipping one
+ * to the browser, and this renders on the server with the rest of the page.
+ */
+export function TrafficChart({ points }: { points: RequestPoint[] }) {
+  const peak = Math.max(1, ...points.map((point) => point.requests));
+  const day = new Intl.DateTimeFormat(undefined, { weekday: "short" });
+
+  return (
+    <div className="flex items-end gap-2" role="img" aria-label={`Requests a day for the last ${points.length} days`}>
+      {points.map((point) => {
+        const height = Math.max(2, Math.round((point.requests / peak) * 100));
+        const errorShare = point.requests > 0 ? (point.errors / point.requests) * 100 : 0;
+        return (
+          <div key={point.date} className="flex flex-1 flex-col items-center gap-2">
+            <span className="text-xs tabular-nums text-muted-foreground">{point.requests.toLocaleString()}</span>
+            <div className="flex h-32 w-full items-end" title={`${point.date}: ${point.requests.toLocaleString()} requests, ${point.errors.toLocaleString()} errors`}>
+              <div className="relative w-full overflow-hidden rounded-t-md bg-primary/80" style={{ height: `${height}%` }}>
+                {errorShare > 0 && <div className="absolute inset-x-0 bottom-0 bg-destructive" style={{ height: `${Math.max(4, errorShare)}%` }} />}
+              </div>
+            </div>
+            <span className="text-xs text-muted-foreground">{day.format(new Date(`${point.date}T00:00:00Z`))}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/templates/app/components/dashboard/user-menu.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+import Link from "next/link";
+import { KeyRoundIcon, LogOutIcon, MonitorSmartphoneIcon, ShieldCheckIcon, UserIcon } from "lucide-react";
+import { authClient } from "@/lib/auth-client";
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
+import {
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+} from "@/components/ui/dropdown-menu";
+
+export interface DashboardUser {
+  name?: string | null;
+  email: string;
+  image?: string | null;
+}
+
+/** "Ada Lovelace" → "AL"; an address falls back to its first letter. */
+export function initials(user: DashboardUser): string {
+  const source = user.name?.trim() || user.email;
+  const parts = source.split(/[\s@._-]+/).filter(Boolean);
+  return (parts.length > 1 ? `${parts[0]![0]}${parts[1]![0]}` : source.slice(0, 2)).toUpperCase();
+}
+
+export function UserAvatar({ user, className }: { user: DashboardUser; className?: string }) {
+  return (
+    <Avatar className={className}>
+      {user.image && <AvatarImage src={user.image} alt="" />}
+      <AvatarFallback className="bg-primary/10 text-xs font-medium text-primary">{initials(user)}</AvatarFallback>
+    </Avatar>
+  );
+}
+
+/**
+ * What's inside the account menu, wherever it's opened from — the header's avatar and
+ * the sidebar's footer both show this, so there's one list of account actions, not two.
+ */
+export function UserMenuItems({ user }: { user: DashboardUser }) {
+  const signOut = async () => {
+    await authClient.signOut();
+    window.location.assign("/sign-in");
+  };
+
+  return (
+    <>
+      <DropdownMenuLabel className="flex items-center gap-2 font-normal">
+        <UserAvatar user={user} className="size-8" />
+        <span className="grid min-w-0">
+          <span className="truncate text-sm font-medium">{user.name || "Signed in"}</span>
+          <span className="truncate text-xs text-muted-foreground">{user.email}</span>
+        </span>
+      </DropdownMenuLabel>
+      <DropdownMenuSeparator />
+      <DropdownMenuGroup>
+        <DropdownMenuItem asChild>
+          <Link href="/dashboard/account">
+            <UserIcon />
+            Profile
+          </Link>
+        </DropdownMenuItem>
+        <DropdownMenuItem asChild>
+          <Link href="/dashboard/account/password">
+            <KeyRoundIcon />
+            Password
+          </Link>
+        </DropdownMenuItem>
+        <DropdownMenuItem asChild>
+          <Link href="/dashboard/account/security">
+            <ShieldCheckIcon />
+            Security
+          </Link>
+        </DropdownMenuItem>
+        <DropdownMenuItem asChild>
+          <Link href="/dashboard/account/sessions">
+            <MonitorSmartphoneIcon />
+            Devices
+          </Link>
+        </DropdownMenuItem>
+      </DropdownMenuGroup>
+      <DropdownMenuSeparator />
+      <DropdownMenuGroup>
+        <DropdownMenuItem variant="destructive" onSelect={signOut}>
+          <LogOutIcon />
+          Sign out
+        </DropdownMenuItem>
+      </DropdownMenuGroup>
+    </>
+  );
+}

package/templates/app/components/ui/sonner.tsx

@@ -1,20 +1,23 @@
-"use client"
+"use client";
 
-import {
-  CircleCheckIcon,
-  InfoIcon,
-  Loader2Icon,
-  OctagonXIcon,
-  TriangleAlertIcon,
-} from "lucide-react"
-import { Toaster as Sonner, type ToasterProps } from "sonner"
+import { CircleCheckIcon, InfoIcon, Loader2Icon, OctagonXIcon, TriangleAlertIcon } from "lucide-react";
+import { Toaster as Sonner, type ToasterProps } from "sonner";
 
-// The theme comes from the admin layout (cookie-backed), so no theme provider is needed.
+/**
+ * Toasts in the app's theme.
+ *
+ * The colours come from the theme tokens (app/globals.css), so success is the theme's
+ * green, an error is its red, and the corner radius matches everything else — switch
+ * the theme and the toasts switch with it. Light or dark comes from the dashboard
+ * layout's cookie, so there's no theme provider in the tree.
+ */
 const Toaster = ({ theme = "system", ...props }: ToasterProps) => {
   return (
     <Sonner
       theme={theme as ToasterProps["theme"]}
       className="toaster group"
+      position="bottom-right"
+      closeButton
       icons={{
         success: <CircleCheckIcon className="size-4" />,
         info: <InfoIcon className="size-4" />,
@@ -22,17 +25,34 @@ const Toaster = ({ theme = "system", ...props }: ToasterProps) => {
         error: <OctagonXIcon className="size-4" />,
         loading: <Loader2Icon className="size-4 animate-spin" />,
       }}
+      toastOptions={{
+        classNames: {
+          // A tinted left edge and a matching icon: the tone reads at a glance without
+          // colouring the whole toast, which would fight the page behind it.
+          toast:
+            "group toast border-l-4 shadow-lg data-[type=success]:border-l-success data-[type=error]:border-l-danger data-[type=warning]:border-l-warning data-[type=info]:border-l-link",
+          icon: "group-data-[type=success]:text-success group-data-[type=error]:text-danger group-data-[type=warning]:text-warning group-data-[type=info]:text-link",
+          title: "text-sm font-medium",
+          description: "text-xs text-muted-foreground",
+          actionButton: "bg-primary text-primary-foreground",
+          cancelButton: "bg-muted text-muted-foreground",
+        },
+      }}
       style={
         {
           "--normal-bg": "var(--popover)",
           "--normal-text": "var(--popover-foreground)",
           "--normal-border": "var(--border)",
           "--border-radius": "var(--radius)",
+          "--success-bg": "var(--popover)",
+          "--success-text": "var(--popover-foreground)",
+          "--error-bg": "var(--popover)",
+          "--error-text": "var(--popover-foreground)",
         } as React.CSSProperties
       }
       {...props}
     />
-  )
-}
+  );
+};
 
-export { Toaster }
+export { Toaster };

package/templates/app/db/flare-schema.ts

@@ -1,5 +1,5 @@
 import { sql } from "drizzle-orm";
-import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
 
 /**
  * Roles a user can hold (`user.role` from Better Auth's admin plugin).
@@ -13,3 +13,57 @@ export const role = sqliteTable("role", {
     .notNull()
     .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`),
 });
+
+/**
+ * Who changed what, and when. Written by the dashboard's actions (lib/audit.ts) for
+ * every create, update, delete and import, and read by /dashboard/observability.
+ *
+ * `changes` holds only the fields that moved, as JSON, never the whole record: an audit
+ * trail that copies every row is a second database of the same data, and a place for
+ * secrets to leak into.
+ */
+export const auditLog = sqliteTable(
+  "audit_log",
+  {
+    id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
+    /** "create", "update", "delete", "import" or "bulk-delete". */
+    action: text("action").notNull(),
+    /** The resource's descriptor name, e.g. "Contact". */
+    resource: text("resource").notNull(),
+    /** The record, when the action was about one. */
+    recordId: text("record_id"),
+    /** How the record reads afterwards, for the log's own listing. */
+    recordLabel: text("record_label"),
+    userId: text("user_id"),
+    userEmail: text("user_email"),
+    /** Fields that changed: { field: { from, to } }, or a count for bulk actions. */
+    changes: text("changes", { mode: "json" }).$type<Record<string, unknown> | null>(),
+    ip: text("ip"),
+    createdAt: integer("created_at", { mode: "timestamp_ms" })
+      .notNull()
+      .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`),
+  },
+  (table) => [index("audit_log_created_at_idx").on(table.createdAt), index("audit_log_resource_idx").on(table.resource)],
+);
+
+/**
+ * A filtered, sorted, column-picked view of a resource that someone wanted to keep, like
+ * "Overdue invoices". The query is the table's own URL query string, so saving a view is
+ * saving what's in the address bar — nothing about the table has to know views exist.
+ */
+export const savedView = sqliteTable(
+  "saved_view",
+  {
+    id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()),
+    userId: text("user_id").notNull(),
+    /** The resource's descriptor name, e.g. "Invoice". */
+    resource: text("resource").notNull(),
+    name: text("name").notNull(),
+    /** "q=ada&filter[status]=lead&sort=-createdAt", without the leading "?". */
+    query: text("query").notNull(),
+    createdAt: integer("created_at", { mode: "timestamp_ms" })
+      .notNull()
+      .default(sql`(cast(unixepoch('subsecond') * 1000 as integer))`),
+  },
+  (table) => [index("saved_view_user_idx").on(table.userId, table.resource)],
+);

package/templates/app/lib/analytics.ts

@@ -0,0 +1,121 @@
+/**
+ * Traffic, errors and latency for this Worker, from Cloudflare's GraphQL Analytics API.
+ *
+ * Needs two secrets, and works without them: `CLOUDFLARE_ACCOUNT_ID` and
+ * `CLOUDFLARE_API_TOKEN` (a token with Account Analytics: Read). Without them the
+ * dashboard says so and shows the rest of the page, because analytics is the one part
+ * of an app that can't be read from its own database.
+ *
+ *   wrangler secret put CLOUDFLARE_API_TOKEN
+ */
+import { env } from "cloudflare:workers";
+
+const ENDPOINT = "https://api.cloudflare.com/client/v4/graphql";
+
+export interface RequestPoint {
+  /** "2026-09-22" */
+  date: string;
+  requests: number;
+  errors: number;
+  /** Median CPU time in milliseconds. */
+  medianCpuMs: number;
+}
+
+export interface WorkerAnalytics {
+  points: RequestPoint[];
+  requests: number;
+  errors: number;
+  /** Errors as a percentage of requests. */
+  errorRate: number;
+  medianCpuMs: number;
+}
+
+/** Why there's nothing to show, when there's nothing to show. */
+export type AnalyticsResult = { ok: true; data: WorkerAnalytics } | { ok: false; reason: "unconfigured" | "failed"; message: string };
+
+interface GraphQlResponse {
+  data?: {
+    viewer?: {
+      accounts?: {
+        workersInvocationsAdaptive?: {
+          dimensions: { date: string };
+          sum: { requests: number; errors: number };
+          quantiles: { cpuTimeP50: number };
+        }[];
+      }[];
+    };
+  };
+  errors?: { message: string }[];
+}
+
+const QUERY = `query WorkerTraffic($accountTag: String!, $scriptName: String!, $since: Date!, $until: Date!) {
+  viewer {
+    accounts(filter: { accountTag: $accountTag }) {
+      workersInvocationsAdaptive(
+        limit: 100
+        filter: { scriptName: $scriptName, date_geq: $since, date_leq: $until }
+        orderBy: [date_ASC]
+      ) {
+        dimensions { date }
+        sum { requests errors }
+        quantiles { cpuTimeP50 }
+      }
+    }
+  }
+}`;
+
+/** Traffic for the last `days` days, a point per day. */
+export async function workerAnalytics(scriptName: string, days = 7): Promise<AnalyticsResult> {
+  const vars = env as unknown as Record<string, string | undefined>;
+  const accountTag = vars.CLOUDFLARE_ACCOUNT_ID;
+  const token = vars.CLOUDFLARE_API_TOKEN;
+  if (!accountTag || !token) {
+    return {
+      ok: false,
+      reason: "unconfigured",
+      message: "Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN to read traffic, errors and CPU time from Cloudflare.",
+    };
+  }
+
+  const day = (offset: number) => new Date(Date.now() - offset * 86_400_000).toISOString().slice(0, 10);
+  try {
+    const response = await fetch(ENDPOINT, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({
+        query: QUERY,
+        variables: { accountTag, scriptName, since: day(days - 1), until: day(0) },
+      }),
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!response.ok) {
+      return { ok: false, reason: "failed", message: `Cloudflare answered ${response.status}. Check the token's Account Analytics: Read permission.` };
+    }
+    const body = (await response.json()) as GraphQlResponse;
+    if (body.errors?.length) return { ok: false, reason: "failed", message: body.errors[0]!.message };
+
+    const series = body.data?.viewer?.accounts?.[0]?.workersInvocationsAdaptive ?? [];
+    const points: RequestPoint[] = series.map((entry) => ({
+      date: entry.dimensions.date,
+      requests: entry.sum.requests,
+      errors: entry.sum.errors,
+      // Cloudflare reports CPU time in microseconds.
+      medianCpuMs: Math.round((entry.quantiles.cpuTimeP50 / 1000) * 100) / 100,
+    }));
+    const requests = points.reduce((total, point) => total + point.requests, 0);
+    const errors = points.reduce((total, point) => total + point.errors, 0);
+    const medians = points.map((point) => point.medianCpuMs).sort((a, b) => a - b);
+    return {
+      ok: true,
+      data: {
+        points,
+        requests,
+        errors,
+        errorRate: requests > 0 ? (errors / requests) * 100 : 0,
+        medianCpuMs: medians.length ? medians[Math.floor(medians.length / 2)]! : 0,
+      },
+    };
+  } catch (error) {
+    return { ok: false, reason: "failed", message: error instanceof Error ? error.message : "Couldn't reach Cloudflare." };
+  }
+}

package/templates/app/lib/api.ts

@@ -1,8 +1,20 @@
+import { headers } from "next/headers";
 import { can, type Policy } from "@flaredev/core";
 import type { Authorize } from "@flaredev/core/server";
 import { policies } from "@/policies";
 import { auth } from "./auth";
 
+/**
+ * Who is making this request, for a resource's hooks (`hooks.beforeCreate` and friends
+ * in the descriptor). Reads the session the same way everything else does.
+ */
+export async function currentUser() {
+  const session = await auth.api.getSession({ headers: await headers() });
+  if (!session) return null;
+  const { id, email } = session.user;
+  return { id, email, role: (session.user as { role?: string | null }).role ?? null };
+}
+
 /**
  * Authorization for every generated resource API (`app/api/<resource>/...`).
  * Return a Response to deny the request; return nothing to allow it.

package/templates/app/lib/audit.ts

@@ -0,0 +1,80 @@
+import { headers } from "next/headers";
+import { desc, eq, gte, sql } from "drizzle-orm";
+import { getDb } from "@/db";
+import { auditLog } from "@/db/flare-schema";
+import { dashboardSession } from "./dashboard";
+
+export type AuditAction = "create" | "update" | "delete" | "import" | "bulk-delete";
+
+export interface AuditEntry {
+  action: AuditAction;
+  resource: string;
+  recordId?: string | null;
+  recordLabel?: string | null;
+  changes?: Record<string, unknown> | null;
+}
+
+/**
+ * Record a change in the audit log.
+ *
+ * Never throws: an audit trail that can take the write down with it is worse than one
+ * with a gap, and the caller has already changed the database by the time we're here.
+ */
+export async function recordAudit(entry: AuditEntry): Promise<void> {
+  try {
+    const { session } = await dashboardSession();
+    const headerList = await headers();
+    await getDb()
+      .insert(auditLog)
+      .values({
+        action: entry.action,
+        resource: entry.resource,
+        recordId: entry.recordId ?? null,
+        recordLabel: entry.recordLabel ?? null,
+        userId: session?.user.id ?? null,
+        userEmail: session?.user.email ?? null,
+        changes: entry.changes ?? null,
+        ip: headerList.get("cf-connecting-ip") ?? null,
+      });
+  } catch {
+    // Deliberately quiet.
+  }
+}
+
+/** Which fields moved, and from what to what. Only the differences, never the whole record. */
+export function diffFields(before: Record<string, unknown> | null | undefined, after: Record<string, unknown>): Record<string, { from: unknown; to: unknown }> {
+  const changes: Record<string, { from: unknown; to: unknown }> = {};
+  for (const [key, value] of Object.entries(after)) {
+    if (key === "updatedAt" || key === "createdAt") continue;
+    const previous = before?.[key];
+    const same = JSON.stringify(previous ?? null) === JSON.stringify(value ?? null);
+    if (!same) changes[key] = { from: previous ?? null, to: value ?? null };
+  }
+  return changes;
+}
+
+export interface AuditRow {
+  id: string;
+  action: string;
+  resource: string;
+  recordId: string | null;
+  recordLabel: string | null;
+  userEmail: string | null;
+  changes: Record<string, unknown> | null;
+  createdAt: Date;
+}
+
+/** The most recent entries, newest first. */
+export async function recentAudit(limit = 25, resource?: string): Promise<AuditRow[]> {
+  const db = getDb();
+  const query = db.select().from(auditLog).orderBy(desc(auditLog.createdAt)).limit(limit);
+  const rows = resource ? await query.where(eq(auditLog.resource, resource)) : await query;
+  return rows as AuditRow[];
+}
+
+/** How many changes were recorded in the last `days` days, for the observability summary. */
+export async function auditCount(days = 7): Promise<number> {
+  const since = new Date(Date.now() - days * 86_400_000);
+  const [row] = await getDb().select({ total: sql<number>`count(*)` }).from(auditLog).where(gte(auditLog.createdAt, since));
+  return row?.total ?? 0;
+}