@flaredev/cli 0.2.0 → 0.3.0

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/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;
+}

package/templates/app/lib/auth-config.ts

@@ -1,33 +1,38 @@
-/**
- * How people sign in to this app. `flare create` wrote the choices you made; change
- * them here any time. Every method's tables already exist, so switching one on or off
- * needs no migration, and a method that's off is refused by the API, not just hidden.
- *
- * Email and password sign-in is always available.
- */
-export const authConfig = {
-  /** A sign-in link by email. */
-  magicLink: true,
-  /** A 6-digit sign-in code by email. */
-  emailOtp: true,
-  /** Face ID, Touch ID, Windows Hello or a security key. */
-  passkeys: true,
-  twoFactor: {
-    /** Codes from an authenticator app (TOTP), with backup codes. */
-    authenticator: true,
-    /** Codes by email as the second step. */
-    email: true,
-  },
-  /**
-   * Social sign-in. Each provider also needs its credentials (see .dev.vars.example);
-   * without them its button stays hidden.
-   */
-  social: [] as SocialProvider[],
-  /** Refuse password sign-in until the email address is verified. */
-  requireEmailVerification: false,
-};
-
-export type SocialProvider = "google" | "github" | "apple" | "microsoft";
-
-/** Whether any second factor can be set up. */
-export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;
+/**
+ * How people sign in to this app. `flare create` wrote the choices you made; change
+ * them here any time. Every method's tables already exist, so switching one on or off
+ * needs no migration, and a method that's off is refused by the API, not just hidden.
+ *
+ * Email and password sign-in is always available.
+ */
+export const authConfig = {
+  /** A sign-in link by email. */
+  magicLink: true,
+  /** A 6-digit sign-in code by email. */
+  emailOtp: true,
+  /** Face ID, Touch ID, Windows Hello or a security key. */
+  passkeys: true,
+  twoFactor: {
+    /** Codes from an authenticator app (TOTP), with backup codes. */
+    authenticator: true,
+    /** Codes by email as the second step. */
+    email: true,
+  },
+  /**
+   * Social sign-in. Each provider also needs its credentials (see .dev.vars.example);
+   * without them its button stays hidden.
+   */
+  social: [] as SocialProvider[],
+  /** Refuse password sign-in until the email address is verified. */
+  requireEmailVerification: false,
+  /**
+   * Check new passwords against Have I Been Pwned's breach list. Only the first five
+   * characters of the password's hash are sent, and an outage lets the password through.
+   */
+  checkBreachedPasswords: true,
+};
+
+export type SocialProvider = "google" | "github" | "apple" | "microsoft";
+
+/** Whether any second factor can be set up. */
+export const twoFactorAvailable = authConfig.twoFactor.authenticator || authConfig.twoFactor.email;

package/templates/app/lib/auth.ts

@@ -11,6 +11,7 @@ import { twoFactor } from "better-auth/plugins/two-factor";
 import { hashPassword, verifyPassword } from "@flaredev/core";
 import { getDb, schema } from "@/db";
 import { authConfig, type SocialProvider } from "./auth-config";
+import { checkPassword, isBreachedPassword, PASSWORD_MAX_LENGTH } from "./password-rules";
 import { sendEmailCode, sendMagicLink, sendPasswordReset, sendTwoFactorCode, sendVerificationEmail } from "./auth-emails";
 
 const vars = env as unknown as Record<string, string | undefined>;
@@ -51,6 +52,38 @@ function disabledPath(path: string): boolean {
   return false;
 }
 
+/** Where a new password arrives, and what it's called in the body. */
+const NEW_PASSWORD_FIELDS: Record<string, string> = {
+  "/sign-up/email": "password",
+  "/reset-password": "newPassword",
+  "/change-password": "newPassword",
+};
+
+/**
+ * The same password rules the sign-up and reset forms show as you type
+ * (lib/password-rules.ts), enforced here so the API agrees with the screens.
+ * Checked on the way in, before the password is hashed or stored.
+ */
+async function guardPassword(path: string, body: Record<string, unknown> | undefined) {
+  const field = NEW_PASSWORD_FIELDS[path];
+  if (!field) return;
+  const password = body?.[field];
+  if (typeof password !== "string") return;
+
+  if (password.length > PASSWORD_MAX_LENGTH) {
+    throw new APIError("BAD_REQUEST", { message: `Passwords can be at most ${PASSWORD_MAX_LENGTH} characters.` });
+  }
+  const check = checkPassword(password, [body?.email as string | undefined, body?.name as string | undefined]);
+  if (!check.valid) throw new APIError("BAD_REQUEST", { message: check.advice ?? "That password is too short." });
+
+  // A password in a public breach list is already guessed, however strong it looks.
+  if (authConfig.checkBreachedPasswords && (await isBreachedPassword(password))) {
+    throw new APIError("BAD_REQUEST", {
+      message: "That password has appeared in a data breach, so it isn't safe to use here. Pick a different one.",
+    });
+  }
+}
+
 export const auth = betterAuth({
   appName: "__APP_NAME__",
   secret: env.BETTER_AUTH_SECRET,
@@ -90,6 +123,7 @@ export const auth = betterAuth({
   hooks: {
     before: createAuthMiddleware(async (ctx) => {
       if (disabledPath(ctx.path)) throw new APIError("NOT_FOUND", { message: "This sign-in method isn't enabled." });
+      await guardPassword(ctx.path, ctx.body as Record<string, unknown> | undefined);
     }),
   },
   plugins: [

package/templates/app/lib/cache.ts

@@ -1,83 +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 });
-}
+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/dashboard.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/csv.ts

@@ -0,0 +1,24 @@
+/**
+ * CSV, the way spreadsheets expect it (RFC 4180): fields holding a comma, a quote or a
+ * line break are quoted, and quotes inside them are doubled.
+ *
+ * Shared by the table's "export selected" (in the browser) and the export action (on
+ * the server), so both produce the same file.
+ */
+
+export interface CsvColumn {
+  key: string;
+  label: string;
+}
+
+export function csvCell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const text = Array.isArray(value) ? value.join("; ") : value instanceof Date ? value.toISOString() : String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export function toCsv(rows: Record<string, unknown>[], columns: CsvColumn[]): string {
+  const header = columns.map((column) => csvCell(column.label)).join(",");
+  const body = rows.map((row) => columns.map((column) => csvCell(row[column.key])).join(","));
+  return [header, ...body].join("\r\n");
+}

package/templates/app/lib/dashboard-nav.ts

@@ -0,0 +1,15 @@
+// Extra dashboard sidebar links (maintained by flare generators such as `flare gen security`).
+// Add your own links outside the generated block.
+// generated:start
+export interface DashboardLink {
+  label: string;
+  href: string;
+  /** A resource icon name, e.g. "shield" (see components/dashboard/resource-icon.tsx). */
+  icon: string;
+}
+
+export const generatedDashboardLinks: DashboardLink[] = [];
+// generated:end
+
+/** Links shown under "Platform" in the dashboard sidebar. */
+export const dashboardLinks: DashboardLink[] = [...generatedDashboardLinks, { label: "API reference", href: "/api/reference", icon: "book" }];