@techstream/quark-create-app 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@techstream/quark-create-app",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"type": "module",
 	"bin": {
 		"quark-create-app": "src/index.js",
@@ -29,6 +29,7 @@
 		"access": "public"
 	},
 	"engines": {
-		"node": ">=24"
-	}
+		"node": ">=22"
+	},
+	"license": "ISC"
 }

package/src/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import crypto from "node:crypto";
+import net from "node:net";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
@@ -47,6 +48,48 @@ function generateSecurePassword(length = 24) {
 	return result;
 }
 
+/**
+ * Check if a TCP port is available on localhost.
+ * Uses a connect test (not bind) to reliably detect Docker-bound ports on macOS.
+ * @param {number} port
+ * @returns {Promise<boolean>}
+ */
+function isPortAvailable(port) {
+	return new Promise((resolve) => {
+		const socket = new net.Socket();
+		socket.setTimeout(500);
+		socket.once("connect", () => {
+			socket.destroy();
+			resolve(false); // something is listening — port is in use
+		});
+		socket.once("error", () => {
+			socket.destroy();
+			resolve(true); // ECONNREFUSED — port is free
+		});
+		socket.once("timeout", () => {
+			socket.destroy();
+			resolve(true); // no response — port is free
+		});
+		socket.connect(port, "127.0.0.1");
+	});
+}
+
+/**
+ * Find the next available port starting from a given port
+ * @param {number} startPort
+ * @param {number} [maxAttempts=20]
+ * @returns {Promise<number>}
+ */
+async function findAvailablePort(startPort, maxAttempts = 20) {
+	for (let i = 0; i < maxAttempts; i++) {
+		const port = startPort + i;
+		if (await isPortAvailable(port)) {
+			return port;
+		}
+	}
+	return startPort; // fallback to default if all checked ports are busy
+}
+
 /**
  * Copy a template directory to the target location, with variable substitution
  */
@@ -131,8 +174,8 @@ function replaceDepsScope(deps, scope, selectedPackages) {
 		if (key.startsWith("@techstream/quark-") && value === "workspace:*") {
 			const packageName = key.replace("@techstream/quark-", "");
 			delete deps[key];
-			// Only keep the dep if the package was selected (or is "db" which is always required)
-			if (packageName === "db" || selectedPackages.includes(packageName)) {
+			// Only keep the dep if the package was selected (or is always required)
+			if (packageName === "db" || packageName === "config" || selectedPackages.includes(packageName)) {
 				deps[`@${scope}/${packageName}`] = value;
 			}
 		}
@@ -210,8 +253,30 @@ program
 
 		// Check if directory already exists
 		if (await fs.pathExists(targetDir)) {
-			console.error(chalk.red(`✗ Directory already exists: ${targetDir}`));
-			process.exit(1);
+			const { overwrite } = await prompts({
+				type: "confirm",
+				name: "overwrite",
+				message: `Directory "${projectName}" already exists. Remove it and recreate?`,
+				initial: false,
+			});
+
+			if (!overwrite) {
+				console.log(chalk.yellow("Aborted."));
+				process.exit(1);
+			}
+
+			// Clean up Docker resources (volumes hold old credentials)
+			try {
+				await execa("docker", ["compose", "down", "-v"], {
+					cwd: targetDir,
+					stdio: "ignore",
+				});
+				console.log(chalk.green("  ✓ Cleaned up Docker volumes"));
+			} catch {
+				// No docker-compose file or Docker not running — fine
+			}
+
+			await fs.remove(targetDir);
 		}
 
 		try {
@@ -233,25 +298,33 @@ program
 			// Step 4: Copy required packages (always included)
 			console.log(chalk.cyan("\n  📦 Setting up required packages..."));
 
-			// Database package is always required (already copied from base-project)
-			// Just update its package.json name
-			const dbPackageDir = path.join(targetDir, "packages", "db");
-			const dbPackageJsonPath = path.join(dbPackageDir, "package.json");
-			const dbPackageJson = await fs.readJSON(dbPackageJsonPath);
-			dbPackageJson.name = `@${scope}/db`;
-			await fs.writeFile(
-				dbPackageJsonPath,
-				`${JSON.stringify(dbPackageJson, null, 2)}\n`,
-			);
-			console.log(chalk.green(`    ✓ db (required)`));
+			// Database and config packages are always required
+			const requiredPackages = ["db", "config"];
+			for (const reqPkg of requiredPackages) {
+				const pkgDir = path.join(targetDir, "packages", reqPkg);
+				// db is already copied from base-project; config needs to be copied from its template
+				if (!(await fs.pathExists(pkgDir))) {
+					await fs.ensureDir(pkgDir);
+					await copyTemplate(reqPkg, pkgDir);
+				}
+				const pkgJsonPath = path.join(pkgDir, "package.json");
+				const pkgJson = await fs.readJSON(pkgJsonPath);
+				pkgJson.name = `@${scope}/${reqPkg}`;
+				await fs.writeFile(
+					pkgJsonPath,
+					`${JSON.stringify(pkgJson, null, 2)}\n`,
+				);
+				console.log(chalk.green(`    ✓ ${reqPkg} (required)`));
+			}
 
 			// Step 5: Ask which optional features to eject
-			console.log(chalk.cyan("\n  🎯 Configuring optional features..."));
+			console.log(chalk.cyan("\n  🎯 Configuring optional features...\n"));
 			const response = await prompts([
 				{
 					type: "multiselect",
 					name: "features",
 					message: "Which optional packages would you like to include?",
+					instructions: false,
 					choices: [
 						{
 							title: "UI Components (packages/ui)",
@@ -263,11 +336,6 @@ program
 							value: "jobs",
 							selected: true,
 						},
-						{
-							title: "Configuration (packages/config)",
-							value: "config",
-							selected: false,
-						},
 					],
 				},
 			]);
@@ -298,27 +366,47 @@ program
 				}
 			}
 
-			// Step 7: Update app dependencies to use correct scope
+			// Step 7: Update all package.json dependencies to use correct scope
 			console.log(chalk.cyan("\n  🔧 Updating app dependencies..."));
 
-			// Update app package.json files to use correct scope
-			const appPaths = [
+			// Collect all package.json files that need scope replacement (apps + packages)
+			const allPkgPaths = [
 				path.join(targetDir, "apps", "web", "package.json"),
 				path.join(targetDir, "apps", "worker", "package.json"),
+				// Also update cross-dependencies in scaffolded packages (e.g. db → config)
+				...["db", ...features].map((pkg) =>
+					path.join(targetDir, "packages", pkg, "package.json"),
+				),
 			];
 
-			for (const appPkgPath of appPaths) {
-				if (await fs.pathExists(appPkgPath)) {
-					const appPkg = await fs.readJSON(appPkgPath);
-					replaceDepsScope(appPkg.dependencies, scope, features);
-					replaceDepsScope(appPkg.devDependencies, scope, features);
+			for (const pkgPath of allPkgPaths) {
+				if (await fs.pathExists(pkgPath)) {
+					const pkg = await fs.readJSON(pkgPath);
+					// Rename package name if it uses @quark/ prefix
+					if (pkg.name && pkg.name.startsWith("@quark/")) {
+						const shortName = pkg.name.replace("@quark/", "");
+						pkg.name = `@${scope}/${shortName}`;
+					}
+					replaceDepsScope(pkg.dependencies, scope, features);
+					replaceDepsScope(pkg.devDependencies, scope, features);
 					await fs.writeFile(
-						appPkgPath,
-						`${JSON.stringify(appPkg, null, 2)}\n`,
+						pkgPath,
+						`${JSON.stringify(pkg, null, 2)}\n`,
 					);
 				}
 			}
 
+			// Also rename root package.json
+			const rootPkgPath = path.join(targetDir, "package.json");
+			if (await fs.pathExists(rootPkgPath)) {
+				const rootPkg = await fs.readJSON(rootPkgPath);
+				rootPkg.name = `@${scope}/root`;
+				await fs.writeFile(
+					rootPkgPath,
+					`${JSON.stringify(rootPkg, null, 2)}\n`,
+				);
+			}
+
 			console.log(chalk.green(`    ✓ App dependencies updated`));
 
 			// Step 7b: Replace workspace package imports in source files
@@ -354,11 +442,9 @@ MAILHOG_UI_PORT=8025
 # MAILHOG_SMTP_URL="smtp://localhost:1025"
 
 # --- Application URL ---
-# The canonical URL of your application.
-# NEXTAUTH_URL, CORS origins, and other URL-dependent settings are derived from this.
-# Development: http://localhost:3000
-# Production: https://yourdomain.com
-APP_URL=http://localhost:3000
+# In development, APP_URL is derived automatically from PORT — no need to set it.
+# In production, set this to your real domain:
+# APP_URL=https://yourdomain.com
 
 # --- NextAuth Configuration ---
 # ⚠️  CRITICAL: Generate a secure secret with: openssl rand -base64 32
@@ -375,7 +461,7 @@ NEXTAUTH_SECRET=CHANGE_ME_TO_STRONG_SECRET
 # GOOGLE_CLIENT_SECRET=your_google_client_secret
 
 # --- Web App Configuration ---
-WEB_PORT=3000
+PORT=3000
 
 # --- Worker Configuration ---
 WORKER_CONCURRENCY=5
@@ -386,7 +472,30 @@ WORKER_CONCURRENCY=5
 			);
 			console.log(chalk.green(`    ✓ .env.example`));
 
-			// Step 9: Generate .env with secure defaults
+			// Step 9: Find available ports and generate .env
+			console.log(chalk.cyan("\n  🔌 Checking port availability..."));
+			const postgresPort = await findAvailablePort(5432);
+			const redisPort = await findAvailablePort(6379);
+			const mailSmtpPort = await findAvailablePort(1025);
+			const mailUiPort = await findAvailablePort(8025);
+			const webPort = await findAvailablePort(3000);
+
+			const portChanges = [];
+			if (postgresPort !== 5432) portChanges.push(`PostgreSQL: ${postgresPort}`);
+			if (redisPort !== 6379) portChanges.push(`Redis: ${redisPort}`);
+			if (mailSmtpPort !== 1025) portChanges.push(`Mail SMTP: ${mailSmtpPort}`);
+			if (mailUiPort !== 8025) portChanges.push(`Mail UI: ${mailUiPort}`);
+			if (webPort !== 3000) portChanges.push(`Web: ${webPort}`);
+
+			if (portChanges.length > 0) {
+				console.log(chalk.yellow(`    ⚡ Ports adjusted to avoid conflicts:`));
+				for (const change of portChanges) {
+					console.log(chalk.yellow(`      • ${change}`));
+				}
+			} else {
+				console.log(chalk.green(`    ✓ All default ports available`));
+			}
+
 			console.log(chalk.cyan("\n  🔑 Generating secure environment file..."));
 
 			// Generate secure random values
@@ -396,28 +505,27 @@ WORKER_CONCURRENCY=5
 			// Create .env with auto-generated secure values
 			const envContent = `# --- Database Configuration ---
 POSTGRES_HOST=localhost
-POSTGRES_PORT=5432
+POSTGRES_PORT=${postgresPort}
 POSTGRES_USER=quark_user
 POSTGRES_PASSWORD=${dbPassword}
 POSTGRES_DB=${scope}_dev
 
 # --- Redis Configuration ---
 REDIS_HOST=localhost
-REDIS_PORT=6379
+REDIS_PORT=${redisPort}
 
-# --- Mailhog Configuration ---
+# --- Mail Configuration ---
 MAILHOG_HOST=localhost
-MAILHOG_SMTP_PORT=1025
-MAILHOG_UI_PORT=8025
+MAILHOG_SMTP_PORT=${mailSmtpPort}
+MAILHOG_UI_PORT=${mailUiPort}
 
 # --- NextAuth Configuration ---
 NEXTAUTH_SECRET=${nextAuthSecret}
 
-# --- Application URL ---
-APP_URL=http://localhost:3000
-
 # --- Web App Configuration ---
-WEB_PORT=3000
+# APP_URL is derived from PORT automatically in development.
+# In production, set APP_URL explicitly in your environment.
+PORT=${webPort}
 
 # --- Worker Configuration ---
 WORKER_CONCURRENCY=5
@@ -432,7 +540,7 @@ WORKER_CONCURRENCY=5
 				quarkVersion: process.env.QUARK_VERSION || "latest",
 				quarkSourcePath: process.env.QUARK_SOURCE_PATH || "../../quark",
 				scaffoldedDate: new Date().toISOString(),
-				requiredPackages: ["db"],
+				requiredPackages: ["db", "config"],
 				packages: features,
 			};
 			await fs.writeFile(
@@ -469,6 +577,27 @@ WORKER_CONCURRENCY=5
 				);
 			}
 
+			// Step 13: Generate Prisma client
+			console.log(chalk.cyan("\n  🗄️  Generating Prisma client..."));
+			try {
+				await execa("pnpm", ["--filter", "db", "db:generate"], {
+					cwd: targetDir,
+					stdio: "inherit",
+				});
+				console.log(chalk.green(`    ✓ Prisma client generated`));
+			} catch (generateError) {
+				console.warn(
+					chalk.yellow(
+						`\n    ⚠️  Prisma generate failed: ${generateError.message}`,
+					),
+				);
+				console.warn(
+					chalk.yellow(
+						`    Run 'pnpm --filter db db:generate' manually.`,
+					),
+				);
+			}
+
 			// Success message
 			console.log(
 				chalk.green.bold(
@@ -480,7 +609,8 @@ WORKER_CONCURRENCY=5
 			console.log(chalk.cyan("Next steps:"));
 			console.log(chalk.white(`  1. cd ${projectName}`));
 			console.log(chalk.white(`  2. docker compose up -d`));
-			console.log(chalk.white(`  3. pnpm dev\n`));
+			console.log(chalk.white(`  3. pnpm --filter db db:push`));
+			console.log(chalk.white(`  4. pnpm dev\n`));
 
 			console.log(chalk.cyan("Important:"));
 			console.log(

package/templates/base-project/apps/web/src/app/api/error-handler.js

@@ -1,8 +1,10 @@
-import { AppError } from "@techstream/quark-core";
+import { AppError, createLogger } from "@techstream/quark-core";
 import { NextResponse } from "next/server";
 
+const logger = createLogger("api");
+
 export function handleError(error) {
-	console.error("API Error:", error);
+	logger.error("API Error", { error: error.message, stack: error.stack });
 
 	if (error instanceof AppError) {
 		return NextResponse.json(error.toJSON(), { status: error.statusCode });

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

@@ -4,10 +4,12 @@
  * Times out after 5 seconds to prevent hanging.
  */
 
-import { pingRedis } from "@techstream/quark-core";
+import { createLogger, pingRedis } from "@techstream/quark-core";
 import { prisma } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
 
+const logger = createLogger("health");
+
 /** Overall timeout for the health check (ms). */
 const HEALTH_CHECK_TIMEOUT = 5000;
 
@@ -27,12 +29,12 @@ export async function GET() {
 			status: result.status === "ok" ? 200 : 503,
 		});
 	} catch (error) {
-		console.error("Health check failed:", error);
+		logger.error("Health check failed", { error: error.message, stack: error.stack });
 		return NextResponse.json(
 			{
 				status: "error",
 				timestamp: new Date().toISOString(),
-				message: error.message,
+				message: "Service health check failed",
 			},
 			{ status: 500 },
 		);

package/templates/base-project/apps/web/src/app/api/posts/[id]/route.js

@@ -1,4 +1,4 @@
-import { UnauthorizedError, validateBody } from "@techstream/quark-core";
+import { UnauthorizedError, validateBody, withCsrfProtection } from "@techstream/quark-core";
 import { post, postUpdateSchema } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
 import { requireAuth } from "@/lib/auth-middleware";
@@ -17,7 +17,7 @@ export async function GET(_request, { params }) {
 	}
 }
 
-export async function PATCH(request, { params }) {
+export const PATCH = withCsrfProtection(async (request, { params }) => {
 	try {
 		const session = await requireAuth();
 		const { id } = await params;
@@ -37,9 +37,9 @@ export async function PATCH(request, { params }) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});
 
-export async function DELETE(_request, { params }) {
+export const DELETE = withCsrfProtection(async (_request, { params }) => {
 	try {
 		const session = await requireAuth();
 		const { id } = await params;
@@ -58,4 +58,4 @@ export async function DELETE(_request, { params }) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});

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

@@ -1,14 +1,22 @@
-import { validateBody } from "@techstream/quark-core";
+import { validateBody, withCsrfProtection } from "@techstream/quark-core";
 import { post, postCreateSchema } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
+import { z } from "zod";
 import { requireAuth } from "@/lib/auth-middleware";
 import { handleError } from "../error-handler";
 
+const paginationSchema = z.object({
+	page: z.coerce.number().int().min(1).default(1),
+	limit: z.coerce.number().int().min(1).max(100).default(10),
+});
+
 export async function GET(request) {
 	try {
 		const { searchParams } = new URL(request.url);
-		const page = parseInt(searchParams.get("page") || "1", 10);
-		const limit = parseInt(searchParams.get("limit") || "10", 10);
+		const { page, limit } = paginationSchema.parse({
+			page: searchParams.get("page") ?? undefined,
+			limit: searchParams.get("limit") ?? undefined,
+		});
 		const skip = (page - 1) * limit;
 
 		const posts = await post.findAll({ skip, take: limit });
@@ -18,7 +26,7 @@ export async function GET(request) {
 	}
 }
 
-export async function POST(request) {
+export const POST = withCsrfProtection(async (request) => {
 	try {
 		const session = await requireAuth();
 		const data = await validateBody(request, postCreateSchema);
@@ -31,4 +39,4 @@ export async function POST(request) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});

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

@@ -1,12 +1,12 @@
-import { validateBody } from "@techstream/quark-core";
+import { validateBody, withCsrfProtection } from "@techstream/quark-core";
 import { user, userUpdateSchema } 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, { params }) {
 	try {
-		await requireAuth();
+		await requireRole("admin");
 		const { id } = await params;
 		const foundUser = await user.findById(id);
 		if (!foundUser) {
@@ -18,9 +18,9 @@ export async function GET(_request, { params }) {
 	}
 }
 
-export async function PATCH(request, { params }) {
+export const PATCH = withCsrfProtection(async (request, { params }) => {
 	try {
-		await requireAuth();
+		await requireRole("admin");
 		const { id } = await params;
 
 		const existingUser = await user.findById(id);
@@ -34,11 +34,11 @@ export async function PATCH(request, { params }) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});
 
-export async function DELETE(_request, { params }) {
+export const DELETE = withCsrfProtection(async (_request, { params }) => {
 	try {
-		await requireAuth();
+		await requireRole("admin");
 		const { id } = await params;
 
 		const existingUser = await user.findById(id);
@@ -51,4 +51,4 @@ export async function DELETE(_request, { params }) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});

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

@@ -11,10 +11,6 @@ import {
 } 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();
 
 const logger = createLogger("worker");
 
@@ -24,6 +20,18 @@ const workers = [];
 // Initialize email service
 const emailService = createEmailService();
 
+/**
+ * Escape HTML entities to prevent XSS in email body
+ */
+function escapeHtml(str) {
+	return str
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#039;");
+}
+
 /**
  * Job handler for SEND_WELCOME_EMAIL
  * @param {Job} bullJob - BullMQ job object
@@ -51,11 +59,12 @@ async function handleSendWelcomeEmail(bullJob) {
 	}
 
 	const displayName = userRecord.name || "there";
+	const safeDisplayName = escapeHtml(displayName);
 
 	await emailService.sendEmail(
 		userRecord.email,
 		"Welcome to Quark!",
-		`<h1>Welcome, ${displayName}!</h1>
+		`<h1>Welcome, ${safeDisplayName}!</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.`,

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,18 @@
 	"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/src/client.js

@@ -49,4 +49,4 @@ if (!isProduction) {
 	globalForPrisma.prisma = prisma;
 }
 
-export * from "./generated/prisma/client.js";
+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,8 @@
 		},
 		"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();
+	}
+}

package/templates/config/src/validate-env.js

@@ -0,0 +1,104 @@
+import { syncNextAuthUrl } from "./app-url.js";
+
+/**
+ * Environment variable validation schema
+ * Validates all required and optional environment variables on startup
+ */
+
+const envSchema = {
+	// Database
+	DATABASE_URL: {
+		required: false,
+		description: "PostgreSQL connection string",
+	},
+	POSTGRES_HOST: { required: false, description: "PostgreSQL host" },
+	POSTGRES_PORT: { required: false, description: "PostgreSQL port" },
+	POSTGRES_USER: { required: false, description: "PostgreSQL user" },
+	POSTGRES_PASSWORD: { required: false, description: "PostgreSQL password" },
+	POSTGRES_DB: { required: false, description: "PostgreSQL database name" },
+
+	// Redis
+	REDIS_URL: { required: false, description: "Redis connection string" },
+	REDIS_HOST: { required: false, description: "Redis host" },
+	REDIS_PORT: { required: false, description: "Redis port" },
+
+	// Mailhog
+	MAILHOG_SMTP_URL: { required: false, description: "Mailhog SMTP URL" },
+	MAILHOG_HOST: { required: false, description: "Mailhog host" },
+	MAILHOG_SMTP_PORT: { required: false, description: "Mailhog SMTP port" },
+	MAILHOG_UI_PORT: { required: false, description: "Mailhog UI port" },
+
+	// NextAuth
+	NEXTAUTH_SECRET: {
+		required: true,
+		description: "NextAuth secret for JWT signing",
+	},
+	NEXTAUTH_URL: {
+		required: false,
+		description: "NextAuth callback URL (derived from APP_URL if not set)",
+	},
+
+	// Application
+	APP_URL: {
+		required: false,
+		description:
+			"Canonical application URL — derives NEXTAUTH_URL and CORS origins",
+	},
+	NODE_ENV: {
+		required: false,
+		description: "Environment (development, test, production)",
+	},
+	PORT: { required: false, description: "Web server port" },
+};
+
+/**
+ * Validates environment variables against schema
+ * @throws {Error} If required environment variables are missing
+ * @returns {Object} Validated environment object
+ */
+export function validateEnv() {
+	const errors = [];
+	const validated = {};
+
+	for (const [key, config] of Object.entries(envSchema)) {
+		const value = process.env[key];
+
+		if (config.required && !value) {
+			errors.push(
+				`Missing required environment variable: ${key} (${config.description})`,
+			);
+		}
+
+		if (value) {
+			validated[key] = value;
+		}
+	}
+
+	if (errors.length > 0) {
+		const errorMessage = `Environment Validation Failed:\n${errors.join("\n")}`;
+		throw new Error(errorMessage);
+	}
+
+	// Ensure NEXTAUTH_URL is derived from APP_URL when not explicitly set
+	syncNextAuthUrl();
+
+	// Include the (possibly derived) NEXTAUTH_URL in the validated object
+	if (process.env.NEXTAUTH_URL && !validated.NEXTAUTH_URL) {
+		validated.NEXTAUTH_URL = process.env.NEXTAUTH_URL;
+	}
+
+	return validated;
+}
+
+/**
+ * Loads and validates environment variables
+ * Call this function at application startup
+ */
+export function loadEnv() {
+	try {
+		return validateEnv();
+	} catch (error) {
+		console.error(error.message);
+		process.exit(1);
+	}
+}