@techstream/quark-create-app 1.9.0 → 1.10.0

package/templates/base-project/apps/web/src/app/icon.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/src/app/layout.js

@@ -1,3 +1,4 @@
+import "./globals.css";
 import { getSiteMetadata } from "../lib/seo/site-metadata.js";
 
 export const metadata = getSiteMetadata();

package/templates/base-project/apps/web/src/app/not-found.js

@@ -0,0 +1,35 @@
+import Link from "next/link";
+
+export const metadata = {
+	title: "404 — Not Found",
+};
+
+export default function NotFound() {
+	return (
+		<main
+			style={{ background: "#05070a" }}
+			className="fixed inset-0 flex flex-col items-center justify-center"
+		>
+			<p
+				className="font-mono uppercase"
+				style={{ color: "#3a3a4a", fontSize: "11px", letterSpacing: "0.15em" }}
+			>
+				404
+			</p>
+			<p
+				className="font-mono mt-2"
+				style={{ color: "#2a2a3a", fontSize: "11px" }}
+			>
+				page not found
+			</p>
+			<nav
+				className="mt-6"
+				style={{ fontSize: "11px", fontFamily: "monospace" }}
+			>
+				<Link href="/" className="quark-home-link">
+					← home
+				</Link>
+			</nav>
+		</main>
+	);
+}

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

@@ -1,10 +1,43 @@
+import HealthIndicator from "./_components/HealthIndicator.js";
+import HomeThemeToggle from "./_components/HomeThemeToggle.js";
+import QuarkAnimation from "./_components/QuarkAnimation.js";
+
 export default function Home() {
 	return (
-		<main className="min-h-screen flex flex-col items-center justify-center p-8">
-			<h1 className="text-4xl font-bold text-center mb-4">Quark</h1>
-			<p className="text-lg text-gray-600 text-center max-w-md">
-				Welcome to the Quark monorepo. This is a Next.js 16 app with React 19.
-			</p>
+		<main className="quark-home-main min-h-screen flex flex-col items-center justify-center">
+			{/* Hero: animated ASCII logo, centered */}
+			<QuarkAnimation />
+
+			{/* Footer — flows naturally below the animation */}
+			<div className="quark-home-footer flex flex-col items-center gap-2 pt-8 pb-8">
+				{/* Identity */}
+				<p className="quark-home-label font-mono uppercase">Your Quark App</p>
+
+				{/* Navigation */}
+				<nav className="flex items-center gap-2">
+					<a href="/api/health" className="quark-home-link">
+						health
+					</a>
+					<span className="quark-home-sep">·</span>
+					<a href="/playground" className="quark-home-link">
+						playground
+					</a>
+					<span className="quark-home-sep">·</span>
+					<a
+						href="https://www.npmjs.com/package/@techstream/quark-create-app"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="quark-home-link"
+					>
+						npm
+					</a>
+					<span className="quark-home-sep">·</span>
+					<HomeThemeToggle />
+				</nav>
+
+				{/* Status — supplementary, last */}
+				<HealthIndicator />
+			</div>
 		</main>
 	);
 }

package/templates/base-project/apps/web/src/lib/theme.js

@@ -0,0 +1,23 @@
+/**
+ * Theme system constants for the home page shell.
+ *
+ * These three values form the contract between HomeThemeToggle and any
+ * ThemeProvider that may be present in the tree (e.g. from @techstream/quark-ui).
+ *
+ * An identical copy lives in packages/ui/src/theme-constants.js — each
+ * package owns its own copy so there is no cross-package import. If you
+ * rename any of these, update both files and the CSS selectors in globals.css.
+ */
+
+/** Key used to persist the user's explicit theme choice in localStorage. */
+export const THEME_STORAGE_KEY = "quark-theme";
+
+/**
+ * Attribute set on <html> so CSS custom properties can react to JS state.
+ * Use via element.setAttribute(THEME_ATTR, value) / element.getAttribute(THEME_ATTR).
+ * Referenced in globals.css as [data-theme="light"] / [data-theme="dark"].
+ */
+export const THEME_ATTR = "data-theme";
+
+/** CustomEvent name dispatched when the theme changes outside a ThemeProvider. */
+export const THEME_CHANGE_EVENT = "quark-theme-change";

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

@@ -92,7 +92,16 @@ const CORS_CONFIG = {
 
 /**
  * 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 _scriptSrc =
+	process.env.NODE_ENV !== "production"
+		? "script-src 'self' 'unsafe-inline' 'unsafe-eval'"
+		: "script-src 'self' 'unsafe-inline'";
+
 const SECURITY_HEADERS = {
 	"X-DNS-Prefetch-Control": "on",
 	"Strict-Transport-Security": "max-age=63072000; includeSubDomains",
@@ -100,8 +109,7 @@ const SECURITY_HEADERS = {
 	"X-Content-Type-Options": "nosniff",
 	"Referrer-Policy": "strict-origin-when-cross-origin",
 	"Permissions-Policy": "camera=(), microphone=(), geolocation=()",
-	"Content-Security-Policy":
-		"default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';",
+	"Content-Security-Policy": `default-src 'self'; ${_scriptSrc}; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';`,
 };
 
 /**

package/templates/base-project/package.json

@@ -16,6 +16,8 @@
 		"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",
 		"prepare": "simple-git-hooks"
 	},
 	"simple-git-hooks": {

package/templates/base-project/packages/db/src/client.js

@@ -41,10 +41,15 @@ function getPrismaClient() {
 /**
  * Prisma client singleton. Lazily initialized on first use so the module
  * can be imported safely at build time (no DB env vars needed).
+ *
+ * Methods are bound to the real client so `this` inside Prisma internals is
+ * always the PrismaClient instance, never the Proxy wrapper.
  */
 export const prisma = new Proxy(/** @type {PrismaClient} */ ({}), {
 	get(_target, prop) {
-		return getPrismaClient()[prop];
+		const client = getPrismaClient();
+		const value = client[prop];
+		return typeof value === "function" ? value.bind(client) : value;
 	},
 });
 

package/templates/base-project/packages/db/src/index.js

@@ -1,3 +1,4 @@
 export * from "./client.js";
+export * from "./ping.js";
 export * from "./queries.js";
 export * from "./schemas.js";

package/templates/base-project/packages/db/src/ping.js

@@ -0,0 +1,66 @@
+import { getConnectionString } from "./connection.js";
+
+/**
+ * Pings PostgreSQL to verify connectivity.
+ * Uses a raw `pg.Client` directly so the check is immune to Prisma
+ * adapter quirks — in particular, Prisma 7 + @prisma/adapter-pg surfaces
+ * connection failures as a misleading "Invalid invocation" error rather
+ * than a proper ECONNREFUSED.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeout=3000] - Connection/query timeout in milliseconds.
+ * @returns {Promise<{ status: "ok", latencyMs: number } | { status: "error", message: string }>}
+ */
+export async function pingDatabase({ timeout = 3000 } = {}) {
+	/** @type {import("pg").Client | null} */
+	let client = null;
+	let connectionString;
+
+	try {
+		const { default: pg } = await import("pg");
+		connectionString = getConnectionString();
+
+		client = new pg.Client({
+			connectionString,
+			connectionTimeoutMillis: timeout,
+			query_timeout: timeout,
+		});
+
+		await client.connect();
+
+		const start = performance.now();
+		await client.query("SELECT 1");
+		const latencyMs = Math.round(performance.now() - start);
+
+		return { status: "ok", latencyMs };
+	} catch (/** @type {any} */ error) {
+		let message;
+		if (
+			error?.code === "MODULE_NOT_FOUND" ||
+			error?.code === "ERR_MODULE_NOT_FOUND"
+		) {
+			message = "pg is not installed";
+		} else if (
+			error?.code === "ECONNREFUSED" ||
+			/ECONNREFUSED/i.test(error?.message ?? "")
+		) {
+			try {
+				const { hostname, port } = new URL(connectionString);
+				message = `PostgreSQL unreachable at ${hostname}:${port || "5432"}`;
+			} catch {
+				message = "PostgreSQL unreachable";
+			}
+		} else if (error?.code === "ENOTFOUND") {
+			message = `PostgreSQL host not found: ${error.hostname ?? "unknown"}`;
+		} else {
+			message = error?.message ?? String(error);
+		}
+		return { status: "error", message };
+	} finally {
+		try {
+			await client?.end();
+		} catch {
+			// ignore disconnect errors
+		}
+	}
+}

package/templates/base-project/scripts/doctor.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * scripts/doctor.js
+ *
+ * Audits this project for unfinished post-scaffold customisation.
+ * Run it at any time — it is safe, read-only by default.
+ *
+ * Usage:
+ *   pnpm doctor          # Audit only
+ *   pnpm doctor:fix      # Audit + auto-remove Quark aesthetic scaffolding
+ *
+ * Extend the CHECKS array below to add your own project-specific rules.
+ * This script has zero external dependencies.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "..");
+const FIX = process.argv.includes("--fix");
+
+// ─── ANSI helpers ─────────────────────────────────────────────────────────────
+
+const c = {
+	reset: "\x1b[0m",
+	bold: "\x1b[1m",
+	dim: "\x1b[2m",
+	red: "\x1b[31m",
+	green: "\x1b[32m",
+	yellow: "\x1b[33m",
+	blue: "\x1b[34m",
+};
+
+const fmt = {
+	bold: (s) => `${c.bold}${s}${c.reset}`,
+	dim: (s) => `${c.dim}${s}${c.reset}`,
+	red: (s) => `${c.red}${s}${c.reset}`,
+	green: (s) => `${c.green}${s}${c.reset}`,
+	yellow: (s) => `${c.yellow}${s}${c.reset}`,
+	blue: (s) => `${c.blue}${s}${c.reset}`,
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function exists(rel) {
+	return fs.existsSync(path.join(ROOT, rel));
+}
+
+function read(rel) {
+	const abs = path.join(ROOT, rel);
+	return fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
+}
+
+/** Remove a file or directory tree (relative to ROOT). */
+function remove(rel) {
+	const abs = path.join(ROOT, rel);
+	fs.rmSync(abs, { recursive: true, force: true });
+}
+
+// ─── Finding model ────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{ category: string, status: 'error'|'warn'|'info', key: string,
+ *             message: string, detail: string, fix: string, fixable: boolean }} Finding
+ */
+
+/** @type {Finding[]} */
+const findings = [];
+
+function warn(key, category, message, detail, fix, fixable = false) {
+	findings.push({ category, status: "warn", key, message, detail, fix, fixable });
+}
+
+function error(key, category, message, detail, fix, fixable = false) {
+	findings.push({ category, status: "error", key, message, detail, fix, fixable });
+}
+
+function info(key, category, message, detail, fix) {
+	findings.push({ category, status: "info", key, message, detail, fix, fixable: false });
+}
+
+// ─── Checks ───────────────────────────────────────────────────────────────────
+
+// Read .quark-link.json to understand what packages were included at scaffold time.
+const quarkLink = (() => {
+	try {
+		return JSON.parse(read(".quark-link.json") ?? "{}");
+	} catch {
+		return {};
+	}
+})();
+const hasUI = Array.isArray(quarkLink.packages) && quarkLink.packages.includes("ui");
+
+// ── Check 1: Quark Animation still present ────────────────────────────────────
+if (exists("apps/web/src/app/_components/QuarkAnimation.js")) {
+	warn(
+		"quark-animation",
+		"branding",
+		"QuarkAnimation is still in the project",
+		"apps/web/src/app/_components/QuarkAnimation.js",
+		"Replace or remove the animation and update the home page with your own hero content",
+		true,
+	);
+}
+
+// ── Check 2: Playground page present (only relevant with UI package) ──────────
+if (hasUI && exists("apps/web/src/app/playground")) {
+	warn(
+		"playground",
+		"branding",
+		"Playground page is still present",
+		"apps/web/src/app/playground/",
+		"Consider removing the playground before going to production",
+		true,
+	);
+}
+
+// ── Check 3: APP_NAME / APP_DESCRIPTION still reference "Quark" ───────────────
+const envContent = read(".env");
+if (envContent) {
+	const nameMatch = envContent.match(/^APP_NAME=(.+)$/m);
+	const descMatch = envContent.match(/^APP_DESCRIPTION=(.+)$/m);
+	const nameVal = nameMatch?.[1]?.trim() ?? "";
+	const descVal = descMatch?.[1]?.trim() ?? "";
+
+	if (/\bquark\b/i.test(nameVal) || /\bquark\b/i.test(descVal)) {
+		warn(
+			"app-identity",
+			"metadata",
+			'APP_NAME or APP_DESCRIPTION still references "Quark"',
+			`.env → APP_NAME="${nameVal}", APP_DESCRIPTION="${descVal}"`,
+			"Update APP_NAME and APP_DESCRIPTION in your .env to match your project",
+		);
+	}
+}
+
+// ── Check 4: Placeholder secrets (CHANGE_ME) left in .env ────────────────────
+if (envContent && envContent.includes("CHANGE_ME")) {
+	const lines = envContent
+		.split("\n")
+		.map((l, i) => ({ line: i + 1, text: l }))
+		.filter(({ text }) => text.includes("CHANGE_ME"))
+		.map(({ line, text }) => `  line ${line}: ${text.split("=")[0]}`);
+
+	error(
+		"secrets",
+		"security",
+		"CHANGE_ME placeholders found in .env — rotate these before deploying",
+		lines.join("\n"),
+		"Replace every CHANGE_ME value with a real secret",
+	);
+}
+
+// ── Check 5: .env missing vars that exist in .env.example ────────────────────
+const exampleContent = read(".env.example");
+if (envContent && exampleContent) {
+	const defined = new Set(
+		envContent
+			.split("\n")
+			.filter((l) => l.includes("=") && !l.startsWith("#"))
+			.map((l) => l.split("=")[0].trim()),
+	);
+	const missing = exampleContent
+		.split("\n")
+		.filter((l) => l.includes("=") && !l.startsWith("#"))
+		.map((l) => l.split("=")[0].trim())
+		.filter((k) => k && !defined.has(k));
+
+	if (missing.length > 0) {
+		warn(
+			"env-missing",
+			"configuration",
+			`.env.example defines ${missing.length} key(s) not present in .env`,
+			missing.map((k) => `  ${k}`).join("\n"),
+			"Add the missing keys to your .env (copy from .env.example and fill in values)",
+		);
+	}
+}
+
+// ── Check 6: README still contains Quark template content ────────────────────
+const readmeContent = read("README.md");
+if (readmeContent && /quark/i.test(readmeContent)) {
+	info(
+		"readme",
+		"documentation",
+		"README.md still contains references to Quark",
+		"README.md",
+		"Update the README to describe your own project",
+	);
+}
+
+// ─── --fix: auto-remove fixable items ────────────────────────────────────────
+
+const STATUS_ICON = { error: "✗", warn: "⚠", info: "·" };
+const STATUS_COLOR = { error: fmt.red, warn: fmt.yellow, info: fmt.dim };
+
+// Print the report first so users see what was found before anything is changed.
+console.log(fmt.bold(fmt.blue("\n🩺 Quark Doctor\n")));
+
+if (findings.length === 0) {
+	console.log(fmt.green("  ✓ Nothing to do — project looks clean!\n"));
+	process.exit(0);
+}
+
+// Group by category
+const categories = [...new Set(findings.map((f) => f.category))];
+for (const cat of categories) {
+	console.log(fmt.bold(`  ${cat}`));
+	for (const f of findings.filter((f) => f.category === cat)) {
+		const icon = STATUS_ICON[f.status];
+		const colorFn = STATUS_COLOR[f.status];
+		console.log(`    ${colorFn(`${icon} ${f.message}`)}`);
+		if (f.detail) {
+			for (const line of f.detail.split("\n")) {
+				console.log(fmt.dim(`      ${line}`));
+			}
+		}
+		if (!FIX || !f.fixable) {
+			console.log(fmt.dim(`      → ${f.fix}`));
+		}
+	}
+	console.log();
+}
+
+const errorCount = findings.filter((f) => f.status === "error").length;
+const warnCount = findings.filter((f) => f.status === "warn").length;
+const fixableCount = findings.filter((f) => f.fixable).length;
+
+const parts = [];
+if (errorCount) parts.push(fmt.red(`${errorCount} error${errorCount > 1 ? "s" : ""}`));
+if (warnCount) parts.push(fmt.yellow(`${warnCount} warning${warnCount > 1 ? "s" : ""}`));
+console.log(fmt.bold(`  Summary: ${parts.join(", ")}`));
+
+if (FIX) {
+	const fixable = findings.filter((f) => f.fixable);
+	if (fixable.length === 0) {
+		console.log(fmt.dim("  No auto-fixable items found.\n"));
+	} else {
+		console.log(fmt.bold(fmt.blue("\n🔧 Applying fixes…\n")));
+		for (const f of fixable) {
+			if (f.key === "quark-animation") {
+				remove("apps/web/src/app/_components/QuarkAnimation.js");
+				console.log(fmt.green(`  ✓ Removed QuarkAnimation.js`));
+			} else if (f.key === "playground") {
+				remove("apps/web/src/app/playground");
+				console.log(fmt.green(`  ✓ Removed apps/web/src/app/playground/`));
+			}
+		}
+		console.log();
+	}
+} else if (fixableCount > 0) {
+	console.log(
+		fmt.dim(`  ${fixableCount} item(s) can be auto-removed with: pnpm doctor:fix\n`),
+	);
+} else {
+	console.log();
+}
+
+if (errorCount > 0) process.exit(1);

package/templates/base-project/turbo.json

@@ -18,7 +18,8 @@
 			"outputs": ["node_modules/.prisma/client"]
 		},
 		"db:migrate": {
-			"cache": false
+			"cache": false,
+			"interactive": true
 		},
 		"db:push": {
 			"cache": false

package/templates/config/package.json

@@ -2,6 +2,7 @@
 	"name": "@myquark/config",
 	"version": "1.0.0",
 	"type": "module",
+	"main": "src/index.js",
 	"exports": {
 		".": "./src/index.js",
 		"./app-url": "./src/app-url.js",

package/templates/jobs/package.json

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

package/templates/ui/README.md

@@ -0,0 +1,67 @@
+# @yourscope/ui
+
+Scaffolded UI primitives for your Quark project. These components are **yours** — modify, extend, or replace them freely.
+
+> This package is scaffolded via `quark-create-app`. There is no version sync back to Quark after scaffolding.
+
+## Import
+
+```javascript
+import { Button, Card, Badge } from '@yourscope/ui';
+```
+
+## Components
+
+### Button
+Props: `variant` ('primary' | 'secondary' | 'danger' | 'ghost', default: 'primary'), `size` ('sm' | 'md' | 'lg', default: 'md'), `className`, all native button attributes.
+
+### Input
+Props: `className`, all native input attributes.
+
+### Label
+Props: `className`, all native label attributes.
+
+### Textarea
+Props: `className`, all native textarea attributes.
+
+### Select
+Props: `className`, `children` (option elements), all native select attributes.
+
+### Checkbox
+Props: `id`, `label` (string), `className`, all native checkbox input attributes.
+
+### Badge
+Props: `variant` ('default' | 'success' | 'warning' | 'danger' | 'info', default: 'default'), `className`.
+
+### Card / CardHeader / CardTitle / CardContent / CardFooter
+Composable card container. All parts accept `className`.
+
+### Table / TableHeader / TableBody / TableRow / TableHead / TableCell
+Composable table. `Table` wraps in a scrollable container. All parts accept `className`.
+
+### Skeleton
+Props: `className` (use to set width/height for the placeholder shape).
+
+### Dialog
+`"use client"` — Props: `open` (bool), `onClose` (fn), `title` (string), `children`, `className`.
+
+### Toast / useToast
+`"use client"` — `Toast` props: `message`, `variant` ('default' | 'success' | 'error'), `onClose` (fn), `visible` (bool).  
+`useToast()` returns `{ show(message, variant?), hide, toastProps }`. Spread `toastProps` onto `<Toast />`.
+
+```javascript
+// Example
+const { show, toastProps } = useToast();
+return (
+  <>
+    <Button onClick={() => show('Saved!', 'success')}>Save</Button>
+    <Toast {...toastProps} />
+  </>
+);
+```
+
+## Design notes
+- Tailwind CSS only. No CSS-in-JS, no external dependencies.
+- All components accept `className` for overrides.
+- Server Component compatible except Dialog and Toast (marked `"use client"`).
+- Accessible: ARIA attributes, focus management on interactive elements.

package/templates/ui/package.json

@@ -2,6 +2,7 @@
 	"name": "@myquark/ui",
 	"version": "1.0.0",
 	"type": "module",
+	"main": "src/index.js",
 	"devDependencies": {
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",