@techstream/quark-create-app 1.7.0 → 1.9.0

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

@@ -4,8 +4,8 @@
  * Handles job execution, retries, and error tracking
  */
 
-import { loadEnv } from "@techstream/quark-config";
 import {
+	checkQueueHealth,
 	createLogger,
 	createQueue,
 	createWorker,
@@ -14,15 +14,176 @@ 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;
 
+// ============================================================================
+// RESILIENCE UTILITIES
+// ============================================================================
+
+/**
+ * Detects if error is a connection/network error
+ * @param {Error} error
+ * @returns {boolean}
+ */
+export function isConnectionError(error) {
+	if (!error) return false;
+	const message = (error.message || "") + (error.code || "");
+	const connectionErrors = [
+		"ECONNREFUSED", // Connection refused
+		"ECONNRESET", // Connection reset
+		"ENOTFOUND", // DNS lookup failure
+		"ETIMEDOUT", // Connection timeout
+		"EHOSTUNREACH", // Host unreachable
+		"ENETUNREACH", // Network unreachable
+		"Error: Redis connection failed", // Generic redis failure
+		"Ready status is false", // BullMQ readiness
+	];
+	return connectionErrors.some((err) => message.includes(err));
+}
+
+/**
+ * Creates a throttled error logger
+ * Suppresses duplicate errors within a time window
+ * @param {Object} logger
+ * @param {number} windowMs - Throttle window in milliseconds
+ * @returns {Function} throttle function
+ */
+export function throttledError(logger, windowMs = 5000) {
+	let lastErrorTime = 0;
+	let lastErrorMsg = "";
+
+	return (error) => {
+		const now = Date.now();
+		const msg = error.message || String(error);
+
+		// Log if new error type or window expired
+		if (msg !== lastErrorMsg || now - lastErrorTime > windowMs) {
+			logger.error(`Connection error (will retry)`, {
+				error: msg,
+				code: error.code,
+				timestamp: new Date().toISOString(),
+			});
+			lastErrorTime = now;
+			lastErrorMsg = msg;
+		}
+	};
+}
+
+/**
+ * Waits for Redis to be ready with retries
+ * @param {Function} healthCheck - Async function that returns boolean or throws
+ * @param {Object} config
+ * @param {number} config.maxRetries - Maximum retry attempts
+ * @param {number} config.intervalMs - Delay between retries
+ * @returns {Promise<boolean>}
+ */
+export async function waitForRedis(
+	healthCheck = checkQueueHealth,
+	config = {},
+) {
+	const {
+		maxRetries = parseInt(process.env.WORKER_HEALTH_RETRIES || "10", 10),
+		intervalMs = parseInt(process.env.WORKER_HEALTH_INTERVAL_MS || "1000", 10),
+	} = config;
+
+	const reportThrottledError = throttledError(logger, 3000);
+	let lastError;
+
+	for (let attempt = 1; attempt <= maxRetries; attempt++) {
+		try {
+			const isReady = await healthCheck();
+			if (isReady) {
+				logger.info(
+					`Redis health check passed (attempt ${attempt}/${maxRetries})`,
+				);
+				return true;
+			}
+		} catch (error) {
+			lastError = error;
+			if (isConnectionError(error)) {
+				reportThrottledError(error);
+				if (attempt < maxRetries) {
+					// Wait before retrying
+					await new Promise((resolve) => setTimeout(resolve, intervalMs));
+				}
+			} else {
+				// Non-connection error; don't retry
+				logger.error("Health check failed with non-network error", {
+					error: error.message,
+				});
+				throw error;
+			}
+		}
+	}
+
+	// All retries exhausted
+	logger.error("Redis health check failed after all retries", {
+		attempts: maxRetries,
+		lastError: lastError?.message,
+	});
+	throw new Error(
+		`Failed to connect to Redis after ${maxRetries} attempts: ${lastError?.message}`,
+	);
+}
+
+// ============================================================================
+// PREFLIGHT MODE
+// ============================================================================
+
+/**
+ * Runs pre-flight health checks and exits
+ * Used for deployment readiness probes
+ */
+async function preflight() {
+	// Load and validate environment variables
+	const { loadEnv } = await import("@techstream/quark-config");
+	loadEnv("worker");
+
+	logger.info("Running preflight health checks");
+
+	try {
+		// Check Redis
+		logger.info("Checking Redis connectivity...");
+		const redisReady = await checkQueueHealth();
+		if (!redisReady) {
+			throw new Error("Redis health check returned false");
+		}
+		logger.info("✓ Redis connected");
+
+		// Check Database
+		logger.info("Checking database connectivity...");
+		await prisma.$queryRaw`SELECT 1`;
+		logger.info("✓ Database connected");
+
+		// Validate handlers are registered
+		logger.info("Checking job handler registration...");
+		let handlerCount = 0;
+		for (const queueName of Object.values(JOB_QUEUES)) {
+			const queue = createQueue(queueName);
+			for (const jobName of Object.values(JOB_NAMES)) {
+				if (jobHandlers[jobName]) {
+					handlerCount++;
+				}
+			}
+			await queue.close();
+		}
+		logger.info(`✓ ${handlerCount} job handlers registered`);
+
+		logger.info("✓ All preflight checks passed");
+		process.exit(0);
+	} catch (error) {
+		logger.error("Preflight check failed", {
+			error: error.message,
+			stack: error.stack,
+		});
+		process.exit(1);
+	}
+}
+
 /**
  * Generic queue processor — dispatches jobs to registered handlers
  * @param {string} queueName
@@ -86,9 +247,17 @@ function createQueueWorker(queueName) {
  * Start the worker service
  */
 async function startWorker() {
+	// Load and validate environment variables
+	const { loadEnv } = await import("@techstream/quark-config");
+	loadEnv("worker");
+
 	logger.info("Starting Quark Worker Service");
 
 	try {
+		// Pre-flight: Wait for Redis with health checks and retries
+		logger.info("Performing health checks...");
+		await waitForRedis();
+
 		// Register a worker for each queue
 		for (const queueName of Object.values(JOB_QUEUES)) {
 			createQueueWorker(queueName);
@@ -162,4 +331,20 @@ process.on("SIGINT", () => {
 	void shutdown("SIGINT");
 });
 
-startWorker();
+// ============================================================================
+// ENTRY POINT
+// ============================================================================
+
+// Only start the worker if this file is being run directly
+// Convert file:// URL to path for comparison
+const currentFile = new URL(import.meta.url).pathname;
+const mainModule = process.argv[1];
+const isMainModule = currentFile === mainModule;
+
+if (isMainModule) {
+	if (process.argv.includes("--preflight")) {
+		void preflight();
+	} else {
+		void startWorker();
+	}
+}

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

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { describe, mock, test } from "node:test";
+import { isConnectionError, throttledError, waitForRedis } from "./index.js";
 
 // ---------------------------------------------------------------------------
 // Helpers: lightweight fakes for Prisma, emailService, and storage
@@ -298,3 +299,280 @@ describe("jobHandlers registry", () => {
 		});
 	});
 });
+
+// ---------------------------------------------------------------------------
+// Resilience Utilities: isConnectionError
+// ---------------------------------------------------------------------------
+
+describe("isConnectionError", () => {
+	test("detects ECONNREFUSED (connection refused)", () => {
+		const error = new Error("connect ECONNREFUSED 127.0.0.1:6379");
+		assert.strictEqual(isConnectionError(error), true);
+	});
+
+	test("detects ECONNRESET (connection reset)", () => {
+		const error = new Error("read ECONNRESET");
+		assert.strictEqual(isConnectionError(error), true);
+	});
+
+	test("detects ENOTFOUND (DNS lookup failure)", () => {
+		const error = new Error("getaddrinfo ENOTFOUND redis.example.com");
+		assert.strictEqual(isConnectionError(error), true);
+	});
+
+	test("detects ETIMEDOUT (connection timeout)", () => {
+		const error = new Error("connect ETIMEDOUT");
+		assert.strictEqual(isConnectionError(error), true);
+	});
+
+	test("detects EHOSTUNREACH (host unreachable)", () => {
+		const error = new Error("EHOSTUNREACH 10.0.0.1");
+		assert.strictEqual(isConnectionError(error), true);
+	});
+
+	test("detects ENETUNREACH (network unreachable)", () => {
+		const error = new Error("ENETUNREACH 10.0.0.1");
+		assert.strictEqual(isConnectionError(error), true);
+	});
+
+	test("returns false for non-connection errors", () => {
+		const error = new Error("Invalid queue configuration");
+		assert.strictEqual(isConnectionError(error), false);
+	});
+
+	test("returns false for null or undefined", () => {
+		assert.strictEqual(isConnectionError(null), false);
+		assert.strictEqual(isConnectionError(undefined), false);
+	});
+
+	test("handles error objects with code property", () => {
+		const error = { code: "ECONNREFUSED", message: "refused" };
+		assert.strictEqual(isConnectionError(error), true);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Resilience Utilities: throttledError
+// ---------------------------------------------------------------------------
+
+describe("throttledError", () => {
+	test("logs first error immediately", () => {
+		const logger = createMockLogger();
+		const throttle = throttledError(logger, 100);
+
+		throttle(new Error("Redis unavailable"));
+
+		assert.strictEqual(logger.error.mock.callCount(), 1);
+		const call = logger.error.mock.calls[0];
+		assert.ok(call.arguments[0].includes("Connection error"));
+	});
+
+	test("suppresses duplicate errors within window", () => {
+		const logger = createMockLogger();
+		const throttle = throttledError(logger, 100);
+
+		throttle(new Error("Redis unavailable"));
+		assert.strictEqual(logger.error.mock.callCount(), 1);
+
+		// Same error within window — should be suppressed
+		throttle(new Error("Redis unavailable"));
+		assert.strictEqual(logger.error.mock.callCount(), 1);
+
+		// Different error within window — should log
+		throttle(new Error("Redis timeout"));
+		assert.strictEqual(logger.error.mock.callCount(), 2);
+	});
+
+	test("logs error again after window expires", async () => {
+		const logger = createMockLogger();
+		const throttle = throttledError(logger, 50); // 50ms window
+
+		throttle(new Error("Redis unavailable"));
+		assert.strictEqual(logger.error.mock.callCount(), 1);
+
+		// Same error within window — suppressed
+		throttle(new Error("Redis unavailable"));
+		assert.strictEqual(logger.error.mock.callCount(), 1);
+
+		// Wait for window to expire
+		await new Promise((resolve) => setTimeout(resolve, 60));
+
+		// Same error after window — logged again
+		throttle(new Error("Redis unavailable"));
+		assert.strictEqual(logger.error.mock.callCount(), 2);
+	});
+
+	test("includes error details in log", () => {
+		const logger = createMockLogger();
+		const throttle = throttledError(logger, 100);
+
+		const error = new Error("ECONNREFUSED");
+		error.code = "ECONNREFUSED";
+		throttle(error);
+
+		const call = logger.error.mock.calls[0];
+		const args = call.arguments;
+		assert.strictEqual(args[0], "Connection error (will retry)");
+		assert.ok(args[1].error.includes("ECONNREFUSED"));
+		assert.ok(args[1].timestamp); // Should have timestamp
+	});
+
+	test("uses default 5 second window if not specified", async () => {
+		const logger = createMockLogger();
+		const throttle = throttledError(logger); // No window specified
+
+		throttle(new Error("Test"));
+		assert.strictEqual(logger.error.mock.callCount(), 1);
+
+		throttle(new Error("Test"));
+		assert.strictEqual(logger.error.mock.callCount(), 1); // Suppressed
+
+		// 5 second default window hasn't expired
+		throttle(new Error("Test"));
+		assert.strictEqual(logger.error.mock.callCount(), 1); // Still suppressed
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Resilience Utilities: waitForRedis
+// ---------------------------------------------------------------------------
+
+describe("waitForRedis", () => {
+	test("returns true when health check succeeds immediately", async () => {
+		const healthCheck = mock.fn(async () => true);
+		const result = await waitForRedis(healthCheck, {
+			maxRetries: 3,
+			intervalMs: 10,
+		});
+
+		assert.strictEqual(result, true);
+		assert.strictEqual(healthCheck.mock.callCount(), 1);
+	});
+
+	test("retries and succeeds on second attempt", async () => {
+		let attempts = 0;
+		const healthCheck = mock.fn(async () => {
+			attempts++;
+			if (attempts < 2) {
+				throw new Error("ECONNREFUSED 127.0.0.1:6379");
+			}
+			return true;
+		});
+
+		const result = await waitForRedis(healthCheck, {
+			maxRetries: 3,
+			intervalMs: 10,
+		});
+
+		assert.strictEqual(result, true);
+		assert.strictEqual(healthCheck.mock.callCount(), 2);
+	});
+
+	test("fails after max retries exhausted", async () => {
+		const healthCheck = mock.fn(async () => {
+			throw new Error("ECONNREFUSED");
+		});
+
+		await assert.rejects(
+			() =>
+				waitForRedis(healthCheck, {
+					maxRetries: 2,
+					intervalMs: 10,
+				}),
+			{ message: /Failed to connect to Redis after 2 attempts/ },
+		);
+
+		assert.strictEqual(healthCheck.mock.callCount(), 2);
+	});
+
+	test("stops retrying on non-connection errors", async () => {
+		const healthCheck = mock.fn(async () => {
+			throw new Error("Invalid configuration");
+		});
+
+		await assert.rejects(
+			() =>
+				waitForRedis(healthCheck, {
+					maxRetries: 5,
+					intervalMs: 10,
+				}),
+			{ message: "Invalid configuration" },
+		);
+
+		// Should fail immediately, not retry 5 times
+		assert.strictEqual(healthCheck.mock.callCount(), 1);
+	});
+
+	test("respects maxRetries from config", async () => {
+		const healthCheck = mock.fn(async () => {
+			throw new Error("ETIMEDOUT");
+		});
+
+		await assert.rejects(
+			() =>
+				waitForRedis(healthCheck, {
+					maxRetries: 4,
+					intervalMs: 10,
+				}),
+			/Failed to connect to Redis after 4 attempts/,
+		);
+
+		assert.strictEqual(healthCheck.mock.callCount(), 4);
+	});
+
+	test("respects intervalMs delay between retries", async () => {
+		let attempts = 0;
+		const startTime = Date.now();
+		const healthCheck = mock.fn(async () => {
+			attempts++;
+			if (attempts < 3) {
+				throw new Error("ECONNREFUSED");
+			}
+			return true;
+		});
+
+		const result = await waitForRedis(healthCheck, {
+			maxRetries: 3,
+			intervalMs: 30,
+		});
+
+		const duration = Date.now() - startTime;
+
+		assert.strictEqual(result, true);
+		// Should have ~60ms delay (2 retries × 30ms)
+		// Allow some variance for test execution
+		assert.ok(
+			duration >= 50,
+			`Expected at least 50ms delay, got ${duration}ms`,
+		);
+	});
+
+	test("reads environment variables for config defaults", async () => {
+		// Save original env
+		const originalRetries = process.env.WORKER_HEALTH_RETRIES;
+		const originalInterval = process.env.WORKER_HEALTH_INTERVAL_MS;
+
+		try {
+			process.env.WORKER_HEALTH_RETRIES = "2";
+			process.env.WORKER_HEALTH_INTERVAL_MS = "20";
+
+			let _attempts = 0;
+			const healthCheck = mock.fn(async () => {
+				_attempts++;
+				throw new Error("ECONNREFUSED");
+			});
+
+			// Call without explicit config — should use env defaults
+			await assert.rejects(
+				() => waitForRedis(healthCheck),
+				/Failed to connect to Redis after 2 attempts/,
+			);
+
+			assert.strictEqual(healthCheck.mock.callCount(), 2);
+		} finally {
+			// Restore env
+			process.env.WORKER_HEALTH_RETRIES = originalRetries;
+			process.env.WORKER_HEALTH_INTERVAL_MS = originalInterval;
+		}
+	});
+});

package/templates/base-project/package.json

@@ -15,7 +15,18 @@
 		"db:migrate": "turbo run db:migrate",
 		"db:push": "turbo run db:push",
 		"db:seed": "turbo run db:seed",
-		"db:studio": "turbo run db:studio"
+		"db:studio": "turbo run db:studio",
+		"prepare": "simple-git-hooks"
+	},
+	"simple-git-hooks": {
+		"pre-commit": "pnpm nano-staged",
+		"pre-push": "pnpm test"
+	},
+	"nano-staged": {
+		"**/*.{js,mjs,ts,tsx,json,css}": [
+			"biome format --write",
+			"biome check --write"
+		]
 	},
 	"keywords": [],
 	"author": "",
@@ -39,6 +50,8 @@
 		"@biomejs/biome": "^2.4.0",
 		"@types/node": "^24.10.9",
 		"dotenv-cli": "^11.0.0",
+		"nano-staged": "^0.9.0",
+		"simple-git-hooks": "^2.13.1",
 		"tsx": "^4.21.0",
 		"turbo": "^2.8.1"
 	}

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

@@ -13,9 +13,6 @@
 		"db:seed": "prisma db seed",
 		"db:studio": "prisma studio"
 	},
-	"prisma": {
-		"seed": "node scripts/seed.js"
-	},
 	"keywords": [],
 	"author": "",
 	"license": "ISC",
@@ -24,12 +21,12 @@
 		"@faker-js/faker": "^10.3.0",
 		"@techstream/quark-config": "workspace:*",
 		"bcryptjs": "^3.0.3",
-		"prisma": "^7.4.0"
+		"prisma": "^7.4.2"
 	},
 	"dependencies": {
-		"@prisma/adapter-pg": "^7.4.0",
-		"@prisma/client": "^7.4.0",
-		"pg": "^8.18.0",
+		"@prisma/adapter-pg": "^7.4.2",
+		"@prisma/client": "^7.4.2",
+		"pg": "^8.20.0",
 		"zod": "^4.3.6"
 	}
 }

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

@@ -0,0 +1,119 @@
+import crypto from "node:crypto";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { getConnectionString } from "../src/connection.js";
+import { PrismaClient } from "../src/generated/prisma/client.ts";
+
+/**
+ * Deterministic hash for dev seed users only.
+ * The app uses bcrypt for real user passwords — do not use this elsewhere.
+ */
+function devHash(password) {
+	return crypto.createHash("sha256").update(`${password}salt`).digest("hex");
+}
+
+/**
+ * Minimal seed: creates a single admin user.
+ * Used standalone in production initial setup (SEED_PROFILE=minimal).
+ * Also called by seedDev to avoid duplication.
+ */
+async function seedMinimal(prisma) {
+	const existing = await prisma.user.findUnique({
+		where: { email: "admin@example.com" },
+	});
+
+	if (existing) {
+		console.log("✓ Admin user already exists");
+		return null;
+	}
+
+	const admin = await prisma.user.create({
+		data: {
+			email: "admin@example.com",
+			name: "Admin User",
+			role: "admin",
+			password: devHash("admin123"),
+		},
+	});
+
+	console.log(`✓ Created admin user: ${admin.email}`);
+	return admin;
+}
+
+/**
+ * Development seed: admin user + representative sample data for local testing.
+ * Runs by default (SEED_PROFILE=dev).
+ */
+async function seedDev(prisma) {
+	const admin = await seedMinimal(prisma);
+
+	// If admin already existed, skip the rest to remain idempotent
+	if (!admin) return;
+
+	const sampleUser = await prisma.user.create({
+		data: {
+			email: "user@example.com",
+			name: "Sample User",
+			role: "viewer",
+			image: "https://api.dicebear.com/7.x/avataaars/svg?seed=user@example.com",
+		},
+	});
+
+	console.log(`✓ Created sample user: ${sampleUser.email}`);
+
+	await prisma.auditLog.create({
+		data: {
+			userId: admin.id,
+			action: "CREATE",
+			entity: "User",
+			entityId: sampleUser.id,
+			metadata: { email: sampleUser.email, role: sampleUser.role },
+		},
+	});
+
+	console.log("✓ Created sample audit log");
+
+	await prisma.job.create({
+		data: {
+			queue: "default",
+			name: "example-job",
+			status: "COMPLETED",
+			data: { message: "This is a sample job" },
+			completedAt: new Date(),
+		},
+	});
+
+	console.log("✓ Created sample job");
+}
+
+async function main() {
+	const prisma = new PrismaClient({
+		adapter: new PrismaPg({ connectionString: getConnectionString() }),
+		errorFormat: "pretty",
+	});
+
+	try {
+		// SEED_PROFILE is intentionally separate from NODE_ENV.
+		// Railway sets NODE_ENV=production on ALL deployed services (including staging)
+		// for build/performance reasons, so NODE_ENV cannot reliably distinguish staging
+		// from production at seed time. Set SEED_PROFILE explicitly in your deploy command:
+		//   production: SEED_PROFILE=minimal pnpm db:seed
+		//   staging:    pnpm db:seed   (defaults to "dev")
+		const seedProfile = process.env.SEED_PROFILE || "dev";
+		console.log(`🌱 Seeding database with profile: "${seedProfile}"`);
+
+		if (seedProfile === "minimal") {
+			await seedMinimal(prisma);
+		} else {
+			await seedDev(prisma);
+		}
+
+		console.log("✅ Database seeding completed");
+	} finally {
+		await prisma.$disconnect();
+	}
+}
+
+main().catch((error) => {
+	console.error("❌ Seed failed:", error.message);
+	process.exit(1);
+});

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

@@ -16,6 +16,7 @@ export default defineConfig({
 	schema: "prisma/schema.prisma",
 	migrations: {
 		path: "prisma/migrations",
+		seed: "tsx prisma/seed.js",
 	},
 	datasource: {
 		url: databaseUrl,