@techstream/quark-create-app 1.5.3 → 1.7.0

package/templates/config/src/environment.js

@@ -0,0 +1,270 @@
+/**
+ * @techstream/quark-config - Environment Configuration
+ * Provides environment-specific defaults for dev, test, staging, and production.
+ * Each environment defines sensible defaults that can be overridden via env vars.
+ */
+
+/**
+ * @typedef {"development" | "test" | "staging" | "production"} Environment
+ *
+ * @typedef {Object} EnvironmentConfig
+ * @property {Environment} environment - Resolved environment name
+ * @property {boolean} isProduction - True in production and staging
+ * @property {boolean} isDevelopment - True in development
+ * @property {boolean} isTest - True in test
+ * @property {Object} server - Server configuration
+ * @property {number} server.port - HTTP port
+ * @property {Object} rateLimit - Rate limiting defaults
+ * @property {number} rateLimit.windowMs - Rate limit window in ms
+ * @property {number} rateLimit.maxRequests - Max requests per window
+ * @property {number} rateLimit.authMaxRequests - Max auth requests per window
+ * @property {Object} cache - Cache configuration
+ * @property {number} cache.defaultTtl - Default cache TTL in seconds
+ * @property {Object} logging - Logging configuration
+ * @property {string} logging.level - Minimum log level
+ * @property {boolean} logging.json - Use JSON format
+ * @property {Object} db - Database configuration
+ * @property {number} db.poolMax - Max DB pool connections
+ * @property {number} db.poolIdleTimeout - Idle timeout in seconds
+ * @property {number} db.connectionTimeout - Connection timeout in seconds
+ * @property {Object} email - Email configuration
+ * @property {number} email.timeout - SMTP/API timeout in ms
+ * @property {Object} security - Security configuration
+ * @property {boolean} security.enforceHttps - Require HTTPS
+ * @property {boolean} security.trustProxy - Trust proxy headers
+ * @property {Object} features - Feature flags
+ * @property {boolean} features.debugRoutes - Enable debug endpoints
+ * @property {boolean} features.seedOnStart - Auto-seed database on startup
+ * @property {boolean} features.detailedErrors - Include stack traces in error responses
+ */
+
+/** @type {Record<Environment, EnvironmentConfig>} */
+const ENVIRONMENT_CONFIGS = {
+	development: {
+		environment: "development",
+		isProduction: false,
+		isDevelopment: true,
+		isTest: false,
+		server: {
+			port: 3000,
+		},
+		rateLimit: {
+			windowMs: 15 * 60 * 1000,
+			maxRequests: 1000,
+			authMaxRequests: 50,
+		},
+		cache: {
+			defaultTtl: 60,
+		},
+		logging: {
+			level: "debug",
+			json: false,
+		},
+		db: {
+			poolMax: 5,
+			poolIdleTimeout: 30,
+			connectionTimeout: 5,
+		},
+		email: {
+			timeout: 10_000,
+		},
+		security: {
+			enforceHttps: false,
+			trustProxy: false,
+		},
+		features: {
+			debugRoutes: true,
+			seedOnStart: false,
+			detailedErrors: true,
+		},
+	},
+
+	test: {
+		environment: "test",
+		isProduction: false,
+		isDevelopment: false,
+		isTest: true,
+		server: {
+			port: 3001,
+		},
+		rateLimit: {
+			windowMs: 15 * 60 * 1000,
+			maxRequests: 10_000,
+			authMaxRequests: 10_000,
+		},
+		cache: {
+			defaultTtl: 0,
+		},
+		logging: {
+			level: "warn",
+			json: false,
+		},
+		db: {
+			poolMax: 3,
+			poolIdleTimeout: 10,
+			connectionTimeout: 5,
+		},
+		email: {
+			timeout: 5_000,
+		},
+		security: {
+			enforceHttps: false,
+			trustProxy: false,
+		},
+		features: {
+			debugRoutes: true,
+			seedOnStart: false,
+			detailedErrors: true,
+		},
+	},
+
+	staging: {
+		environment: "staging",
+		isProduction: true,
+		isDevelopment: false,
+		isTest: false,
+		server: {
+			port: 3000,
+		},
+		rateLimit: {
+			windowMs: 15 * 60 * 1000,
+			maxRequests: 100,
+			authMaxRequests: 5,
+		},
+		cache: {
+			defaultTtl: 300,
+		},
+		logging: {
+			level: "info",
+			json: true,
+		},
+		db: {
+			poolMax: 10,
+			poolIdleTimeout: 30,
+			connectionTimeout: 5,
+		},
+		email: {
+			timeout: 10_000,
+		},
+		security: {
+			enforceHttps: true,
+			trustProxy: true,
+		},
+		features: {
+			debugRoutes: false,
+			seedOnStart: false,
+			detailedErrors: false,
+		},
+	},
+
+	production: {
+		environment: "production",
+		isProduction: true,
+		isDevelopment: false,
+		isTest: false,
+		server: {
+			port: 3000,
+		},
+		rateLimit: {
+			windowMs: 15 * 60 * 1000,
+			maxRequests: 100,
+			authMaxRequests: 5,
+		},
+		cache: {
+			defaultTtl: 600,
+		},
+		logging: {
+			level: "info",
+			json: true,
+		},
+		db: {
+			poolMax: 10,
+			poolIdleTimeout: 30,
+			connectionTimeout: 5,
+		},
+		email: {
+			timeout: 10_000,
+		},
+		security: {
+			enforceHttps: true,
+			trustProxy: true,
+		},
+		features: {
+			debugRoutes: false,
+			seedOnStart: false,
+			detailedErrors: false,
+		},
+	},
+};
+
+/** Valid environment names */
+export const ENVIRONMENTS = /** @type {const} */ ([
+	"development",
+	"test",
+	"staging",
+	"production",
+]);
+
+/**
+ * Resolves the current environment from NODE_ENV.
+ * Maps common aliases (e.g. "dev" → "development", "prod" → "production").
+ * Defaults to "development" if unset or unrecognized.
+ *
+ * @param {string} [nodeEnv] - Override for NODE_ENV (defaults to process.env.NODE_ENV)
+ * @returns {Environment}
+ */
+export function resolveEnvironment(nodeEnv) {
+	const raw = (nodeEnv ?? process.env.NODE_ENV ?? "").toLowerCase().trim();
+
+	const aliases = {
+		dev: "development",
+		development: "development",
+		test: "test",
+		testing: "test",
+		staging: "staging",
+		stage: "staging",
+		prod: "production",
+		production: "production",
+	};
+
+	return aliases[raw] || "development";
+}
+
+/**
+ * Returns the full environment configuration for a given environment.
+ * Unknown environments fall back to development.
+ *
+ * @param {string} [nodeEnv] - Override for NODE_ENV
+ * @returns {EnvironmentConfig}
+ */
+export function getEnvironmentConfig(nodeEnv) {
+	const env = resolveEnvironment(nodeEnv);
+	return { ...ENVIRONMENT_CONFIGS[env] };
+}
+
+/**
+ * Shallow-merges environment config with user-provided overrides (one level deep).
+ * Top-level scalars are replaced; top-level objects are spread-merged.
+ * Useful when downstream apps need to adjust defaults per-environment.
+ *
+ * @param {EnvironmentConfig} base - Base environment config
+ * @param {Record<string, unknown>} overrides - Partial overrides to merge
+ * @returns {EnvironmentConfig}
+ */
+export function mergeConfig(base, overrides) {
+	const result = { ...base };
+	for (const [key, value] of Object.entries(overrides)) {
+		if (
+			value != null &&
+			typeof value === "object" &&
+			!Array.isArray(value) &&
+			typeof result[key] === "object" &&
+			result[key] != null
+		) {
+			result[key] = { ...result[key], ...value };
+		} else {
+			result[key] = value;
+		}
+	}
+	return result;
+}

package/templates/config/src/index.js

@@ -1,21 +1,16 @@
 export const config = {
-	appName: "My Quark App",
-	environment: process.env.NODE_ENV || "development",
-	api: {
-		baseUrl: process.env.API_BASE_URL || "http://localhost:3000",
-	},
-	database: {
-		url:
-			process.env.DATABASE_URL ||
-			"postgresql://user:password@localhost:5432/myapp",
-	},
-	redis: {
-		url: process.env.REDIS_URL || "redis://localhost:6379",
-	},
-	email: {
-		from: process.env.EMAIL_FROM || "noreply@myquarkapp.com",
-		provider: process.env.EMAIL_PROVIDER || "smtp",
-	},
+	appName: process.env.APP_NAME || "Quark",
+	appDescription:
+		process.env.APP_DESCRIPTION ||
+		"A modern monorepo with Next.js, React, and Prisma",
 };
 
-export default config;
+export { getAllowedOrigins, getAppUrl, syncNextAuthUrl } from "./app-url.js";
+export {
+	ENVIRONMENTS,
+	getEnvironmentConfig,
+	mergeConfig,
+	resolveEnvironment,
+} from "./environment.js";
+export { getConfig, loadConfig, resetConfig } from "./load-config.js";
+export { loadEnv, validateEnv } from "./validate-env.js";

package/templates/config/src/load-config.js

@@ -0,0 +1,135 @@
+/**
+ * @techstream/quark-config - Configuration Loader
+ * Centralised configuration management that combines environment validation,
+ * environment-specific defaults, and user overrides into a single config object.
+ *
+ * Usage:
+ *   import { loadConfig } from "@techstream/quark-config";
+ *   const config = loadConfig();          // validates env + returns typed config
+ *   const config = loadConfig({ cache: { defaultTtl: 120 } }); // with overrides
+ */
+
+import { getAllowedOrigins, getAppUrl } from "./app-url.js";
+import { getEnvironmentConfig, mergeConfig } from "./environment.js";
+import { validateEnv } from "./validate-env.js";
+
+/** @type {import("./environment.js").EnvironmentConfig | null} */
+let cachedConfig = null;
+
+/**
+ * Loads the full application configuration.
+ *
+ * 1. Validates all required environment variables (throws on failure).
+ * 2. Resolves the current environment (dev/test/staging/production).
+ * 3. Merges environment-specific defaults with any user overrides.
+ * 4. Enriches with computed values (APP_URL, allowed origins, ports).
+ * 5. Caches the result — subsequent calls return the same object.
+ *
+ * @param {Record<string, unknown>} [overrides] - Optional partial overrides
+ * @param {Object} [options]
+ * @param {boolean} [options.fresh=false] - Force re-computation (bypass cache)
+ * @returns {import("./environment.js").EnvironmentConfig & { appUrl: string, allowedOrigins: string[], validated: Record<string, string> }}
+ */
+export function loadConfig(overrides = {}, options = {}) {
+	if (cachedConfig && !options.fresh) {
+		return cachedConfig;
+	}
+
+	// Step 1: Validate environment variables
+	const { validated } = validateEnv();
+
+	// Step 2: Resolve environment and get defaults
+	const envConfig = getEnvironmentConfig();
+
+	// Step 3: Apply env-var driven overrides
+	const envOverrides = buildEnvOverrides(envConfig);
+
+	// Step 4: Merge: env defaults → env-var overrides → user overrides
+	let config = mergeConfig(envConfig, envOverrides);
+	config = mergeConfig(config, overrides);
+
+	// Step 5: Attach computed values
+	config.appUrl = getAppUrl();
+	config.allowedOrigins = getAllowedOrigins();
+	config.validated = validated;
+
+	cachedConfig = config;
+	return config;
+}
+
+/**
+ * Clears the cached configuration. Useful in tests.
+ */
+export function resetConfig() {
+	cachedConfig = null;
+}
+
+/**
+ * Returns the cached configuration if already loaded, otherwise null.
+ * Does NOT trigger validation — use `loadConfig()` for that.
+ * @returns {ReturnType<typeof loadConfig> | null}
+ */
+export function getConfig() {
+	return cachedConfig;
+}
+
+/**
+ * Reads specific environment variables and converts them to config overrides.
+ * This allows env vars to take precedence over environment defaults.
+ *
+ * @param {import("./environment.js").EnvironmentConfig} envConfig
+ * @returns {Record<string, unknown>}
+ */
+function buildEnvOverrides(_envConfig) {
+	const overrides = {};
+
+	// Server
+	if (process.env.PORT) {
+		const port = Number.parseInt(process.env.PORT, 10);
+		if (!Number.isNaN(port)) overrides.server = { port };
+	}
+
+	// Rate limiting
+	if (process.env.RATE_LIMIT_MAX) {
+		const maxRequests = Number.parseInt(process.env.RATE_LIMIT_MAX, 10);
+		if (!Number.isNaN(maxRequests)) {
+			overrides.rateLimit = { ...overrides.rateLimit, maxRequests };
+		}
+	}
+	if (process.env.RATE_LIMIT_WINDOW_MS) {
+		const windowMs = Number.parseInt(process.env.RATE_LIMIT_WINDOW_MS, 10);
+		if (!Number.isNaN(windowMs)) {
+			overrides.rateLimit = { ...overrides.rateLimit, windowMs };
+		}
+	}
+
+	// Cache
+	if (process.env.CACHE_TTL) {
+		const defaultTtl = Number.parseInt(process.env.CACHE_TTL, 10);
+		if (!Number.isNaN(defaultTtl)) overrides.cache = { defaultTtl };
+	}
+
+	// Logging
+	if (process.env.LOG_LEVEL) {
+		overrides.logging = { ...overrides.logging, level: process.env.LOG_LEVEL };
+	}
+
+	// Database pool
+	if (process.env.DB_POOL_MAX) {
+		const poolMax = Number.parseInt(process.env.DB_POOL_MAX, 10);
+		if (!Number.isNaN(poolMax)) {
+			overrides.db = { ...overrides.db, poolMax };
+		}
+	}
+	if (process.env.DB_POOL_IDLE_TIMEOUT) {
+		const poolIdleTimeout = Number.parseInt(
+			process.env.DB_POOL_IDLE_TIMEOUT,
+			10,
+		);
+		if (!Number.isNaN(poolIdleTimeout)) {
+			overrides.db = { ...overrides.db, poolIdleTimeout };
+		}
+	}
+
+	return overrides;
+}

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

@@ -22,16 +22,31 @@ const envSchema = {
 	REDIS_HOST: { required: false, description: "Redis host" },
 	REDIS_PORT: { required: false, description: "Redis port" },
 
-	// Mail (local SMTP server)
-	MAIL_SMTP_URL: { required: false, description: "Mail SMTP URL" },
+	// Mail (local SMTP — Mailpit in dev)
 	MAIL_HOST: { required: false, description: "Mail host" },
 	MAIL_SMTP_PORT: { required: false, description: "Mail SMTP port" },
 	MAIL_UI_PORT: { required: false, description: "Mail UI port" },
 
+	// Production SMTP (used when SMTP_HOST is set)
+	SMTP_HOST: { required: false, description: "Production SMTP host" },
+	SMTP_PORT: { required: false, description: "Production SMTP port" },
+	SMTP_SECURE: { required: false, description: "Use TLS for SMTP" },
+	SMTP_USER: { required: false, description: "SMTP username" },
+	SMTP_PASSWORD: { required: false, description: "SMTP password" },
+
+	// Email provider
+	EMAIL_PROVIDER: {
+		required: false,
+		description: 'Email provider — "smtp" (default) or "resend"',
+	},
+	EMAIL_FROM: { required: false, description: "Sender email address" },
+	RESEND_API_KEY: { required: false, description: "Resend API key" },
+
 	// NextAuth
 	NEXTAUTH_SECRET: {
 		required: true,
 		description: "NextAuth secret for JWT signing",
+		minLength: 32,
 	},
 	NEXTAUTH_URL: {
 		required: false,
@@ -39,6 +54,10 @@ const envSchema = {
 	},
 
 	// Application
+	APP_NAME: {
+		required: false,
+		description: "Application name — used in metadata, emails, and page titles",
+	},
 	APP_URL: {
 		required: false,
 		description:
@@ -46,57 +65,145 @@ const envSchema = {
 	},
 	NODE_ENV: {
 		required: false,
-		description: "Environment (development, test, production)",
+		description: "Environment (development, test, staging, production)",
 	},
 	PORT: { required: false, description: "Web server port" },
+
+	// Storage
+	STORAGE_PROVIDER: {
+		required: false,
+		description: 'Storage provider — "local" (default) or "s3"',
+	},
+	STORAGE_LOCAL_DIR: {
+		required: false,
+		description: "Local storage directory",
+	},
+	S3_BUCKET: { required: false, description: "S3 bucket name" },
+	S3_REGION: { required: false, description: "S3 region" },
+	S3_ENDPOINT: { required: false, description: "S3-compatible endpoint URL" },
+	S3_ACCESS_KEY_ID: { required: false, description: "S3 access key" },
+	S3_SECRET_ACCESS_KEY: { required: false, description: "S3 secret key" },
+	S3_PUBLIC_URL: { required: false, description: "S3 public URL prefix" },
 };
 
 /**
- * Validates environment variables against schema
+ * Validates environment variables against schema.
+ *
+ * @param {"web" | "worker"} [service="web"] — The service being validated.
+ *   Worker skips web-only checks (e.g. NEXTAUTH_SECRET).
  * @throws {Error} If required environment variables are missing
- * @returns {Object} Validated environment object
+ * @returns {{ validated: Object, warnings: string[] }}
  */
-export function validateEnv() {
+export function validateEnv(service = "web") {
 	const errors = [];
+	const warnings = [];
 	const validated = {};
+	const isTest = process.env.NODE_ENV === "test";
+
+	// Web-only required fields that workers can skip
+	const webOnlyRequired = new Set(["NEXTAUTH_SECRET"]);
 
 	for (const [key, config] of Object.entries(envSchema)) {
 		const value = process.env[key];
 
-		if (config.required && !value) {
+		// Skip web-only required checks for worker service
+		const isRequired =
+			config.required && !(service === "worker" && webOnlyRequired.has(key));
+
+		if (isRequired && !value) {
 			errors.push(
 				`Missing required environment variable: ${key} (${config.description})`,
 			);
 		}
 
+		if (value && config.minLength && value.length < config.minLength) {
+			errors.push(
+				`${key} must be at least ${config.minLength} characters (${config.description})`,
+			);
+		}
+
 		if (value) {
 			validated[key] = value;
 		}
 	}
 
+	// --- Cross-field validation ---
+
+	// Database: either DATABASE_URL or POSTGRES_USER must be set (skip in test)
+	if (!isTest) {
+		const hasDbUrl = !!process.env.DATABASE_URL;
+		const hasPostgresUser = !!process.env.POSTGRES_USER;
+		if (!hasDbUrl && !hasPostgresUser) {
+			errors.push(
+				"Database not configured: set DATABASE_URL or POSTGRES_USER + POSTGRES_PASSWORD + POSTGRES_DB",
+			);
+		}
+	}
+
+	// Redis: warn if not configured (defaults to localhost in dev, will fail in prod)
+	if (
+		!process.env.REDIS_URL &&
+		!process.env.REDIS_HOST &&
+		process.env.NODE_ENV === "production"
+	) {
+		warnings.push(
+			"Redis not configured: set REDIS_URL or REDIS_HOST (defaults to localhost)",
+		);
+	}
+
+	// Conditional: S3 storage requires bucket + credentials
+	if (process.env.STORAGE_PROVIDER === "s3") {
+		for (const key of [
+			"S3_BUCKET",
+			"S3_ACCESS_KEY_ID",
+			"S3_SECRET_ACCESS_KEY",
+		]) {
+			if (!process.env[key]) {
+				errors.push(
+					`Missing ${key} — required when STORAGE_PROVIDER=s3 (${envSchema[key].description})`,
+				);
+			}
+		}
+	}
+
+	// Conditional: Resend provider requires API key
+	if (process.env.EMAIL_PROVIDER === "resend" && !process.env.RESEND_API_KEY) {
+		errors.push("Missing RESEND_API_KEY — required when EMAIL_PROVIDER=resend");
+	}
+
+	// Log warnings (non-fatal)
+	for (const warning of warnings) {
+		console.warn(`[env] ⚠️  ${warning}`);
+	}
+
 	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();
+	if (service === "web") {
+		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;
+		// 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;
+	return { validated, warnings };
 }
 
 /**
- * Loads and validates environment variables
- * Call this function at application startup
+ * Loads and validates environment variables.
+ * Call this function at application startup.
+ *
+ * @param {"web" | "worker"} [service="web"]
  */
-export function loadEnv() {
+export function loadEnv(service = "web") {
 	try {
-		return validateEnv();
+		const { validated } = validateEnv(service);
+		return validated;
 	} catch (error) {
 		console.error(error.message);
 		process.exit(1);

package/templates/jobs/package.json

@@ -2,7 +2,7 @@
 	"name": "@myquark/jobs",
 	"version": "1.0.0",
 	"type": "module",
-	"exports": {
-		".": "./src/index.js"
+	"dependencies": {
+		"bullmq": "^5.69.3"
 	}
 }

package/templates/jobs/src/definitions.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { JOB_NAMES, JOB_QUEUES } from "./definitions.js";
+
+test("Job Definitions - defines email queue", () => {
+	assert.strictEqual(JOB_QUEUES.EMAIL, "email-queue");
+});
+
+test("Job Definitions - defines files queue", () => {
+	assert.strictEqual(JOB_QUEUES.FILES, "files-queue");
+});
+
+test("Job Definitions - defines welcome email job name", () => {
+	assert.strictEqual(JOB_NAMES.SEND_WELCOME_EMAIL, "send-welcome-email");
+});
+
+test("Job Definitions - defines reset password email job name", () => {
+	assert.strictEqual(
+		JOB_NAMES.SEND_RESET_PASSWORD_EMAIL,
+		"send-reset-password-email",
+	);
+});
+
+test("Job Definitions - defines cleanup orphaned files job name", () => {
+	assert.strictEqual(
+		JOB_NAMES.CLEANUP_ORPHANED_FILES,
+		"cleanup-orphaned-files",
+	);
+});
+
+test("Job Definitions - queues are readonly", () => {
+	assert.strictEqual(typeof JOB_QUEUES.EMAIL, "string");
+	assert.strictEqual(typeof JOB_QUEUES.FILES, "string");
+});

package/templates/jobs/src/index.js

@@ -1 +1 @@
-export { JOB_NAMES, JOB_QUEUES } from "./definitions.js";
+export * from "./definitions.js";