@techstream/quark-create-app 1.2.0 → 1.4.0

package/templates/base-project/apps/web/src/app/api/users/route.js

@@ -1,12 +1,12 @@
-import { validateBody } from "@techstream/quark-core";
+import { validateBody, withCsrfProtection } from "@techstream/quark-core";
 import { user, userCreateSchema } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
-import { requireAuth } from "@/lib/auth-middleware";
+import { requireRole } from "@/lib/auth-middleware";
 import { handleError } from "../error-handler";
 
 export async function GET(_request) {
 	try {
-		await requireAuth();
+		await requireRole("admin");
 		const users = await user.findAll();
 		return NextResponse.json(users);
 	} catch (error) {
@@ -14,9 +14,9 @@ export async function GET(_request) {
 	}
 }
 
-export async function POST(request) {
+export const POST = withCsrfProtection(async (request) => {
 	try {
-		await requireAuth();
+		await requireRole("admin");
 		const data = await validateBody(request, userCreateSchema);
 
 		// Check if email already exists
@@ -33,4 +33,4 @@ export async function POST(request) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});

package/templates/base-project/apps/web/src/lib/auth-middleware.js

@@ -1,4 +1,4 @@
-import { UnauthorizedError } from "@techstream/quark-core";
+import { ForbiddenError, UnauthorizedError } from "@techstream/quark-core";
 import { auth } from "./auth";
 
 export async function requireAuth() {
@@ -12,3 +12,20 @@ export async function requireAuth() {
 
 	return session;
 }
+
+/**
+ * Require the current user to have a specific role.
+ * @param {string} role - Required role (e.g. "admin")
+ * @returns {Promise<import("next-auth").Session>}
+ */
+export async function requireRole(role) {
+	const session = await requireAuth();
+
+	if (session.user?.role !== role) {
+		throw new ForbiddenError(
+			"You do not have permission to access this resource",
+		);
+	}
+
+	return session;
+}

package/templates/base-project/apps/web/src/{middleware.js → proxy.js}

@@ -1,5 +1,5 @@
 /**
- * Next.js Middleware
+ * Next.js Proxy
  * Handles rate limiting, CORS, and security headers
  */
 
@@ -112,7 +112,7 @@ const REQUEST_SIZE_LIMITS = {
 	upload: parseInt(process.env.UPLOAD_SIZE_LIMIT || "10485760", 10), // 10MB for uploads
 };
 
-export function middleware(request) {
+export function proxy(request) {
 	const { pathname } = request.nextUrl;
 	const origin = request.headers.get("origin") || "";
 
@@ -250,7 +250,7 @@ export function middleware(request) {
 	return response;
 }
 
-// Configure which routes the middleware runs on
+// Configure which routes the proxy runs on
 export const config = {
 	matcher: [
 		/*

package/templates/base-project/apps/worker/package.json

@@ -17,8 +17,7 @@
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
-		"bullmq": "^5.64.1",
-		"dotenv": "^17.2.3"
+		"bullmq": "^5.64.1"
 	},
 	"devDependencies": {
 		"@techstream/quark-config": "workspace:*",

package/templates/base-project/apps/worker/src/index.js

@@ -8,13 +8,11 @@ import {
 	createEmailService,
 	createLogger,
 	createWorker,
+	passwordResetEmail,
+	welcomeEmail,
 } from "@techstream/quark-core";
-import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 import { prisma } from "@techstream/quark-db";
-import dotenv from "dotenv";
-
-// Load environment variables
-dotenv.config();
+import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 
 const logger = createLogger("worker");
 
@@ -40,7 +38,6 @@ async function handleSendWelcomeEmail(bullJob) {
 		userId,
 	});
 
-	// Look up the user's email
 	const userRecord = await prisma.user.findUnique({
 		where: { id: userId },
 		select: { email: true, name: true },
@@ -50,15 +47,60 @@ async function handleSendWelcomeEmail(bullJob) {
 		throw new Error(`User ${userId} not found or has no email`);
 	}
 
-	const displayName = userRecord.name || "there";
+	const template = welcomeEmail({
+		name: userRecord.name,
+		loginUrl: process.env.APP_URL
+			? `${process.env.APP_URL}/api/auth/signin`
+			: undefined,
+	});
+
+	await emailService.sendEmail(
+		userRecord.email,
+		template.subject,
+		template.html,
+		template.text,
+	);
+
+	return { success: true, userId, email: userRecord.email };
+}
+
+/**
+ * Job handler for SEND_RESET_PASSWORD_EMAIL
+ * @param {Job} bullJob - BullMQ job object
+ */
+async function handleSendResetPasswordEmail(bullJob) {
+	const { userId, resetUrl } = bullJob.data;
+
+	if (!userId || !resetUrl) {
+		throw new Error(
+			"userId and resetUrl are required for SEND_RESET_PASSWORD_EMAIL job",
+		);
+	}
+
+	logger.info(`Sending password reset email for user ${userId}`, {
+		job: JOB_NAMES.SEND_RESET_PASSWORD_EMAIL,
+		userId,
+	});
+
+	const userRecord = await prisma.user.findUnique({
+		where: { id: userId },
+		select: { email: true, name: true },
+	});
+
+	if (!userRecord?.email) {
+		throw new Error(`User ${userId} not found or has no email`);
+	}
+
+	const template = passwordResetEmail({
+		name: userRecord.name,
+		resetUrl,
+	});
 
 	await emailService.sendEmail(
 		userRecord.email,
-		"Welcome to Quark!",
-		`<h1>Welcome, ${displayName}!</h1>
-<p>Your account has been created successfully.</p>
-<p>You can now sign in and start using the application.</p>`,
-		`Welcome, ${displayName}!\n\nYour account has been created successfully.\nYou can now sign in and start using the application.`,
+		template.subject,
+		template.html,
+		template.text,
 	);
 
 	return { success: true, userId, email: userRecord.email };
@@ -70,6 +112,7 @@ async function handleSendWelcomeEmail(bullJob) {
  */
 const jobHandlers = {
 	[JOB_NAMES.SEND_WELCOME_EMAIL]: handleSendWelcomeEmail,
+	[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: handleSendResetPasswordEmail,
 };
 
 /**
@@ -104,11 +147,14 @@ async function startWorker() {
 		});
 
 		emailQueueWorker.on("failed", (job, error) => {
-			logger.error(`Job ${job.id} (${job.name}) failed after ${job.attemptsMade} attempts`, {
-				error: error.message,
-				jobName: job.name,
-				attemptsMade: job.attemptsMade,
-			});
+			logger.error(
+				`Job ${job.id} (${job.name}) failed after ${job.attemptsMade} attempts`,
+				{
+					error: error.message,
+					jobName: job.name,
+					attemptsMade: job.attemptsMade,
+				},
+			);
 		});
 
 		logger.info(
@@ -118,7 +164,10 @@ async function startWorker() {
 		// Ready to process jobs
 		logger.info("Worker service ready");
 	} catch (error) {
-		logger.error("Failed to start worker service", { error: error.message, stack: error.stack });
+		logger.error("Failed to start worker service", {
+			error: error.message,
+			stack: error.stack,
+		});
 		process.exit(1);
 	}
 }
@@ -141,7 +190,10 @@ async function shutdown() {
 		logger.info("All workers closed");
 		process.exit(0);
 	} catch (error) {
-		logger.error("Error during shutdown", { error: error.message, stack: error.stack });
+		logger.error("Error during shutdown", {
+			error: error.message,
+			stack: error.stack,
+		});
 		process.exit(1);
 	}
 }

package/templates/base-project/docker-compose.yml

@@ -2,7 +2,6 @@ services:
   # --- 1. PostgreSQL Database ---
   postgres:
     image: postgres:16-alpine
-    container_name: postgres
     restart: always
     ports:
       - "${POSTGRES_PORT:-5432}:5432"
@@ -16,7 +15,6 @@ services:
   # --- 2. Redis Cache & Job Queue ---
   redis:
     image: redis:7-alpine
-    container_name: redis
     restart: always
     ports:
       - "${REDIS_PORT:-6379}:6379"
@@ -24,10 +22,9 @@ services:
     volumes:
       - redis_data:/data
 
-  # --- 3. Mailhog (Local SMTP Server) ---
-  mailhog:
-    image: mailhog/mailhog
-    container_name: mailhog
+  # --- 3. Mailpit (Local SMTP Server) ---
+  mailpit:
+    image: ghcr.io/axllent/mailpit
     restart: always
     ports:
       # SMTP port (used by application to send mail)

package/templates/base-project/package.json

@@ -6,7 +6,7 @@
 	"main": "index.js",
 	"scripts": {
 		"build": "turbo run build",
-		"dev": "turbo run dev",
+		"dev": "dotenv -- turbo run dev",
 		"lint": "turbo run lint",
 		"test": "turbo run test",
 		"docker:up": "docker compose up -d",
@@ -17,9 +17,24 @@
 	"author": "",
 	"license": "ISC",
 	"packageManager": "pnpm@10.12.1",
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"@prisma/engines",
+			"esbuild",
+			"msgpackr-extract",
+			"prisma",
+			"sharp"
+		],
+		"peerDependencyRules": {
+			"allowedVersions": {
+				"nodemailer": "*"
+			}
+		}
+	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.13",
 		"@types/node": "^24.10.9",
+		"dotenv-cli": "^11.0.0",
 		"tsx": "^4.21.0",
 		"turbo": "^2.8.1"
 	}

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

@@ -10,20 +10,26 @@
 		"db:generate": "prisma generate",
 		"db:migrate": "prisma migrate dev",
 		"db:push": "prisma db push",
-		"db:seed": "node scripts/seed.js",
+		"db:seed": "prisma db seed",
 		"db:studio": "prisma studio"
 	},
+	"prisma": {
+		"seed": "node scripts/seed.js"
+	},
 	"keywords": [],
 	"author": "",
 	"license": "ISC",
 	"packageManager": "pnpm@10.12.1",
 	"devDependencies": {
 		"@techstream/quark-config": "workspace:*",
-		"prisma": "^7.0.0"
+		"bcryptjs": "^3.0.3",
+		"prisma": "^7.3.0"
 	},
 	"dependencies": {
-		"@prisma/client": "^7.0.0",
-		"dotenv": "^17.2.3",
+		"@prisma/adapter-pg": "^7.3.0",
+		"@prisma/client": "^7.3.0",
+		"dotenv": "^17.2.4",
+		"pg": "^8.18.0",
 		"zod": "^4.3.6"
 	}
 }

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

@@ -2,8 +2,8 @@ import { resolve } from "node:path";
 import { config } from "dotenv";
 import { defineConfig } from "prisma/config";
 
-// Load .env from monorepo root
-config({ path: resolve(__dirname, "../../.env") });
+// Load .env from monorepo root (needed for standalone commands like db:push, db:seed)
+config({ path: resolve(__dirname, "../../.env"), quiet: true });
 
 // Construct DATABASE_URL from individual env vars - single source of truth
 const user = process.env.POSTGRES_USER || "quark_user";

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

@@ -1,5 +1,5 @@
-import { PrismaClient } from "../src/generated/prisma/client.js";
 import bcrypt from "bcryptjs";
+import { PrismaClient } from "../src/generated/prisma/client.js";
 
 const prisma = new PrismaClient();
 

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

@@ -1,19 +1,23 @@
 import { PrismaPg } from "@prisma/adapter-pg";
 import { PrismaClient } from "./generated/prisma/client.ts";
 
-// Construct DATABASE_URL from individual env vars (mirrors prisma.config.ts)
-// POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB are required — no silent fallbacks.
-const user = process.env.POSTGRES_USER;
-if (!user) throw new Error("POSTGRES_USER environment variable is required");
-const password = process.env.POSTGRES_PASSWORD;
-if (!password) throw new Error("POSTGRES_PASSWORD environment variable is required");
-const host = process.env.POSTGRES_HOST || "localhost";
-const port = process.env.POSTGRES_PORT || "5432";
-const db = process.env.POSTGRES_DB;
-if (!db) throw new Error("POSTGRES_DB environment variable is required");
-const connectionString = `postgresql://${user}:${password}@${host}:${port}/${db}?schema=public`;
-
-const isProduction = process.env.NODE_ENV === "production";
+/**
+ * Builds a Postgres connection string from individual env vars (mirrors prisma.config.ts).
+ * Throws if any required variable is missing — but only when actually called,
+ * so the module can be safely imported at build time (e.g. during `next build`).
+ */
+function getConnectionString() {
+	const user = process.env.POSTGRES_USER;
+	if (!user) throw new Error("POSTGRES_USER environment variable is required");
+	const password = process.env.POSTGRES_PASSWORD;
+	if (!password)
+		throw new Error("POSTGRES_PASSWORD environment variable is required");
+	const host = process.env.POSTGRES_HOST || "localhost";
+	const port = process.env.POSTGRES_PORT || "5432";
+	const db = process.env.POSTGRES_DB;
+	if (!db) throw new Error("POSTGRES_DB environment variable is required");
+	return `postgresql://${user}:${password}@${host}:${port}/${db}?schema=public`;
+}
 
 /**
  * Returns the connection pool configuration for the `pg` driver.
@@ -26,6 +30,7 @@ const isProduction = process.env.NODE_ENV === "production";
  * @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,
@@ -34,19 +39,30 @@ export function getPoolConfig() {
 	};
 }
 
-// Create a singleton Prisma client with the PostgreSQL driver adapter and pool settings
+// 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;
-export const prisma =
-	globalForPrisma.prisma ||
-	new PrismaClient({
-		adapter: new PrismaPg({
-			connectionString,
-			...getPoolConfig(),
-		}),
-	});
 
-if (!isProduction) {
-	globalForPrisma.prisma = prisma;
+function getPrismaClient() {
+	if (!globalForPrisma.__prisma) {
+		globalForPrisma.__prisma = new PrismaClient({
+			adapter: new PrismaPg({
+				connectionString: getConnectionString(),
+				...getPoolConfig(),
+			}),
+		});
+	}
+	return globalForPrisma.__prisma;
 }
 
-export * from "./generated/prisma/client.js";
+/**
+ * Prisma client singleton. Lazily initialized on first use so the module
+ * can be imported safely at build time (no DB env vars needed).
+ */
+export const prisma = new Proxy(/** @type {PrismaClient} */ ({}), {
+	get(_target, prop) {
+		return getPrismaClient()[prop];
+	},
+});
+
+export * from "./generated/prisma/client.ts";

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

@@ -67,12 +67,17 @@ export const user = {
 	},
 };
 
+/**
+ * Safe author include — returns author without sensitive fields.
+ */
+const AUTHOR_SAFE_INCLUDE = { author: { select: USER_SAFE_SELECT } };
+
 // Post queries
 export const post = {
 	findById: (id) => {
 		return prisma.post.findUnique({
 			where: { id },
-			include: { author: true },
+			include: AUTHOR_SAFE_INCLUDE,
 		});
 	},
 	findAll: (options = {}) => {
@@ -80,7 +85,7 @@ export const post = {
 		return prisma.post.findMany({
 			skip,
 			take,
-			include: { author: true },
+			include: AUTHOR_SAFE_INCLUDE,
 			orderBy: { createdAt: "desc" },
 		});
 	},
@@ -90,7 +95,7 @@ export const post = {
 			where: { published: true },
 			skip,
 			take,
-			include: { author: true },
+			include: AUTHOR_SAFE_INCLUDE,
 			orderBy: { createdAt: "desc" },
 		});
 	},
@@ -100,21 +105,21 @@ export const post = {
 			where: { authorId },
 			skip,
 			take,
-			include: { author: true },
+			include: AUTHOR_SAFE_INCLUDE,
 			orderBy: { createdAt: "desc" },
 		});
 	},
 	create: (data) => {
 		return prisma.post.create({
 			data,
-			include: { author: true },
+			include: AUTHOR_SAFE_INCLUDE,
 		});
 	},
 	update: (id, data) => {
 		return prisma.post.update({
 			where: { id },
 			data,
-			include: { author: true },
+			include: AUTHOR_SAFE_INCLUDE,
 		});
 	},
 	delete: (id) => {
@@ -122,7 +127,15 @@ export const post = {
 			where: { id },
 		});
 	},
-};\n\n// Note: Job tracking is handled by BullMQ's built-in Redis persistence.\n// The Prisma Job model is retained in the schema for optional audit/reporting\n// but these query helpers have been removed to avoid confusion with BullMQ.\n// If you need database-backed job auditing, re-add job queries here and wire\n// the worker to write status updates to the Job table.\n\n// Account queries (NextAuth)
+};
+
+// Note: Job tracking is handled by BullMQ's built-in Redis persistence.
+// The Prisma Job model is retained in the schema for optional audit/reporting
+// but these query helpers have been removed to avoid confusion with BullMQ.
+// If you need database-backed job auditing, re-add job queries here and wire
+// the worker to write status updates to the Job table.
+
+// Account queries (NextAuth)
 export const account = {
 	findById: (id) => {
 		return prisma.account.findUnique({
@@ -156,7 +169,7 @@ export const session = {
 	findByToken: (sessionToken) => {
 		return prisma.session.findUnique({
 			where: { sessionToken },
-			include: { user: true },
+			include: { user: { select: USER_SAFE_SELECT } },
 		});
 	},
 	findByUserId: (userId) => {
@@ -167,7 +180,7 @@ export const session = {
 	create: (data) => {
 		return prisma.session.create({
 			data,
-			include: { user: true },
+			include: { user: { select: USER_SAFE_SELECT } },
 		});
 	},
 	update: (sessionToken, data) => {

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

@@ -8,7 +8,12 @@ export const userCreateSchema = z.object({
 
 export const userRegisterSchema = z.object({
 	email: z.string().email("Invalid email address"),
-	password: z.string().min(8, "Password must be at least 8 characters"),
+	password: z
+		.string()
+		.min(8, "Password must be at least 8 characters")
+		.regex(/[A-Z]/, "Password must contain at least one uppercase letter")
+		.regex(/[a-z]/, "Password must contain at least one lowercase letter")
+		.regex(/[0-9]/, "Password must contain at least one number"),
 	name: z.string().min(2, "Name must be at least 2 characters").optional(),
 });
 

package/templates/base-project/turbo.json

@@ -19,7 +19,23 @@
 		},
 		"dev": {
 			"cache": false,
-			"persistent": true
+			"persistent": true,
+			"passThroughEnv": [
+				"PORT",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB",
+				"REDIS_HOST",
+				"REDIS_PORT",
+				"MAILHOG_HOST",
+				"MAILHOG_SMTP_PORT",
+				"MAILHOG_UI_PORT",
+				"NEXTAUTH_SECRET",
+				"APP_URL",
+				"WORKER_CONCURRENCY"
+			]
 		}
 	}
 }

package/templates/config/package.json

@@ -3,6 +3,8 @@
 	"version": "1.0.0",
 	"type": "module",
 	"exports": {
-		".": "./src/index.js"
+		".": "./src/index.js",
+		"./app-url": "./src/app-url.js",
+		"./validate-env": "./src/validate-env.js"
 	}
 }

package/templates/config/src/app-url.js

@@ -0,0 +1,71 @@
+/**
+ * APP_URL — Single source of truth for the application's canonical URL.
+ *
+ * Resolution order:
+ *   1. APP_URL          (production — set to your real domain)
+ *   2. NEXTAUTH_URL     (legacy / backward-compat)
+ *   3. http://localhost:${PORT || 3000}   (local dev fallback)
+ *
+ * In development PORT is the single source of truth for the web server port.
+ * APP_URL is derived from it automatically so the two can never drift.
+ * In production, set APP_URL explicitly (e.g. https://yourdomain.com).
+ *
+ * Derived values:
+ *   - NEXTAUTH_URL  — always set equal to the resolved APP_URL so
+ *                      NextAuth works without a separate variable.
+ *   - allowedOrigins — the resolved APP_URL plus any extra origins
+ *                      listed in ALLOWED_ORIGINS (comma-separated).
+ */
+
+/**
+ * Resolves the canonical application URL.
+ * @returns {string} The canonical URL (no trailing slash)
+ */
+export function getAppUrl() {
+	const raw =
+		process.env.APP_URL ||
+		process.env.NEXTAUTH_URL ||
+		`http://localhost:${process.env.PORT || "3000"}`;
+
+	// Strip trailing slash for consistency
+	return raw.replace(/\/+$/, "");
+}
+
+/**
+ * Returns the list of allowed CORS origins.
+ *
+ * Always includes the canonical APP_URL.
+ * If ALLOWED_ORIGINS is set, those are *added* (not replacing) the canonical
+ * origin so the primary domain is never accidentally excluded.
+ *
+ * @returns {string[]} De-duplicated list of allowed origins
+ */
+export function getAllowedOrigins() {
+	const canonical = getAppUrl();
+	const extras = process.env.ALLOWED_ORIGINS
+		? process.env.ALLOWED_ORIGINS.split(",")
+				.map((o) => o.trim())
+				.filter(Boolean)
+		: [];
+
+	// In development, always allow the common local ports
+	const isDev = process.env.NODE_ENV !== "production";
+	const devOrigins = isDev
+		? ["http://localhost:3000", "http://localhost:3001"]
+		: [];
+
+	// De-duplicate
+	return [...new Set([canonical, ...extras, ...devOrigins])];
+}
+
+/**
+ * Ensures NEXTAUTH_URL is set in process.env so NextAuth picks it up,
+ * even when only APP_URL was configured.
+ *
+ * Call this once at startup (e.g. in your env validation step).
+ */
+export function syncNextAuthUrl() {
+	if (!process.env.NEXTAUTH_URL) {
+		process.env.NEXTAUTH_URL = getAppUrl();
+	}
+}