@usequark/quark-create-app 1.25.0 → 1.25.1

package/package.json

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

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/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/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 });