@techstream/quark-create-app 1.3.0 → 1.4.0

package/package.json

@@ -1,35 +1,35 @@
 {
-	"name": "@techstream/quark-create-app",
-	"version": "1.3.0",
-	"type": "module",
-	"bin": {
-		"quark-create-app": "src/index.js",
-		"create-quark-app": "src/index.js"
-	},
-	"files": [
-		"src",
-		"templates",
-		"README.md"
-	],
-	"scripts": {
-		"test": "node test-cli.js",
-		"test:e2e": "node test-e2e.js",
-		"test:integration": "node test-integration.js",
-		"test:all": "node test-all.js"
-	},
-	"dependencies": {
-		"chalk": "^5.6.2",
-		"commander": "^12.1.0",
-		"execa": "^9.6.1",
-		"fs-extra": "^11.3.3",
-		"prompts": "^2.4.2"
-	},
-	"publishConfig": {
-		"registry": "https://registry.npmjs.org",
-		"access": "public"
-	},
-	"engines": {
-		"node": ">=22"
-	},
-	"license": "ISC"
-}
+  "name": "@techstream/quark-create-app",
+  "version": "1.4.0",
+  "type": "module",
+  "bin": {
+    "quark-create-app": "src/index.js",
+    "create-quark-app": "src/index.js"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "execa": "^9.6.1",
+    "fs-extra": "^11.3.3",
+    "prompts": "^2.4.2"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "ISC",
+  "scripts": {
+    "test": "node test-cli.js",
+    "test:e2e": "node test-e2e.js",
+    "test:integration": "node test-integration.js",
+    "test:all": "node test-all.js"
+  }
+}

package/src/index.js

@@ -110,7 +110,10 @@ async function copyTemplate(templateName, targetDir, variables = {}) {
 			let content = await fs.readFile(packageJsonPath, "utf-8");
 
 			for (const [key, value] of Object.entries(variables)) {
-				const pattern = new RegExp(key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g");
+				const pattern = new RegExp(
+					key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+					"g",
+				);
 				content = content.replace(pattern, value);
 			}
 
@@ -175,7 +178,11 @@ function replaceDepsScope(deps, scope, selectedPackages) {
 			const packageName = key.replace("@techstream/quark-", "");
 			delete deps[key];
 			// Only keep the dep if the package was selected (or is always required)
-			if (packageName === "db" || packageName === "config" || selectedPackages.includes(packageName)) {
+			if (
+				packageName === "db" ||
+				packageName === "config" ||
+				selectedPackages.includes(packageName)
+			) {
 				deps[`@${scope}/${packageName}`] = value;
 			}
 		}
@@ -194,7 +201,11 @@ async function replaceImportsInSourceFiles(dir, scope) {
 	for (const entry of entries) {
 		const fullPath = path.join(dir, entry.name);
 
-		if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".next") {
+		if (
+			entry.isDirectory() &&
+			entry.name !== "node_modules" &&
+			entry.name !== ".next"
+		) {
 			await replaceImportsInSourceFiles(fullPath, scope);
 		} else if (entry.isFile() && /\.(js|ts|jsx|tsx|mjs)$/.test(entry.name)) {
 			let content = await fs.readFile(fullPath, "utf-8");
@@ -245,7 +256,9 @@ program
 	.argument("<project-name>", "Name of the project to create")
 	.action(async (projectName) => {
 		console.log(
-			chalk.blue.bold(`\n\uD83D\uDE80 Creating your new Quark project: ${projectName}\n`),
+			chalk.blue.bold(
+				`\n\uD83D\uDE80 Creating your new Quark project: ${projectName}\n`,
+			),
 		);
 
 		const targetDir = validateProjectName(projectName);
@@ -383,16 +396,13 @@ program
 				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/")) {
+					if (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(
-						pkgPath,
-						`${JSON.stringify(pkg, null, 2)}\n`,
-					);
+					await fs.writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 				}
 			}
 
@@ -481,7 +491,8 @@ WORKER_CONCURRENCY=5
 			const webPort = await findAvailablePort(3000);
 
 			const portChanges = [];
-			if (postgresPort !== 5432) portChanges.push(`PostgreSQL: ${postgresPort}`);
+			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}`);
@@ -566,9 +577,7 @@ WORKER_CONCURRENCY=5
 				console.log(chalk.green(`\n    ✓ Dependencies installed`));
 			} catch (installError) {
 				console.warn(
-					chalk.yellow(
-						`\n    ⚠️  pnpm install failed: ${installError.message}`,
-					),
+					chalk.yellow(`\n    ⚠️  pnpm install failed: ${installError.message}`),
 				);
 				console.warn(
 					chalk.yellow(
@@ -592,9 +601,7 @@ WORKER_CONCURRENCY=5
 					),
 				);
 				console.warn(
-					chalk.yellow(
-						`    Run 'pnpm --filter db db:generate' manually.`,
-					),
+					chalk.yellow(`    Run 'pnpm --filter db db:generate' manually.`),
 				);
 			}
 

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

@@ -1,5 +1,10 @@
-import { hashPassword, validateBody } from "@techstream/quark-core";
+import {
+	createQueue,
+	hashPassword,
+	validateBody,
+} from "@techstream/quark-core";
 import { user, userRegisterSchema } from "@techstream/quark-db";
+import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 import { NextResponse } from "next/server";
 import { handleError } from "../../error-handler";
 
@@ -29,6 +34,17 @@ export async function POST(request) {
 			password: hashedPassword,
 		});
 
+		// Enqueue welcome email (fire-and-forget)
+		try {
+			const emailQueue = createQueue(JOB_QUEUES.EMAIL);
+			await emailQueue.add(JOB_NAMES.SEND_WELCOME_EMAIL, {
+				userId: newUser.id,
+			});
+		} catch (emailError) {
+			// Don't fail registration if email enqueue fails
+			console.error("Failed to enqueue welcome email:", emailError);
+		}
+
 		// Don't return the password
 		const { password: _, ...safeUser } = newUser;
 

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

@@ -29,7 +29,10 @@ export async function GET() {
 			status: result.status === "ok" ? 200 : 503,
 		});
 	} catch (error) {
-		logger.error("Health check failed", { error: error.message, stack: error.stack });
+		logger.error("Health check failed", {
+			error: error.message,
+			stack: error.stack,
+		});
 		return NextResponse.json(
 			{
 				status: "error",

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

@@ -1,4 +1,8 @@
-import { UnauthorizedError, validateBody, withCsrfProtection } 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";

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

@@ -8,9 +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 { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 
 const logger = createLogger("worker");
 
@@ -20,18 +22,6 @@ 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
@@ -48,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 },
@@ -58,16 +47,60 @@ async function handleSendWelcomeEmail(bullJob) {
 		throw new Error(`User ${userId} not found or has no email`);
 	}
 
-	const displayName = userRecord.name || "there";
-	const safeDisplayName = escapeHtml(displayName);
+	const template = welcomeEmail({
+		name: userRecord.name,
+		loginUrl: process.env.APP_URL
+			? `${process.env.APP_URL}/api/auth/signin`
+			: undefined,
+	});
 
 	await emailService.sendEmail(
 		userRecord.email,
-		"Welcome to Quark!",
-		`<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.`,
+		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,
+		template.subject,
+		template.html,
+		template.text,
 	);
 
 	return { success: true, userId, email: userRecord.email };
@@ -79,6 +112,7 @@ async function handleSendWelcomeEmail(bullJob) {
  */
 const jobHandlers = {
 	[JOB_NAMES.SEND_WELCOME_EMAIL]: handleSendWelcomeEmail,
+	[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: handleSendResetPasswordEmail,
 };
 
 /**
@@ -113,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(
@@ -127,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);
 	}
 }
@@ -150,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/package.json

@@ -18,7 +18,13 @@
 	"license": "ISC",
 	"packageManager": "pnpm@10.12.1",
 	"pnpm": {
-		"onlyBuiltDependencies": ["@prisma/engines", "esbuild", "msgpackr-extract", "prisma", "sharp"],
+		"onlyBuiltDependencies": [
+			"@prisma/engines",
+			"esbuild",
+			"msgpackr-extract",
+			"prisma",
+			"sharp"
+		],
 		"peerDependencyRules": {
 			"allowedVersions": {
 				"nodemailer": "*"

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;
 }
 
+/**
+ * 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/turbo.json

@@ -20,7 +20,22 @@
 		"dev": {
 			"cache": false,
 			"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"]
+			"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/base-project/packages/db/src/generated/prisma/browser.ts

@@ -1,53 +0,0 @@
-/* !!! This is code generated by Prisma. Do not edit directly. !!! */
-/* eslint-disable */
-// biome-ignore-all lint: generated file
-// @ts-nocheck
-/*
- * This file should be your main import to use Prisma-related types and utilities in a browser.
- * Use it to get access to models, enums, and input types.
- *
- * This file does not contain a `PrismaClient` class, nor several other helpers that are intended as server-side only.
- * See `client.ts` for the standard, server-side entry point.
- *
- * 🟢 You can import this file directly.
- */
-
-import * as Prisma from "./internal/prismaNamespaceBrowser.ts";
-export { Prisma };
-export * as $Enums from "./enums.ts";
-export * from "./enums.ts";
-/**
- * Model User
- *
- */
-export type User = Prisma.UserModel;
-/**
- * Model Post
- *
- */
-export type Post = Prisma.PostModel;
-/**
- * Model Account
- *
- */
-export type Account = Prisma.AccountModel;
-/**
- * Model Session
- *
- */
-export type Session = Prisma.SessionModel;
-/**
- * Model VerificationToken
- *
- */
-export type VerificationToken = Prisma.VerificationTokenModel;
-/**
- * Model Job
- *
- */
-export type Job = Prisma.JobModel;
-/**
- * Model AuditLog
- *
- */
-export type AuditLog = Prisma.AuditLogModel;

package/templates/base-project/packages/db/src/generated/prisma/client.ts

@@ -1,82 +0,0 @@
-/* !!! This is code generated by Prisma. Do not edit directly. !!! */
-/* eslint-disable */
-// biome-ignore-all lint: generated file
-// @ts-nocheck
-/*
- * This file should be your main import to use Prisma. Through it you get access to all the models, enums, and input types.
- * If you're looking for something you can import in the client-side of your application, please refer to the `browser.ts` file instead.
- *
- * 🟢 You can import this file directly.
- */
-
-import * as path from "node:path";
-import * as process from "node:process";
-import { fileURLToPath } from "node:url";
-
-globalThis["__dirname"] = path.dirname(fileURLToPath(import.meta.url));
-
-import * as runtime from "@prisma/client/runtime/client";
-import * as $Enums from "./enums.ts";
-import * as $Class from "./internal/class.ts";
-import * as Prisma from "./internal/prismaNamespace.ts";
-
-export * as $Enums from "./enums.ts";
-export * from "./enums.ts";
-/**
- * ## Prisma Client
- *
- * Type-safe database client for TypeScript
- * @example
- * ```
- * const prisma = new PrismaClient()
- * // Fetch zero or more Users
- * const users = await prisma.user.findMany()
- * ```
- *
- * Read more in our [docs](https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-client).
- */
-export const PrismaClient = $Class.getPrismaClientClass();
-export type PrismaClient<
-	LogOpts extends Prisma.LogLevel = never,
-	OmitOpts extends
-		Prisma.PrismaClientOptions["omit"] = Prisma.PrismaClientOptions["omit"],
-	ExtArgs extends
-		runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs,
-> = $Class.PrismaClient<LogOpts, OmitOpts, ExtArgs>;
-export { Prisma };
-
-/**
- * Model User
- *
- */
-export type User = Prisma.UserModel;
-/**
- * Model Post
- *
- */
-export type Post = Prisma.PostModel;
-/**
- * Model Account
- *
- */
-export type Account = Prisma.AccountModel;
-/**
- * Model Session
- *
- */
-export type Session = Prisma.SessionModel;
-/**
- * Model VerificationToken
- *
- */
-export type VerificationToken = Prisma.VerificationTokenModel;
-/**
- * Model Job
- *
- */
-export type Job = Prisma.JobModel;
-/**
- * Model AuditLog
- *
- */
-export type AuditLog = Prisma.AuditLogModel;