@techstream/quark-create-app 1.5.3 → 1.6.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,13 @@
 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: "Quark",
+	appDescription: "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";

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,32 @@ const envSchema = {
 	REDIS_HOST: { required: false, description: "Redis host" },
 	REDIS_PORT: { required: false, description: "Redis port" },
 
-	// Mail (local SMTP server)
+	// Mail (local SMTP — Mailpit in dev)
 	MAIL_SMTP_URL: { required: false, description: "Mail SMTP URL" },
 	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,
@@ -46,9 +62,25 @@ 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" },
 };
 
 /**
@@ -69,11 +101,37 @@ export function validateEnv() {
 			);
 		}
 
+		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;
 		}
 	}
 
+	// 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");
+	}
+
 	if (errors.length > 0) {
 		const errorMessage = `Environment Validation Failed:\n${errors.join("\n")}`;
 		throw new Error(errorMessage);

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.67.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";

package/templates/ui/package.json

@@ -2,10 +2,10 @@
 	"name": "@myquark/ui",
 	"version": "1.0.0",
 	"type": "module",
-	"exports": {
-		".": "./src/index.js"
-	},
 	"devDependencies": {
-		"react": "^18.0.0"
+		"@types/react": "^19.2.13",
+		"@types/react-dom": "^19.2.3",
+		"react": "19.2.0",
+		"react-dom": "19.2.0"
 	}
 }

package/templates/ui/src/button.test.js

@@ -0,0 +1,23 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { Button } from "./button.js";
+
+test("Button - component exports correctly", () => {
+	assert(typeof Button === "function", "Button should be a function");
+});
+
+test("Button - component accepts props", () => {
+	// Test that component can be called with props
+	const result = Button({ variant: "primary", className: "custom" });
+	assert.ok(result, "Component should return an element");
+});
+
+test("Button - supports primary variant", () => {
+	const result = Button({ variant: "primary" });
+	assert.ok(result, "Primary variant should be supported");
+});
+
+test("Button - supports secondary variant", () => {
+	const result = Button({ variant: "secondary" });
+	assert.ok(result, "Secondary variant should be supported");
+});

package/templates/ui/src/index.js

@@ -1,3 +1 @@
-export { Button } from "./button.js";
-export { Card } from "./card.js";
-export { Input } from "./input.js";
+export * from "./button.js";

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

@@ -1,65 +0,0 @@
-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";
-import { handleError } from "../../error-handler";
-
-export async function GET(_request, { params }) {
-	try {
-		const { id } = await params;
-		const foundPost = await post.findById(id);
-		if (!foundPost) {
-			return NextResponse.json({ message: "Post not found" }, { status: 404 });
-		}
-		return NextResponse.json(foundPost);
-	} catch (error) {
-		return handleError(error);
-	}
-}
-
-export const PATCH = withCsrfProtection(async (request, { params }) => {
-	try {
-		const session = await requireAuth();
-		const { id } = await params;
-
-		const foundPost = await post.findById(id);
-		if (!foundPost) {
-			return NextResponse.json({ message: "Post not found" }, { status: 404 });
-		}
-
-		if (foundPost.authorId !== session.user.id) {
-			throw new UnauthorizedError("You can only edit your own posts");
-		}
-
-		const data = await validateBody(request, postUpdateSchema);
-		const updatedPost = await post.update(id, data);
-		return NextResponse.json(updatedPost);
-	} catch (error) {
-		return handleError(error);
-	}
-});
-
-export const DELETE = withCsrfProtection(async (_request, { params }) => {
-	try {
-		const session = await requireAuth();
-		const { id } = await params;
-
-		const foundPost = await post.findById(id);
-		if (!foundPost) {
-			return NextResponse.json({ message: "Post not found" }, { status: 404 });
-		}
-
-		if (foundPost.authorId !== session.user.id) {
-			throw new UnauthorizedError("You can only delete your own posts");
-		}
-
-		await post.delete(id);
-		return NextResponse.json({ success: true });
-	} catch (error) {
-		return handleError(error);
-	}
-});