@usequark/quark-create-app 1.23.11

package/templates/ui/src/theme.js

@@ -0,0 +1,196 @@
+"use client";
+import React, {
+	createContext,
+	useCallback,
+	useContext,
+	useEffect,
+	useLayoutEffect,
+	useState,
+} from "react";
+import {
+	THEME_ATTR,
+	THEME_CHANGE_EVENT,
+	THEME_STORAGE_KEY,
+} from "./theme-constants.js";
+
+const ThemeCtx = createContext({ theme: "dark", setTheme: () => {} });
+
+/**
+ * Wraps a subtree with a shared theme value.
+ *
+ * Behaviour:
+ * - If `defaultTheme` is provided it is used as the fallback when no stored
+ *   preference exists (good for pages with a deliberate starting theme).
+ * - If `defaultTheme` is omitted the fallback is the OS `prefers-color-scheme`
+ *   media query, evaluated after hydration in a layout effect.
+ * - The user's explicit toggle choice is persisted to
+ *   `localStorage` under the key `quark-theme` and restored on subsequent
+ *   visits so their preference is remembered across sessions.
+ *
+ * @param {{ defaultTheme?: 'light' | 'dark', children: React.ReactNode }} props
+ */
+export function ThemeProvider({ defaultTheme, children }) {
+	// Always initialize from the server-safe default. The lazy initialiser cannot
+	// run during React hydration (React reuses the server state), so we sync to
+	// the real user preference in a layout effect instead.
+	const [theme, setTheme] = useState(defaultTheme ?? "dark");
+
+	// useLayoutEffect fires synchronously after DOM mutations but BEFORE the
+	// browser paints, so the toggle snaps to the correct position with no
+	// visible flash. On the server it is a no-op (same as useEffect).
+	useLayoutEffect(() => {
+		const stored = localStorage.getItem(THEME_STORAGE_KEY);
+		const resolved =
+			stored === "light" || stored === "dark"
+				? stored
+				: (defaultTheme ??
+					(window.matchMedia("(prefers-color-scheme: dark)").matches
+						? "dark"
+						: "light"));
+		document.documentElement.setAttribute(THEME_ATTR, resolved);
+		setTheme(resolved);
+	}, [defaultTheme]);
+
+	const persistSetTheme = useCallback((t) => {
+		localStorage.setItem(THEME_STORAGE_KEY, t);
+		document.documentElement.setAttribute(THEME_ATTR, t);
+		setTheme(t);
+	}, []);
+
+	// Keep state and DOM in sync when the OS colour scheme changes (only
+	// relevant when no defaultTheme was provided and the user has no stored
+	// preference). Must call persistSetTheme so data-theme and CSS vars update.
+	useEffect(() => {
+		const stored = localStorage.getItem(THEME_STORAGE_KEY);
+		if (stored || defaultTheme != null) return;
+		const mq = window.matchMedia("(prefers-color-scheme: dark)");
+		const onChange = (e) => persistSetTheme(e.matches ? "dark" : "light");
+		mq.addEventListener("change", onChange);
+		return () => mq.removeEventListener("change", onChange);
+	}, [defaultTheme, persistSetTheme]);
+
+	// Listen for toggles fired by HomeThemeToggle (or any other out-of-tree
+	// component) so React context stays in sync without any import coupling.
+	useEffect(() => {
+		function onExternalChange(e) {
+			const t = e.detail?.theme;
+			if (t === "light" || t === "dark") setTheme(t);
+		}
+		document.addEventListener(THEME_CHANGE_EVENT, onExternalChange);
+		return () =>
+			document.removeEventListener(THEME_CHANGE_EVENT, onExternalChange);
+	}, []);
+
+	return React.createElement(
+		ThemeCtx.Provider,
+		{ value: { theme, setTheme: persistSetTheme } },
+		children,
+	);
+}
+
+/**
+ * Returns the current theme and a setter from the nearest ThemeProvider.
+ * Falls back to `{ theme: 'dark' }` when used outside a provider.
+ *
+ * @returns {{ theme: 'light' | 'dark', setTheme: (t: string) => void }}
+ */
+export function useTheme() {
+	return useContext(ThemeCtx);
+}
+
+/**
+ * Labeled pill button that shows the current theme and switches on click.
+ * Displays "🌙 Dark Mode" when dark, "☀ Light Mode" when light.
+ * Must be rendered inside a ThemeProvider.
+ */
+export function ThemeToggle({ className = "" }) {
+	const { theme, setTheme } = useTheme();
+	const isDark = theme === "dark";
+
+	const icon = isDark
+		? React.createElement(
+				"svg",
+				{
+					"aria-hidden": "true",
+					width: "13",
+					height: "13",
+					viewBox: "0 0 24 24",
+					fill: "currentColor",
+					className: "shrink-0",
+				},
+				React.createElement("path", {
+					d: "M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z",
+				}),
+			)
+		: React.createElement(
+				"svg",
+				{
+					"aria-hidden": "true",
+					width: "13",
+					height: "13",
+					viewBox: "0 0 24 24",
+					fill: "none",
+					stroke: "currentColor",
+					strokeWidth: "2",
+					strokeLinecap: "round",
+					strokeLinejoin: "round",
+					className: "shrink-0",
+				},
+				React.createElement("circle", { cx: "12", cy: "12", r: "5" }),
+				React.createElement("line", { x1: "12", y1: "1", x2: "12", y2: "3" }),
+				React.createElement("line", { x1: "12", y1: "21", x2: "12", y2: "23" }),
+				React.createElement("line", {
+					x1: "4.22",
+					y1: "4.22",
+					x2: "5.64",
+					y2: "5.64",
+				}),
+				React.createElement("line", {
+					x1: "18.36",
+					y1: "18.36",
+					x2: "19.78",
+					y2: "19.78",
+				}),
+				React.createElement("line", { x1: "1", y1: "12", x2: "3", y2: "12" }),
+				React.createElement("line", { x1: "21", y1: "12", x2: "23", y2: "12" }),
+				React.createElement("line", {
+					x1: "4.22",
+					y1: "19.78",
+					x2: "5.64",
+					y2: "18.36",
+				}),
+				React.createElement("line", {
+					x1: "18.36",
+					y1: "5.64",
+					x2: "19.78",
+					y2: "4.22",
+				}),
+			);
+
+	return React.createElement(
+		"button",
+		{
+			type: "button",
+			onClick: () => setTheme(isDark ? "light" : "dark"),
+			"aria-label": `Switch to ${isDark ? "light" : "dark"} theme`,
+			"aria-pressed": isDark,
+			className:
+				`inline-flex items-center cursor-pointer whitespace-nowrap shrink-0 outline-none transition-[background,border-color,color] duration-150 ease-in ${className || ""}`.trim(),
+			style: {
+				gap: "var(--toggle-gap, 6px)",
+				height: "var(--toggle-height, 28px)",
+				paddingLeft: "var(--toggle-padding-x, 10px)",
+				paddingRight: "var(--toggle-padding-x-right, 12px)",
+				borderRadius: "var(--toggle-radius, 14px)",
+				border: "1px solid var(--toggle-track-border)",
+				background: "var(--toggle-track-bg)",
+				color: "var(--toggle-text, var(--color-text-muted))",
+				fontSize: "var(--toggle-font-size, 12px)",
+				fontWeight: "500",
+				letterSpacing: "0.01em",
+			},
+		},
+		icon,
+		isDark ? "Dark Mode" : "Light Mode",
+	);
+}

package/templates/ui/src/toast.js

@@ -0,0 +1,206 @@
+"use client";
+import React, { useCallback, useEffect, useRef, useState } from "react";
+
+const RADIUS = 9;
+const CIRC = 2 * Math.PI * RADIUS;
+
+// Visual properties driven entirely by CSS variables — see globals.css
+// [data-toast-variant] selectors override --toast-bg, --toast-border, --toast-text, --toast-shadow
+
+export function Toast({
+	message,
+	variant = "default",
+	onClose,
+	visible = true,
+	duration = 4000,
+	_toastId,
+}) {
+	const [progress, setProgress] = useState(100);
+	const [hovered, setHovered] = useState(false);
+	const [isAnimatingOut, setIsAnimatingOut] = useState(false);
+	const [shouldRender, setShouldRender] = useState(visible);
+
+	const variantCls =
+		"bg-[--toast-bg] border-[--toast-border] text-[--toast-text] shadow-[var(--toast-shadow)]";
+
+	const remainingRef = useRef(duration);
+	const startRef = useRef(null);
+	const intervalRef = useRef(null);
+	const isClosingRef = useRef(false);
+
+	const stop = useCallback(() => clearInterval(intervalRef.current), []);
+
+	const start = useCallback(() => {
+		stop();
+		startRef.current = Date.now();
+		intervalRef.current = setInterval(() => {
+			const elapsed = Date.now() - startRef.current;
+			const pct = Math.max(0, 100 - (elapsed / remainingRef.current) * 100);
+			setProgress(pct);
+			if (pct <= 0) {
+				stop();
+				onClose?.();
+			}
+		}, 16);
+	}, [stop, onClose]);
+
+	useEffect(() => {
+		if (visible) {
+			setShouldRender(true);
+			setIsAnimatingOut(false);
+			isClosingRef.current = false;
+			remainingRef.current = duration;
+			setProgress(100);
+			setHovered(false);
+			start();
+		} else {
+			if (isClosingRef.current) return;
+			isClosingRef.current = true;
+			setIsAnimatingOut(true);
+			stop();
+			// Wait for animation to finish before removing from DOM
+			const t = setTimeout(() => {
+				setShouldRender(false);
+				setIsAnimatingOut(false);
+				isClosingRef.current = false;
+			}, 200);
+			return () => clearTimeout(t);
+		}
+		return stop;
+	}, [visible, duration, start, stop]);
+
+	useEffect(() => {
+		if (!visible || isAnimatingOut) return;
+		if (hovered) {
+			stop();
+		} else {
+			remainingRef.current = duration;
+			start();
+		}
+	}, [hovered, duration, start, stop, visible, isAnimatingOut]);
+
+	if (!shouldRender) return null;
+
+	const dashOffset = CIRC * (1 - progress / 100);
+
+	const animStyle = isAnimatingOut
+		? { animation: "quark-toast-out 0.2s ease-in forwards" }
+		: {
+				animation:
+					"quark-toast-in 0.25s cubic-bezier(0.16, 1, 0.3, 1) forwards",
+			};
+
+	return React.createElement(
+		"div",
+		{
+			role: "alert",
+			"aria-live": "assertive",
+			"data-toast-variant": variant,
+			onMouseEnter: () => setHovered(true),
+			onMouseLeave: () => setHovered(false),
+			className: `fixed bottom-4 right-4 z-50 flex items-center gap-3 rounded-[--radius-default] px-4 py-3 text-sm transition-colors duration-200 ${variantCls}`,
+			style: animStyle,
+		},
+		React.createElement("span", null, message),
+		React.createElement(
+			"div",
+			{
+				className:
+					"relative ml-2 flex h-6 w-6 shrink-0 items-center justify-center",
+			},
+			hovered
+				? React.createElement(
+						"button",
+						{
+							type: "button",
+							"aria-label": "Dismiss notification",
+							onClick: onClose,
+							className:
+								"flex h-6 w-6 cursor-pointer items-center justify-center rounded-[--radius-default] text-base leading-none opacity-80 transition-all hover:bg-black/10 dark:hover:bg-white/10 hover:opacity-100 active:bg-black/20 dark:active:bg-white/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/60",
+						},
+						React.createElement(
+							"svg",
+							{
+								width: 10,
+								height: 10,
+								viewBox: "0 0 10 10",
+								"aria-hidden": "true",
+								fill: "none",
+								className: "shrink-0",
+							},
+							React.createElement("path", {
+								d: "M1 1L9 9",
+								stroke: "currentColor",
+								strokeWidth: 1.5,
+								strokeLinecap: "round",
+							}),
+							React.createElement("path", {
+								d: "M9 1L1 9",
+								stroke: "currentColor",
+								strokeWidth: 1.5,
+								strokeLinecap: "round",
+							}),
+						),
+					)
+				: React.createElement(
+						"svg",
+						{
+							width: 24,
+							height: 24,
+							viewBox: "0 0 24 24",
+							"aria-hidden": "true",
+						},
+						React.createElement("circle", {
+							cx: 12,
+							cy: 12,
+							r: RADIUS,
+							fill: "none",
+							stroke: "currentColor",
+							strokeOpacity: 0.2,
+							strokeWidth: 2,
+						}),
+						React.createElement("circle", {
+							cx: 12,
+							cy: 12,
+							r: RADIUS,
+							fill: "none",
+							stroke: "currentColor",
+							strokeWidth: 2,
+							strokeLinecap: "round",
+							strokeDasharray: CIRC,
+							strokeDashoffset: dashOffset,
+							style: { transform: "rotate(-90deg)", transformOrigin: "center" },
+						}),
+					),
+		),
+	);
+}
+
+export function useToast() {
+	const [state, setState] = useState({
+		visible: false,
+		message: "",
+		variant: "default",
+		duration: 4000,
+		toastId: 0,
+	});
+
+	const show = useCallback(
+		(message, variant = "default", duration = 4000) =>
+			setState((s) => ({
+				visible: true,
+				message,
+				variant,
+				duration,
+				toastId: s.toastId + 1,
+			})),
+		[],
+	);
+
+	const hide = useCallback(
+		() => setState((s) => ({ ...s, visible: false })),
+		[],
+	);
+
+	return { show, hide, toastProps: { ...state, onClose: hide } };
+}

package/templates/worker/Dockerfile

@@ -0,0 +1,64 @@
+FROM node:22-alpine@sha256:9385cd9f3001dfc3431e8ead12c43e9e1f87cc1b9b5c6cfd0f73865d405b27c4 AS builder
+
+WORKDIR /app
+
+RUN corepack enable
+
+COPY . .
+
+RUN pnpm install --frozen-lockfile --filter ./apps/worker... --filter ./packages/db \
+	&& pnpm --filter ./packages/db db:generate \
+	&& pnpm --filter ./apps/worker --prod deploy --legacy /app/deploy
+
+# `pnpm deploy --prod` correctly drops `prisma` (a devDependency of
+# packages/db), but it keeps the peer subtrees pnpm auto-installed *for* that
+# devDependency. `prisma` declares `typescript` as an optional peer, so the
+# hoisted store ends up with typescript@7 - the native Go build, which ships
+# @typescript/typescript-<platform> (a ~100 MB Go `tsc` with 10 HIGH CVEs).
+#
+# Nothing at runtime needs it: the worker runs compiled JS and talks to
+# Postgres through @prisma/client. Remove the auto-installed peer subtrees from
+# the deploy output so the runtime image stays free of dev-only binaries.
+RUN rm -rf \
+	/app/deploy/node_modules/.pnpm/typescript@* \
+	/app/deploy/node_modules/.pnpm/@typescript+typescript-* \
+	/app/deploy/node_modules/.pnpm/node_modules/typescript \
+	/app/deploy/node_modules/.pnpm/node_modules/@typescript \
+	/app/deploy/node_modules/.pnpm/node_modules/.bin/tsc \
+	/app/deploy/node_modules/typescript \
+	/app/deploy/node_modules/@typescript
+
+# `pnpm deploy` rewrites peer-suffixed directory names (e.g.
+# valibot@1.4.2_typescript@7.0.2) and nested `.bin/tsc` shims that link back
+# into the removed store, so drop those too.
+RUN find /app/deploy/node_modules -type d -name '*_typescript@*' -prune \
+		-exec rm -rf {} + \
+	&& find /app/deploy/node_modules -path '*/node_modules/.bin/tsc*' -delete
+
+# Fail the build rather than ship silently if a future dependency reintroduces
+# a dev-only native binary through the same path.
+RUN if find /app/deploy -name 'tsc' -type f 2>/dev/null | grep -q .; then \
+		echo 'error: dev-only TypeScript binary leaked into the deploy output' >&2; \
+		find /app/deploy -name 'tsc' -type f >&2; \
+		exit 1; \
+	fi
+
+FROM node:22-alpine@sha256:9385cd9f3001dfc3431e8ead12c43e9e1f87cc1b9b5c6cfd0f73865d405b27c4 AS runtime
+
+RUN apk upgrade --no-cache
+
+ENV NODE_ENV=production
+
+WORKDIR /app
+
+RUN rm -rf \
+	/usr/local/lib/node_modules/npm \
+	/usr/local/bin/npm \
+	/usr/local/bin/npx \
+	/opt/yarn-v1.22.22 \
+	/usr/local/bin/yarn \
+	/usr/local/bin/yarnpkg
+
+COPY --from=builder /app/deploy/ ./
+
+CMD ["node", "src/index.js"]

package/templates/worker/README.md

@@ -0,0 +1,56 @@
+# Quark Worker Service
+
+Background job processor using **BullMQ** and **Redis**.
+
+## Quick Start
+
+```bash
+docker compose up -d     # Redis required
+pnpm install
+pnpm dev                 # Starts worker with file watching
+```
+
+## Adding a Job Handler
+
+1. Define the job name in `packages/jobs/src/definitions.js`
+2. Create a handler in `apps/worker/src/handlers/<job-name>.js`:
+
+```javascript
+import { createLogger } from "@techstream/quark-core";
+
+const log = createLogger("job:my-task");
+
+export async function handleMyTask({ data }) {
+  log.info("processing", data);
+  // your logic here
+}
+```
+
+3. Register it in `apps/worker/src/handlers/index.js`:
+
+```javascript
+import { handleMyTask } from "./my-task.js";
+
+const jobHandlers = {
+  [JOB_NAMES.MY_TASK]: handleMyTask,
+};
+```
+
+## Dispatching Jobs
+
+```javascript
+import { createQueue, addJob } from "@techstream/quark-core";
+import { JOB_NAMES } from "@yourscope/jobs";
+
+const queue = createQueue("default");
+await addJob(queue, JOB_NAMES.MY_TASK, { userId: "123" });
+```
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `src/index.js` | Worker entry point, queue registration |
+| `src/handlers/` | Job handler functions |
+| `src/lib/` | Shared utilities (tokens, Railway helpers) |
+| `railway.json` | Railway deployment config *(deprecated - use `.railway/railway.ts`)* |

package/templates/worker/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "@myquark/worker",
+	"version": "1.0.0",
+	"private": true,
+	"type": "module",
+	"description": "",
+	"main": "index.js",
+	"exports": {
+		".": "./src/index.js",
+		"./tools": "./src/lib/tools/index.js"
+	},
+	"scripts": {
+		"clean": "rm -rf dist",
+		"test": "node ../../scripts/run-tests.mjs src --exclude=integration.test.js",
+		"dev": "tsx watch src/index.js",
+		"start:deploy": "node src/index.js",
+		"preflight": "node src/index.js --preflight",
+		"lint": "biome format --write && biome check --write"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "MIT",
+	"packageManager": "pnpm@10.12.1",
+	"dependencies": {
+		"@techstream/quark-config": "workspace:*",
+		"@techstream/quark-core": "^2.0.0",
+		"@techstream/quark-db": "workspace:*",
+		"@techstream/quark-jobs": "workspace:*",
+		"bullmq": "^6.3.8",
+		"jose": "^6.2.12"
+	},
+	"devDependencies": {
+		"@types/node": "^26.6.2",
+		"tsx": "^4.23.15"
+	}
+}

package/templates/worker/src/config/pricing.js

@@ -0,0 +1,46 @@
+/**
+ * Default model pricing (USD per 1M tokens).
+ *
+ * Override or extend at runtime via OPENROUTER_PRICING_OVERRIDE (JSON string).
+ * Example:
+ *   OPENROUTER_PRICING_OVERRIDE='{"openai/gpt-4o":{"input":2.0,"output":8.0}}'
+ *
+ * Override entries are shallow-merged on top of these defaults.
+ */
+
+/** @type {Record<string, { input: number, output: number }>} */
+export const DEFAULT_PRICING = {
+	"deepseek/deepseek-v4-flash": { input: 0.09, output: 0.18 },
+	"anthropic/claude-3.5-sonnet": { input: 3, output: 15 },
+	"anthropic/claude-3-opus": { input: 15, output: 75 },
+	"anthropic/claude-4-sonnet": { input: 15, output: 75 },
+	"openai/gpt-4o": { input: 2.5, output: 10 },
+	"openai/gpt-4o-mini": { input: 0.15, output: 0.6 },
+	"google/gemini-2.0-flash": { input: 0.1, output: 0.4 },
+};
+
+/**
+ * Resolve pricing table: defaults merged with optional OPENROUTER_PRICING_OVERRIDE.
+ * @returns {Record<string, { input: number, output: number }>}
+ */
+export function getPricing() {
+	const pricing = { ...DEFAULT_PRICING };
+	const override = process.env.OPENROUTER_PRICING_OVERRIDE;
+
+	if (!override) {
+		return pricing;
+	}
+
+	try {
+		const parsed = JSON.parse(override);
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+			return { ...pricing, ...parsed };
+		}
+	} catch {
+		// Invalid JSON — fall back to defaults
+	}
+
+	return pricing;
+}
+
+export default getPricing;

package/templates/worker/src/handlers/email-job-validation.js

@@ -0,0 +1,36 @@
+import { AppError, ValidationError } from "@techstream/quark-core/errors";
+
+export function requireWelcomeEmailUserId(data) {
+	const userId = data?.userId;
+
+	if (!userId) {
+		throw new ValidationError("userId is required for SEND_WELCOME_EMAIL job");
+	}
+
+	return userId;
+}
+
+export function requireResetPasswordEmailData(data) {
+	const userId = data?.userId;
+	const resetUrl = data?.resetUrl;
+
+	if (!userId || !resetUrl) {
+		throw new ValidationError(
+			"userId and resetUrl are required for SEND_RESET_PASSWORD_EMAIL job",
+		);
+	}
+
+	return { userId, resetUrl };
+}
+
+export function requireUserEmailRecord(userId, userRecord) {
+	if (!userRecord?.email) {
+		throw new AppError(
+			`User ${userId} not found or has no email`,
+			404,
+			"USER_EMAIL_NOT_FOUND",
+		);
+	}
+
+	return userRecord;
+}