@usequark/quark-create-app 1.23.11

package/templates/base-project/skills/quark-skills/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: quark-skills
+description: Index of every skill bundled with this Quark project - what each skill is for and when to load it. Start here when deciding which skill applies to a task.
+---
+
+# Quark Skills Index
+
+Every skill below ships with this project and is always available. Skills are abstract and domain-neutral: they describe framework patterns and workflows, not a specific business. Load the relevant `SKILL.md` before starting work in its area.
+
+## Core workflow skills
+
+| Skill | Path | Purpose |
+|---|---|---|
+| add-model | `add-model/SKILL.md` | Add a new Prisma model, query helpers, and tests to the db package. |
+| add-endpoint | `add-endpoint/SKILL.md` | Add an API route (or Server Action) with Zod validation, CSRF, and role guards. |
+| add-dashboard | `add-dashboard/SKILL.md` | Add a metrics/overview dashboard page with metric cards and loading states. |
+| admin-dashboard | `admin-dashboard/SKILL.md` | Build a full admin/back-office area: guarded routes, CRUD screens, audit logging. |
+
+## Domain starters
+
+These teach the AI to build a complete vertical on demand. No starter code is scaffolded - the AI generates it from the skill.
+
+| Skill | Path | Purpose |
+|---|---|---|
+| bookings | `bookings/SKILL.md` | Booking/reservation/appointment/scheduling systems. |
+| crm | `crm/SKILL.md` | Contact/pipeline/customer relationship systems. |
+| cms | `cms/SKILL.md` | Content modeling, authoring, and publishing systems. |
+| ai | `ai/SKILL.md` | AI assistant features (chat, completions) on app data. |
+| payment | `payment/SKILL.md` | Stripe payment integration, checkout, webhooks, fulfillment. |
+| ecommerce | `ecommerce/SKILL.md` | Product catalog, cart, checkout, orders, inventory. Sub-skills: `ecommerce-catalog`, `ecommerce-cart`, `ecommerce-checkout`. |
+| i18n | `i18n/SKILL.md` | Internationalization, locale routing, localized CMS content, hreflang SEO. |
+
+## How to use skills
+
+1. Match the user's request to a skill above; read its `SKILL.md` first.
+2. Skills assume the Quark conventions: Zod-validated actions/routes, query helpers in `packages/db/src/queries.js`, shared UI imports, `createLogger()` logging, models with `createdAt`/`updatedAt`.
+3. If no skill matches, follow `CLAUDE.md` / project context and the reference patterns in `apps/web/src/app/api/users/route.js` and `apps/web/src/app/page.js`.

package/templates/base-project/turbo.json

@@ -0,0 +1,143 @@
+{
+	"$schema": "https://v2-10-12.turborepo.dev/schema.json",
+	"ui": "stream",
+	"globalEnv": [
+		"GITHUB_OUTPUT",
+		"npm_execpath",
+		"npm_lifecycle_event",
+		"QUARK_SKIP_AUTO_CLEAN",
+		"QUARK_SKIP_DEV_PREFLIGHT",
+		"QUARK_SKIP_GIT_INIT"
+	],
+	"tasks": {
+		"clean": {
+			"cache": false
+		},
+		"build": {
+			"dependsOn": ["^build", "db:generate"],
+			"outputs": ["dist/**", ".next/**"],
+			"env": ["NODE_ENV"],
+			"passThroughEnv": [
+				"DATABASE_URL",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB",
+				"APP_URL",
+				"ALLOW_INDEXING",
+				"PORT",
+				"NEXTAUTH_SECRET",
+				"AUTH_SECRET"
+			]
+		},
+		"lint": {
+			"outputs": []
+		},
+		"test": {
+			"dependsOn": ["^build", "db:generate"],
+			"outputs": [],
+			"passThroughEnv": [
+				"DATABASE_URL",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB",
+				"REDIS_URL",
+				"REDIS_HOST",
+				"REDIS_PORT",
+				"NEXTAUTH_SECRET",
+				"AUTH_SECRET",
+				"APP_URL",
+				"ALLOW_INDEXING",
+				"PORT"
+			]
+		},
+		"db:generate": {
+			"cache": false,
+			"outputs": ["node_modules/.prisma/client"],
+			"passThroughEnv": [
+				"DATABASE_URL",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB"
+			]
+		},
+		"db:migrate:deploy": {
+			"cache": false,
+			"passThroughEnv": [
+				"DATABASE_URL",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB"
+			]
+		},
+		"db:push": {
+			"cache": false,
+			"passThroughEnv": [
+				"DATABASE_URL",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB"
+			]
+		},
+		"db:seed": {
+			"cache": false,
+			"passThroughEnv": [
+				"DATABASE_URL",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB",
+				"SEED_PROFILE",
+				"ADMIN_EMAIL",
+				"ADMIN_PASSWORD",
+				"ADMIN_NAME"
+			]
+		},
+		"dev": {
+			"cache": false,
+			"persistent": true,
+			"passThroughEnv": [
+				"DATABASE_URL",
+				"PORT",
+				"POSTGRES_HOST",
+				"POSTGRES_PORT",
+				"POSTGRES_USER",
+				"POSTGRES_PASSWORD",
+				"POSTGRES_DB",
+				"REDIS_URL",
+				"REDIS_HOST",
+				"REDIS_PORT",
+				"MAIL_HOST",
+				"MAIL_SMTP_PORT",
+				"MAIL_UI_PORT",
+				"NEXTAUTH_URL",
+				"NEXTAUTH_SECRET",
+				"AUTH_SECRET",
+				"APP_URL",
+				"ALLOW_INDEXING",
+				"WORKER_CONCURRENCY",
+				"STORAGE_PROVIDER",
+				"STORAGE_LOCAL_DIR",
+				"S3_BUCKET",
+				"S3_REGION",
+				"S3_ENDPOINT",
+				"S3_ACCESS_KEY_ID",
+				"S3_SECRET_ACCESS_KEY",
+				"S3_PUBLIC_URL",
+				"UPLOAD_MAX_SIZE",
+				"UPLOAD_ALLOWED_TYPES",
+				"EXPO_PUBLIC_API_URL"
+			]
+		}
+	}
+}

package/templates/config/package.json

@@ -0,0 +1,20 @@
+{
+	"name": "@myquark/config",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "src/index.js",
+	"exports": {
+		".": "./src/index.js",
+		"./rate-limit": "./src/rate-limit.js",
+		"./app-url": "./src/app-url.js",
+		"./environment": "./src/environment.js",
+		"./load-config": "./src/load-config.js",
+		"./validate-env": "./src/validate-env.js",
+		"./redis": "./src/redis.js"
+	},
+	"dependencies": {
+		"@techstream/quark-core": "^2.0.0",
+		"ioredis": "^6.0.0",
+		"zod": "^4.6.5"
+	}
+}

package/templates/config/src/app-url.js

@@ -0,0 +1,134 @@
+/**
+ * APP_URL - Single source of truth for the application's canonical URL.
+ *
+ * Resolution order:
+ *   1. APP_URL          (canonical origin - set it in every environment)
+ *   2. NEXTAUTH_URL     (legacy / backward-compat)
+ *   3. http://localhost:${PORT || 3000}   (local dev fallback)
+ *
+ * In development PORT is the default source for the web server port, but
+ * APP_URL should still be set explicitly whenever the origin you browse on is
+ * not exactly localhost:PORT (127.0.0.1, a LAN IP, a tunnel, another port).
+ * Auth.js derives its post-sign-in redirect and its client-side base URL from
+ * this value, so a mismatch silently drops the session.
+ * In production, set APP_URL explicitly (e.g. https://yourdomain.com).
+ *
+ * Derived values:
+ *   - NEXTAUTH_URL  - always set equal to the resolved APP_URL so
+ *                      NextAuth works without a separate variable.
+ *   - allowedOrigins - the resolved APP_URL plus any extra origins
+ *                      listed in ALLOWED_ORIGINS (comma-separated).
+ */
+
+import { ValidationError } from "@techstream/quark-core/errors";
+
+/**
+ * Resolves the canonical application URL.
+ * @returns {string} The canonical URL (no trailing slash)
+ */
+export function getAppUrl() {
+	const configuredAppUrl = process.env.APP_URL?.trim();
+	if (configuredAppUrl) {
+		return normalizeAppUrl(configuredAppUrl, "APP_URL");
+	}
+
+	const configuredNextAuthUrl = process.env.NEXTAUTH_URL?.trim();
+	if (configuredNextAuthUrl) {
+		return normalizeAppUrl(configuredNextAuthUrl, "NEXTAUTH_URL");
+	}
+
+	const fallbackPort = resolveLocalPort(process.env.PORT);
+
+	return normalizeAppUrl(`http://localhost:${fallbackPort}`, "derived APP_URL");
+}
+
+function resolveLocalPort(value) {
+	const parsedPort = Number.parseInt(value, 10);
+	if (Number.isInteger(parsedPort) && parsedPort > 0) {
+		return String(parsedPort);
+	}
+
+	return "3000";
+}
+
+function normalizeAppUrl(rawUrl, label) {
+	let parsedUrl;
+
+	try {
+		parsedUrl = new URL(rawUrl);
+	} catch {
+		throw new ValidationError(
+			`${label} must be an absolute http(s) URL. Received: ${rawUrl}`,
+		);
+	}
+
+	if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+		throw new ValidationError(
+			`${label} must use http:// or https://. Received: ${rawUrl}`,
+		);
+	}
+
+	return parsedUrl.toString().replace(/\/+$/, "");
+}
+
+/**
+ * Returns the list of allowed CORS origins.
+ *
+ * Always includes the canonical APP_URL.
+ * If ALLOWED_ORIGINS is set, those are *added* (not replacing) the canonical
+ * origin so the primary domain is never accidentally excluded.
+ *
+ * @returns {string[]} De-duplicated list of allowed origins
+ */
+export function getAllowedOrigins() {
+	const canonical = getAppUrl();
+	const extras = process.env.ALLOWED_ORIGINS
+		? process.env.ALLOWED_ORIGINS.split(",")
+				.map((o) => o.trim())
+				.filter(Boolean)
+		: [];
+
+	// In development, allow the ports the dev server actually listens on plus
+	// the loopback aliases people type by hand. `getEnvironmentConfig()` returns
+	// the hard-coded default (3000) and ignores `process.env.PORT`, so reading it
+	// here silently drifted from the real port whenever PORT was overridden.
+	const isDev = process.env.NODE_ENV !== "production";
+	// resolveLocalPort() returns a string - parse before doing arithmetic or
+	// "3000" + 1 silently becomes "30001".
+	const devPort = Number.parseInt(resolveLocalPort(process.env.PORT), 10);
+	const devOrigins = isDev
+		? [
+				`http://localhost:${devPort}`,
+				`http://localhost:${devPort + 1}`,
+				`http://127.0.0.1:${devPort}`,
+				`http://127.0.0.1:${devPort + 1}`,
+			]
+		: [];
+
+	// Extra LAN/VPN dev hosts accepted by next.config.js `allowedDevOrigins`,
+	// so CORS and the Next.js dev host allow-list stay in agreement.
+	const devHostExtras = isDev
+		? ["NEXT_DEV_ALLOWED_ORIGINS", "ALLOWED_DEV_ORIGINS"].flatMap((key) =>
+				(process.env[key] ?? "")
+					.split(",")
+					.map((host) => host.trim())
+					.filter(Boolean)
+					.map((host) => (host.includes("://") ? host : `http://${host}`)),
+			)
+		: [];
+
+	// De-duplicate
+	return [...new Set([canonical, ...extras, ...devOrigins, ...devHostExtras])];
+}
+
+/**
+ * Ensures NEXTAUTH_URL is set in process.env so NextAuth picks it up,
+ * even when only APP_URL was configured.
+ *
+ * Call this once at startup (e.g. in your env validation step).
+ */
+export function syncNextAuthUrl() {
+	if (!process.env.NEXTAUTH_URL) {
+		process.env.NEXTAUTH_URL = getAppUrl();
+	}
+}

package/templates/config/src/environment.js

@@ -0,0 +1,284 @@
+/**
+ * @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} auth - Authentication configuration
+ * @property {boolean} auth.allowSignup - Allow public self-service signup
+ * @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,
+		},
+		auth: {
+			allowSignup: true,
+		},
+		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,
+		},
+		auth: {
+			allowSignup: true,
+		},
+		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,
+		},
+		auth: {
+			allowSignup: 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,
+		},
+		auth: {
+			allowSignup: 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

@@ -0,0 +1,16 @@
+export const config = {
+	appName: process.env.APP_NAME || "Quark",
+	appDescription: process.env.APP_DESCRIPTION || "A Quark-powered application",
+};
+
+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 { applyRateLimit, rateLimit } from "./rate-limit.js";
+export { closeSharedRedisClient, getSharedRedisClient } from "./redis.js";
+export { loadEnv } from "./validate-env.js";