@techstream/quark-create-app 1.8.0 → 1.10.0

package/templates/base-project/README.md

@@ -1,49 +1,91 @@
-# My Quark Project
+# __QUARK_PROJECT_NAME__
 
-A modern, scalable monorepo built with Quark.
+Scaffolded with [Quark](https://github.com/Bobnoddle/quark) on __QUARK_SCAFFOLD_DATE__.
 
-## Quick Start
+## Local Development
 
 ```bash
-pnpm install
-docker compose up -d
-pnpm db:migrate
-pnpm dev
+docker compose up -d   # Start PostgreSQL, Redis, Mailpit
+pnpm install           # Install dependencies
+pnpm db:migrate        # Apply migrations
+pnpm dev               # Start web + worker
 ```
 
-Open http://localhost:3000
+Open [http://localhost:3000](http://localhost:3000)
 
-## Services
+## Database
 
-- **Docker**: `docker compose up -d`
-- **Database**: PostgreSQL
-- **Cache**: Redis
-- **Email**: Mailpit
+| Task | Command |
+|------|---------|
+| Run migrations | `pnpm db:migrate` |
+| Push schema (no migration) | `pnpm db:push` |
+| Generate Prisma client | `pnpm db:generate` |
+| Seed database | `pnpm db:seed` |
+| Open Prisma Studio | `pnpm db:studio` |
 
-## Development
+## Other Commands
 
 ```bash
-# Build all packages
-pnpm build
+pnpm build    # Build all packages
+pnpm test     # Run all tests (requires Docker)
+pnpm lint     # Lint + format check (Biome)
+```
 
-# Run tests
-pnpm test
+## Launch
 
-# Lint
-pnpm lint
+### 1. Push to GitHub
+
+```bash
+gh repo create __QUARK_PROJECT_NAME__ --private --source=. --push
 ```
 
-## Database
+No `gh` CLI? Go to [github.com/new](https://github.com/new), create the repo, then:
 
-| Task | Command |
-|------|--------|
-| Run migrations | `pnpm db:migrate` |
-| Push schema (no migration) | `pnpm db:push` |
-| Generate Prisma client | `pnpm db:generate` |
-| Seed database | `pnpm db:seed` |
-| Open Prisma Studio | `pnpm db:studio` |
+```bash
+git remote add origin https://github.com/<you>/__QUARK_PROJECT_NAME__.git
+git push -u origin main
+```
+
+### 2. Deploy on Railway
+
+> **One-click Railway template coming soon.** For now, follow these steps:
+
+1. Go to [railway.app](https://railway.app) → **New Project** → **Deploy from GitHub repo** → select `__QUARK_PROJECT_NAME__`
+2. In the service → **Settings** → **Source** → set **Config File** to `apps/web/railway.json`
+3. In the project → **+ New** → **Database** → **Add PostgreSQL** (injects `DATABASE_URL` automatically)
+4. In the project → **+ New** → **Database** → **Add Redis** (injects `REDIS_URL` automatically)
+5. In your web service → **Variables** → add:
+   - `NEXTAUTH_SECRET` → run `openssl rand -base64 32` locally and paste the result
+   - `APP_URL` → your Railway public domain (e.g. `https://__QUARK_PROJECT_NAME__.railway.app`)
+6. *(If you included the worker)* **+ New** → **GitHub Repo** → same repo → **Config File** → `apps/worker/railway.json`
+
+Railway auto-deploys on every push to `main`. Migrations run automatically before each deploy.
+
+## AI-Assisted Development
+
+This project ships with pre-loaded context for Claude Code, Cursor, GitHub Copilot, and others — see `CLAUDE.md` for the full reference.
+
+**Suggested first prompt:**
+
+> I'm building __QUARK_PROJECT_NAME__ — [describe what your app does in one sentence].
+>
+> Start by reviewing `CLAUDE.md` so you understand the full stack, then:
+> 1. Add the Prisma models we need to `packages/db/prisma/schema.prisma`
+> 2. Create the query helpers in `packages/db/src/queries.js`
+> 3. Build the first page in `apps/web/src/app/` using our UI component system
+
+Replace that bracketed description with what you're actually building, and the AI has everything it needs.
 
 ## Structure
 
-- `apps/` - Applications (web, worker, etc.)
-- `packages/` - Shared packages (ui, jobs, config, core, db, cli)
+```
+__QUARK_PROJECT_NAME__/
+├── apps/
+│   ├── web/         # Next.js 16 (App Router, Server Actions)
+│   └── worker/      # BullMQ background worker
+├── packages/
+│   ├── db/          # Prisma schema + query helpers
+│   └── config/      # Environment validation
+├── docker-compose.yml
+└── CLAUDE.md        # AI tool context — keep this updated
+```

package/templates/base-project/apps/web/next.config.js

@@ -43,8 +43,12 @@ const nextConfig = {
 					},
 					{
 						key: "Content-Security-Policy",
+						// unsafe-eval is required by Turbopack in development only.
+						// It is deliberately excluded from the production directive.
 						value:
-							"default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';",
+							process.env.NODE_ENV !== "production"
+								? "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';"
+								: "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';",
 					},
 				],
 			},

package/templates/base-project/apps/web/package.json

@@ -12,22 +12,24 @@
 	},
 	"dependencies": {
 		"@auth/prisma-adapter": "^2.11.1",
+		"@aws-sdk/client-s3": "^3.1004.0",
+		"@aws-sdk/s3-request-presigner": "^3.1004.0",
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
 		"@techstream/quark-ui": "workspace:*",
-		"@prisma/client": "^7.4.0",
+		"@prisma/client": "^7.4.2",
 		"next": "16.1.6",
 		"next-auth": "5.0.0-beta.30",
-		"pg": "^8.18.0",
+		"pg": "^8.20.0",
 		"react": "19.2.4",
 		"react-dom": "19.2.4",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@tailwindcss/postcss": "^4.2.0",
-		"@types/node": "^25.2.3",
-		"tailwindcss": "^4.2.0",
+		"@tailwindcss/postcss": "^4.2.1",
+		"@types/node": "^25.3.5",
+		"tailwindcss": "^4.2.1",
 		"@techstream/quark-config": "workspace:*"
 	}
 }

package/templates/base-project/apps/web/public/quark.svg

@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" fill="none">
+  <!--
+    Quark logo — SVG master
+    Geometry mirrors QuarkAnimation.js constants (ring/dash thickness ratio ~0.20)
+
+    Ring: center (100,100), centerline radius 65, stroke-width 26
+    Gap:  centred at 45.8° (dashAngle=0.8 rad), half-width 27.1° (0.472 rad)
+    Dash: radial at 45.8°, from radius 23.4 → 103.4 (proportional to animation dL)
+         stroke-width 28 (= dashThickness/ringThickness × 26 = 2.8/2.6 × 26)
+
+    Colors: #2d3436 (dark/top) · #377dff (blue/bottom-left) · #ff4757 (red/tail)
+  -->
+
+  <!-- Dark arc — upper semicircle: left (180°) → top (270°) → right (360°) -->
+  <path
+    d="M 35,100 A 65,65 0 0,1 165,100"
+    stroke="#2d3436"
+    stroke-width="26"
+    stroke-linecap="butt"
+  />
+
+  <!-- Blue arc — bottom-left: gap-end (72.9°) → left (180°) -->
+  <path
+    d="M 119.1,162.1 A 65,65 0 0,1 35,100"
+    stroke="#377dff"
+    stroke-width="26"
+    stroke-linecap="butt"
+  />
+
+  <!-- Red arc — tiny pre-gap sliver: right (0°) → gap-start (18.8°) -->
+  <path
+    d="M 165,100 A 65,65 0 0,1 161.5,121"
+    stroke="#ff4757"
+    stroke-width="26"
+    stroke-linecap="butt"
+  />
+
+  <!-- Red dash — radial tail through the gap -->
+  <line
+    x1="116.3" y1="116.8"
+    x2="172"   y2="174.2"
+    stroke="#ff4757"
+    stroke-width="28"
+    stroke-linecap="butt"
+  />
+</svg>

package/templates/base-project/apps/web/railway.json

@@ -6,10 +6,10 @@
 		"watchPatterns": ["apps/web/**", "packages/**"]
 	},
 	"deploy": {
-		"releaseCommand": "pnpm --filter @techstream/quark-db exec prisma migrate deploy",
+		"releaseCommand": "pnpm --filter './packages/db' exec prisma migrate deploy",
 		"startCommand": "node apps/web/.next/standalone/server.js",
 		"healthcheckPath": "/api/health",
-		"healthcheckTimeout": 30,
+		"healthcheckTimeout": 120,
 		"restartPolicyType": "ON_FAILURE",
 		"restartPolicyMaxRetries": 5
 	}

package/templates/base-project/apps/web/src/app/_components/HealthIndicator.js

@@ -0,0 +1,85 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+const STATUS_COLORS = {
+	ok: "#22c55e",
+	degraded: "#f59e0b",
+	error: "#ef4444",
+};
+
+function Dot({ status, label }) {
+	const dotColor = STATUS_COLORS[status] ?? "var(--quark-health-dot-idle)";
+	return (
+		<span
+			title={`${label}: ${status ?? "checking…"}`}
+			style={{
+				display: "inline-flex",
+				alignItems: "center",
+				gap: "4px",
+				color: "var(--quark-health-text)",
+				fontFamily: "monospace",
+				fontSize: "11px",
+			}}
+		>
+			<span
+				style={{
+					display: "inline-block",
+					width: "5px",
+					height: "5px",
+					borderRadius: "50%",
+					backgroundColor: dotColor,
+					transition: "background-color 0.3s ease",
+					flexShrink: 0,
+				}}
+			/>
+			{label}
+		</span>
+	);
+}
+
+/**
+ * Fetches /api/health once on mount and renders small coloured dots for
+ * database, Redis, and storage status. Shows neutral dots while loading.
+ * Fails silently so the home page aesthetic is never disrupted.
+ * Colours are driven by CSS custom properties (prefers-color-scheme aware).
+ */
+export default function HealthIndicator() {
+	const [checks, setChecks] = useState(null);
+
+	useEffect(() => {
+		let cancelled = false;
+		fetch("/api/health")
+			.then((r) => r.json())
+			.then((data) => {
+				if (!cancelled) setChecks(data.checks ?? {});
+			})
+			.catch(() => {
+				if (!cancelled) setChecks({});
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+
+	return (
+		<div
+			style={{
+				display: "flex",
+				alignItems: "center",
+				gap: "8px",
+				fontFamily: "monospace",
+				fontSize: "11px",
+			}}
+		>
+			<Dot status={checks?.database?.status} label="db" />
+			<span style={{ color: "var(--quark-health-sep)" }}>·</span>
+			<Dot status={checks?.redis?.status} label="redis" />
+			<span style={{ color: "var(--quark-health-sep)" }}>·</span>
+			<Dot
+				status={checks?.storage?.status}
+				label={checks?.storage?.provider ?? "storage"}
+			/>
+		</div>
+	);
+}

package/templates/base-project/apps/web/src/app/_components/HomeThemeToggle.js

@@ -0,0 +1,63 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import {
+	THEME_ATTR,
+	THEME_CHANGE_EVENT,
+	THEME_STORAGE_KEY,
+} from "../../lib/theme.js";
+
+/**
+ * Text-link theme toggle for the home page nav.
+ * Shows "light" when dark mode is active (click to switch to light) and vice versa.
+ * Styled identically to the other nav links via the quark-home-link class.
+ *
+ * Uses the same localStorage key as ThemeProvider (THEME_STORAGE_KEY) and sets
+ * the same HTML attribute (THEME_ATTR) so CSS variables react instantly. Fires
+ * a THEME_CHANGE_EVENT custom event so ThemeProvider (if present) stays in sync
+ * without any import coupling between the two packages.
+ */
+export default function HomeThemeToggle() {
+	const [isDark, setIsDark] = useState(true);
+
+	useEffect(() => {
+		const stored = localStorage.getItem(THEME_STORAGE_KEY);
+		if (stored === "light" || stored === "dark") {
+			setIsDark(stored === "dark");
+			document.documentElement.setAttribute(THEME_ATTR, stored);
+			return;
+		}
+		const osDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+		setIsDark(osDark);
+	}, []);
+
+	function toggle() {
+		setIsDark((prev) => {
+			const next = prev ? "light" : "dark";
+			localStorage.setItem(THEME_STORAGE_KEY, next);
+			document.documentElement.setAttribute(THEME_ATTR, next);
+			// Notify ThemeProvider (if present in the tree) so React context stays in sync.
+			document.dispatchEvent(
+				new CustomEvent(THEME_CHANGE_EVENT, { detail: { theme: next } }),
+			);
+			return !prev;
+		});
+	}
+
+	return (
+		<button
+			type="button"
+			onClick={toggle}
+			aria-label={`Switch to ${isDark ? "light" : "dark"} mode`}
+			className="quark-home-link"
+			style={{
+				background: "none",
+				border: "none",
+				padding: 0,
+				cursor: "pointer",
+			}}
+		>
+			{isDark ? "light" : "dark"}
+		</button>
+	);
+}

package/templates/base-project/apps/web/src/app/_components/QuarkAnimation.js

@@ -0,0 +1,168 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+const CHARS = " .:-=+*#%@";
+const W = 110;
+const H = 55;
+
+const CONF = {
+	zoom: 1.16,
+	speed: 1.7,
+	dashLength: 16,
+	dashThickness: 2.8,
+	dashDistFactor: 0.36,
+	ringGapMultiplier: 0.3,
+	angleLimit: 0.3,
+	yBounce: 1,
+	ringRadius: 13,
+	ringThickness: 2.6,
+	yScaleFactor: 1.05,
+	dashAngle: 0.8,
+};
+
+// Fixed brand palette — all three colors are part of the Quark logo identity.
+const CLASS_COLORS = { s: "#2d3436", b: "#377dff", c: "#ff4757" };
+
+export default function QuarkAnimation() {
+	const ref = useRef(null);
+
+	useEffect(() => {
+		const el = ref.current;
+		if (!el) return;
+
+		let t = 0;
+		let raf;
+
+		function render() {
+			t += 0.01 * CONF.speed;
+
+			const rY = Math.sin(t) * CONF.angleLimit;
+			const yO = Math.sin(t * 1.5) * CONF.yBounce;
+			const cB = new Array(W * H).fill(" ");
+			const clB = new Array(W * H).fill("");
+			const zB = new Float32Array(W * H).fill(-1000);
+
+			const rR = CONF.ringRadius * CONF.zoom;
+			const rT = CONF.ringThickness * CONF.zoom;
+			const dL = CONF.dashLength * CONF.zoom;
+			const dT = CONF.dashThickness * CONF.zoom;
+			const dA = CONF.dashAngle;
+			const gap = (dT / rR) * 0.8 + CONF.ringGapMultiplier;
+
+			// Ring (torus)
+			for (let p = 0; p < Math.PI * 2; p += 0.12) {
+				for (let th = 0; th < Math.PI * 2; th += 0.04) {
+					let d = Math.abs(th - dA);
+					if (d > Math.PI) d = 2 * Math.PI - d;
+					if (d < gap) continue;
+
+					const rXx = Math.cos(th);
+					const rYy = Math.sin(th);
+					const x = (rR + rT * Math.cos(p)) * rXx;
+					const y = (rR + rT * Math.cos(p)) * rYy * CONF.yScaleFactor;
+					const z = rT * Math.sin(p);
+
+					const rx = x * Math.cos(rY) + z * Math.sin(rY);
+					const rz = -x * Math.sin(rY) + z * Math.cos(rY);
+					const ry = y + yO;
+
+					const xp = Math.floor(W / 2 + rx * 1.5);
+					const yp = Math.floor(H / 2 + ry);
+
+					if (xp >= 0 && xp < W && yp >= 0 && yp < H) {
+						const i = yp * W + xp;
+						if (rz > zB[i]) {
+							zB[i] = rz;
+							const nT = ((th % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2);
+							const nD = ((dA % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2);
+							clB[i] = rYy < 0 ? "s" : nT > nD ? "b" : "c";
+							cB[i] =
+								CHARS[
+									Math.floor(
+										Math.max(0, Math.min(1, (rz + rT) / (rT * 2) + 0.3)) *
+											(CHARS.length - 1),
+									)
+								];
+						}
+					}
+				}
+			}
+
+			// Dash (quark)
+			for (let l = 0; l < dL; l += 0.6) {
+				for (let p = 0; p < Math.PI * 2; p += 0.2) {
+					for (let rad = 0; rad < dT; rad += 0.6) {
+						const sR = rR * CONF.dashDistFactor;
+						const lx = rad * Math.cos(p);
+						const ly = rad * Math.sin(p);
+						const lz = l;
+
+						const tx =
+							sR * Math.cos(dA) + lz * Math.cos(dA) - lx * Math.sin(dA);
+						const ty =
+							(sR * Math.sin(dA) + lz * Math.sin(dA) + lx * Math.cos(dA)) *
+							CONF.yScaleFactor;
+						const tz = ly;
+
+						const rtx = tx * Math.cos(rY) + tz * Math.sin(rY);
+						const rtz = -tx * Math.sin(rY) + tz * Math.cos(rY);
+						const rty = ty + yO;
+
+						const xp = Math.floor(W / 2 + rtx * 1.5);
+						const yp = Math.floor(H / 2 + rty);
+
+						if (xp >= 0 && xp < W && yp >= 0 && yp < H) {
+							const i = yp * W + xp;
+							if (rtz > zB[i]) {
+								zB[i] = rtz;
+								clB[i] = "c";
+								cB[i] =
+									CHARS[
+										Math.floor(
+											Math.max(0, Math.min(1, (rtz + dT) / (dT * 2) + 0.3)) *
+												(CHARS.length - 1),
+										)
+									];
+							}
+						}
+					}
+				}
+			}
+
+			// Build HTML string — inline colors avoid global CSS pollution
+			let o = "";
+			for (let i = 0; i < cB.length; i++) {
+				if (i > 0 && i % W === 0) o += "\n";
+				const cls = clB[i];
+				if (cls) {
+					o += `<span style="color:${CLASS_COLORS[cls]}">${cB[i]}</span>`;
+				} else {
+					o += cB[i];
+				}
+			}
+
+			el.innerHTML = o;
+			raf = requestAnimationFrame(render);
+		}
+
+		render();
+		return () => cancelAnimationFrame(raf);
+	}, []);
+
+	return (
+		<div
+			ref={ref}
+			style={{
+				lineHeight: "0.82",
+				letterSpacing: "0",
+				whiteSpace: "pre",
+				textAlign: "center",
+				fontSize: "11px",
+				fontWeight: "bold",
+				fontFamily: "monospace",
+				color: "#e0e0e0",
+			}}
+		/>
+	);
+}

package/templates/base-project/apps/web/src/app/api/health/route.js

@@ -4,8 +4,8 @@
  * Times out after 5 seconds to prevent hanging.
  */
 
-import { createLogger, pingRedis } from "@techstream/quark-core";
-import { prisma } from "@techstream/quark-db";
+import { createLogger, createStorage, pingRedis } from "@techstream/quark-core";
+import { pingDatabase } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
 
 const logger = createLogger("health");
@@ -15,18 +15,25 @@ const HEALTH_CHECK_TIMEOUT = 5000;
 
 export async function GET() {
 	try {
-		const result = await Promise.race([
-			runHealthChecks(),
-			new Promise((_, reject) =>
-				setTimeout(
-					() => reject(new Error("Health check timed out")),
-					HEALTH_CHECK_TIMEOUT,
-				),
-			),
-		]);
+		const result = await new Promise((resolve, reject) => {
+			const timer = setTimeout(
+				() => reject(new Error("Health check timed out")),
+				HEALTH_CHECK_TIMEOUT,
+			);
+			runHealthChecks().then(
+				(val) => {
+					clearTimeout(timer);
+					resolve(val);
+				},
+				(err) => {
+					clearTimeout(timer);
+					reject(err);
+				},
+			);
+		});
 
 		return NextResponse.json(result, {
-			status: result.status === "ok" ? 200 : 503,
+			status: result.status === "error" ? 503 : 200,
 		});
 	} catch (error) {
 		logger.error("Health check failed", {
@@ -56,13 +63,13 @@ async function runHealthChecks() {
 	};
 
 	// Check database connectivity
-	try {
-		await prisma.$queryRaw`SELECT 1`;
-		health.checks.database = { status: "ok" };
-	} catch (error) {
+	const dbResult = await pingDatabase();
+	if (dbResult.status === "ok") {
+		health.checks.database = { status: "ok", latencyMs: dbResult.latencyMs };
+	} else {
 		health.checks.database = {
 			status: "error",
-			message: error.message,
+			message: dbResult.message,
 		};
 		health.status = "degraded";
 	}
@@ -79,5 +86,37 @@ async function runHealthChecks() {
 		health.status = "degraded";
 	}
 
+	// Check storage connectivity
+	const storageResult = await checkStorage();
+	health.checks.storage = storageResult;
+	if (storageResult.status === "error") {
+		health.status = "degraded";
+	}
+
 	return health;
 }
+
+/**
+ * Verifies storage is reachable and writable by writing then deleting a
+ * small sentinel object. Uses whichever provider is configured via
+ * STORAGE_PROVIDER (defaults to "local" when unset).
+ * @returns {Promise<{ status: string, provider: string, message?: string }>}
+ */
+async function checkStorage() {
+	const provider = process.env.STORAGE_PROVIDER || "local";
+	try {
+		const storage = createStorage();
+		const sentinelKey = ".health-check-sentinel";
+		await storage.put(sentinelKey, Buffer.from("ok"), {
+			contentType: "text/plain",
+		});
+		await storage.delete(sentinelKey);
+		return { status: "ok", provider };
+	} catch (error) {
+		const message =
+			process.env.NODE_ENV === "production"
+				? "Storage unavailable"
+				: error.message;
+		return { status: "error", provider, message };
+	}
+}