@usequark/quark-create-app 1.24.3 → 1.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.24.3",
+  "version": "1.25.1",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",

package/src/index.js

@@ -214,8 +214,23 @@ async function initializeGit(projectDir) {
 	}
 
 	try {
-		// Initialize git repo
-		await execa("git", ["init"], { cwd: projectDir });
+		// Initialize git repo.
+		//
+		// `-b main` pins the branch name rather than inheriting whatever the
+		// machine has in `init.defaultBranch`. Without it the scaffold is not
+		// reproducible: `git init` falls back to `master` wherever that setting
+		// is unset (the common case, and GitHub's own default until the hint
+		// is followed), so the same CLI produced `master` on one machine and
+		// `main` on another. `main` is the name GitHub defaults a new repository
+		// to, so it is also what the README's push instructions assume.
+		//
+		// `-b` needs git 2.28 (2020). If it is unavailable the bare `init` still
+		// produces a working repository, just with git's own default branch.
+		try {
+			await execa("git", ["init", "-b", "main"], { cwd: projectDir });
+		} catch {
+			await execa("git", ["init"], { cwd: projectDir });
+		}
 
 		// Add all files
 		await execa("git", ["add", "."], { cwd: projectDir });

package/templates/base-project/apps/web/src/app/api/files/[id]/route.js

@@ -5,6 +5,8 @@
  */
 
 import {
+	ConflictError,
+	createLogger,
 	createStorage,
 	ForbiddenError,
 	NotFoundError,
@@ -15,16 +17,30 @@ import { NextResponse } from "next/server";
 import { requireAuth } from "@/lib/auth-middleware";
 import { handleError } from "../../error-handler";
 
+const logger = createLogger("files");
+
 /**
  * GET /api/files/[id]
- * Serve / download a file by its database ID.
- * Public endpoint (no auth required) - access control is by knowledge of ID.
+ * Serve / download a file by its database ID or its storage key.
+ * Public endpoint (no auth required) - access control is by knowledge of the
+ * identifier.
+ *
+ * Both identifier forms are accepted because `getAssetUrl()` in
+ * `@usequark/quark-core` builds `/api/files/<key>` from a storage key, and
+ * nothing in this app ever called it with anything else. Serving only by id
+ * made every URL that function produces a 404.
  */
 export async function GET(_request, { params }) {
 	try {
 		const { id } = await params;
 
-		const record = await file.findById(id);
+		// The two forms are disjoint: a cuid never contains "/", and a storage key
+		// always does (`<prefix>/<year>/<month>/<id>-<name>`). An id lookup that
+		// misses is followed by a key lookup, so the id path costs no extra query.
+		let record = await file.findById(id);
+		if (!record && id.includes("/")) {
+			record = await file.findByStorageKey(id);
+		}
 		if (!record) {
 			throw new NotFoundError("File not found");
 		}
@@ -35,7 +51,13 @@ export async function GET(_request, { params }) {
 		const headers = new Headers();
 		headers.set("Content-Type", contentType || record.mimeType);
 		headers.set("Content-Length", String(body.length));
-		headers.set("Cache-Control", "public, max-age=31536000, immutable");
+		// Bounded, not `immutable`. The URL carries no version segment and nothing
+		// in the path is content-addressed, so `immutable` (never revalidate for a
+		// year) was a promise this route cannot keep: any code path that reuses an
+		// identifier — admin tooling, a seed, a restore from backup — would leave
+		// every browser and CDN holding the old bytes indefinitely. A bounded
+		// max-age bounds that window instead.
+		headers.set("Cache-Control", "public, max-age=3600");
 
 		// Inline display for images; attachment download for everything else
 		const isImage = record.mimeType.startsWith("image/");
@@ -57,6 +79,20 @@ export async function GET(_request, { params }) {
 /**
  * DELETE /api/files/[id]
  * Delete a file. Only the uploader or an admin can delete.
+ *
+ * Order matters: the database row goes first, the storage object second.
+ *
+ * `File` has no incoming relations today, so nothing can make the row delete
+ * fail on a foreign key — but a future incoming relation with a restrictive
+ * `onDelete` will, and at that point this ordering is what keeps the storage
+ * object intact. The old order (storage, then row) destroyed the bytes first,
+ * so a refused row delete left a row pointing at a blob that no longer existed:
+ * unrecoverable, because the bytes are the only copy and they are already gone.
+ *
+ * `deleteIfPresent` also closes the concurrent-delete race. Two overlapping
+ * requests both pass the ownership check above; the row delete reports how many
+ * rows it removed, so only the request that actually removed the row goes on to
+ * delete the storage object. The loser returns 404 without touching storage.
  */
 export const DELETE = withCsrfProtection(async (_request, { params }) => {
 	try {
@@ -75,12 +111,42 @@ export const DELETE = withCsrfProtection(async (_request, { params }) => {
 			throw new ForbiddenError("You can only delete your own files");
 		}
 
-		// Remove from storage
-		const storage = createStorage();
-		await storage.delete(record.storageKey);
+		// Remove the database record first. This is the reversible step: if the
+		// storage delete below fails, we have an orphaned blob, which is junk but
+		// harmless. The reverse order risks a row whose bytes are already gone.
+		let deleted;
+		try {
+			({ count: deleted } = await file.deleteIfPresent(record.id));
+		} catch (error) {
+			// P2003: a foreign key still references this row. Reachable once File
+			// gains incoming relations; the storage object is untouched at this point.
+			if (error?.code === "P2003") {
+				throw new ConflictError("File is referenced and cannot be deleted");
+			}
+			throw error;
+		}
 
-		// Remove database record
-		await file.delete(record.id);
+		// count === 0 means a concurrent request already removed the row. It owns
+		// the storage cleanup; touching it here would race that request's delete.
+		if (deleted === 0) {
+			throw new NotFoundError("File not found");
+		}
+
+		// Row is gone, so the blob is now unreferenced. This is the irreversible
+		// step and deliberately last.
+		const storage = createStorage();
+		try {
+			await storage.delete(record.storageKey);
+		} catch (error) {
+			// The row is already deleted, so the delete as a whole succeeded from the
+			// caller's point of view. Reporting an error would be a lie the client
+			// cannot act on, and the leftover blob is recoverable via the existing
+			// orphaned-file cleanup job. Log it rather than swallow it.
+			logger.error("Failed to remove file from storage", {
+				fileId: record.id,
+				error: error?.message ?? String(error),
+			});
+		}
 
 		return NextResponse.json({ message: "File deleted" });
 	} catch (error) {

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

@@ -1,7 +1,15 @@
 /**
  * Health Check Endpoint
- * Verifies the application and its dependencies are functioning correctly.
- * Times out after 5 seconds to prevent hanging.
+ *
+ * Reports the status of the application and its dependencies. Every dependency
+ * is probed concurrently, each under its own deadline, and the route always
+ * answers `200` — the verdict lives in the body's `status` field.
+ *
+ * Why always 200: this endpoint is the platform healthcheck. A non-200 here
+ * makes the orchestrator restart the container, which drops every warm
+ * connection and produces a fresh connection storm on the dependency that was
+ * already struggling. That turns a transient blip into a restart loop.
+ * Callers that need a hard verdict should read `status`, not the status code.
  */
 
 import {
@@ -15,146 +23,241 @@ import { NextResponse } from "next/server";
 
 const logger = createLogger("health");
 
-/** Overall timeout for the health check (ms). */
+/** Ceiling for the whole check (ms). */
 const HEALTH_CHECK_TIMEOUT = 5000;
 
+/** Ceiling for one dependency probe (ms). Clamped to the overall budget, so a
+ * single probe can never outlive the request. */
+const PROBE_TIMEOUT = 3000;
+
+/** Message returned in place of a real error when NODE_ENV is production. */
+const GENERIC_MESSAGES = {
+	database: "Database unavailable",
+	redis: "Redis unavailable",
+	storage: "Storage unavailable",
+	queue: "Queue unavailable",
+};
+
 export async function GET() {
 	try {
-		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);
-				},
-			);
-		});
+		const result = await runHealthChecks();
 
+		// Always 200 — see the module comment. An orchestrator restarting this
+		// service is what turns a dependency blip into an outage.
 		return NextResponse.json(result, {
-			status: result.status === "error" ? 503 : 200,
+			status: 200,
+			headers: { "Cache-Control": "no-store" },
 		});
 	} catch (error) {
+		// Unreachable in practice: every probe below is individually settled and
+		// deadline-bounded, so runHealthChecks cannot reject. Kept so a future
+		// edit that reintroduces a throw still returns a parseable body.
 		logger.error("Health check failed", {
 			error: error.message,
 			stack: error.stack,
 		});
+
 		return NextResponse.json(
 			{
 				status: "error",
 				timestamp: new Date().toISOString(),
 				message: "Service health check failed",
 			},
-			{ status: 500 },
+			{ status: 200, headers: { "Cache-Control": "no-store" } },
 		);
 	}
 }
 
 /**
- * Runs all individual health checks and aggregates the results.
- * @returns {Promise<{ status: string, timestamp: string, checks: Record<string, object> }>}
+ * Runs every dependency probe concurrently and aggregates the results.
+ *
+ * Concurrency matters as much as the deadlines: run sequentially, a 3s database
+ * timeout plus a 3s Redis timeout exhausts the 5s budget before storage is even
+ * attempted, and the whole request falls through to the give-up path.
+ *
+ * @returns {Promise<{ status: string, timestamp: string, durationMs: number, checks: Record<string, object> }>}
  */
 async function runHealthChecks() {
-	const health = {
-		status: "ok",
+	const startedAt = performance.now();
+
+	// Every probe is wrapped in settleProbe(), so this Promise.all cannot reject
+	// and cannot outlast the deadline.
+	const [database, redis, storage, queues] = await Promise.all([
+		settleProbe("database", () => pingDatabase()),
+		settleProbe("redis", () => pingRedis()),
+		// `provider` rides along on the error result so a failure still names the
+		// provider that failed — settleProbe owns the message redaction.
+		settleProbe("storage", checkStorage, {
+			provider: process.env.STORAGE_PROVIDER || "local",
+		}),
+		settleProbe("queues", checkQueues),
+	]);
+
+	const checks = { database, redis, storage };
+	if (queues) checks.queues = queues;
+
+	return {
+		// "degraded" means at least one dependency failed. Both this and "ok"
+		// answer 200 — see the module comment.
+		status: Object.values(checks).some(isFailing) ? "degraded" : "ok",
 		timestamp: new Date().toISOString(),
-		checks: {},
+		durationMs: Math.round(performance.now() - startedAt),
+		checks,
 	};
+}
 
-	// Check database connectivity
-	const dbResult = await pingDatabase();
-	if (dbResult.status === "ok") {
-		health.checks.database = { status: "ok", latencyMs: dbResult.latencyMs };
-	} else {
-		health.checks.database = {
-			status: "error",
-			message: dbResult.message,
-		};
-		health.status = "degraded";
+/**
+ * Reports whether a check entry counts as a failure. Handles both a flat probe
+ * result (`{ status: "error" }`) and the nested queue map, where the verdict
+ * lives on each queue rather than on the map itself.
+ *
+ * @param {unknown} check
+ * @returns {boolean}
+ */
+function isFailing(check) {
+	if (!check || typeof check !== "object") return false;
+
+	// A flat probe result carries its own `status`. The nested queue map does
+	// not, so fall through to its entries.
+	if (typeof (/** @type {any} */ (check).status) === "string") {
+		return /** @type {any} */ (check).status === "error";
 	}
 
-	// Check Redis connectivity (actual PING)
-	const redisResult = await pingRedis();
-	if (redisResult.status === "ok") {
-		health.checks.redis = { status: "ok", latencyMs: redisResult.latencyMs };
-	} else {
-		health.checks.redis = {
+	return Object.values(/** @type {Record<string, any>} */ (check)).some(
+		(entry) => entry?.status === "error",
+	);
+}
+
+/**
+ * Runs one dependency probe with its own deadline and normalises every failure
+ * mode — rejection, timeout, or a probe that never settles — into a result
+ * object. Never throws, so callers can rely on `Promise.all` resolving.
+ *
+ * @param {string} name - Probe name, also the key under `checks`.
+ * @param {() => Promise<object>} probe
+ * @param {object} [context] - Fields to merge into the error result.
+ * @returns {Promise<{ status: string } & Record<string, unknown>>}
+ */
+async function settleProbe(name, probe, context = {}) {
+	// A probe that hangs must not hold up the aggregate, and must never outlive
+	// the overall budget. The timer is always cleared, so it never leaks.
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(
+			() => resolve({ status: "error", message: `${name} check timed out` }),
+			Math.min(PROBE_TIMEOUT, HEALTH_CHECK_TIMEOUT),
+		);
+	});
+
+	try {
+		return withSafeMessage(name, await Promise.race([probe(), deadline]));
+	} catch (/** @type {any} */ error) {
+		return withSafeMessage(name, {
+			...context,
 			status: "error",
-			message: redisResult.message,
-		};
-		health.status = "degraded";
+			message: error?.message,
+		});
+	} finally {
+		clearTimeout(timer);
 	}
+}
 
-	// Check storage connectivity
-	const storageResult = await checkStorage();
-	health.checks.storage = storageResult;
-	if (storageResult.status === "error") {
-		health.status = "degraded";
-	}
+/**
+ * Returns a check result whose message is safe to serve publicly.
+ *
+ * A probe can signal failure two ways — by rejecting, or by *resolving* with
+ * `{ status: "error", message }`. Both are routed through here so neither can
+ * bypass the redaction: `pingRedis` returned `{ status: "error" }` carrying the
+ * raw `REDIS_URL`, so a normaliser that only handled rejections would have let
+ * the password straight through.
+ *
+ * @param {string} name - Probe name.
+ * @param {object} [result]
+ * @returns {object}
+ */
+function withSafeMessage(name, result) {
+	if (result?.status !== "error") return result;
 
-	// Check queue depths (only when queues are registered in this process)
-	const registeredQueues = getRegisteredQueues();
-	if (registeredQueues.size > 0) {
-		const entries = [...registeredQueues.entries()];
-		const results = await Promise.allSettled(
-			entries.map(([, queue]) =>
-				Promise.all([
-					queue.getWaitingCount(),
-					queue.getActiveCount(),
-					queue.getFailedCount(),
-				]),
-			),
-		);
+	const { message, ...rest } = result;
+	return { ...rest, status: "error", message: safeMessage(name, message) };
+}
 
-		const queueChecks = {};
-		for (let i = 0; i < entries.length; i++) {
-			const [name] = entries[i];
-			const result = results[i];
-			if (result.status === "fulfilled") {
-				const [waiting, active, failed] = result.value;
-				queueChecks[name] = { status: "ok", waiting, active, failed };
-			} else {
-				const message =
-					process.env.NODE_ENV === "production"
-						? "Queue unavailable"
-						: result.reason?.message;
-				queueChecks[name] = { status: "error", message };
-				health.status = "degraded";
-			}
-		}
-		health.checks.queues = queueChecks;
+/**
+ * Reduces a failure to a message safe to return from an unauthenticated route.
+ *
+ * Driver errors carry the connection string they failed on, so the raw text is
+ * only echoed outside production. `pingRedis`/`pingDatabase` redact at the
+ * source regardless; this is the second layer.
+ *
+ * @param {string} name - Probe name.
+ * @param {string|Error} [source] - The failure message or the error itself.
+ * @returns {string}
+ */
+function safeMessage(name, source) {
+	if (process.env.NODE_ENV === "production") {
+		return GENERIC_MESSAGES[name] ?? "Check unavailable";
 	}
 
-	return health;
+	return source?.message ?? source ?? "Unknown error";
 }
 
 /**
  * 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 }>}
+ * @returns {Promise<{ status: string, provider: 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 };
+	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 };
+}
+
+/**
+ * Reports queue depths. Only meaningful in a process that registered the
+ * queues — the web app registers none, so this resolves to null and the key is
+ * omitted from the response rather than reported as a false pass.
+ *
+ * @returns {Promise<Record<string, { status: string, waiting?: number, active?: number, failed?: number, message?: string }> | null>}
+ */
+async function checkQueues() {
+	const registeredQueues = getRegisteredQueues();
+	if (registeredQueues.size === 0) return null;
+
+	const entries = [...registeredQueues.entries()];
+	const results = await Promise.allSettled(
+		entries.map(([, queue]) =>
+			Promise.all([
+				queue.getWaitingCount(),
+				queue.getActiveCount(),
+				queue.getFailedCount(),
+			]),
+		),
+	);
+
+	const queueChecks = {};
+
+	for (let i = 0; i < entries.length; i++) {
+		const [name] = entries[i];
+		const result = results[i];
+
+		if (result.status === "fulfilled") {
+			const [waiting, active, failed] = result.value;
+			queueChecks[name] = { status: "ok", waiting, active, failed };
+		} else {
+			queueChecks[name] = withSafeMessage("queue", {
+				status: "error",
+				message: result.reason?.message,
+			});
+		}
 	}
+
+	return queueChecks;
 }

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

@@ -1,4 +1,5 @@
 import "./globals.css";
+import { ThemeProvider } from "@usequark/quark-ui";
 import {
 	THEME_ATTR,
 	THEME_STORAGE_KEY,
@@ -48,7 +49,11 @@ export default function RootLayout({ children }) {
 				) : null}
 			</head>
 			<body>
-				{children}
+				{/* ThemeProvider renders no markup. It publishes theme state to
+				    React consumers (useTheme/ThemeToggle) and syncs data-theme
+				    after hydration via useLayoutEffect, which is why it must
+				    coexist with the blocking script above rather than replace it. */}
+				<ThemeProvider>{children}</ThemeProvider>
 				{umamiConfig.enabled ? <UmamiWebVitals /> : null}
 				{umamiConfig.replayEnabled ? <UmamiReplayRecorder /> : null}
 			</body>

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

@@ -7,6 +7,17 @@ const STRICT_AUTH_RATE_LIMIT_ROUTES = new Set([
 	"/api/auth/signin/credentials",
 ]);
 
+/**
+ * Routes that are never rate limited.
+ *
+ * `/api/health` is the platform healthcheck. It sits behind the same 100-req
+ * `api` bucket as everything else, so a probe that lands in an already-full
+ * bucket gets a 429 — the orchestrator reads that as unhealthy and restarts the
+ * container, which fills the bucket again on startup. Limiting the probe is how
+ * a healthy service gets killed.
+ */
+const RATE_LIMIT_EXEMPT_ROUTES = new Set(["/api/health"]);
+
 function getForwardedProtocol(request) {
 	const forwardedProto = request.headers.get("x-forwarded-proto");
 	if (!forwardedProto) return null;
@@ -78,3 +89,12 @@ export function getRateLimitBucket(pathname, method = "GET") {
 		? "auth"
 		: "api";
 }
+
+/**
+ * Whether a route bypasses rate limiting entirely.
+ * @param {string} pathname
+ * @returns {boolean}
+ */
+export function isRateLimitExempt(pathname) {
+	return RATE_LIMIT_EXEMPT_ROUTES.has(pathname);
+}

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

@@ -5,14 +5,15 @@
  * 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.
+ *   2. Rate limiting, CORS, security headers for all API routes, except the
+ *      rate-limit-exempt healthcheck (see lib/proxy-auth.js).
  */
 
 import { getAllowedOrigins } from "@usequark/quark-config/app-url";
 import { NextResponse } from "next/server";
 
 import { buildContentSecurityPolicy } from "./lib/analytics/umami-csp.js";
-import { getRateLimitBucket } from "./lib/proxy-auth";
+import { getRateLimitBucket, isRateLimitExempt } from "./lib/proxy-auth";
 
 // ─── 1. Metrics guard ────────────────────────────────────────────────────────
 
@@ -218,8 +219,9 @@ export async function proxy(request) {
 		}
 	}
 
-	// Apply rate limiting to API routes only
-	if (pathname.startsWith("/api/")) {
+	// Apply rate limiting to API routes only. Exempt routes (the healthcheck)
+	// skip the bucket entirely — no counter, no headers.
+	if (pathname.startsWith("/api/") && !isRateLimitExempt(pathname)) {
 		const ip = getClientIp(request);
 		const rateLimitBucket = getRateLimitBucket(pathname, request.method);
 		const maxRequests = RATE_LIMIT_CONFIG.maxRequests[rateLimitBucket];

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

@@ -283,6 +283,23 @@ export const file = {
 	delete: (id) => {
 		return prisma.file.delete({ where: { id } });
 	},
+	/**
+	 * Deletes a File row and reports whether this call was the one that removed
+	 * it.
+	 *
+	 * `delete()` throws P2025 when the row is already gone, which is the normal
+	 * outcome of two concurrent DELETEs of the same file and is not an error
+	 * worth surfacing. This returns `{ count }` instead so the caller can tell
+	 * "I deleted it" from "someone beat me to it" and skip the destructive
+	 * follow-up (removing the storage object) in the second case.
+	 *
+	 * A count of 1 means the caller owns the cleanup. Any incoming relation
+	 * added later still surfaces here as a P2003 foreign-key error, before the
+	 * storage object has been touched.
+	 */
+	deleteIfPresent: (id) => {
+		return prisma.file.deleteMany({ where: { id } });
+	},
 	deleteMany: (ids) => {
 		return prisma.file.deleteMany({ where: { id: { in: ids } } });
 	},

package/templates/base-project/scripts/run-tests.mjs

@@ -31,7 +31,18 @@ function collectTests(targetPath) {
 				continue;
 			}
 
-			if (!entry.isFile() || !entry.name.endsWith(".test.js")) {
+			// `*.integration-test.js` renders components through jsdom + react-dom,
+			// so it must be collected too. It was previously skipped, which meant
+			// those suites never ran in CI - a real gap, not a naming preference:
+			// every one of them passed locally but was invisible to the pipeline.
+			// Note the file suffix is `-integration-test.js`, so
+			// `*.integration.test.js` (a different, separately-excluded name) is
+			// still only picked up by the plain `.test.js` rule below.
+			if (
+				!entry.isFile() ||
+				(!entry.name.endsWith(".test.js") &&
+					!entry.name.endsWith(".integration-test.js"))
+			) {
 				continue;
 			}
 

package/templates/ui/src/form-field.integration-test.js

@@ -57,7 +57,8 @@ test("FormField - renders label and input", async () => {
 	assert.ok(input, "should render an input");
 	assert.strictEqual(label.textContent, "Name");
 	assert.strictEqual(input.getAttribute("name"), "name");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - connects label to input via htmlFor/id", async () => {
@@ -76,7 +77,8 @@ test("FormField - connects label to input via htmlFor/id", async () => {
 	const input = container.querySelector("input");
 	assert.strictEqual(label.getAttribute("for"), "custom-id");
 	assert.strictEqual(input.getAttribute("id"), "custom-id");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - renders error message with role alert", async () => {
@@ -94,7 +96,8 @@ test("FormField - renders error message with role alert", async () => {
 	const errorEl = container.querySelector("[role='alert']");
 	assert.ok(errorEl, "should render an error element with role alert");
 	assert.strictEqual(errorEl.textContent, "Required");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - sets aria-invalid and aria-describedby when error present", async () => {
@@ -110,13 +113,127 @@ test("FormField - sets aria-invalid and aria-describedby when error present", as
 			}),
 		),
 	);
-	const wrapper = container.querySelector('[aria-invalid="true"]');
-	assert.ok(wrapper, "should set aria-invalid on wrapper");
-	const errorId = wrapper.getAttribute("aria-describedby");
-	assert.ok(errorId, "should set aria-describedby");
+	const input = container.querySelector("input");
+	assert.ok(input, "should render an input");
+	assert.strictEqual(
+		input.getAttribute("aria-invalid"),
+		"true",
+		"aria-invalid must be on the focusable control",
+	);
+	assert.ok(
+		!container.querySelector("div[aria-invalid]"),
+		"aria-invalid on a non-interactive wrapper has no effect",
+	);
+	const errorId = input.getAttribute("aria-describedby");
+	assert.ok(errorId, "should set aria-describedby on the input");
+	assert.strictEqual(errorId, "email-field-error");
 	const errorEl = container.querySelector(`#${errorId}`);
 	assert.ok(errorEl, "aria-describedby should point to existing error element");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - applies className to the control, not the wrapper", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(FormField, {
+				label: "Name",
+				name: "name",
+				className: "w-72",
+			}),
+		),
+	);
+	const input = container.querySelector("input");
+	assert.match(input.getAttribute("class"), /\bw-72\b/);
+	assert.doesNotMatch(
+		container.firstElementChild.getAttribute("class"),
+		/\bw-72\b/,
+		"className targets the control; the wrapper is layout-only",
+	);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - wrapperClassName styles the layout container", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(FormField, {
+				label: "Name",
+				name: "name",
+				wrapperClassName: "sm:col-span-2",
+			}),
+		),
+	);
+	assert.match(
+		container.firstElementChild.getAttribute("class"),
+		/\bsm:col-span-2\b/,
+	);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - forwards error ARIA to a custom child control", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(
+				FormField,
+				{ label: "Bio", name: "bio", error: "Too short", id: "bio" },
+				createElement("textarea", { id: "bio", "data-testid": "custom" }),
+			),
+		),
+	);
+	const textarea = container.querySelector("textarea");
+	assert.strictEqual(textarea.getAttribute("aria-invalid"), "true");
+	assert.strictEqual(textarea.getAttribute("aria-describedby"), "bio-error");
+	assert.ok(
+		container.querySelector("#bio-error"),
+		"describedby target must exist",
+	);
+	assert.strictEqual(
+		textarea.getAttribute("name"),
+		"bio",
+		"name should be forwarded to the custom control",
+	);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - preserves a custom child's own className", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(
+			createElement(
+				FormField,
+				{ label: "Bio", name: "bio", className: "h-40" },
+				createElement("textarea", { className: "resize-y" }),
+			),
+		),
+	);
+	const cls = container.querySelector("textarea").getAttribute("class");
+	assert.match(cls, /\bresize-y\b/);
+	assert.match(cls, /\bh-40\b/);
+	await act(() => root.unmount());
+	container.remove();
+});
+
+test("FormField - leaves aria-invalid off when there is no error", async () => {
+	const container = setupContainer();
+	const root = createRoot(container);
+	await act(() =>
+		root.render(createElement(FormField, { label: "Name", name: "name" })),
+	);
+	const input = container.querySelector("input");
+	assert.strictEqual(input.getAttribute("aria-invalid"), null);
+	assert.strictEqual(input.getAttribute("aria-describedby"), null);
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("FormField - renders children instead of default input", async () => {
@@ -138,5 +255,6 @@ test("FormField - renders children instead of default input", async () => {
 		null,
 		"should not render default input",
 	);
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });

package/templates/ui/src/form-field.js

@@ -3,12 +3,33 @@ import React, { useId } from "react";
 import { Input } from "./input.js";
 import { Label } from "./label.js";
 
+/**
+ * Label + control + error message, wired together for accessibility.
+ *
+ * `className` is applied to the control, matching every other component in this
+ * package (`Input`, `Textarea`, `Select`, `Card`, …), where it extends the
+ * component's own root element. Use `wrapperClassName` to style the layout
+ * container instead.
+ *
+ * The error association (`aria-invalid` / `aria-describedby`) always lands on
+ * the focusable control, never on a wrapper element, so a screen reader that is
+ * sitting on the control actually announces it.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} [props.label]
+ * @param {string} [props.name]
+ * @param {string} [props.error]
+ * @param {React.ReactNode} [props.children] custom control, e.g. a <Textarea>
+ * @param {string} [props.className] classes for the control
+ * @param {string} [props.wrapperClassName] classes for the layout container
+ */
 export function FormField({
 	label,
 	name,
 	error,
 	children,
 	className = "",
+	wrapperClassName = "",
 	...props
 }) {
 	const generatedId = useId();
@@ -16,25 +37,44 @@ export function FormField({
 
 	const errorId = `${fieldId}-error`;
 
-	const inputProps = { id: fieldId, name, ...props };
-	if (error) {
-		inputProps["aria-invalid"] = true;
-		inputProps["aria-describedby"] = errorId;
-	}
+	const ariaProps = error
+		? { "aria-invalid": true, "aria-describedby": errorId }
+		: {};
 
-	const childrenWrapperProps = {};
-	if (error) {
-		childrenWrapperProps["aria-invalid"] = true;
-		childrenWrapperProps["aria-describedby"] = errorId;
-	}
+	const control = children
+		? // A caller-supplied control already owns its own markup; forward the
+			// accessibility wiring to it so the attributes land on the element
+			// that can receive focus. Explicit props on the child win, so a
+			// caller can still override them.
+			React.Children.map(children, (child) => {
+				if (!React.isValidElement(child)) return child;
+				const merged = [child.props.className, className]
+					.filter(Boolean)
+					.join(" ");
+				return React.cloneElement(child, {
+					id: child.props.id ?? fieldId,
+					name: child.props.name ?? name,
+					// Omitted entirely when empty so a bare child is not given a
+					// meaningless class="" attribute.
+					...(merged ? { className: merged } : {}),
+					...ariaProps,
+				});
+			})
+		: React.createElement(Input, {
+				id: fieldId,
+				name,
+				className,
+				...ariaProps,
+				...props,
+			});
 
 	return React.createElement(
 		"div",
-		{ className: `min-w-0 space-y-1.5 ${className}`.trim() },
+		{
+			className: `min-w-0 space-y-1.5 ${wrapperClassName}`.trim(),
+		},
 		label ? React.createElement(Label, { htmlFor: fieldId }, label) : null,
-		children
-			? React.createElement("div", childrenWrapperProps, children)
-			: React.createElement(Input, inputProps),
+		control,
 		error
 			? React.createElement(
 					"p",

package/templates/ui/src/lightbox.integration-test.js

@@ -56,7 +56,8 @@ test("Lightbox - renders nothing when closed", async () => {
 	const root = createRoot(container);
 	await act(() => root.render(createElement(Lightbox, { open: false })));
 	assert.strictEqual(container.innerHTML, "");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - renders overlay when open", async () => {
@@ -76,7 +77,8 @@ test("Lightbox - renders overlay when open", async () => {
 	assert.ok(img, "should render an img element");
 	assert.strictEqual(img.getAttribute("src"), "/test.jpg");
 	assert.strictEqual(img.getAttribute("alt"), "Test image");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - calls onClose when close button clicked", async () => {
@@ -100,7 +102,8 @@ test("Lightbox - calls onClose when close button clicked", async () => {
 	assert.ok(closeBtn, "should have a close button");
 	await act(() => closeBtn.click());
 	assert.ok(closed, "onClose should be called");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - shows prev/next buttons and counter", async () => {
@@ -127,7 +130,8 @@ test("Lightbox - shows prev/next buttons and counter", async () => {
 	);
 	assert.ok(container.textContent.includes("Next"), "should show Next button");
 	assert.ok(container.textContent.includes("2 / 5"), "should show counter");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });
 
 test("Lightbox - calls onPrevious and onNext on button clicks", async () => {
@@ -163,5 +167,6 @@ test("Lightbox - calls onPrevious and onNext on button clicks", async () => {
 	assert.ok(prev, "onPrevious should be called");
 	await act(() => nextBtn.click());
 	assert.ok(next, "onNext should be called");
-	root.unmount();
+	await act(() => root.unmount());
+	container.remove();
 });

package/templates/ui/src/theme.js

@@ -13,7 +13,11 @@ import {
 	THEME_STORAGE_KEY,
 } from "./theme-constants.js";
 
-const ThemeCtx = createContext({ theme: "dark", setTheme: () => {} });
+// `undefined` means "no ThemeProvider above this consumer". It must not be a
+// usable default: a plausible-looking default ({ theme, setTheme: noop }) turns a
+// missing provider into a silently broken toggle that still renders and still
+// reports a theme. See useTheme().
+const ThemeCtx = createContext(undefined);
 
 /**
  * Wraps a subtree with a shared theme value.
@@ -90,18 +94,29 @@ export function ThemeProvider({ defaultTheme, children }) {
 
 /**
  * Returns the current theme and a setter from the nearest ThemeProvider.
- * Falls back to `{ theme: 'dark' }` when used outside a provider.
+ *
+ * Throws when there is no ThemeProvider above the caller. A missing provider is
+ * a wiring bug, not a state to default: `ThemeToggle` renders a labelled,
+ * focusable button either way, so a silent fallback yields a control that looks
+ * real, reports the wrong theme, and does nothing when clicked.
  *
  * @returns {{ theme: 'light' | 'dark', setTheme: (t: string) => void }}
+ * @throws {Error} if called outside a ThemeProvider
  */
 export function useTheme() {
-	return useContext(ThemeCtx);
+	const ctx = useContext(ThemeCtx);
+	if (ctx === undefined) {
+		throw new Error(
+			"useTheme() must be used within a ThemeProvider. Wrap your app in <ThemeProvider> (import it from @scope/ui) around the tree containing this component.",
+		);
+	}
+	return ctx;
 }
 
 /**
  * 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.
+ * Must be rendered inside a ThemeProvider — outside one, `useTheme()` throws.
  */
 export function ThemeToggle({ className = "" }) {
 	const { theme, setTheme } = useTheme();

package/templates/worker/src/handlers/files.js

@@ -37,8 +37,16 @@ export async function handleCleanupOrphanedFiles(bullJob, logger) {
 
 	for (const record of orphaned) {
 		try {
+			// Row first, storage second — same ordering as DELETE /api/files/[id].
+			// Storage-first means a failed row delete leaves a row pointing at bytes
+			// that are already gone, which cannot be recovered: the blob was the only
+			// copy. A failed storage delete here leaves an orphaned blob instead, and
+			// this very job is what sweeps those up on a later pass.
+			const { count } = await file.deleteIfPresent(record.id);
+			// A concurrent request (or an earlier pass of this job) already took it.
+			if (count === 0) continue;
+
 			await storage.delete(record.storageKey);
-			await file.delete(record.id);
 			deleted++;
 		} catch (err) {
 			errors.push({ id: record.id, error: err.message });

package/templates/worker/src/index.js

@@ -9,7 +9,7 @@ import {
 	createLogger,
 	createQueue,
 	createWorker,
-	getRedisUrl,
+	getRedisEndpoint,
 	updateQueueDepths,
 } from "@usequark/quark-core";
 import { AppError } from "@usequark/quark-core/errors";
@@ -170,7 +170,7 @@ export async function waitForRedis(
 
 	// All retries exhausted
 	throw new AppError(
-		`Redis unavailable at ${getRedisUrl()} after ${maxRetries} attempts. Start Redis or check REDIS_URL/REDIS_HOST/REDIS_PORT.`,
+		`Redis unavailable at ${getRedisEndpoint()} after ${maxRetries} attempts. Start Redis or check REDIS_URL/REDIS_HOST/REDIS_PORT.`,
 		503,
 		"REDIS_UNAVAILABLE",
 	);
@@ -397,7 +397,7 @@ async function startWorker() {
 			isDevMode ? { maxRetries: 3, intervalMs: 500 } : {},
 		);
 
-		logger.info("Redis connected", { address: getRedisUrl() });
+		logger.info("Redis connected", { address: getRedisEndpoint() });
 
 		// Wait for database schema to be ready (migrations may still be running)
 		logger.info("Checking database schema readiness...");