@deepraxis/app-template 0.0.0-stage → 0.1.0-dev.2990b29

package/template/app/api/auth/register/route.ts

@@ -0,0 +1,24 @@
+import { env } from "cloudflare:workers";
+import { credentialsSchema, hashPassword, MissingSecretError, requireSecret } from "@/lib/auth";
+import { getDb } from "@/lib/db";
+import { redirectResponse } from "@/lib/guard";
+import { createSession, sessionCookie } from "@/lib/session";
+import { createUser } from "@/lib/users";
+
+// Rate limiting for sign-up (per IP) would go here, before any hashing or database work.
+export async function POST(req: Request) {
+  try {
+    requireSecret(env.SESSION_SECRET); // fail before creating a user that could never sign in
+    const form = await req.formData();
+    const parsed = credentialsSchema.safeParse({ username: form.get("username"), password: form.get("password") });
+    if (!parsed.success) return redirectResponse(`/register?error=${encodeURIComponent(parsed.error.issues[0]!.message)}`);
+    const db = await getDb();
+    const created = await createUser(db, { username: parsed.data.username, passwordHash: await hashPassword(parsed.data.password) });
+    if (!created.ok) return redirectResponse(`/register?error=${encodeURIComponent("That username is taken")}`);
+    const session = await createSession(db, created.user.id, env.SESSION_SECRET);
+    return redirectResponse("/account", sessionCookie(session.value, session.expiresAt));
+  } catch (e) {
+    if (e instanceof MissingSecretError) return new Response(e.message, { status: 500 });
+    throw e;
+  }
+}

package/template/app/api/health/route.ts

@@ -0,0 +1,10 @@
+import { sql } from "drizzle-orm";
+import { getDb } from "@/lib/db";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const db = await getDb();
+  await db.run(sql`SELECT 1`);
+  return Response.json({ ok: true });
+}

package/template/app/api/images/route.ts

@@ -0,0 +1,15 @@
+import { env } from "cloudflare:workers";
+import { getDb } from "@/lib/db";
+import { getCurrentUser, redirectResponse } from "@/lib/guard";
+import { checkImage, saveImage } from "@/lib/storage";
+
+export async function POST(req: Request) {
+  const user = await getCurrentUser(req.headers.get("cookie"));
+  if (!user) return redirectResponse("/login?next=%2Faccount");
+  const file = (await req.formData()).get("image");
+  if (!(file instanceof File)) return redirectResponse(`/account?error=${encodeURIComponent("Choose an image to upload")}`);
+  const problem = checkImage(file);
+  if (problem) return redirectResponse(`/account?error=${encodeURIComponent(problem)}`);
+  await saveImage(await getDb(), env.IMAGES, user.id, file);
+  return redirectResponse("/account");
+}

package/template/app/globals.css

@@ -0,0 +1,45 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* The look of the app lives here. Values are HSL triplets (hue saturation lightness) used as hsl(var(--x)).
+   Every *-foreground must keep at least 4.5:1 contrast on its background; the design test checks it. */
+@layer base {
+  :root {
+    --background: 0 0% 99%;
+    --foreground: 222 25% 12%;
+    --card: 0 0% 100%;
+    --card-foreground: 222 25% 12%;
+    --muted: 220 14% 96%;
+    --muted-foreground: 220 9% 38%;
+    --border: 220 13% 88%;
+    --input: 220 13% 78%;
+    --ring: 222 47% 11%;
+    --primary: 222 47% 11%;
+    --primary-foreground: 0 0% 98%;
+    --accent: 220 14% 93%;
+    --accent-foreground: 222 47% 11%;
+    --destructive: 0 70% 38%;
+    --destructive-foreground: 0 0% 100%;
+    --success: 142 70% 22%;
+    --success-foreground: 0 0% 100%;
+    --warning: 40 95% 55%;
+    --warning-foreground: 30 80% 10%;
+    --radius: 0.5rem;
+  }
+
+  body {
+    @apply bg-background text-foreground antialiased;
+    font-size: 16px;
+    line-height: 1.7;
+  }
+
+  h1, h2, h3, h4, h5, h6 {
+    @apply font-bold;
+  }
+
+  :focus-visible {
+    outline: 2px solid hsl(var(--ring));
+    outline-offset: 2px;
+  }
+}

package/template/app/images/[...key]/route.ts

@@ -0,0 +1,20 @@
+import { env } from "cloudflare:workers";
+import { getDb } from "@/lib/db";
+import { getCurrentUser } from "@/lib/guard";
+import { findImage } from "@/lib/storage";
+
+export const dynamic = "force-dynamic";
+
+// Images are private: only the owner and admins can read them.
+export async function GET(req: Request, { params }: { params: Promise<{ key: string[] }> }) {
+  const user = await getCurrentUser(req.headers.get("cookie"));
+  if (!user) return new Response("Sign in first", { status: 401 });
+  const key = (await params).key.join("/");
+  const image = await findImage(await getDb(), key);
+  if (!image || (image.ownerId !== user.id && user.role !== "admin")) return new Response("Not found", { status: 404 });
+  const object = await env.IMAGES.get(key);
+  if (!object) return new Response("Not found", { status: 404 });
+  return new Response(object.body, {
+    headers: { "Content-Type": image.contentType, "Content-Length": String(image.size), "Cache-Control": "private, max-age=3600", "X-Content-Type-Options": "nosniff" },
+  });
+}

package/template/app/layout.tsx

@@ -0,0 +1,35 @@
+import "./globals.css";
+import Link from "next/link";
+import { getCurrentUser } from "@/lib/guard";
+
+export const metadata = { title: "Praxis App", description: "A Praxis application" };
+export const dynamic = "force-dynamic";
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const user = await getCurrentUser();
+  return (
+    <html lang="en">
+      <body className="min-h-screen">
+        <header className="border-b border-border bg-card">
+          <nav className="mx-auto flex max-w-4xl flex-wrap items-center gap-x-4 gap-y-1 px-4 py-2 text-sm">
+            <Link href="/" className="inline-flex min-h-11 items-center font-semibold">Praxis App</Link>
+            <span className="hidden flex-1 sm:block" />
+            {user ? (
+              <>
+                <Link href="/account" className="inline-flex min-h-11 items-center">Account</Link>
+                {user.role === "admin" && <Link href="/admin" className="inline-flex min-h-11 items-center">Admin</Link>}
+                <form action="/logout" method="post"><button className="inline-flex min-h-11 items-center text-muted-foreground underline-offset-4 hover:underline">Sign out ({user.username})</button></form>
+              </>
+            ) : (
+              <>
+                <Link href="/login" className="inline-flex min-h-11 items-center">Sign in</Link>
+                <Link href="/register" className="inline-flex min-h-11 items-center">Sign up</Link>
+              </>
+            )}
+          </nav>
+        </header>
+        <main className="mx-auto max-w-4xl px-4 py-8">{children}</main>
+      </body>
+    </html>
+  );
+}

package/template/app/login/page.tsx

@@ -0,0 +1,26 @@
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export const dynamic = "force-dynamic";
+
+export default async function Login({ searchParams }: { searchParams: Promise<{ error?: string; next?: string }> }) {
+  const { error, next } = await searchParams;
+  return (
+    <Card className="mx-auto max-w-sm">
+      <CardHeader><CardTitle>Sign in</CardTitle></CardHeader>
+      <CardContent>
+        <form action="/api/auth/login" method="post" className="space-y-4">
+          <input type="hidden" name="next" value={next ?? ""} />
+          <div className="space-y-1.5"><Label htmlFor="username">Username</Label><Input id="username" name="username" autoComplete="username" required /></div>
+          <div className="space-y-1.5"><Label htmlFor="password">Password</Label><Input id="password" name="password" type="password" autoComplete="current-password" required /></div>
+          {error && <p role="alert" className="text-sm text-destructive">{error}</p>}
+          <Button type="submit" className="w-full">Sign in</Button>
+        </form>
+        <p className="mt-4 text-sm"><Link className="underline" href="/register">Create an account</Link></p>
+      </CardContent>
+    </Card>
+  );
+}

package/template/app/logout/route.ts

@@ -0,0 +1,9 @@
+import { env } from "cloudflare:workers";
+import { getDb } from "@/lib/db";
+import { redirectResponse } from "@/lib/guard";
+import { clearedSessionCookie, destroySession } from "@/lib/session";
+
+export async function POST(req: Request) {
+  await destroySession(await getDb(), req.headers.get("cookie"), env.SESSION_SECRET);
+  return redirectResponse("/", clearedSessionCookie);
+}

package/template/app/page.tsx

@@ -0,0 +1,21 @@
+import Link from "next/link";
+import { getCurrentUser } from "@/lib/guard";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+
+export const dynamic = "force-dynamic";
+
+export default async function Home() {
+  const user = await getCurrentUser();
+  return (
+    <Card>
+      <CardHeader><CardTitle>Welcome</CardTitle></CardHeader>
+      <CardContent className="space-y-3 text-sm">
+        {user ? (
+          <p>Signed in as <strong>{user.username}</strong> ({user.role}). <Link className="underline" href="/account">Go to your account</Link>.</p>
+        ) : (
+          <p>You are not signed in. <Link className="underline" href="/login">Sign in</Link> or <Link className="underline" href="/register">create an account</Link>.</p>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

package/template/app/register/page.tsx

@@ -0,0 +1,25 @@
+import Link from "next/link";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+export const dynamic = "force-dynamic";
+
+export default async function Register({ searchParams }: { searchParams: Promise<{ error?: string }> }) {
+  const { error } = await searchParams;
+  return (
+    <Card className="mx-auto max-w-sm">
+      <CardHeader><CardTitle>Create account</CardTitle></CardHeader>
+      <CardContent>
+        <form action="/api/auth/register" method="post" className="space-y-4">
+          <div className="space-y-1.5"><Label htmlFor="username">Username</Label><Input id="username" name="username" autoComplete="username" required /></div>
+          <div className="space-y-1.5"><Label htmlFor="password">Password</Label><Input id="password" name="password" type="password" autoComplete="new-password" required /></div>
+          {error && <p role="alert" className="text-sm text-destructive">{error}</p>}
+          <Button type="submit" className="w-full">Create account</Button>
+        </form>
+        <p className="mt-4 text-sm"><Link className="underline" href="/login">Already have an account?</Link></p>
+      </CardContent>
+    </Card>
+  );
+}

package/template/components/ui/badge.tsx

@@ -0,0 +1,26 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const badgeVariants = cva(
+  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent bg-primary text-primary-foreground",
+        secondary: "border-transparent bg-accent text-accent-foreground",
+        success: "border-transparent bg-success text-success-foreground",
+        warning: "border-transparent bg-warning text-warning-foreground",
+        destructive: "border-transparent bg-destructive text-destructive-foreground",
+        outline: "border-border text-foreground",
+      },
+    },
+    defaultVariants: { variant: "default" },
+  },
+);
+
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {}
+
+export function Badge({ className, variant, ...props }: BadgeProps) {
+  return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
+}

package/template/components/ui/button.tsx

@@ -0,0 +1,24 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        outline: "border border-input bg-card text-card-foreground hover:bg-accent",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+      },
+      size: { default: "h-11 px-5 py-2", sm: "h-11 px-4" },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  },
+);
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />;
+}

package/template/components/ui/card.tsx

@@ -0,0 +1,17 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+type DivProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function Card({ className, ...props }: DivProps) {
+  return <div className={cn("rounded-lg border border-border bg-card text-card-foreground shadow-sm", className)} {...props} />;
+}
+export function CardHeader({ className, ...props }: DivProps) {
+  return <div className={cn("flex flex-col gap-1.5 p-6", className)} {...props} />;
+}
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h2 className={cn("text-lg font-semibold leading-none", className)} {...props} />;
+}
+export function CardContent({ className, ...props }: DivProps) {
+  return <div className={cn("p-6 pt-0", className)} {...props} />;
+}

package/template/components/ui/input.tsx

@@ -0,0 +1,14 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export function Input({ className, ...props }: React.InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <input
+      className={cn(
+        "flex h-11 w-full rounded-md border border-input bg-card px-3 py-2 text-base shadow-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/template/components/ui/label.tsx

@@ -0,0 +1,6 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export function Label({ className, ...props }: React.LabelHTMLAttributes<HTMLLabelElement>) {
+  return <label className={cn("text-sm font-medium leading-none", className)} {...props} />;
+}

package/template/env.d.ts

@@ -0,0 +1,11 @@
+// Types of the bindings declared in wrangler.jsonc and the secrets declared in praxis.jsonc.
+// Read them with `import { env } from "cloudflare:workers"`; add a line here for every new one.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    IMAGES: R2Bucket;
+    ASSETS: Fetcher;
+    /** Signs session cookies; created by `praxis app deploy` ("generate" in praxis.jsonc). */
+    SESSION_SECRET?: string;
+  }
+}

package/template/lib/auth.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { credentialsSchema, hashPassword, MissingSecretError, newSessionToken, sha256Hex, signToken, verifyPassword, verifySignedToken } from "./auth";
+
+describe("passwords", () => {
+  test("hash has the documented format and verifies", async () => {
+    const stored = await hashPassword("correct horse");
+    expect(stored).toMatch(/^pbkdf2\$100000\$[A-Za-z0-9+/=]+\$[A-Za-z0-9+/=]+$/);
+    expect(await verifyPassword("correct horse", stored)).toBe(true);
+  });
+  test("wrong password is rejected", async () => {
+    expect(await verifyPassword("wrong horse", await hashPassword("correct horse"))).toBe(false);
+  });
+  test("same password hashes differently (random salt)", async () => {
+    expect(await hashPassword("same-password")).not.toBe(await hashPassword("same-password"));
+  });
+  test("malformed or over-limit stored values never verify", async () => {
+    expect(await verifyPassword("x", "garbage")).toBe(false);
+    expect(await verifyPassword("x", "pbkdf2$99999999$AAAA$AAAA")).toBe(false);
+  });
+});
+
+describe("signed session token", () => {
+  const secret = "test-secret";
+  test("round-trips", async () => {
+    const token = newSessionToken();
+    expect(await verifySignedToken(await signToken(token, secret), secret)).toBe(token);
+  });
+  test("tampered signature or token is rejected", async () => {
+    const token = newSessionToken();
+    const value = await signToken(token, secret);
+    const flipped = value.slice(0, -2) + (value.endsWith("AA") ? "BB" : "AA");
+    expect(await verifySignedToken(flipped, secret)).toBeNull();
+    expect(await verifySignedToken(`${newSessionToken()}.${value.split(".")[1]}`, secret)).toBeNull();
+  });
+  test("a signature made with another secret is rejected", async () => {
+    expect(await verifySignedToken(await signToken("tok", "other-secret"), secret)).toBeNull();
+  });
+  test("garbage cookie values are rejected, not thrown", async () => {
+    for (const v of ["", "nodot", ".sig", "tok.", "tok.%%%"]) expect(await verifySignedToken(v, secret)).toBeNull();
+  });
+  test("missing secret throws a clear error naming SESSION_SECRET and never signs", async () => {
+    await expect(signToken("tok", undefined)).rejects.toThrow(MissingSecretError);
+    await expect(signToken("tok", "")).rejects.toThrow(/SESSION_SECRET/);
+    await expect(verifySignedToken("tok.sig", undefined)).rejects.toThrow(MissingSecretError);
+  });
+  test("session id is the sha256 of the token", async () => {
+    expect(await sha256Hex("abc")).toBe("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad");
+  });
+});
+
+describe("validation", () => {
+  test("username and password bounds", () => {
+    const ok = (username: string, password: string) => credentialsSchema.safeParse({ username, password }).success;
+    expect(ok("alice_1", "12345678")).toBe(true);
+    expect(ok("ab", "12345678")).toBe(false);
+    expect(ok("Alice", "12345678")).toBe(false);
+    expect(ok("a".repeat(33), "12345678")).toBe(false);
+    expect(ok("alice", "1234567")).toBe(false);
+    expect(ok("alice", "x".repeat(129))).toBe(false);
+  });
+});

package/template/lib/auth.ts

@@ -0,0 +1,107 @@
+// Credentials and cookie signing, WebCrypto only. No framework or Cloudflare imports, so it runs under `bun test`.
+//
+// Password hash format: pbkdf2$<iterations>$<salt_b64>$<hash_b64> (PBKDF2-SHA256, 16-byte salt).
+// 100000 iterations is the maximum the Workers runtime accepts.
+// Cookie value: <token>.<signature>, signature = HMAC-SHA256(token) keyed by the SESSION_SECRET binding.
+// Rate limiting (per IP and per username on sign-in and sign-up) belongs in the two route handlers under app/api/auth/.
+import { z } from "zod";
+
+export const PBKDF2_ITERATIONS = 100000;
+
+export const usernameSchema = z.string().regex(/^[a-z0-9_]{3,32}$/, "Username: 3-32 characters of a-z, 0-9 and _");
+export const passwordSchema = z.string().min(8, "Password: at least 8 characters").max(128, "Password: at most 128 characters");
+export const credentialsSchema = z.object({ username: usernameSchema, password: passwordSchema });
+
+export class MissingSecretError extends Error {
+  readonly status = 500;
+  constructor() {
+    super("SESSION_SECRET is not configured: pass it as a secret_text binding when deploying. Refusing to sign sessions without it.");
+    this.name = "MissingSecretError";
+  }
+}
+
+export function requireSecret(secret: string | undefined): string {
+  if (!secret) throw new MissingSecretError();
+  return secret;
+}
+
+type Bytes = Uint8Array<ArrayBuffer>;
+const enc = new TextEncoder();
+
+function toB64(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+function fromB64(b64: string): Bytes {
+  const s = atob(b64);
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+const toB64Url = (bytes: Uint8Array) => toB64(bytes).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+const fromB64Url = (s: string) => fromB64(s.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - (s.length % 4)) % 4));
+
+/** Constant-time comparison of two byte arrays (length difference is not secret). */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ b[i]!;
+  return diff === 0;
+}
+
+async function pbkdf2(password: string, salt: Bytes, iterations: number): Promise<Uint8Array> {
+  const key = await crypto.subtle.importKey("raw", enc.encode(password), "PBKDF2", false, ["deriveBits"]);
+  const bits = await crypto.subtle.deriveBits({ name: "PBKDF2", hash: "SHA-256", salt, iterations }, key, 256);
+  return new Uint8Array(bits);
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const hash = await pbkdf2(password, salt, PBKDF2_ITERATIONS);
+  return `pbkdf2$${PBKDF2_ITERATIONS}$${toB64(salt)}$${toB64(hash)}`;
+}
+
+export async function verifyPassword(password: string, stored: string): Promise<boolean> {
+  const [scheme, iterations, salt, hash] = stored.split("$");
+  const n = Number(iterations);
+  if (scheme !== "pbkdf2" || !Number.isInteger(n) || n < 1 || n > PBKDF2_ITERATIONS || !salt || !hash) return false;
+  const actual = await pbkdf2(password, fromB64(salt), n);
+  return timingSafeEqual(actual, fromB64(hash));
+}
+
+/** A fresh random session token (32 bytes, base64url). Only its sha256 is stored. */
+export function newSessionToken(): string {
+  return toB64Url(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+export async function sha256Hex(value: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", enc.encode(value)));
+  return [...digest].map(b => b.toString(16).padStart(2, "0")).join("");
+}
+
+const hmacKey = (secret: string, usage: "sign" | "verify") =>
+  crypto.subtle.importKey("raw", enc.encode(requireSecret(secret)), { name: "HMAC", hash: "SHA-256" }, false, [usage]);
+
+/** `token.signature` — the cookie value. Throws MissingSecretError when the secret is empty. */
+export async function signToken(token: string, secret: string | undefined): Promise<string> {
+  const key = await hmacKey(requireSecret(secret), "sign");
+  const sig = new Uint8Array(await crypto.subtle.sign("HMAC", key, enc.encode(token)));
+  return `${token}.${toB64Url(sig)}`;
+}
+
+/** The token when the signature is valid, otherwise null. Verification is constant-time (subtle.verify). */
+export async function verifySignedToken(value: string | null | undefined, secret: string | undefined): Promise<string | null> {
+  if (!value) return null;
+  const dot = value.lastIndexOf(".");
+  if (dot <= 0) return null;
+  const token = value.slice(0, dot);
+  let sig: Bytes;
+  try {
+    sig = fromB64Url(value.slice(dot + 1));
+  } catch {
+    return null;
+  }
+  const key = await hmacKey(requireSecret(secret), "verify");
+  return (await crypto.subtle.verify("HMAC", key, sig, enc.encode(token))) ? token : null;
+}

package/template/lib/db.ts

@@ -0,0 +1,19 @@
+// Database access. `getDb()` applies pending migrations once per isolate, then returns a drizzle client.
+import { env } from "cloudflare:workers";
+import { drizzle } from "drizzle-orm/d1";
+import { runMigrations } from "./migrate";
+import { migrations } from "./migrations";
+import * as schema from "./schema";
+
+let ready: Promise<unknown> | undefined;
+
+export async function getDb() {
+  ready ??= runMigrations(env.DB, migrations).catch(e => {
+    ready = undefined; // retry on the next request instead of caching the failure
+    throw e;
+  });
+  await ready;
+  return drizzle(env.DB, { schema });
+}
+
+export type Db = Awaited<ReturnType<typeof getDb>>;

package/template/lib/design-tokens.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+
+const root = path.join(import.meta.dir, "..");
+
+/** WCAG 2.x contrast ratio between two HSL triplets written as "H S% L%". */
+export function hslToRgb(triplet: string): [number, number, number] {
+  const m = triplet.trim().match(/^(-?[\d.]+)\s+([\d.]+)%\s+([\d.]+)%$/);
+  if (!m) throw new Error(`not an HSL triplet: "${triplet}"`);
+  const h = ((Number(m[1]) % 360) + 360) % 360, s = Number(m[2]) / 100, l = Number(m[3]) / 100;
+  const k = (n: number) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return [f(0), f(8), f(4)];
+}
+export function contrast(fg: string, bg: string): number {
+  const lum = (t: string) => {
+    const [r, g, b] = hslToRgb(t).map(c => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)) as [number, number, number];
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  };
+  const [hi, lo] = [lum(fg), lum(bg)].sort((x, y) => y - x) as [number, number];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+function tokens(): Record<string, string> {
+  const css = fs.readFileSync(path.join(root, "app/globals.css"), "utf8");
+  const block = css.match(/:root\s*\{([^}]*)\}/)?.[1] ?? "";
+  return Object.fromEntries([...block.matchAll(/--([\w-]+):\s*([^;]+);/g)].map(m => [m[1]!, m[2]!.trim()]));
+}
+
+const REQUIRED = [
+  "background", "foreground", "card", "card-foreground", "muted", "muted-foreground", "border", "input", "ring",
+  "primary", "primary-foreground", "accent", "accent-foreground", "destructive", "destructive-foreground",
+  "success", "success-foreground", "warning", "warning-foreground", "radius",
+];
+// [foreground token, background token] pairs that carry text.
+const PAIRS: [string, string][] = [
+  ["foreground", "background"], ["card-foreground", "card"], ["muted-foreground", "background"], ["muted-foreground", "card"],
+  ["muted-foreground", "muted"], ["primary-foreground", "primary"], ["accent-foreground", "accent"],
+  ["destructive-foreground", "destructive"], ["success-foreground", "success"], ["warning-foreground", "warning"],
+  ["destructive", "background"], ["destructive", "card"],
+];
+
+describe("design tokens", () => {
+  const t = tokens();
+  test("every required token is defined", () => {
+    expect(REQUIRED.filter(k => !(k in t))).toEqual([]);
+  });
+  for (const [fg, bg] of PAIRS) {
+    test(`${fg} on ${bg} has at least 4.5:1 contrast`, () => {
+      const ratio = contrast(t[fg]!, t[bg]!);
+      expect(ratio, `${fg} (${t[fg]}) on ${bg} (${t[bg]}) is ${ratio.toFixed(2)}:1`).toBeGreaterThanOrEqual(4.5);
+    });
+  }
+  test("contrast function matches known values", () => {
+    expect(contrast("0 0% 0%", "0 0% 100%")).toBeCloseTo(21, 1);
+    expect(contrast("0 0% 100%", "0 0% 100%")).toBeCloseTo(1, 5);
+  });
+});
+
+const PALETTE = "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
+const RAW_COLOR = new RegExp(`\\b(?:bg|text|border|ring|from|to|via|fill|stroke|outline|divide|placeholder|decoration|shadow)-(?:${PALETTE})-\\d+\\b`, "g");
+const HEX_IN_CLASS = /className\s*=\s*(?:"[^"]*|'[^']*|\{[^}]*)#[0-9a-fA-F]{3,8}\b|\[(?:#[0-9a-fA-F]{3,8})\]/g;
+
+function sources(dir: string): string[] {
+  const out: string[] = [];
+  const abs = path.join(root, dir);
+  if (!fs.existsSync(abs)) return out;
+  for (const e of fs.readdirSync(abs, { recursive: true, withFileTypes: true })) {
+    if (e.isFile() && /\.(ts|tsx)$/.test(e.name)) out.push(path.relative(root, path.join(e.parentPath, e.name)));
+  }
+  return out;
+}
+
+export function findRawColors(file: string, text: string): string[] {
+  return [...(text.match(RAW_COLOR) ?? []), ...(text.match(HEX_IN_CLASS) ?? [])].map(c => `${file}: ${c}`);
+}
+
+describe("semantic classes only", () => {
+  test("detector flags palette classes and hex colors", () => {
+    expect(findRawColors("x.tsx", `<p className="bg-slate-900 hover:text-pink-500">`)).toHaveLength(2);
+    expect(findRawColors("x.tsx", `<p className="bg-[#ff0000]">`)).toHaveLength(1);
+    expect(findRawColors("x.tsx", `<p className="bg-primary text-muted-foreground">`)).toEqual([]);
+  });
+  test("app/ and components/ use no raw palette class or hex color", () => {
+    const hits = [...sources("app"), ...sources("components")].flatMap(f => findRawColors(f, fs.readFileSync(path.join(root, f), "utf8")));
+    expect(hits, `Use semantic classes (bg-primary, text-muted-foreground, text-destructive...) or edit the tokens in app/globals.css:\n${hits.join("\n")}`).toEqual([]);
+  });
+});

package/template/lib/format.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+import { formatBytes, formatDateTime } from "./format";
+
+test("dates show minutes in the app time zone, not raw ISO", () => {
+  expect(formatDateTime(Date.UTC(2026, 9, 25, 15, 3, 49))).toBe("2026-10-25 23:03");
+});
+
+test("sizes use readable units", () => {
+  expect(formatBytes(70)).toBe("70 B");
+  expect(formatBytes(12_595)).toBe("12.3 KB");
+  expect(formatBytes(4_718_592)).toBe("4.5 MB");
+});