create-ailk 0.1.0

package/templates/database/__tests__/user-cascade.test.ts

@@ -0,0 +1,125 @@
+/**
+ * @file user-cascade.test.ts
+ *
+ * Schema-shape verification for the User cascade contract (#587 spec §3
+ * "Database schema" + AC #9: "Deleting a User cascades to all five custom
+ * relations").
+ *
+ * Approach: read `database/schema.prisma` as text and assert that each of the
+ * five User-relation foreign keys declares `onDelete: Cascade`. We deliberately
+ * avoid live Postgres in this test:
+ *
+ *   - The repo's existing pattern (database/inbox/__tests__/schema.test.ts)
+ *     validates model presence at the generated-client level only.
+ *   - A real cascade integration test runs in the `apps/api Route Tests
+ *     (Postgres)` non-required workflow, which spins up Postgres + applies the
+ *     migration generated by `pnpm db:migrate`.
+ *   - The schema-text assertion catches the regression class that matters
+ *     most: accidental loss of the `onDelete: Cascade` directive during the
+ *     Better Auth migration. Once the schema declares cascade, Prisma + the
+ *     generated migration are responsible for enforcing it at runtime.
+ *
+ * If a future contributor proposes a real-DB cascade test, they should add it
+ * under `apps/api Route Tests (Postgres)` rather than here so the workspace's
+ * Jest run stays DB-free.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const SCHEMA_PATH = resolve(__dirname, "..", "schema.prisma");
+
+/**
+ * `relationField` is the field name on User that points at each related
+ * model. It's intentionally not always the lowercased model name — the schema
+ * uses `oauthAuthorizations` (lowercase `oauth-`) but the model itself is
+ * `OAuthAuthorization` (Pascal `OAuth-`). Listing it explicitly is more
+ * readable than a regex with multiple optional casings.
+ */
+const CUSTOM_RELATIONS: Array<{
+  model: string;
+  relationField: string;
+  description: string;
+}> = [
+  { model: "ApiToken", relationField: "apiTokens", description: "API tokens (Bearer auth)" },
+  { model: "RefreshToken", relationField: "refreshTokens", description: "Mobile session refresh tokens" },
+  {
+    model: "OAuthAuthorization",
+    relationField: "oauthAuthorizations",
+    description: "OAuth grants to ChatGPT/Slack/etc",
+  },
+  { model: "PushToken", relationField: "pushTokens", description: "Mobile / web push subscription tokens" },
+  { model: "UserData", relationField: "userData", description: "Customer key-value preferences" },
+];
+
+const BETTER_AUTH_RELATIONS: Array<{ model: string }> = [
+  { model: "Session" },
+  { model: "Account" },
+];
+
+describe("User cascade — schema-shape contract (#587)", () => {
+  const schema = readFileSync(SCHEMA_PATH, "utf-8");
+
+  it.each(CUSTOM_RELATIONS)(
+    "$model FK to User declares onDelete: Cascade ($description)",
+    ({ model }) => {
+      // Find the model block, then check the User @relation line within it
+      // carries onDelete: Cascade.
+      const modelRegex = new RegExp(`model ${model} \\{([\\s\\S]*?)^}`, "m");
+      const match = modelRegex.exec(schema);
+      expect(match).not.toBeNull();
+      const body = match![1];
+      // The relation line referencing User.id MUST contain onDelete: Cascade.
+      const relationLine = body
+        .split("\n")
+        .find(
+          (line) =>
+            /@relation\s*\(/.test(line) && /references:\s*\[id\]/.test(line),
+        );
+      expect(relationLine).toBeDefined();
+      expect(relationLine).toMatch(/onDelete:\s*Cascade/);
+    },
+  );
+
+  it.each(BETTER_AUTH_RELATIONS)(
+    "$model FK to User declares onDelete: Cascade (Better Auth surface)",
+    ({ model }) => {
+      const modelRegex = new RegExp(`model ${model} \\{([\\s\\S]*?)^}`, "m");
+      const match = modelRegex.exec(schema);
+      expect(match).not.toBeNull();
+      const body = match![1];
+      const relationLine = body
+        .split("\n")
+        .find(
+          (line) =>
+            /@relation\s*\(/.test(line) && /references:\s*\[id\]/.test(line),
+        );
+      expect(relationLine).toBeDefined();
+      expect(relationLine).toMatch(/onDelete:\s*Cascade/);
+    },
+  );
+
+  it("User model still declares every required custom relation back-reference", () => {
+    const userRegex = /model User \{([\s\S]*?)^}/m;
+    const match = userRegex.exec(schema);
+    expect(match).not.toBeNull();
+    const body = match![1];
+    for (const { model, relationField } of CUSTOM_RELATIONS) {
+      // The User model must reference each related model (plural array or
+      // optional singular). Catches accidental relation drops during schema
+      // refactors.
+      const typePattern = new RegExp(`\\b${model}(\\[\\]|\\?)?\\b`);
+      expect(body).toMatch(typePattern);
+      // And the matching back-reference field name must be present.
+      const fieldPattern = new RegExp(`\\b${relationField}\\b`);
+      expect(body).toMatch(fieldPattern);
+    }
+  });
+
+  it("Better Auth replaces three NextAuth tables (Authenticator was never present)", () => {
+    expect(schema).not.toMatch(/model VerificationToken/);
+    expect(schema).toMatch(/model Verification\b/);
+    expect(schema).toMatch(/model Session\b/);
+    expect(schema).toMatch(/model Account\b/);
+  });
+});

package/templates/database/inbox/README.md

@@ -0,0 +1,3 @@
+# inbox namespace
+
+The `inbox` namespace owns lead and relationship data: anonymous leads submitted via MCP tools or API routes, newsletter subscribers, and callback requests. All three models use `siteId` as a plain string identifier — there is no foreign-key relationship to auth-namespace models per [ADR 0009](../../docs/adr/0009-database-namespace-separation.md) D2. When a feature needs "leads with their owning user's name," that assembly happens in `apps/api/src/services/` (the D3 service-layer exemption), never via a Prisma `@relation` crossing the namespace boundary.

package/templates/database/inbox/__tests__/schema.test.ts

@@ -0,0 +1,40 @@
+/**
+ * Smoke tests for the inbox namespace schema (issue #214 — B1).
+ *
+ * Model presence is checked against the generator-emitted per-model files
+ * rather than via PrismaClient instantiation: the v7 `prisma-client`
+ * generator's client.ts uses `import.meta.url`, which the CommonJS Jest
+ * runtime can't load.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+const REPO_ROOT = resolve(__dirname, "..", "..", "..");
+const MODELS_DIR = resolve(__dirname, "..", "..", "generated", "client", "models");
+
+describe("inbox namespace — Prisma client model presence", () => {
+  it("emits Lead model file", () => {
+    expect(existsSync(resolve(MODELS_DIR, "Lead.ts"))).toBe(true);
+  });
+
+  it("emits Subscriber model file", () => {
+    expect(existsSync(resolve(MODELS_DIR, "Subscriber.ts"))).toBe(true);
+  });
+
+  it("emits Callback model file", () => {
+    expect(existsSync(resolve(MODELS_DIR, "Callback.ts"))).toBe(true);
+  });
+});
+
+describe("inbox namespace — architecture lint", () => {
+  it("namespace lint exits 0 (no cross-namespace violations)", () => {
+    const result = spawnSync(
+      "pnpm",
+      ["exec", "tsx", "tools/lint-architecture.ts"],
+      { cwd: REPO_ROOT, encoding: "utf-8" },
+    );
+    expect(result.status).toBe(0);
+  });
+});

package/templates/database/inbox/schema.prisma

@@ -0,0 +1,52 @@
+// inbox namespace — Lead, Subscriber, Callback
+//
+// Backs the Phase B anonymous-write MCP tools (submit_lead, subscribe_newsletter,
+// request_callback) and their corresponding POST routes (B6).
+//
+// Per ADR 0009 D2: no @relation directives cross namespace boundaries.
+// siteId is a plain String identifier — no FK to auth/users.
+//
+// Generator + datasource blocks live in database/schema.prisma (the root schema
+// file). This file holds only model definitions for the inbox namespace.
+
+/// Lead — anonymous lead submission (Phase B submit_lead tool / B6 route)
+model Lead {
+  id        String   @id @default(cuid())
+  siteId    String   @map("site_id")
+  source    String
+  email     String
+  payload   Json
+  createdAt DateTime @default(now()) @map("created_at")
+
+  @@index([siteId])
+  @@index([createdAt])
+  @@map("leads")
+}
+
+/// Subscriber — newsletter subscription (Phase B subscribe_newsletter tool / B6 route)
+model Subscriber {
+  id        String   @id @default(cuid())
+  siteId    String   @map("site_id")
+  email     String
+  source    String
+  createdAt DateTime @default(now()) @map("created_at")
+
+  @@unique([siteId, email])
+  @@index([siteId])
+  @@map("subscribers")
+}
+
+/// Callback — callback request (Phase B request_callback tool / B6 route)
+model Callback {
+  id            String   @id @default(cuid())
+  siteId        String   @map("site_id")
+  name          String
+  phone         String
+  preferredTime String?  @map("preferred_time")
+  payload       Json
+  createdAt     DateTime @default(now()) @map("created_at")
+
+  @@index([siteId])
+  @@index([createdAt])
+  @@map("callbacks")
+}

package/templates/database/jest.config.cjs

@@ -0,0 +1,29 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  roots: ["<rootDir>"],
+  testMatch: ["**/__tests__/**/*.test.ts"],
+  testPathIgnorePatterns: ["/node_modules/", "/generated/"],
+  moduleFileExtensions: ["ts", "js", "json"],
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        tsconfig: {
+          target: "ES2020",
+          module: "commonjs",
+          lib: ["ES2020"],
+          declaration: false,
+          strict: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          ignoreDeprecations: '6.0',
+          types: ["node", "jest"],
+        },
+      },
+    ],
+  },
+};

package/templates/database/migrations/20260508000000_add_inbox_namespace/migration.sql

@@ -0,0 +1,328 @@
+-- CreateSchema
+CREATE SCHEMA IF NOT EXISTS "public";
+
+-- CreateTable
+CREATE TABLE "users" (
+    "id" TEXT NOT NULL,
+    "email" TEXT NOT NULL,
+    "name" TEXT,
+    "image" TEXT,
+    "email_verified" TIMESTAMP(3),
+    "role" TEXT NOT NULL DEFAULT 'user',
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "users_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "accounts" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "provider_account_id" TEXT NOT NULL,
+    "refresh_token" TEXT,
+    "access_token" TEXT,
+    "expires_at" INTEGER,
+    "token_type" TEXT,
+    "scope" TEXT,
+    "id_token" TEXT,
+    "session_state" TEXT,
+
+    CONSTRAINT "accounts_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "sessions" (
+    "id" TEXT NOT NULL,
+    "session_token" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "expires" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "sessions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "verification_tokens" (
+    "identifier" TEXT NOT NULL,
+    "token" TEXT NOT NULL,
+    "expires" TIMESTAMP(3) NOT NULL
+);
+
+-- CreateTable
+CREATE TABLE "api_tokens" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "token" TEXT NOT NULL,
+    "token_prefix" TEXT NOT NULL,
+    "client_type" TEXT NOT NULL DEFAULT 'api',
+    "device_info" TEXT,
+    "scopes" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "expires_at" TIMESTAMP(3),
+    "last_used_at" TIMESTAMP(3),
+    "last_used_ip" TEXT,
+    "revoked_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "api_tokens_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "refresh_tokens" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "api_token_id" TEXT NOT NULL,
+    "token" TEXT NOT NULL,
+    "expires_at" TIMESTAMP(3) NOT NULL,
+    "used_at" TIMESTAMP(3),
+    "revoked_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "refresh_tokens_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "oauth_clients" (
+    "id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "description" TEXT,
+    "logo_url" TEXT,
+    "client_id" TEXT NOT NULL,
+    "client_secret" TEXT NOT NULL,
+    "redirect_uris" TEXT[],
+    "scopes" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "enabled" BOOLEAN NOT NULL DEFAULT true,
+    "trusted" BOOLEAN NOT NULL DEFAULT false,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "oauth_clients_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "oauth_authorizations" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "scopes" TEXT[],
+    "access_token" TEXT NOT NULL,
+    "refresh_token" TEXT,
+    "expires_at" TIMESTAMP(3) NOT NULL,
+    "revoked_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "oauth_authorizations_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "push_tokens" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "token" TEXT NOT NULL,
+    "platform" TEXT NOT NULL,
+    "device_id" TEXT,
+    "device_name" TEXT,
+    "app_version" TEXT,
+    "enabled" BOOLEAN NOT NULL DEFAULT true,
+    "failed_at" TIMESTAMP(3),
+    "fail_count" INTEGER NOT NULL DEFAULT 0,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "push_tokens_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "user_data" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "value" JSONB NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "user_data_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "site_settings" (
+    "id" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "value" JSONB NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "site_settings_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "leads" (
+    "id" TEXT NOT NULL,
+    "site_id" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "email" TEXT NOT NULL,
+    "payload" JSONB NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "leads_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "subscribers" (
+    "id" TEXT NOT NULL,
+    "site_id" TEXT NOT NULL,
+    "email" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "subscribers_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "callbacks" (
+    "id" TEXT NOT NULL,
+    "site_id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "phone" TEXT NOT NULL,
+    "preferred_time" TEXT,
+    "payload" JSONB NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "callbacks_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "users_email_key" ON "users"("email");
+
+-- CreateIndex
+CREATE INDEX "accounts_user_id_idx" ON "accounts"("user_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "accounts_provider_provider_account_id_key" ON "accounts"("provider", "provider_account_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "sessions_session_token_key" ON "sessions"("session_token");
+
+-- CreateIndex
+CREATE INDEX "sessions_user_id_idx" ON "sessions"("user_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "verification_tokens_token_key" ON "verification_tokens"("token");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "verification_tokens_identifier_token_key" ON "verification_tokens"("identifier", "token");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "api_tokens_token_key" ON "api_tokens"("token");
+
+-- CreateIndex
+CREATE INDEX "api_tokens_user_id_idx" ON "api_tokens"("user_id");
+
+-- CreateIndex
+CREATE INDEX "api_tokens_token_idx" ON "api_tokens"("token");
+
+-- CreateIndex
+CREATE INDEX "api_tokens_token_prefix_idx" ON "api_tokens"("token_prefix");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "refresh_tokens_token_key" ON "refresh_tokens"("token");
+
+-- CreateIndex
+CREATE INDEX "refresh_tokens_user_id_idx" ON "refresh_tokens"("user_id");
+
+-- CreateIndex
+CREATE INDEX "refresh_tokens_api_token_id_idx" ON "refresh_tokens"("api_token_id");
+
+-- CreateIndex
+CREATE INDEX "refresh_tokens_token_idx" ON "refresh_tokens"("token");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "oauth_clients_client_id_key" ON "oauth_clients"("client_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "oauth_authorizations_access_token_key" ON "oauth_authorizations"("access_token");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "oauth_authorizations_refresh_token_key" ON "oauth_authorizations"("refresh_token");
+
+-- CreateIndex
+CREATE INDEX "oauth_authorizations_user_id_idx" ON "oauth_authorizations"("user_id");
+
+-- CreateIndex
+CREATE INDEX "oauth_authorizations_client_id_idx" ON "oauth_authorizations"("client_id");
+
+-- CreateIndex
+CREATE INDEX "oauth_authorizations_access_token_idx" ON "oauth_authorizations"("access_token");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "oauth_authorizations_user_id_client_id_key" ON "oauth_authorizations"("user_id", "client_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "push_tokens_token_key" ON "push_tokens"("token");
+
+-- CreateIndex
+CREATE INDEX "push_tokens_user_id_idx" ON "push_tokens"("user_id");
+
+-- CreateIndex
+CREATE INDEX "push_tokens_platform_idx" ON "push_tokens"("platform");
+
+-- CreateIndex
+CREATE INDEX "user_data_user_id_idx" ON "user_data"("user_id");
+
+-- CreateIndex
+CREATE INDEX "user_data_key_idx" ON "user_data"("key");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "user_data_user_id_key_key" ON "user_data"("user_id", "key");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "site_settings_key_key" ON "site_settings"("key");
+
+-- CreateIndex
+CREATE INDEX "leads_site_id_idx" ON "leads"("site_id");
+
+-- CreateIndex
+CREATE INDEX "leads_created_at_idx" ON "leads"("created_at");
+
+-- CreateIndex
+CREATE INDEX "subscribers_site_id_idx" ON "subscribers"("site_id");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "subscribers_site_id_email_key" ON "subscribers"("site_id", "email");
+
+-- CreateIndex
+CREATE INDEX "callbacks_site_id_idx" ON "callbacks"("site_id");
+
+-- CreateIndex
+CREATE INDEX "callbacks_created_at_idx" ON "callbacks"("created_at");
+
+-- AddForeignKey
+ALTER TABLE "accounts" ADD CONSTRAINT "accounts_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "sessions" ADD CONSTRAINT "sessions_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "api_tokens" ADD CONSTRAINT "api_tokens_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "refresh_tokens" ADD CONSTRAINT "refresh_tokens_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "refresh_tokens" ADD CONSTRAINT "refresh_tokens_api_token_id_fkey" FOREIGN KEY ("api_token_id") REFERENCES "api_tokens"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "oauth_authorizations" ADD CONSTRAINT "oauth_authorizations_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "oauth_authorizations" ADD CONSTRAINT "oauth_authorizations_client_id_fkey" FOREIGN KEY ("client_id") REFERENCES "oauth_clients"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "push_tokens" ADD CONSTRAINT "push_tokens_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "user_data" ADD CONSTRAINT "user_data_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+

package/templates/database/migrations/20260513000000_better_auth_migration/migration.sql

@@ -0,0 +1,100 @@
+-- Better Auth migration (#587)
+--
+-- Drops the three NextAuth tables (accounts, sessions, verification_tokens)
+-- and recreates accounts + sessions with the Better Auth column shape, plus a
+-- new `verifications` table for Better Auth's email/magic-link surface.
+--
+-- The User table changes `email_verified` from a nullable timestamp to a
+-- boolean. Pre-OSS posture: existing dev rows are sacrificed.
+--
+-- The five custom User relations (ApiToken, RefreshToken, OAuthAuthorization,
+-- PushToken, UserData) are unaffected — their FKs to users.id and ON DELETE
+-- CASCADE semantics remain identical.
+
+-- DropForeignKey
+ALTER TABLE "accounts" DROP CONSTRAINT "accounts_user_id_fkey";
+
+-- DropForeignKey
+ALTER TABLE "sessions" DROP CONSTRAINT "sessions_user_id_fkey";
+
+-- DropTable
+DROP TABLE "accounts";
+
+-- DropTable
+DROP TABLE "sessions";
+
+-- DropTable
+DROP TABLE "verification_tokens";
+
+-- AlterTable: switch users.email_verified from timestamp? to boolean
+ALTER TABLE "users" DROP COLUMN "email_verified";
+ALTER TABLE "users" ADD COLUMN "email_verified" BOOLEAN NOT NULL DEFAULT false;
+
+-- CreateTable: Better Auth sessions
+CREATE TABLE "sessions" (
+    "id" TEXT NOT NULL,
+    "expires_at" TIMESTAMP(3) NOT NULL,
+    "token" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+    "ip_address" TEXT,
+    "user_agent" TEXT,
+    "user_id" TEXT NOT NULL,
+
+    CONSTRAINT "sessions_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "sessions_token_key" ON "sessions"("token");
+
+-- CreateIndex
+CREATE INDEX "sessions_user_id_idx" ON "sessions"("user_id");
+
+-- CreateIndex
+CREATE INDEX "sessions_token_idx" ON "sessions"("token");
+
+-- AddForeignKey
+ALTER TABLE "sessions" ADD CONSTRAINT "sessions_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- CreateTable: Better Auth accounts
+CREATE TABLE "accounts" (
+    "id" TEXT 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" TIMESTAMP(3),
+    "refresh_token_expires_at" TIMESTAMP(3),
+    "scope" TEXT,
+    "password" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "accounts_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "accounts_provider_id_account_id_key" ON "accounts"("provider_id", "account_id");
+
+-- CreateIndex
+CREATE INDEX "accounts_user_id_idx" ON "accounts"("user_id");
+
+-- AddForeignKey
+ALTER TABLE "accounts" ADD CONSTRAINT "accounts_user_id_fkey" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- CreateTable: Better Auth verifications
+CREATE TABLE "verifications" (
+    "id" TEXT NOT NULL,
+    "identifier" TEXT NOT NULL,
+    "value" TEXT NOT NULL,
+    "expires_at" TIMESTAMP(3) NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "verifications_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "verifications_identifier_idx" ON "verifications"("identifier");