@usequark/quark-create-app 1.23.11

package/templates/base-project/packages/db/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@myquark/db",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "",
+	"main": "src/index.js",
+	"exports": {
+		".": "./src/index.js",
+		"./umami": "./src/umami.js"
+	},
+	"scripts": {
+		"test": "node --test 'src/**/*.test.js'",
+		"lint": "biome format --write && biome check --write",
+		"db:generate": "prisma generate",
+		"db:migrate": "prisma migrate dev",
+		"db:migrate:deploy": "prisma migrate deploy",
+		"db:push": "prisma db push",
+		"db:seed": "prisma db seed",
+		"db:studio": "prisma studio"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "MIT",
+	"packageManager": "pnpm@10.12.1",
+	"devDependencies": {
+		"@faker-js/faker": "^10.6.0",
+		"@techstream/quark-config": "workspace:*",
+		"bcryptjs": "^3.0.3",
+		"prisma": "^7.10.0"
+	},
+	"dependencies": {
+		"@prisma/adapter-pg": "^7.10.0",
+		"@prisma/client": "^7.10.0",
+		"@techstream/quark-core": "^2.0.0",
+		"pg": "^8.23.0",
+		"zod": "^4.6.5"
+	}
+}

package/templates/base-project/packages/db/prisma/migrations/20260202061128_initial/migration.sql

@@ -0,0 +1,202 @@
+-- CreateSchema
+CREATE SCHEMA IF NOT EXISTS "public";
+
+-- CreateEnum
+CREATE TYPE "UserRole" AS ENUM ('admin', 'lead_dev', 'client_admin', 'editor', 'viewer');
+
+-- CreateEnum
+CREATE TYPE "JobStatus" AS ENUM ('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED', 'CANCELLED');
+
+-- CreateTable
+CREATE TABLE "User" (
+    "id" TEXT NOT NULL,
+    "email" TEXT NOT NULL,
+    "emailVerified" TIMESTAMP(3),
+    "name" TEXT,
+    "password" TEXT,
+    "image" TEXT,
+    "role" "UserRole" NOT NULL DEFAULT 'viewer',
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "User_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Account" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "providerAccountId" TEXT NOT NULL,
+    "refresh_token" TEXT,
+    "access_token" TEXT,
+    "expires_at" INTEGER,
+    "token_type" TEXT,
+    "scope" TEXT,
+    "id_token" TEXT,
+    "session_state" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Account_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "Session" (
+    "id" TEXT NOT NULL,
+    "sessionToken" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "expires" TIMESTAMP(3) NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Session_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "VerificationToken" (
+    "identifier" TEXT NOT NULL,
+    "token" TEXT NOT NULL,
+    "expires" TIMESTAMP(3) NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL
+);
+
+-- CreateTable
+CREATE TABLE "Job" (
+    "id" TEXT NOT NULL,
+    "queue" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "data" JSONB,
+    "status" "JobStatus" NOT NULL DEFAULT 'PENDING',
+    "error" TEXT,
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "maxRetries" INTEGER NOT NULL DEFAULT 3,
+    "runAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "startedAt" TIMESTAMP(3),
+    "completedAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "Job_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "File" (
+    "id" TEXT NOT NULL,
+    "filename" TEXT NOT NULL,
+    "originalName" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "storageKey" TEXT NOT NULL,
+    "storageProvider" TEXT NOT NULL DEFAULT 'local',
+    "uploadedById" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "File_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "AuditLog" (
+    "id" TEXT NOT NULL,
+    "userId" TEXT NOT NULL,
+    "action" TEXT NOT NULL,
+    "entity" TEXT NOT NULL,
+    "entityId" TEXT NOT NULL,
+    "changes" JSONB,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "AuditLog_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "User_email_key" ON "User"("email");
+
+-- CreateIndex
+CREATE INDEX "User_email_idx" ON "User"("email");
+
+-- CreateIndex
+CREATE INDEX "User_createdAt_idx" ON "User"("createdAt");
+
+-- CreateIndex
+CREATE INDEX "Account_userId_idx" ON "Account"("userId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Account_provider_providerAccountId_key" ON "Account"("provider", "providerAccountId");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Session_sessionToken_key" ON "Session"("sessionToken");
+
+-- CreateIndex
+CREATE INDEX "Session_userId_idx" ON "Session"("userId");
+
+-- CreateIndex
+CREATE INDEX "Session_expires_idx" ON "Session"("expires");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "VerificationToken_token_key" ON "VerificationToken"("token");
+
+-- CreateIndex
+CREATE INDEX "VerificationToken_token_idx" ON "VerificationToken"("token");
+
+-- CreateIndex
+CREATE INDEX "VerificationToken_expires_idx" ON "VerificationToken"("expires");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "VerificationToken_identifier_token_key" ON "VerificationToken"("identifier", "token");
+
+-- CreateIndex
+CREATE INDEX "Job_queue_idx" ON "Job"("queue");
+
+-- CreateIndex
+CREATE INDEX "Job_status_idx" ON "Job"("status");
+
+-- CreateIndex
+CREATE INDEX "Job_runAt_idx" ON "Job"("runAt");
+
+-- CreateIndex
+CREATE INDEX "Job_status_runAt_idx" ON "Job"("status", "runAt");
+
+-- CreateIndex
+CREATE INDEX "Job_createdAt_idx" ON "Job"("createdAt");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "File_storageKey_key" ON "File"("storageKey");
+
+-- CreateIndex
+CREATE INDEX "File_uploadedById_idx" ON "File"("uploadedById");
+
+-- CreateIndex
+CREATE INDEX "File_mimeType_idx" ON "File"("mimeType");
+
+-- CreateIndex
+CREATE INDEX "File_createdAt_idx" ON "File"("createdAt");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_userId_idx" ON "AuditLog"("userId");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_action_idx" ON "AuditLog"("action");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_entity_idx" ON "AuditLog"("entity");
+
+-- CreateIndex
+CREATE INDEX "AuditLog_createdAt_idx" ON "AuditLog"("createdAt");
+
+-- AddForeignKey
+ALTER TABLE "Account" ADD CONSTRAINT "Account_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "Session" ADD CONSTRAINT "Session_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "File" ADD CONSTRAINT "File_uploadedById_fkey" FOREIGN KEY ("uploadedById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "AuditLog" ADD CONSTRAINT "AuditLog_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+

package/templates/base-project/packages/db/prisma/migrations/migration_lock.toml

@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (e.g., Git)
+provider = "postgresql"

package/templates/base-project/packages/db/prisma/schema.prisma

@@ -0,0 +1,161 @@
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+// Looking for ways to speed up your queries, or scale easily with your serverless or edge functions?
+// Try Prisma Accelerate: https://pris.ly/cli/accelerate-init
+
+generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+enum UserRole {
+  admin
+  lead_dev
+  client_admin
+  editor
+  viewer
+}
+
+model User {
+  id            String    @id @default(cuid())
+  email         String    @unique
+  emailVerified DateTime?
+  name          String?
+  password      String?
+  image         String?
+  role          UserRole  @default(viewer)
+  createdAt     DateTime  @default(now())
+  updatedAt     DateTime  @updatedAt
+
+  accounts      Account[]
+  sessions      Session[]
+  auditLogs     AuditLog[]
+  files         File[]
+
+  @@index([email])
+  @@index([createdAt])
+}
+
+// NextAuth Models
+model Account {
+  id                 String   @id @default(cuid())
+  userId             String
+  type               String
+  provider           String
+  providerAccountId  String
+  refresh_token      String?  @db.Text
+  access_token       String?  @db.Text
+  expires_at         Int?
+  token_type         String?
+  scope              String?
+  id_token           String?  @db.Text
+  session_state      String?
+  createdAt          DateTime @default(now())
+  updatedAt          DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@unique([provider, providerAccountId])
+  @@index([userId])
+}
+
+model Session {
+  id           String   @id @default(cuid())
+  sessionToken String   @unique
+  userId       String
+  expires      DateTime
+  createdAt    DateTime @default(now())
+  updatedAt    DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+  @@index([expires])
+}
+
+model VerificationToken {
+  identifier String
+  token      String   @unique
+  expires    DateTime
+  createdAt  DateTime @default(now())
+  updatedAt  DateTime @updatedAt
+
+  @@unique([identifier, token])
+  @@index([token])
+  @@index([expires])
+}
+
+// Job Queue Model
+model Job {
+  id        String   @id @default(cuid())
+  queue     String
+  name      String
+  data      Json?
+  status    JobStatus @default(PENDING)
+  error     String?
+  attempts  Int       @default(0)
+  maxRetries Int      @default(3)
+  runAt     DateTime  @default(now())
+  startedAt DateTime?
+  completedAt DateTime?
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+
+  @@index([queue])
+  @@index([status])
+  @@index([runAt])
+  @@index([status, runAt])
+  @@index([createdAt])
+}
+
+enum JobStatus {
+  PENDING
+  IN_PROGRESS
+  COMPLETED
+  FAILED
+  CANCELLED
+}
+
+// File Upload Model
+model File {
+  id              String   @id @default(cuid())
+  filename        String
+  originalName    String
+  mimeType        String
+  size            Int
+  storageKey      String   @unique
+  storageProvider String   @default("local")
+  uploadedById    String?
+  uploadedBy      User?    @relation(fields: [uploadedById], references: [id], onDelete: SetNull)
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+
+  @@index([uploadedById])
+  @@index([mimeType])
+  @@index([createdAt])
+}
+
+// Audit Log Model
+model AuditLog {
+  id        String   @id @default(cuid())
+  userId    String
+  action    String
+  entity    String
+  entityId  String
+  changes   Json?
+  metadata  Json?
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId])
+  @@index([action])
+  @@index([entity])
+  @@index([createdAt])
+}

package/templates/base-project/packages/db/prisma/seed.js

@@ -0,0 +1,152 @@
+import { randomBytes } from "node:crypto";
+import bcrypt from "bcryptjs";
+import { prisma } from "../src/index.js";
+
+/**
+ * Minimal seed: creates a single admin user.
+ * Used standalone in production initial setup (SEED_PROFILE=minimal).
+ * Also called by seedDev to avoid duplication.
+ *
+ * Required env vars:
+ *   ADMIN_PASSWORD - min 12 characters, auto-generates if missing (generate: openssl rand -base64 24)
+ * Optional env vars:
+ *   ADMIN_EMAIL    - defaults to admin@example.com
+ *   ADMIN_NAME     - defaults to Admin
+ */
+async function seedMinimal(prisma) {
+	const seedProfile = process.env.SEED_PROFILE || "dev";
+	const adminEmail = process.env.ADMIN_EMAIL;
+	let adminPassword = process.env.ADMIN_PASSWORD;
+	const adminName = process.env.ADMIN_NAME || "Admin";
+
+	if (!adminPassword) {
+		const generated = randomBytes(24).toString("base64url");
+		console.log(
+			"⚠️  ADMIN_PASSWORD not set — auto-generated a random password.\n" +
+				"  Save it if you need to log in as admin.",
+		);
+		adminPassword = generated;
+	}
+	if (adminPassword.length < 12) {
+		throw new Error("ADMIN_PASSWORD must be at least 12 characters.");
+	}
+
+	if (!adminEmail && seedProfile === "minimal") {
+		throw new Error(
+			"ADMIN_EMAIL is required when SEED_PROFILE=minimal.\n" +
+				"  Set it in your environment to the real admin email address.",
+		);
+	}
+
+	const resolvedEmail = adminEmail || "admin@example.com";
+
+	const existing = await prisma.user.findUnique({
+		where: { email: resolvedEmail },
+	});
+
+	if (existing) {
+		console.log("✓ Admin user already exists");
+		return null;
+	}
+
+	const admin = await prisma.user.create({
+		data: {
+			email: resolvedEmail,
+			name: adminName,
+			role: "admin",
+			password: await bcrypt.hash(adminPassword, 12),
+		},
+	});
+
+	console.log(`✓ Created admin user: ${admin.email}`);
+	return admin;
+}
+
+/**
+ * Development seed: admin user + representative sample data for local testing.
+ * Runs by default (SEED_PROFILE=dev).
+ */
+async function seedDev(prisma) {
+	const admin = await seedMinimal(prisma);
+
+	if (admin) {
+		const sampleUser = await prisma.user.create({
+			data: {
+				email: "user@example.com",
+				name: "Sample User",
+				role: "viewer",
+				image:
+					"https://api.dicebear.com/7.x/avataaars/svg?seed=user@example.com",
+			},
+		});
+
+		console.log(`✓ Created sample user: ${sampleUser.email}`);
+
+		await prisma.auditLog.create({
+			data: {
+				userId: admin.id,
+				action: "CREATE",
+				entity: "User",
+				entityId: sampleUser.id,
+				metadata: { email: sampleUser.email, role: sampleUser.role },
+			},
+		});
+
+		console.log("✓ Created sample audit log");
+
+		await prisma.job.create({
+			data: {
+				queue: "default",
+				name: "example-job",
+				status: "COMPLETED",
+				data: { message: "This is a sample job" },
+				completedAt: new Date(),
+			},
+		});
+
+		console.log("✓ Created sample job");
+	}
+}
+
+async function main() {
+	// Guard: require an explicit SEED_PROFILE when seeding a remote database.
+	// Without this, a missing SEED_PROFILE silently defaults to "dev" and seeds
+	// sample data onto production or staging databases.
+	if (!process.env.SEED_PROFILE) {
+		const host = process.env.POSTGRES_HOST || "";
+		const url = process.env.DATABASE_URL || "";
+		const isRemote =
+			(host && host !== "localhost" && host !== "127.0.0.1") ||
+			(url && !url.includes("localhost") && !url.includes("127.0.0.1"));
+		if (isRemote) {
+			console.error(
+				"❌ Set SEED_PROFILE explicitly when seeding a remote database.\n" +
+					"   Production: SEED_PROFILE=minimal pnpm db:seed\n" +
+					"   Staging:    SEED_PROFILE=dev pnpm db:seed",
+			);
+			process.exit(1);
+		}
+	}
+
+	// SEED_PROFILE is intentionally separate from NODE_ENV.
+	// Railway sets NODE_ENV=production on ALL deployed services (including staging)
+	// for build/performance reasons, so NODE_ENV cannot reliably distinguish staging
+	// from production at seed time. Set SEED_PROFILE explicitly in your deploy command:
+	//   production: SEED_PROFILE=minimal pnpm db:seed
+	//   staging:    pnpm db:seed   (defaults to "dev")
+	const seedProfile = process.env.SEED_PROFILE || "dev";
+	console.log(`🌱 Seeding database with profile: "${seedProfile}"`);
+
+	if (seedProfile === "minimal") {
+		await seedMinimal(prisma);
+	} else {
+		await seedDev(prisma);
+	}
+
+	console.log("✅ Database seeding completed");
+}
+
+main().catch((error) => {
+	console.error("❌ Seed failed:", error);
+	process.exit(1);
+});

package/templates/base-project/packages/db/prisma.config.js

@@ -0,0 +1,27 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "prisma/config";
+import { getConnectionString } from "./src/connection.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Load .env from monorepo root (needed for standalone commands like db:push, db:seed)
+try {
+	process.loadEnvFile(resolve(__dirname, "../../.env"));
+} catch {}
+
+// Use shared connection builder - throwOnMissing=false so `prisma generate` works
+// even without database credentials (e.g. in CI). Commands that need a real
+// connection (migrate, push, studio) will fail at connect time.
+const databaseUrl = getConnectionString({ throwOnMissing: false });
+
+export default defineConfig({
+	schema: "prisma/schema.prisma",
+	migrations: {
+		path: "prisma/migrations",
+		seed: "tsx prisma/seed.js",
+	},
+	datasource: {
+		url: databaseUrl,
+	},
+});

package/templates/base-project/packages/db/src/client.js

@@ -0,0 +1,75 @@
+import { PrismaPg } from "@prisma/adapter-pg";
+import { getConnectionString } from "./connection.js";
+import { PrismaClient } from "./generated/prisma/client.ts";
+
+/**
+ * Returns the connection pool configuration for the `pg` driver.
+ *
+ * Reads from environment variables with sensible defaults:
+ * - `DB_POOL_MAX` - maximum number of connections (default: 10 in production, 5 in development)
+ * - `DB_POOL_IDLE_TIMEOUT` - milliseconds before an idle connection is closed (default: 30 000)
+ * - `DB_POOL_CONNECTION_TIMEOUT` - milliseconds to wait for a new connection (default: 5 000)
+ *
+ * @returns {{ max: number, idleTimeoutMillis: number, connectionTimeoutMillis: number }}
+ */
+export function getPoolConfig() {
+	const isProduction = process.env.NODE_ENV === "production";
+	return {
+		max: Number(process.env.DB_POOL_MAX) || (isProduction ? 10 : 5),
+		idleTimeoutMillis: Number(process.env.DB_POOL_IDLE_TIMEOUT) || 30_000,
+		connectionTimeoutMillis:
+			Number(process.env.DB_POOL_CONNECTION_TIMEOUT) || 5_000,
+	};
+}
+
+// Lazy singleton - the client is created on first property access, not at import time.
+// This allows Next.js to import the module at build time without requiring DB env vars.
+const globalForPrisma = globalThis;
+
+function getPrismaClient() {
+	if (!globalForPrisma.__prisma) {
+		const baseClient = new PrismaClient({
+			adapter: new PrismaPg({
+				connectionString: getConnectionString(),
+				...getPoolConfig(),
+			}),
+		});
+
+		// Assign base client immediately so the proxy never blocks.
+		globalForPrisma.__prisma = baseClient;
+
+		// Apply optional query instrumentation extension from @techstream/quark-core.
+		// Loaded asynchronously — the base client is used in the meantime, then
+		// upgraded in-place once the extension module arrives.
+		// The extension handles slow-query logging, argument masking, and Prometheus
+		// metrics.  It is schema-agnostic and respects the DB_INSTRUMENTATION env var.
+		import("@techstream/quark-core")
+			.then(({ createDbInstrumentation }) => {
+				const ext = createDbInstrumentation();
+				if (ext) {
+					globalForPrisma.__prisma = baseClient.$extends(ext);
+				}
+			})
+			.catch(() => {
+				// @techstream/quark-core not available or old version — base client remains.
+			});
+	}
+	return globalForPrisma.__prisma;
+}
+
+/**
+ * Prisma client singleton. Lazily initialized on first use so the module
+ * can be imported safely at build time (no DB env vars needed).
+ *
+ * Methods are bound to the real client so `this` inside Prisma internals is
+ * always the PrismaClient instance, never the Proxy wrapper.
+ */
+export const prisma = new Proxy(/** @type {PrismaClient} */ ({}), {
+	get(_target, prop) {
+		const client = getPrismaClient();
+		const value = client[prop];
+		return typeof value === "function" ? value.bind(client) : value;
+	},
+});
+
+export * from "./generated/prisma/client.ts";