@usequark/quark-create-app 1.23.11

package/templates/base-project/apps/web/src/proxy.js

@@ -0,0 +1,328 @@
+/**
+ * Next.js Proxy
+ * Handles auth guards, rate limiting, CORS, and security headers.
+ *
+ * Guards (in order):
+ *   1. Metrics guard        - optionally protects /api/metrics with a bearer
+ *                             token. Set METRICS_TOKEN in env to enable.
+ *   2. Rate limiting, CORS, security headers for all API routes.
+ */
+
+import { getAllowedOrigins } from "@techstream/quark-config/app-url";
+import { NextResponse } from "next/server";
+
+import { buildContentSecurityPolicy } from "./lib/analytics/umami-csp.js";
+import { getRateLimitBucket } from "./lib/proxy-auth";
+
+// ─── 1. Metrics guard ────────────────────────────────────────────────────────
+
+function metricsGuard(request) {
+	const { pathname } = request.nextUrl;
+	if (pathname !== "/api/metrics") return null;
+
+	// If METRICS_TOKEN is not configured, the endpoint is unprotected (existing
+	// behaviour preserved). Set METRICS_TOKEN in env to enable protection.
+	const expectedToken = process.env.METRICS_TOKEN;
+	if (!expectedToken) return null;
+
+	const authHeader = request.headers.get("authorization") ?? "";
+	const providedToken = authHeader.startsWith("Bearer ")
+		? authHeader.slice(7)
+		: (request.headers.get("x-metrics-token") ?? "");
+
+	if (providedToken !== expectedToken) {
+		return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+	}
+
+	return null; // authorised - continue
+}
+
+// Simple in-memory rate limiter (use Redis for production)
+const rateLimit = new Map();
+
+/**
+ * Resolve the client IP for rate-limit keying.
+ *
+ * `NextRequest.ip` was removed in Next 15, so `request.ip` is always
+ * `undefined` here and every caller collapsed onto the literal key
+ * "unknown" — one shared bucket for the whole server. That let a single
+ * burst of 5 credential posts (the `auth` bucket) lock out sign-in for
+ * everyone for 15 minutes.
+ *
+ * Trust `x-forwarded-for`/`x-real-ip` only when you are actually behind a
+ * reverse proxy (Railway, Docker, nginx) that overwrites them; otherwise a
+ * client can spoof them to evade the limiter.
+ *
+ * @param {import("next/server").NextRequest} request
+ * @returns {string}
+ */
+function getClientIp(request) {
+	const forwardedFor = request.headers.get("x-forwarded-for");
+	if (forwardedFor) {
+		// Left-most entry is the originating client; later entries are proxies.
+		const client = forwardedFor
+			.split(",")
+			.map((value) => value.trim())
+			.filter(Boolean)[0];
+		if (client) return client;
+	}
+
+	const realIp = request.headers.get("x-real-ip");
+	if (realIp) return realIp.trim();
+
+	return "unknown";
+}
+
+const RATE_LIMIT_CONFIG = {
+	windowMs: 15 * 60 * 1000, // 15 minutes
+	maxRequests: {
+		api: 100, // 100 requests per 15 minutes for general API
+		auth: 5, // 5 requests per 15 minutes for auth endpoints
+	},
+};
+
+/**
+ * Rate limiting implementation
+ */
+function checkRateLimit(ip, path, method) {
+	const now = Date.now();
+	const key = `${ip}:${path}`;
+
+	const maxRequests =
+		RATE_LIMIT_CONFIG.maxRequests[getRateLimitBucket(path, method)];
+
+	// Get or create rate limit record
+	const record = rateLimit.get(key) || {
+		count: 0,
+		resetTime: now + RATE_LIMIT_CONFIG.windowMs,
+	};
+
+	// Reset if window has passed
+	if (now > record.resetTime) {
+		record.count = 0;
+		record.resetTime = now + RATE_LIMIT_CONFIG.windowMs;
+	}
+
+	// Check if limit exceeded
+	if (record.count >= maxRequests) {
+		return {
+			limited: true,
+			resetTime: record.resetTime,
+			remaining: 0,
+		};
+	}
+
+	// Increment counter
+	record.count++;
+	rateLimit.set(key, record);
+
+	return {
+		limited: false,
+		resetTime: record.resetTime,
+		remaining: maxRequests - record.count,
+	};
+}
+
+/**
+ * Clean up old rate limit records periodically.
+ * `unref()` so the timer never holds the Node process open on shutdown.
+ */
+const rateLimitCleanup = setInterval(() => {
+	const now = Date.now();
+	for (const [key, record] of rateLimit.entries()) {
+		if (now > record.resetTime) {
+			rateLimit.delete(key);
+		}
+	}
+}, 60 * 1000); // Clean up every minute
+if (typeof rateLimitCleanup.unref === "function") rateLimitCleanup.unref();
+
+/**
+ * CORS configuration
+ */
+const CORS_CONFIG = {
+	allowedOrigins: getAllowedOrigins(),
+	allowedMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+	allowedHeaders: ["Content-Type", "Authorization", "X-CSRF-Token"],
+	exposedHeaders: [
+		"X-RateLimit-Limit",
+		"X-RateLimit-Remaining",
+		"X-RateLimit-Reset",
+	],
+	credentials: true,
+	maxAge: 86400, // 24 hours
+};
+
+/**
+ * Security headers configuration
+ *
+ * In development, Turbopack's hot-reload runtime uses eval() for module
+ * evaluation. 'unsafe-eval' is therefore added to script-src only when
+ * NODE_ENV is not 'production' - it must never reach a production build.
+ */
+const SECURITY_HEADERS = {
+	"X-DNS-Prefetch-Control": "on",
+	"Strict-Transport-Security": "max-age=63072000; includeSubDomains",
+	"X-Frame-Options": "SAMEORIGIN",
+	"X-Content-Type-Options": "nosniff",
+	"Referrer-Policy": "strict-origin-when-cross-origin",
+	"Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+	"Content-Security-Policy": buildContentSecurityPolicy(),
+};
+
+/**
+ * Request size limits (in bytes)
+ */
+const REQUEST_SIZE_LIMITS = {
+	api: parseInt(process.env.API_BODY_SIZE_LIMIT || "2097152", 10), // 2MB default
+	upload: parseInt(process.env.UPLOAD_SIZE_LIMIT || "10485760", 10), // 10MB for uploads
+};
+
+export async function proxy(request) {
+	const metricsResponse = metricsGuard(request);
+	if (metricsResponse) return metricsResponse;
+
+	const { pathname } = request.nextUrl;
+	const origin = request.headers.get("origin") || "";
+
+	// Create response
+	const response = NextResponse.next();
+
+	// Check request body size for API routes
+	if (
+		pathname.startsWith("/api/") &&
+		["POST", "PUT", "PATCH"].includes(request.method)
+	) {
+		const contentLength = request.headers.get("content-length");
+		if (contentLength) {
+			const size = parseInt(contentLength, 10);
+			const limit = pathname.startsWith("/api/upload")
+				? REQUEST_SIZE_LIMITS.upload
+				: REQUEST_SIZE_LIMITS.api;
+
+			if (size > limit) {
+				return new NextResponse(
+					JSON.stringify({
+						error: "Payload too large",
+						message: `Request body size exceeds limit of ${Math.round(limit / 1024 / 1024)}MB`,
+						maxSize: limit,
+					}),
+					{
+						status: 413,
+						headers: {
+							"Content-Type": "application/json",
+						},
+					},
+				);
+			}
+		}
+	}
+
+	// Apply rate limiting to API routes only
+	if (pathname.startsWith("/api/")) {
+		const ip = getClientIp(request);
+		const rateLimitBucket = getRateLimitBucket(pathname, request.method);
+		const maxRequests = RATE_LIMIT_CONFIG.maxRequests[rateLimitBucket];
+		const rateLimitResult = checkRateLimit(ip, pathname, request.method);
+
+		if (rateLimitResult.limited) {
+			const retryAfter = Math.ceil(
+				(rateLimitResult.resetTime - Date.now()) / 1000,
+			);
+			return new NextResponse(
+				JSON.stringify({
+					error: "Too many requests",
+					message: "You have exceeded the rate limit. Please try again later.",
+					retryAfter,
+				}),
+				{
+					status: 429,
+					headers: {
+						"Content-Type": "application/json",
+						"Retry-After": retryAfter.toString(),
+						"X-RateLimit-Limit": maxRequests.toString(),
+						"X-RateLimit-Remaining": "0",
+						"X-RateLimit-Reset": new Date(
+							rateLimitResult.resetTime,
+						).toISOString(),
+					},
+				},
+			);
+		}
+
+		// Add rate limit headers to response
+		response.headers.set("X-RateLimit-Limit", maxRequests.toString());
+		response.headers.set(
+			"X-RateLimit-Remaining",
+			rateLimitResult.remaining.toString(),
+		);
+		response.headers.set(
+			"X-RateLimit-Reset",
+			new Date(rateLimitResult.resetTime).toISOString(),
+		);
+	}
+
+	// Handle CORS for API routes
+	if (pathname.startsWith("/api/")) {
+		// Check if origin is allowed
+		const isAllowedOrigin =
+			CORS_CONFIG.allowedOrigins.includes("*") ||
+			CORS_CONFIG.allowedOrigins.includes(origin);
+
+		if (isAllowedOrigin || !origin) {
+			response.headers.set(
+				"Access-Control-Allow-Origin",
+				origin || CORS_CONFIG.allowedOrigins[0],
+			);
+			response.headers.set(
+				"Access-Control-Allow-Methods",
+				CORS_CONFIG.allowedMethods.join(", "),
+			);
+			response.headers.set(
+				"Access-Control-Allow-Headers",
+				CORS_CONFIG.allowedHeaders.join(", "),
+			);
+			response.headers.set(
+				"Access-Control-Expose-Headers",
+				CORS_CONFIG.exposedHeaders.join(", "),
+			);
+			response.headers.set(
+				"Access-Control-Max-Age",
+				CORS_CONFIG.maxAge.toString(),
+			);
+
+			if (CORS_CONFIG.credentials) {
+				response.headers.set("Access-Control-Allow-Credentials", "true");
+			}
+		}
+
+		// Handle preflight requests
+		if (request.method === "OPTIONS") {
+			return new NextResponse(null, {
+				status: 204,
+				headers: response.headers,
+			});
+		}
+	}
+
+	// Apply security headers
+	for (const [key, value] of Object.entries(SECURITY_HEADERS)) {
+		response.headers.set(key, value);
+	}
+
+	return response;
+}
+
+// Configure which routes the proxy runs on
+export const config = {
+	matcher: [
+		/*
+		 * Match all request paths except:
+		 * - _next/static (static files)
+		 * - _next/image (image optimization files)
+		 * - favicon.ico (favicon file)
+		 * - public folder
+		 */
+		"/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
+	],
+};

package/templates/base-project/biome.json

@@ -0,0 +1,52 @@
+{
+	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": [
+			"**",
+			"!**/.next",
+			"!**/dist",
+			"!**/.turbo",
+			"!**/coverage",
+			"!packages/db/src/generated"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"preset": "recommended"
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"css": {
+		"parser": {
+			"cssModules": true,
+			"tailwindDirectives": true
+		},
+		"linter": {
+			"enabled": true
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	},
+	"root": false
+}

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

@@ -0,0 +1,17 @@
+# Dev-only services - auto-merged by `docker compose up`.
+# Not read by Railway, Kubernetes, or other deployment platforms.
+services:
+  # --- Mailpit (Local SMTP Server) ---
+  mailpit:
+    image: ghcr.io/axllent/mailpit
+    restart: always
+    ports:
+      # SMTP port (used by application to send mail)
+      - "${MAIL_SMTP_PORT:-1025}:1025"
+      # Web UI port (to view sent emails)
+      - "${MAIL_UI_PORT:-8025}:8025"
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8025"]
+      interval: 10s
+      timeout: 5s
+      retries: 3

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

@@ -0,0 +1,37 @@
+services:
+  # --- 1. PostgreSQL Database ---
+  postgres:
+    image: postgres:16-alpine
+    restart: always
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    environment:
+      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:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-quark_user}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  # --- 2. Redis Cache & Job Queue ---
+  redis:
+    image: redis:7-alpine
+    restart: always
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    command: redis-server --appendonly yes
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+  redis_data:

package/templates/base-project/docs/FIRST_FEATURE.md

@@ -0,0 +1,74 @@
+# First Feature
+
+Use this guide when you are ready to add the first real feature to your project.
+
+## Goal
+
+Prove the full workflow once:
+
+1. add a Prisma model
+2. run the migration
+3. add query helpers
+4. build a page or mutation flow
+5. add a test near the changed code
+
+## 1. Add the model
+
+Edit `packages/db/prisma/schema.prisma`.
+
+Every model should include:
+
+- `id String @id @default(cuid())`
+- `createdAt DateTime @default(now())`
+- `updatedAt DateTime @updatedAt`
+
+If the new data belongs to a signed-in user, relate it to `User`.
+
+## 2. Generate and migrate
+
+```bash
+pnpm db:generate
+pnpm db:migrate
+```
+
+## 3. Add query helpers
+
+Edit `packages/db/src/queries.js`.
+
+Start with the smallest useful surface:
+
+- `findAll`
+- `findById`
+- `create`
+
+Add `update` and `delete` when the feature actually needs them.
+
+## 4. Build the web flow
+
+Use `apps/web/src/app/` for the first route.
+
+Typical first files:
+
+- `apps/web/src/app/<feature>/page.js`
+- `apps/web/src/app/<feature>/_actions/*.js` for Server Actions
+- `apps/web/src/app/api/<feature>/route.js` if this feature needs an API surface
+
+If the project includes `ui`, use components from `@yourapp/ui`.
+
+## 5. Add one test
+
+Start in the layer you changed first:
+
+- query helper test
+- route test
+- form helper test
+
+Do not wait for a perfect end-to-end suite before writing the first useful test.
+
+## Optional next step
+
+If the feature needs more infrastructure, add it only when necessary:
+
+- `ui` for reusable components
+- `jobs` for async work
+- `cms` for editorial content workflows

package/templates/base-project/docs/START_HERE.md

@@ -0,0 +1,70 @@
+# Start Here
+
+This is the shortest current path through a newly scaffolded Quark project.
+
+## Read these first
+
+1. `README.md` - quick start, included features, and first files to edit
+2. `docs/FIRST_FEATURE.md` - the canonical first product feature walkthrough
+3. `CLAUDE.md` - AI tool context for code generation and refactors
+
+## Know the project contract
+
+Every Quark scaffold gives you:
+
+- `apps/web` - the Next.js app
+- `packages/db` - Prisma schema, client, and query helpers
+- `packages/config` - validated environment config
+- optional local packages like `ui` and `jobs`
+
+The package READMEs explain optional features if they are present:
+
+- `packages/ui/README.md`
+- `packages/jobs/README.md`
+- `packages/cms/README.md`
+
+## Best order to learn the codebase
+
+1. `packages/db/prisma/schema.prisma`
+2. `packages/db/src/queries.js`
+3. `apps/web/src/app/`
+4. `apps/web/src/lib/auth.js`
+5. `apps/worker/src/handlers/` if your project includes background jobs
+
+## Build next
+
+Follow `docs/FIRST_FEATURE.md` and ship one thin vertical slice:
+
+1. add a model
+2. migrate the database
+3. add query helpers
+4. build the page or mutation
+5. add one focused test
+
+That is the fastest way to move from "starter" to "product code."
+
+## Keep your scaffold visible
+
+Before taking Quark infrastructure updates, review scaffold-managed drift from the project root:
+
+```bash
+npx @techstream/quark-create-app update --scaffold-check
+```
+
+If you want CI to fail when scaffold-managed files drift, use:
+
+```bash
+npx @techstream/quark-create-app update --scaffold-check --fail-on-drift
+```
+
+## Recover disk space
+
+When local build artifacts pile up, run these from the project root:
+
+```bash
+pnpm clean:check   # Preview reclaimable build artifacts
+pnpm clean         # Remove .turbo, .next, build, dist, and coverage output
+pnpm clean:deep    # Also remove repo-local temp workspaces
+```
+
+`pnpm dev` also auto-cleans stale oversized local artifacts at most once per day. Set `QUARK_SKIP_AUTO_CLEAN=1` if you want to skip that behavior for a run.

package/templates/base-project/docs/adr/README.md

@@ -0,0 +1,42 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for __QUARK_PROJECT_NAME__.
+
+An ADR documents a significant architectural decision: the context, the decision made, and its consequences.
+
+## Index
+
+| ID | Title | Status |
+|----|-------|--------|
+
+<!-- Add entries here as you make architectural decisions. -->
+<!-- Example: | [ADR-001](./001-example-decision.md) | Why we chose X over Y | Accepted | -->
+
+## Format
+
+Each ADR uses this structure:
+
+- **Status:** Accepted / Superseded / Deprecated
+- **Context:** Why a decision was needed
+- **Decision:** What was decided
+- **Consequences:** Trade-offs and implications
+
+## Template
+
+```markdown
+# ADR-XXX: Title
+
+**Status:** Accepted
+
+## Context
+
+Why was this decision needed?
+
+## Decision
+
+What was decided?
+
+## Consequences
+
+What are the trade-offs?
+```

package/templates/base-project/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@myquark/root",
+	"private": true,
+	"version": "1.0.0",
+	"type": "module",
+	"description": "My Quark project",
+	"main": "index.js",
+	"scripts": {
+		"clean": "node scripts/clean-workspace.mjs",
+		"clean:check": "node scripts/clean-workspace.mjs --check",
+		"clean:deep": "node scripts/clean-workspace.mjs --deep",
+		"build": "dotenv -- turbo run build",
+		"dev": "dotenv -- node scripts/dev-preflight.mjs && dotenv -- turbo run dev",
+		"dev:mobile": "pnpm --filter @myquark/mobile start",
+		"build:mobile": "pnpm --filter @myquark/mobile export",
+		"lint": "turbo run lint",
+		"standards": "node scripts/check-standards.mjs",
+		"check:loading": "node scripts/check-loading.mjs",
+		"test": "turbo run test",
+		"docker:up": "docker compose up -d",
+		"docker:down": "docker compose down",
+		"docker:clean": "docker compose down -v",
+		"db:generate": "turbo run db:generate",
+		"db:migrate": "pnpm --filter ./packages/db db:migrate",
+		"db:migrate:deploy": "pnpm --filter ./packages/db db:migrate:deploy",
+		"db:push": "turbo run db:push",
+		"db:seed": "turbo run db:seed",
+		"db:studio": "turbo run db:studio",
+		"doctor": "node scripts/doctor.js",
+		"doctor:fix": "node scripts/doctor.js --fix",
+		"doctor:ci": "node scripts/doctor.js --ci",
+		"prepare": "node scripts/prepare.js"
+	},
+	"simple-git-hooks": {
+		"pre-commit": "pnpm nano-staged",
+		"pre-push": "pnpm check:loading && pnpm test"
+	},
+	"nano-staged": {
+		"**/*.{js,jsx,mjs,json,css}": [
+			"biome format --no-errors-on-unmatched --write",
+			"biome check --no-errors-on-unmatched --write"
+		]
+	},
+	"keywords": [],
+	"author": "",
+	"license": "MIT",
+	"packageManager": "pnpm@10.12.1",
+	"devDependencies": {
+		"@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"
+	},
+	"pnpm": {}
+}