@techstream/quark-create-app 1.5.3 → 1.7.0

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

@@ -1,8 +1,8 @@
 {
 	"name": "@techstream/quark-worker",
 	"version": "1.0.0",
-	"type": "module",
 	"private": true,
+	"type": "module",
 	"description": "",
 	"main": "index.js",
 	"scripts": {
@@ -15,14 +15,14 @@
 	"license": "ISC",
 	"packageManager": "pnpm@10.12.1",
 	"dependencies": {
+		"@techstream/quark-config": "workspace:*",
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
-		"bullmq": "^5.64.1"
+		"bullmq": "^5.69.3"
 	},
 	"devDependencies": {
-		"@techstream/quark-config": "workspace:*",
-		"@types/node": "^24.10.1",
-		"tsx": "^4.20.6"
+		"@types/node": "^25.2.3",
+		"tsx": "^4.21.0"
 	}
 }

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

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://railway.com/railway.schema.json",
+	"build": {
+		"builder": "RAILPACK",
+		"buildCommand": "pnpm install --frozen-lockfile && pnpm db:generate",
+		"watchPatterns": ["apps/worker/**", "packages/**"]
+	},
+	"deploy": {
+		"startCommand": "node apps/worker/src/index.js",
+		"restartPolicyType": "ON_FAILURE",
+		"restartPolicyMaxRetries": 5
+	}
+}

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

@@ -4,6 +4,7 @@
  * Handles job execution, retries, and error tracking
  */
 
+import { loadEnv } from "@techstream/quark-config";
 import {
 	createLogger,
 	createQueue,
@@ -13,10 +14,14 @@ import { prisma } from "@techstream/quark-db";
 import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 import { jobHandlers } from "./handlers/index.js";
 
+// Validate environment variables (worker-scoped — skips web-only checks)
+loadEnv("worker");
+
 const logger = createLogger("worker");
 
 // Store workers for graceful shutdown
 const workers = [];
+let isShuttingDown = false;
 
 /**
  * Generic queue processor — dispatches jobs to registered handlers
@@ -113,15 +118,31 @@ async function startWorker() {
 /**
  * Graceful shutdown handler
  */
-async function shutdown() {
-	logger.info("Shutting down worker service");
+async function shutdown(signal = "unknown") {
+	if (isShuttingDown) {
+		logger.warn("Shutdown already in progress", { signal });
+		return;
+	}
+
+	isShuttingDown = true;
+	logger.info("Shutting down worker service", { signal });
 
 	try {
 		for (const worker of workers) {
 			await worker.close();
 		}
 
-		await prisma.$disconnect();
+		try {
+			await prisma.$disconnect();
+		} catch (error) {
+			if (error.message?.includes("environment variable is required")) {
+				logger.warn("Skipping Prisma disconnect due missing database env", {
+					error: error.message,
+				});
+			} else {
+				throw error;
+			}
+		}
 
 		logger.info("All workers closed");
 		process.exit(0);
@@ -134,14 +155,11 @@ async function shutdown() {
 	}
 }
 
-process.on("SIGTERM", shutdown);
-process.on("SIGINT", shutdown);
-
-startWorker();
-
-// Register shutdown handlers
-process.on("SIGTERM", shutdown);
-process.on("SIGINT", shutdown);
+process.on("SIGTERM", () => {
+	void shutdown("SIGTERM");
+});
+process.on("SIGINT", () => {
+	void shutdown("SIGINT");
+});
 
-// Start the worker service
 startWorker();

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

@@ -1,19 +1,300 @@
 import assert from "node:assert";
-import { test } from "node:test";
-
-// Mock job definitions for testing
-const mockJobDefinitions = {
-	JOB_QUEUES: { EMAIL: "email-queue" },
-	JOB_NAMES: { SEND_WELCOME_EMAIL: "send-welcome-email" },
-};
-
-test("Worker - imports job definitions correctly", async () => {
-	const { JOB_QUEUES, JOB_NAMES } = mockJobDefinitions;
-	assert.strictEqual(JOB_QUEUES.EMAIL, "email-queue");
-	assert.strictEqual(JOB_NAMES.SEND_WELCOME_EMAIL, "send-welcome-email");
+import { describe, mock, test } from "node:test";
+
+// ---------------------------------------------------------------------------
+// Helpers: lightweight fakes for Prisma, emailService, and storage
+// ---------------------------------------------------------------------------
+
+function createMockLogger() {
+	return {
+		info: mock.fn(),
+		warn: mock.fn(),
+		error: mock.fn(),
+	};
+}
+
+function makeBullJob(name, data, overrides = {}) {
+	return { id: "job-1", name, data, attemptsMade: 0, ...overrides };
+}
+
+// ---------------------------------------------------------------------------
+// handleSendWelcomeEmail
+// ---------------------------------------------------------------------------
+
+describe("handleSendWelcomeEmail", () => {
+	test("throws when userId is missing", async () => {
+		// Inline handler that mirrors the real one's validation
+		const handler = async (bullJob) => {
+			const { userId } = bullJob.data;
+			if (!userId) {
+				throw new Error("userId is required for SEND_WELCOME_EMAIL job");
+			}
+		};
+
+		await assert.rejects(() => handler(makeBullJob("send-welcome-email", {})), {
+			message: "userId is required for SEND_WELCOME_EMAIL job",
+		});
+	});
+
+	test("throws when user is not found", async () => {
+		const handler = async (bullJob) => {
+			const { userId } = bullJob.data;
+			if (!userId) throw new Error("userId is required");
+			// Simulate user not found
+			const userRecord = null;
+			if (!userRecord?.email) {
+				throw new Error(`User ${userId} not found or has no email`);
+			}
+		};
+
+		await assert.rejects(
+			() => handler(makeBullJob("send-welcome-email", { userId: "user-123" })),
+			{ message: "User user-123 not found or has no email" },
+		);
+	});
+
+	test("returns success when user exists and email sends", async () => {
+		const sendEmail = mock.fn(async () => {});
+
+		const handler = async (bullJob, _logger) => {
+			const { userId } = bullJob.data;
+			if (!userId) throw new Error("userId is required");
+
+			const userRecord = { email: "a@b.com", name: "Alice" };
+			if (!userRecord?.email) {
+				throw new Error(`User ${userId} not found or has no email`);
+			}
+
+			await sendEmail(userRecord.email, "Welcome", "<p>Hi</p>", "Hi");
+			return { success: true, userId, email: userRecord.email };
+		};
+
+		const logger = createMockLogger();
+		const result = await handler(
+			makeBullJob("send-welcome-email", { userId: "user-123" }),
+			logger,
+		);
+
+		assert.deepStrictEqual(result, {
+			success: true,
+			userId: "user-123",
+			email: "a@b.com",
+		});
+		assert.strictEqual(sendEmail.mock.callCount(), 1);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// handleSendResetPasswordEmail
+// ---------------------------------------------------------------------------
+
+describe("handleSendResetPasswordEmail", () => {
+	test("throws when userId or resetUrl is missing", async () => {
+		const handler = async (bullJob) => {
+			const { userId, resetUrl } = bullJob.data;
+			if (!userId || !resetUrl) {
+				throw new Error(
+					"userId and resetUrl are required for SEND_RESET_PASSWORD_EMAIL job",
+				);
+			}
+		};
+
+		await assert.rejects(
+			() =>
+				handler(
+					makeBullJob("send-reset-password-email", {
+						userId: "user-1",
+					}),
+				),
+			{
+				message:
+					"userId and resetUrl are required for SEND_RESET_PASSWORD_EMAIL job",
+			},
+		);
+
+		await assert.rejects(
+			() =>
+				handler(
+					makeBullJob("send-reset-password-email", {
+						resetUrl: "https://example.com/reset",
+					}),
+				),
+			{
+				message:
+					"userId and resetUrl are required for SEND_RESET_PASSWORD_EMAIL job",
+			},
+		);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// handleCleanupOrphanedFiles
+// ---------------------------------------------------------------------------
+
+describe("handleCleanupOrphanedFiles", () => {
+	test("returns deleted: 0 when no orphaned files exist", async () => {
+		const handler = async (bullJob, logger) => {
+			const retentionHours = bullJob.data?.retentionHours || 24;
+			const _cutoff = new Date(Date.now() - retentionHours * 60 * 60 * 1000);
+
+			logger.info("Starting orphaned file cleanup", { retentionHours });
+
+			// Simulate no orphaned files
+			const orphaned = [];
+			if (orphaned.length === 0) {
+				logger.info("No orphaned files to clean up");
+				return { success: true, deleted: 0 };
+			}
+		};
+
+		const logger = createMockLogger();
+		const result = await handler(
+			makeBullJob("cleanup-orphaned-files", { retentionHours: 24 }),
+			logger,
+		);
+
+		assert.deepStrictEqual(result, { success: true, deleted: 0 });
+	});
+
+	test("deletes orphaned files and reports counts", async () => {
+		const deletedKeys = [];
+		const deletedIds = [];
+
+		const handler = async (bullJob, logger) => {
+			const retentionHours = bullJob.data?.retentionHours || 24;
+			logger.info("Starting cleanup", { retentionHours });
+
+			const orphaned = [
+				{ id: "f1", storageKey: "uploads/f1.jpg" },
+				{ id: "f2", storageKey: "uploads/f2.png" },
+			];
+
+			let deleted = 0;
+			const errors = [];
+
+			for (const record of orphaned) {
+				try {
+					deletedKeys.push(record.storageKey);
+					deletedIds.push(record.id);
+					deleted++;
+				} catch (err) {
+					errors.push({ id: record.id, error: err.message });
+				}
+			}
+
+			return { success: true, deleted, total: orphaned.length, errors };
+		};
+
+		const logger = createMockLogger();
+		const result = await handler(
+			makeBullJob("cleanup-orphaned-files", { retentionHours: 12 }),
+			logger,
+		);
+
+		assert.strictEqual(result.deleted, 2);
+		assert.strictEqual(result.total, 2);
+		assert.deepStrictEqual(result.errors, []);
+		assert.deepStrictEqual(deletedKeys, ["uploads/f1.jpg", "uploads/f2.png"]);
+	});
+
+	test("continues on individual file delete failure", async () => {
+		const handler = async (_bullJob, logger) => {
+			const orphaned = [
+				{ id: "f1", storageKey: "uploads/f1.jpg" },
+				{ id: "f2", storageKey: "uploads/f2.png" },
+			];
+
+			let deleted = 0;
+			const errors = [];
+
+			for (const record of orphaned) {
+				try {
+					if (record.id === "f1") {
+						throw new Error("S3 timeout");
+					}
+					deleted++;
+				} catch (err) {
+					errors.push({ id: record.id, error: err.message });
+					logger.warn(`Failed to delete file ${record.id}: ${err.message}`);
+				}
+			}
+
+			return { success: true, deleted, total: orphaned.length, errors };
+		};
+
+		const logger = createMockLogger();
+		const result = await handler(
+			makeBullJob("cleanup-orphaned-files", {}),
+			logger,
+		);
+
+		assert.strictEqual(result.deleted, 1);
+		assert.strictEqual(result.errors.length, 1);
+		assert.strictEqual(result.errors[0].id, "f1");
+		assert.strictEqual(result.errors[0].error, "S3 timeout");
+		assert.strictEqual(logger.warn.mock.callCount(), 1);
+	});
+
+	test("uses default 24h retention when not specified", async () => {
+		let capturedRetention;
+
+		const handler = async (bullJob) => {
+			capturedRetention = bullJob.data?.retentionHours || 24;
+			return { success: true, deleted: 0 };
+		};
+
+		await handler(makeBullJob("cleanup-orphaned-files", {}));
+		assert.strictEqual(capturedRetention, 24);
+	});
 });
 
-test("Worker - Worker can be instantiated", async () => {
-	// Basic smoke test - bullmq Worker is available
-	assert.ok(true, "Worker should be instantiable");
+// ---------------------------------------------------------------------------
+// Handler registry
+// ---------------------------------------------------------------------------
+
+describe("jobHandlers registry", () => {
+	test("maps all expected job names to functions", () => {
+		const JOB_NAMES = {
+			SEND_WELCOME_EMAIL: "send-welcome-email",
+			SEND_RESET_PASSWORD_EMAIL: "send-reset-password-email",
+			CLEANUP_ORPHANED_FILES: "cleanup-orphaned-files",
+		};
+
+		// Simulate the registry
+		const jobHandlers = {
+			[JOB_NAMES.SEND_WELCOME_EMAIL]: () => {},
+			[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: () => {},
+			[JOB_NAMES.CLEANUP_ORPHANED_FILES]: () => {},
+		};
+
+		assert.strictEqual(
+			Object.keys(jobHandlers).length,
+			3,
+			"Should have exactly 3 handlers",
+		);
+
+		for (const name of Object.values(JOB_NAMES)) {
+			assert.strictEqual(
+				typeof jobHandlers[name],
+				"function",
+				`Handler for "${name}" should be a function`,
+			);
+		}
+	});
+
+	test("throws for unregistered job name", async () => {
+		const jobHandlers = {};
+
+		const dispatch = async (bullJob) => {
+			const handler = jobHandlers[bullJob.name];
+			if (!handler) {
+				throw new Error(`No handler registered for job: ${bullJob.name}`);
+			}
+			return handler(bullJob);
+		};
+
+		await assert.rejects(() => dispatch(makeBullJob("unknown-job", {})), {
+			message: "No handler registered for job: unknown-job",
+		});
+	});
 });

package/templates/base-project/biome.json

@@ -0,0 +1,44 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.0/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": ["**", "!**/.next", "!**/dist", "!**/.turbo", "!**/coverage"]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"css": {
+		"parser": {
+			"cssModules": true,
+			"tailwindDirectives": true
+		},
+		"linter": {
+			"enabled": true
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}

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

@@ -2,13 +2,14 @@ services:
   # --- 1. PostgreSQL Database ---
   postgres:
     image: postgres:16-alpine
+    container_name: postgres
     restart: always
     ports:
       - "${POSTGRES_PORT:-5432}:5432"
     environment:
-      POSTGRES_USER: ${POSTGRES_USER}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER:-quark_user}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-CHANGE_ME_IN_ENV_FILE}
+      POSTGRES_DB: ${POSTGRES_DB:-quark_dev}
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
@@ -20,6 +21,7 @@ services:
   # --- 2. Redis Cache & Job Queue ---
   redis:
     image: redis:7-alpine
+    container_name: redis
     restart: always
     ports:
       - "${REDIS_PORT:-6379}:6379"
@@ -35,6 +37,7 @@ services:
   # --- 3. Mailpit (Local SMTP Server) ---
   mailpit:
     image: ghcr.io/axllent/mailpit
+    container_name: mailpit
     restart: always
     ports:
       # SMTP port (used by application to send mail)
@@ -49,4 +52,4 @@ services:
 
 volumes:
   postgres_data:
-  redis_data:
+  redis_data:

package/templates/base-project/package.json

@@ -36,7 +36,7 @@
 		}
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.3.13",
+		"@biomejs/biome": "^2.4.0",
 		"@types/node": "^24.10.9",
 		"dotenv-cli": "^11.0.0",
 		"tsx": "^4.21.0",

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

@@ -21,6 +21,7 @@
 	"license": "ISC",
 	"packageManager": "pnpm@10.12.1",
 	"devDependencies": {
+		"@faker-js/faker": "^10.3.0",
 		"@techstream/quark-config": "workspace:*",
 		"bcryptjs": "^3.0.3",
 		"prisma": "^7.4.0"
@@ -28,7 +29,6 @@
 	"dependencies": {
 		"@prisma/adapter-pg": "^7.4.0",
 		"@prisma/client": "^7.4.0",
-		"dotenv": "^17.2.4",
 		"pg": "^8.18.0",
 		"zod": "^4.3.6"
 	}

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

@@ -24,7 +24,6 @@ model User {
   createdAt     DateTime  @default(now())
   updatedAt     DateTime  @updatedAt
 
-  posts         Post[]
   accounts      Account[]
   sessions      Session[]
   auditLogs     AuditLog[]
@@ -34,21 +33,6 @@ model User {
   @@index([createdAt])
 }
 
-model Post {
-  id        String   @id @default(cuid())
-  title     String
-  content   String?  @db.Text
-  published Boolean  @default(false)
-  authorId  String
-  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  @@index([authorId])
-  @@index([published])
-  @@index([createdAt])
-}
-
 // NextAuth Models
 model Account {
   id                 String   @id @default(cuid())
@@ -128,7 +112,7 @@ enum JobStatus {
   CANCELLED
 }
 
-// File Model
+// File Upload Model
 model File {
   id              String   @id @default(cuid())
   filename        String

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

@@ -1,18 +1,16 @@
 import { resolve } from "node:path";
-import { config } from "dotenv";
 import { defineConfig } from "prisma/config";
+import { getConnectionString } from "./src/connection.js";
 
 // Load .env from monorepo root (needed for standalone commands like db:push, db:seed)
-config({ path: resolve(__dirname, "../../.env"), quiet: true });
+try {
+	process.loadEnvFile(resolve(__dirname, "../../.env"));
+} catch {}
 
-// Construct DATABASE_URL from individual env vars - single source of truth
-const user = process.env.POSTGRES_USER || "quark_user";
-const password = process.env.POSTGRES_PASSWORD || "quark_password";
-const host = process.env.POSTGRES_HOST || "localhost";
-const port = process.env.POSTGRES_PORT || "5432";
-const db = process.env.POSTGRES_DB || "quark_dev";
-
-const databaseUrl = `postgresql://${user}:${password}@${host}:${port}/${db}?schema=public`;
+// 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",