@usequark/quark-create-app 1.25.3 → 1.25.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.25.3",
+  "version": "1.25.5",
   "description": "CLI to scaffold new Quark projects with Next.js, Prisma, BullMQ, and Railway deployment",
   "keywords": [
     "quark",
@@ -36,6 +36,9 @@
     "templates",
     "README.md"
   ],
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  },
   "dependencies": {
     "chalk": "^6.0.0",
     "commander": "^15.0.0",

package/src/deploy/adapters/iac.js

@@ -25,6 +25,25 @@ const IAC_HELPERS = [
 	"volume",
 ];
 
+/**
+ * Builds a Railway variable reference as a TypeScript *string literal*.
+ *
+ * Railway's `${{Service.VAR}}` syntax is only reference syntax inside a quoted
+ * string. Emitted bare it is not a valid expression — `${{` parses as an object
+ * literal that opens and never closes — so the file fails to parse before
+ * Railway ever sees it. The value must therefore carry its own quotes.
+ *
+ * Only for values embedded in generated TypeScript. A value passed to
+ * `railway variable set` on a command line wants the bare, unquoted form.
+ *
+ * @param {string} serviceName - Railway service the variable lives on
+ * @param {string} variableName - Variable name on that service
+ * @returns {string} A quoted reference, e.g. `"${{Postgres.DATABASE_URL}}"`
+ */
+export function iacRef(serviceName, variableName) {
+	return `"$\{{${serviceName}.${variableName}}}"`;
+}
+
 /**
  * Escapes a string for safe embedding in a TypeScript string literal.
  * Handles backslashes, quotes, newlines, and template literal interpolation.
@@ -76,6 +95,9 @@ function toIdentifier(value) {
  * @param {object} options.variableRefs - Map of variable key → Railway reference string
  * @param {object} options.serviceVars - Map of service name → extra env vars
  * @param {string} [options.projectName] - Railway project name (defaults to "quark-app")
+ * @returns {Promise<{content: string, changed: boolean, previous: string|null}>}
+ *   `changed` is false when the file on disk already matched, in which case no
+ *   write happened. `previous` is the content that was replaced, or null.
  */
 export async function generateIacFile({
 	iacPath,
@@ -108,13 +130,24 @@ export async function generateIacFile({
 
 		const preDeploy = "pnpm db:migrate:deploy";
 
+		// Each entry is one complete `key: value` field, and the object body is
+		// rendered by joining them. Concatenating pre-rendered blocks instead
+		// means each block has to guess whether it owns the separator between it
+		// and its neighbour — and when two blocks both assume they do, the file
+		// ships with `healthcheckTimeout: 120,,`, which does not parse. A field
+		// list makes that unrepresentable: there is exactly one join.
+		const fields = [
+			`build: "${escapeTsString(buildCmd)}"`,
+			`start: "${escapeTsString(startCmd)}"`,
+			`preDeploy: "${escapeTsString(preDeploy)}"`,
+		];
+
 		// Healthcheck (web only)
-		const healthcheck =
-			svc.kind === "web"
-				? `\n\t\thealthcheck: "/api/health",\n\t\thealthcheckTimeout: 120,`
-				: "";
+		if (svc.kind === "web") {
+			fields.push('healthcheck: "/api/health"', "healthcheckTimeout: 120");
+		}
 
-		// Build env vars — escape all string values
+		// Env vars — escape all string values
 		const extraVars = serviceVars[svc.name] || {};
 		const envEntries = [
 			...Object.entries(variableRefs),
@@ -122,16 +155,16 @@ export async function generateIacFile({
 			...Object.entries(extraVars),
 		];
 
-		const envBlock =
-			envEntries.length > 0
-				? `,\n\t\tenv: {\n${envEntries.map(([k, v]) => `\t\t\t${escapeTsString(k)}: ${v},`).join("\n")}\n\t\t}`
-				: "";
+		if (envEntries.length > 0) {
+			const envLines = envEntries
+				.map(([k, v]) => `\t\t\t${escapeTsString(k)}: ${v},`)
+				.join("\n");
+			fields.push(`env: {\n${envLines}\n\t\t}`);
+		}
 
-		resourceLines.push(`\tconst ${svcIdentifier} = service("${svcLabel}", {
-\t\tbuild: "${escapeTsString(buildCmd)}",
-\t\tstart: "${escapeTsString(startCmd)}",
-\t\tpreDeploy: "${escapeTsString(preDeploy)}",${healthcheck}${envBlock}
-\t});`);
+		resourceLines.push(
+			`\tconst ${svcIdentifier} = service("${svcLabel}", {\n\t\t${fields.join(",\n\t\t")},\n\t});`,
+		);
 	}
 
 	const resources = services.map((s) => toIdentifier(s.name)).join(", ");
@@ -156,7 +189,27 @@ ${resourceLines.join("\n\n")}
 ${body}`;
 
 	await fs.ensureDir(dirname(iacPath));
-	await fs.writeFile(iacPath, content, "utf8");
+
+	// `.railway/railway.ts` is a tracked file that every scaffold ships with a
+	// hand-written copy of. Overwriting it silently is how a deploy once
+	// replaced a committed file with generated output and the user only found
+	// out from `git status` afterwards. So: skip the write when nothing changed,
+	// and hand the previous content back when something did, so the caller can
+	// show the diff. The file is tracked, so `git checkout` remains the escape
+	// hatch — this only makes the change visible at the moment it happens.
+	let previous = null;
+	try {
+		previous = await fs.readFile(iacPath, "utf8");
+	} catch {
+		previous = null;
+	}
+
+	const changed = previous !== content;
+	if (changed) {
+		await fs.writeFile(iacPath, content, "utf8");
+	}
+
+	return { content, changed, previous };
 }
 
 /**
@@ -181,18 +234,68 @@ export async function applyIacConfig({ cwd, timeout = 120_000 } = {}) {
 	}
 }
 
+/**
+ * Checks whether the `railway` package already resolves from `cwd`.
+ *
+ * Walks up from `cwd` the way Node's resolver does, so a hoisted install in a
+ * pnpm workspace root is found from a package directory too.
+ *
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @returns {Promise<boolean>}
+ */
+export async function hasRailwaySdk({ cwd } = {}) {
+	const { default: fs } = await import("fs-extra");
+	const { dirname, join, parse, resolve } = await import("node:path");
+
+	const root = parse(resolve(cwd)).root;
+	let dir = resolve(cwd);
+
+	while (dir !== root) {
+		if (
+			await fs.pathExists(join(dir, "node_modules", "railway", "package.json"))
+		) {
+			return true;
+		}
+		dir = dirname(dir);
+	}
+
+	return false;
+}
+
 /**
  * Installs the Railway SDK (required for TypeScript IaC evaluation).
  *
+ * No-op when the package already resolves, so a repeat deploy does not touch
+ * package.json or the lockfile again.
+ *
+ * `-w` is passed explicitly because every scaffolded project is a pnpm
+ * workspace and the SDK is added at the root. Current pnpm versions accept the
+ * bare form, but older ones reject it with `ERR_PNPM_ADDING_TO_ROOT` and name
+ * the same command as the remedy, so being explicit is the only version this
+ * has to reason about.
+ *
  * @param {object} options
  * @param {string} options.cwd - Project root directory
  * @param {string} [options.packageManager="pnpm"] - Package manager to use
+ * @returns {Promise<{installed: boolean, alreadyPresent: boolean}>}
  */
 export async function installRailwaySdk({ cwd, packageManager = "pnpm" } = {}) {
-	await execa(packageManager, ["add", "-D", "railway"], {
+	if (await hasRailwaySdk({ cwd })) {
+		return { installed: false, alreadyPresent: true };
+	}
+
+	const args = ["add", "-D"];
+	if (packageManager === "pnpm") {
+		args.push("-w");
+	}
+	args.push("railway");
+
+	await execa(packageManager, args, {
 		cwd,
 		timeout: 60_000,
 	});
+	return { installed: true, alreadyPresent: false };
 }
 
 /**

package/src/deploy/adapters/index.js

@@ -3,6 +3,8 @@ export {
 	escapeTsString,
 	generateIacFile,
 	getDeploymentStatus,
+	hasRailwaySdk,
+	iacRef,
 	installRailwaySdk,
 } from "./iac.js";
 export {
@@ -21,7 +23,9 @@ export {
 	listProjects,
 	RAILWAY,
 	RailwayError,
+	readLinkedProject,
 	removeServiceDomain,
+	resolveProjectName,
 	setProjectVariables,
 	tryLinkProject,
 } from "./railway.js";

package/src/deploy/adapters/railway.js

@@ -42,13 +42,8 @@ export async function checkRailwayLogin() {
 }
 
 export async function isProjectLinked(cwd) {
-	const railwayDir = path.join(cwd, ".railway");
-	try {
-		const entries = await fs.readdir(railwayDir);
-		return entries.some((e) => e.endsWith(".json"));
-	} catch {
-		return false;
-	}
+	const { projectId } = await readLinkedProject({ cwd });
+	return projectId !== null;
 }
 
 export async function tryLinkProject(projectId, { cwd } = {}) {
@@ -76,6 +71,124 @@ export async function listProjects({ cwd } = {}) {
 	}
 }
 
+/**
+ * Reads the Railway project this directory is linked to.
+ *
+ * Two layouts are in play, because the CLI moved:
+ *
+ * - Railway CLI 3.x wrote `.railway/config.json` inside the project directory,
+ *   holding only `projectId` — no name to be found in it.
+ * - Railway CLI 5.x (verified against 5.62.1) keeps every link in
+ *   `~/.railway/config.json`, in a `projects` map keyed by absolute directory,
+ *   with `project` (the id) and `name` alongside it. A linked project
+ *   directory contains `.railway/railway.ts` and nothing else.
+ *
+ * Both are read, per-project first. The `~/.railway` file also holds the user's
+ * OAuth tokens; only the `projects` map is read and nothing else from it is
+ * ever returned or logged.
+ *
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @returns {Promise<{projectId: string|null, projectName: string|null}>}
+ */
+export async function readLinkedProject({ cwd } = {}) {
+	const fromProjectDir = await readProjectDirLink(cwd);
+	if (fromProjectDir.projectId) return fromProjectDir;
+
+	return readUserConfigLink(cwd);
+}
+
+/** Railway CLI 3.x layout: `.railway/config.json` in the project directory. */
+async function readProjectDirLink(cwd) {
+	const railwayDir = path.join(cwd, ".railway");
+	try {
+		const entries = await fs.readdir(railwayDir);
+		for (const entry of entries.filter((e) => e.endsWith(".json"))) {
+			try {
+				const parsed = JSON.parse(
+					await fs.readFile(path.join(railwayDir, entry), "utf8"),
+				);
+				const projectId = parsed?.projectId ?? null;
+				const projectName = parsed?.projectName ?? parsed?.name ?? null;
+				if (projectId || projectName) return { projectId, projectName };
+			} catch {
+				// Not the file we were after, or unparseable — try the next.
+			}
+		}
+	} catch {
+		// No .railway directory, or not readable.
+	}
+	return { projectId: null, projectName: null };
+}
+
+/**
+ * Railway CLI 5.x layout: `~/.railway/config.json`, `projects` keyed by
+ * absolute directory path.
+ */
+async function readUserConfigLink(cwd) {
+	const empty = { projectId: null, projectName: null };
+
+	const home = process.env.HOME ?? process.env.USERPROFILE;
+	if (!home) return empty;
+
+	try {
+		const parsed = JSON.parse(
+			await fs.readFile(path.join(home, ".railway", "config.json"), "utf8"),
+		);
+		const projects = parsed?.projects;
+		if (!projects || typeof projects !== "object") return empty;
+
+		const target = path.resolve(cwd);
+		const entry =
+			projects[target] ??
+			Object.values(projects).find(
+				(v) =>
+					typeof v?.projectPath === "string" &&
+					path.resolve(v.projectPath) === target,
+			);
+		if (!entry) return empty;
+
+		return {
+			projectId: entry.project ?? null,
+			projectName: entry.name ?? null,
+		};
+	} catch {
+		// No user config, unparseable, or unreadable — treat as unlinked.
+		return empty;
+	}
+}
+
+/**
+ * Resolves a project id to its name via the API, for when the link record
+ * carries only an id.
+ *
+ * @param {string} projectId
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @returns {Promise<string|null>}
+ */
+export async function resolveProjectName(projectId, { cwd } = {}) {
+	if (!projectId) return null;
+	const match = (await listProjects({ cwd })).find((p) => p.id === projectId);
+	return match?.name ?? null;
+}
+
+/**
+ * Best-effort name for a linked project: the link record when it carries one,
+ * otherwise resolved from its id.
+ *
+ * @param {object} options
+ * @param {string} options.cwd - Project root directory
+ * @returns {Promise<{projectId: string|null, projectName: string|null}>}
+ */
+async function linkedProjectWithName({ cwd }) {
+	const linked = await readLinkedProject({ cwd });
+	if (linked.projectName || !linked.projectId) return linked;
+
+	const projectName = await resolveProjectName(linked.projectId, { cwd });
+	return { projectId: linked.projectId, projectName };
+}
+
 export async function ensureRailwayProject({
 	projectName,
 	projectId,
@@ -86,11 +199,26 @@ export async function ensureRailwayProject({
 	if (alreadyLinked) {
 		try {
 			await execa(RAILWAY, ["status"], { cwd, timeout: 15_000 });
-			return { created: false, linked: true, projectName: null };
+			// Report the linked name rather than null: callers label generated
+			// IaC and app metadata from it, and falling back to the local
+			// directory name is how a project called `quark-site` ended up
+			// advertising itself as whatever directory it was deployed from.
+			const linked = await linkedProjectWithName({ cwd });
+			return {
+				created: false,
+				linked: true,
+				projectName: linked.projectName,
+			};
 		} catch {
-			// Stale link - clean up so we don't create an orphan project
-			const railwayDir = path.join(cwd, ".railway");
-			await fs.rm(railwayDir, { recursive: true, force: true });
+			// Stale link - clear it so we don't create an orphan project.
+			// `railway unlink` is what actually removes the link; it lives in
+			// ~/.railway on CLI 5.x, so deleting .railway/ here would only
+			// destroy the IaC file while leaving the stale link in place.
+			try {
+				await execa(RAILWAY, ["unlink"], { cwd, timeout: 15_000 });
+			} catch {
+				// Nothing to unlink, or it failed — fall through either way.
+			}
 		}
 	}
 
@@ -99,7 +227,8 @@ export async function ensureRailwayProject({
 			cwd,
 			timeout: 30_000,
 		});
-		return { created: false, linked: true, projectName: null };
+		const projectName = await resolveProjectName(projectId, { cwd });
+		return { created: false, linked: true, projectName };
 	}
 
 	if (!projectName) {

package/src/deploy/deploy.js

@@ -12,6 +12,8 @@ import {
 	getDeploymentStatus,
 	getExistingVariable,
 	getServiceUrl,
+	hasRailwaySdk,
+	iacRef,
 	installRailwaySdk,
 	removeServiceDomain,
 	setProjectVariables,
@@ -99,13 +101,17 @@ export async function deployToRailway(options = {}) {
 
 	// --- Step 4: Ensure Railway project ---
 	console.log(chalk.cyan("  Ensuring Railway project..."));
+	let resolvedProjectName = projectName || null;
 	try {
 		const project = await ensureRailwayProject({ projectName, projectId, cwd });
+		// Prefer the name Railway actually resolved. The local directory name is
+		// only a fallback for naming a brand new project — it must not become the
+		// project's identity just because the deploy ran from a differently-named
+		// checkout.
+		resolvedProjectName = project.projectName || resolvedProjectName;
 		if (project.created) {
 			console.log(
-				chalk.green(
-					`  ✔ Created Railway project "${project.projectName || projectName || ""}"`,
-				),
+				chalk.green(`  ✔ Created Railway project "${resolvedProjectName}"`),
 			);
 		} else {
 			console.log(chalk.green("  ✔ Railway project linked"));
@@ -141,7 +147,7 @@ export async function deployToRailway(options = {}) {
 	}
 
 	// --- Step 6: Preserve existing secrets across deploys ---
-	const projectLabel = path.basename(cwd);
+	const projectLabel = resolvedProjectName || path.basename(cwd);
 	let authSecret;
 	let nextAuthSecret;
 
@@ -170,14 +176,18 @@ export async function deployToRailway(options = {}) {
 	console.log(chalk.cyan("  Generating IaC configuration..."));
 	const iacPath = `${cwd}/.railway/railway.ts`;
 
-	await generateIacFile({
+	const iacResult = await generateIacFile({
 		iacPath,
 		services: discovery.services,
 		// Pass raw name — generateIacFile handles escaping internally
-		projectName: projectName || projectLabel,
+		projectName: projectLabel,
 		variableRefs: {
-			DATABASE_URL: `\${{${pgServiceName}.DATABASE_URL}}`,
-			REDIS_URL: `\${{${redisServiceName}.REDIS_URL}}`,
+			// Quoted: these land inside generated TypeScript as object values,
+			// where `${{...}}` must be a string literal to parse at all. The
+			// equivalent bare form is still used in step 9, where the value is a
+			// command-line argument rather than an expression.
+			DATABASE_URL: iacRef(pgServiceName, "DATABASE_URL"),
+			REDIS_URL: iacRef(redisServiceName, "REDIS_URL"),
 			NODE_ENV: '"production"',
 			APP_NAME: `"${escapeTsString(projectLabel)}"`,
 			APP_DESCRIPTION: `"${escapeTsString(`${projectLabel} - Quark application`)}"`,
@@ -197,23 +207,34 @@ export async function deployToRailway(options = {}) {
 			},
 		},
 	});
+	if (iacResult.changed) {
+		console.log(
+			chalk.yellow(
+				"  · .railway/railway.ts rewritten — review with `git diff .railway/railway.ts`",
+			),
+		);
+	}
 	console.log(chalk.green(`  ✔ IaC file generated at .railway/railway.ts`));
 
 	// --- Step 8: Install Railway SDK (required for IaC evaluation) ---
-	console.log(chalk.cyan("  Installing Railway SDK..."));
-	try {
-		await installRailwaySdk({ cwd });
-		console.log(chalk.green("  ✔ Railway SDK installed"));
-	} catch (error) {
-		// SDK is mandatory — railway config apply cannot evaluate .railway/railway.ts without it
-		console.error(
-			chalk.red(`  ✖ Failed to install Railway SDK: ${error.message}`),
-		);
-		throw new Error(
-			`Railway SDK installation failed. The generated IaC file requires the "railway" package.\n` +
-				`Install it manually: pnpm add -D railway\n` +
-				`Original error: ${error.message}`,
-		);
+	if (await hasRailwaySdk({ cwd })) {
+		console.log(chalk.dim("  · Railway SDK already installed"));
+	} else {
+		console.log(chalk.cyan("  Installing Railway SDK..."));
+		try {
+			await installRailwaySdk({ cwd });
+			console.log(chalk.green("  ✔ Railway SDK installed"));
+		} catch (error) {
+			// SDK is mandatory — railway config apply cannot evaluate .railway/railway.ts without it
+			console.error(
+				chalk.red(`  ✖ Failed to install Railway SDK: ${error.message}`),
+			);
+			throw new Error(
+				`Railway SDK installation failed. The generated IaC file requires the "railway" package.\n` +
+					`Install it manually: pnpm add -D -w railway\n` +
+					`Original error: ${error.message}`,
+			);
+		}
 	}
 
 	// --- Step 9: Set dynamic variable references (infrastructure wiring) ---

package/src/deploy/discovery.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import {
 	QUARK_DEPLOY_PROJECT_KIND,
 	QUARK_SERVICE_CONTRACTS,
+	QUARK_SERVICE_KINDS,
 	SUPPORTED_QUARK_SERVICE_KINDS,
 } from "./contract.js";
 
@@ -10,6 +11,17 @@ export const QUARK_DEPLOY_DIAGNOSTIC_CODES = Object.freeze({
 	MISSING_REQUIRED_SERVICE: "missing_required_service",
 });
 
+/**
+ * Codes for conditions that do not block a deploy but are worth saying out loud.
+ *
+ * Kept separate from DIAGNOSTIC_CODES because `resolveQuarkDeployProject` throws on
+ * any diagnostic, and a worker-less project is a legitimate choice — `jobs` is an
+ * optional scaffold feature. Failing the deploy would punish a valid configuration.
+ */
+export const QUARK_DEPLOY_WARNING_CODES = Object.freeze({
+	MISSING_WORKER_SERVICE: "missing_worker_service",
+});
+
 function resolveProjectPath(projectDir, relativePath) {
 	return path.join(projectDir, ...relativePath.split("/"));
 }
@@ -37,6 +49,17 @@ function createMissingRequiredServiceDiagnostic(serviceContract) {
 	};
 }
 
+function createMissingWorkerWarning() {
+	return {
+		code: QUARK_DEPLOY_WARNING_CODES.MISSING_WORKER_SERVICE,
+		serviceKind: "worker",
+		required: false,
+		expectedPath: QUARK_SERVICE_CONTRACTS.worker.relativePackageJsonPath,
+		message:
+			"No Quark worker service found. Scheduled jobs will not run — including CLEANUP_ORPHANED_FILES, which is the only thing that sweeps the File rows left orphaned when a user is deleted (onDelete: SetNull keeps the rows and the blobs). Those rows and blobs accumulate indefinitely. Add the jobs feature (`npx @usequark/quark-create-app add jobs`) if this project uploads files.",
+	};
+}
+
 function createDiscoveredService(projectDir, serviceContract, packageJson) {
 	return {
 		kind: serviceContract.kind,
@@ -68,6 +91,9 @@ export function formatQuarkDeployDiagnostics(diagnostics) {
 export async function discoverQuarkDeployProject(projectDir) {
 	const services = [];
 	const diagnostics = [];
+	const warnings = [];
+	let sawWeb = false;
+	let sawWorker = false;
 
 	for (const serviceKind of SUPPORTED_QUARK_SERVICE_KINDS) {
 		const serviceContract = QUARK_SERVICE_CONTRACTS[serviceKind];
@@ -85,16 +111,26 @@ export async function discoverQuarkDeployProject(projectDir) {
 			continue;
 		}
 
+		if (serviceKind === QUARK_SERVICE_KINDS.WEB) sawWeb = true;
+		if (serviceKind === QUARK_SERVICE_KINDS.WORKER) sawWorker = true;
+
 		services.push(
 			createDiscoveredService(projectDir, serviceContract, packageJson),
 		);
 	}
 
+	// A web project with no worker is valid — `jobs` is optional — but the orphaned
+	// file cleanup only runs there, so say so rather than letting it fail silently.
+	if (sawWeb && !sawWorker) {
+		warnings.push(createMissingWorkerWarning());
+	}
+
 	return {
 		kind: QUARK_DEPLOY_PROJECT_KIND,
 		rootDir: projectDir,
 		services,
 		diagnostics,
+		warnings,
 	};
 }
 

package/src/deploy/index.js

@@ -12,13 +12,17 @@ export {
 	getDeploymentStatus,
 	getExistingVariable,
 	getServiceUrl,
+	hasRailwaySdk,
+	iacRef,
 	installRailwaySdk,
 	isProjectLinked,
 	listProjects,
 	RAILWAY,
 	RAILWAY_DIAGNOSTIC_CODES,
 	RailwayError,
+	readLinkedProject,
 	removeServiceDomain,
+	resolveProjectName,
 	setProjectVariables,
 	tryLinkProject,
 } from "./adapters/index.js";

package/src/deploy/inspect.js

@@ -45,13 +45,23 @@ export async function inspectProject(options = {}) {
 
 	// --- Diagnostics ---
 	if (discovery.diagnostics.length > 0) {
-		output(chalk.yellow("  Diagnostics\n"));
+		output(chalk.yellow("  Diagnostics"));
 		for (const diagnostic of discovery.diagnostics) {
 			output(`  ${chalk.yellow("⚠")} ${diagnostic.message}`);
 		}
 		output();
 	}
 
+	// --- Warnings ---
+	// Non-blocking, so printed after diagnostics and separately from them.
+	if (discovery.warnings.length > 0) {
+		output(chalk.yellow("  Warnings"));
+		for (const warning of discovery.warnings) {
+			output(`  ${chalk.yellow("⚠")} ${warning.message}`);
+		}
+		output();
+	}
+
 	// --- Railway readiness ---
 	output(chalk.cyan("  Railway Readiness\n"));
 

package/src/index.js

@@ -10,6 +10,7 @@ import { execa } from "execa";
 import fs from "fs-extra";
 import prompts from "prompts";
 import { SCAFFOLD_GITIGNORE } from "./scaffold-gitignore.js";
+import { warnIfJobsOmitted } from "./scaffold-warning.js";
 import { findEnclosingGitRepo, formatProjectDisplayName } from "./utils.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -611,7 +612,7 @@ program
 	)
 	.option(
 		"--packages <packages>",
-		"Comma-separated list of optional packages to include (ui,jobs,pwa)",
+		"Comma-separated optional packages to include (ui,jobs,pwa). db, config, ui always scaffolded. Mobile is post-creation: quark add mobile",
 	)
 	.option(
 		"--prompt <prompt>",
@@ -952,6 +953,8 @@ program
 						`  Selected packages: ${features.join(", ") || "none"} (non-interactive mode)`,
 					),
 				);
+
+				warnIfJobsOmitted(features);
 			} else if (!options.prompts) {
 				// Use defaults when --no-prompts is set without --packages
 				console.log(chalk.cyan("\n  🎯 Configuring optional packages..."));
@@ -1014,6 +1017,8 @@ program
 
 				features = resolveFeatureSelection(selectedFeatures);
 
+				warnIfJobsOmitted(features);
+
 				const requestedFeatures = [...selectedFeatures];
 				const autoIncluded = features.filter(
 					(feature) => !requestedFeatures.includes(feature),

package/src/scaffold-warning.js

@@ -0,0 +1,39 @@
+import chalk from "chalk";
+
+/**
+ * Warn when the `jobs` feature was not selected for a scaffold.
+ *
+ * `File.uploadedBy` is `onDelete: SetNull`, so deleting a user orphans their file
+ * rows rather than removing them. `CLEANUP_ORPHANED_FILES` is the only thing that
+ * sweeps those rows and their blobs, and it runs in the worker — which is scaffolded
+ * only alongside `jobs`. Declining `jobs` therefore leaves orphaned rows and blobs
+ * accumulating indefinitely, with nothing reading `uploadedById = null` to surface
+ * them.
+ *
+ * Said at the point of the decision rather than discovered in production. It is a
+ * warning and not a refusal: `jobs` is optional and a project with no uploads has no
+ * orphan problem.
+ *
+ * @param {string[]} features - Resolved feature list for the scaffold.
+ * @returns {boolean} Whether the warning was printed.
+ */
+export function warnIfJobsOmitted(features, log = console.log) {
+	if (features.includes("jobs")) return false;
+
+	log(
+		chalk.yellow(
+			`    ⚠ Background jobs omitted: the orphaned-file cleanup will not exist.`,
+		),
+	);
+	log(
+		chalk.dim(
+			`      Deleting a user leaves their uploaded files orphaned in storage — the schema\n      keeps the rows rather than removing them — and without a worker nothing sweeps them.`,
+		),
+	);
+	log(
+		chalk.dim(
+			`      Add it later with: npx @usequark/quark-create-app add jobs\n`,
+		),
+	);
+	return true;
+}

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

@@ -25,7 +25,7 @@
 		"@usequark/quark-ui": "workspace:*",
 		"ioredis": "^6.0.0",
 		"jose": "^6.2.12",
-		"next": "16.3.6",
+		"next": "16.3.8",
 		"next-auth": "5.0.0-beta.32",
 		"pg": "^8.23.0",
 		"react": "19.3.0",

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

@@ -1,4 +1,8 @@
-import { validateBody, withCsrfProtection } from "@usequark/quark-core";
+import {
+	ConflictError,
+	validateBody,
+	withCsrfProtection,
+} from "@usequark/quark-core";
 import { user, userUpdateSchema } from "@usequark/quark-db";
 import { NextResponse } from "next/server";
 import { requireRole } from "@/lib/auth-middleware";
@@ -36,11 +40,33 @@ export const PATCH = withCsrfProtection(async (request, { params }) => {
 	}
 });
 
+/**
+ * DELETE /api/users/[id]
+ * Delete a user. Admin only.
+ *
+ * Self-deletion is refused. The route resolves its target purely from the path
+ * segment and otherwise only checks the caller's role, so an admin could delete
+ * their own row — and if they were the last admin, leave the deployment with no
+ * way to administer it. Refusing here rather than warning is deliberate: the
+ * request cannot succeed without leaving either the caller or the deployment
+ * locked out, so there is no outcome the caller would want.
+ *
+ * This guard is per-request, not a check on the remaining admin count. Two
+ * concurrent deletes of the two last admins can still both pass it. Enforcing
+ * that invariant needs a transaction around the count and the delete, which is a
+ * larger change than this endpoint's current shape supports.
+ */
 export const DELETE = withCsrfProtection(async (_request, { params }) => {
 	try {
-		await requireRole("admin");
+		const session = await requireRole("admin");
 		const { id } = await params;
 
+		if (session?.user?.id === id) {
+			throw new ConflictError(
+				"You cannot delete the account you are signed in as",
+			);
+		}
+
 		const existingUser = await user.findById(id);
 		if (!existingUser) {
 			return NextResponse.json({ message: "User not found" }, { status: 404 });

package/templates/base-project/packages/db/prisma/migrations/20260202061128_initial/migration.sql

@@ -101,7 +101,8 @@ CREATE TABLE "File" (
 -- CreateTable
 CREATE TABLE "AuditLog" (
     "id" TEXT NOT NULL,
-    "userId" TEXT NOT NULL,
+    "userId" TEXT,
+    "actorEmail" TEXT,
     "action" TEXT NOT NULL,
     "entity" TEXT NOT NULL,
     "entityId" TEXT NOT NULL,
@@ -198,5 +199,5 @@ ALTER TABLE "Session" ADD CONSTRAINT "Session_userId_fkey" FOREIGN KEY ("userId"
 ALTER TABLE "File" ADD CONSTRAINT "File_uploadedById_fkey" FOREIGN KEY ("uploadedById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
 
 -- AddForeignKey
-ALTER TABLE "AuditLog" ADD CONSTRAINT "AuditLog_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+ALTER TABLE "AuditLog" ADD CONSTRAINT "AuditLog_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
 

package/templates/base-project/packages/db/prisma/schema.prisma

@@ -141,18 +141,28 @@ model File {
 }
 
 // Audit Log Model
+//
+// `userId` is nullable and SetNull, not Cascade. An audit record that is deleted
+// along with the user it describes cannot serve as an audit trail — and deleting a
+// user destroys the rows recording what that user did, including the rows recording
+// the deletion itself.
+//
+// `actorEmail` snapshots the actor's address at write time. With SetNull alone the
+// row survives but stops naming who acted, so a trail that outlives its actor would
+// be unattributable. The snapshot keeps the record readable on its own terms.
 model AuditLog {
-  id        String   @id @default(cuid())
-  userId    String
-  action    String
-  entity    String
-  entityId  String
-  changes   Json?
-  metadata  Json?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  user User @relation(fields: [userId], references: [id], onDelete: Cascade)
+  id          String   @id @default(cuid())
+  userId      String?
+  actorEmail  String?
+  action      String
+  entity      String
+  entityId    String
+  changes     Json?
+  metadata    Json?
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+
+  user User? @relation(fields: [userId], references: [id], onDelete: SetNull)
 
   @@index([userId])
   @@index([action])

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

@@ -15,6 +15,22 @@ const USER_SAFE_SELECT = {
 	updatedAt: true,
 };
 
+/**
+ * Look up an actor's email for the AuditLog snapshot.
+ *
+ * The lookup cannot miss: the foreign key rejects a `userId` that names no user,
+ * so `onDelete: SetNull` is the only way `userId` becomes null, and it happens after
+ * the snapshot was written. A null `userId` here means the caller supplied none.
+ */
+async function resolveActorEmail(userId) {
+	if (!userId) return null;
+	const actor = await prisma.user.findUnique({
+		where: { id: userId },
+		select: { email: true },
+	});
+	return actor?.email ?? null;
+}
+
 export { USER_SAFE_SELECT };
 
 // User queries
@@ -188,13 +204,21 @@ export const verificationToken = {
 };
 
 // AuditLog queries
+//
+// `user` is optional: a deleted user leaves `userId` null but the row survives
+// (see the AuditLog model). Every read therefore returns `actorEmail` alongside,
+// so a caller can name the actor without dereferencing `user`. Render `actorEmail`
+// — `user` is for callers that need the live row, e.g. to follow through to the
+// user's current role.
+const AUDIT_ACTOR_SELECT = { id: true, email: true, name: true };
+
 export const auditLog = {
 	findAll: (options = {}) => {
 		const { skip = 0, take = 50 } = options;
 		return prisma.auditLog.findMany({
 			skip,
 			take,
-			include: { user: { select: { id: true, email: true, name: true } } },
+			include: { user: { select: AUDIT_ACTOR_SELECT } },
 			orderBy: { createdAt: "desc" },
 		});
 	},
@@ -204,7 +228,7 @@ export const auditLog = {
 			where: { userId },
 			skip,
 			take,
-			include: { user: { select: { id: true, email: true, name: true } } },
+			include: { user: { select: AUDIT_ACTOR_SELECT } },
 			orderBy: { createdAt: "desc" },
 		});
 	},
@@ -214,7 +238,7 @@ export const auditLog = {
 			where: { entity },
 			skip,
 			take,
-			include: { user: { select: { id: true, email: true, name: true } } },
+			include: { user: { select: AUDIT_ACTOR_SELECT } },
 			orderBy: { createdAt: "desc" },
 		});
 	},
@@ -224,14 +248,25 @@ export const auditLog = {
 			where: { action },
 			skip,
 			take,
-			include: { user: { select: { id: true, email: true, name: true } } },
+			include: { user: { select: AUDIT_ACTOR_SELECT } },
 			orderBy: { createdAt: "desc" },
 		});
 	},
-	create: (data) => {
+	/**
+	 * Create an audit record, snapshotting the actor's email.
+	 *
+	 * The snapshot is written here rather than left to the caller because it is the
+	 * only thing that keeps the record attributable once the user row is gone:
+	 * `onDelete: SetNull` preserves the row but clears `userId`. A caller that
+	 * forgets the field gets a permanent record naming nobody, so this derives it
+	 * from `userId` when not supplied.
+	 */
+	create: async (data) => {
+		const actorEmail =
+			data.actorEmail ?? (await resolveActorEmail(data.userId));
 		return prisma.auditLog.create({
-			data,
-			include: { user: { select: { id: true, email: true, name: true } } },
+			data: { ...data, actorEmail },
+			include: { user: { select: AUDIT_ACTOR_SELECT } },
 		});
 	},
 };

package/templates/base-project/pnpm-workspace.yaml

@@ -11,6 +11,31 @@ onlyBuiltDependencies:
   - simple-git-hooks
 
 overrides:
+  # next-auth@5.0.0-beta.32 and @auth/core@0.41.3 declare nodemailer as an
+  # OPTIONAL peer with the range `^7.0.7 || ^8.0.5`. Every advisory against
+  # nodemailer needs >=10.0.6, so no version inside that peer range is
+  # patched, and neither package has shipped a newer release that widens it.
+  #
+  # Nothing in this repo uses Auth.js's Nodemailer email provider: auth.js
+  # configures Credentials, Github and Google only, and @auth/core's index
+  # never imports nodemailer statically (only providers/nodemailer.js does).
+  # Outgoing mail goes through @usequark/quark-core, which depends on
+  # nodemailer ^10.0.10 directly. Removing the unused peer edge deletes the
+  # vulnerable 7.0.13 copy from the tree instead of forcing it two majors past
+  # a range its author chose. Delete these two lines if you ever add
+  # next-auth/providers/nodemailer.
+  "next-auth>nodemailer": "-"
+  "@auth/core>nodemailer": "-"
+  # stripe@17.7.0 declares `qs: ^6.11.0`, so 6.16.0 is inside its own range and
+  # `pnpm update` cannot move it (qs is not a direct dependency of any workspace
+  # package). GHSA-g4mx-9h6g-cwc7 / GHSA-hrpp-f998-fjpq both need >=6.16.0.
+  qs@>=6.14.2 <=6.15.3: ">=6.16.0"
+  # xcode@3.0.1 declares `uuid: ^7.0.3`; GHSA-w5hq-g745-h8pq needs >=11.1.1,
+  # four majors ahead. Safe here because xcode only calls uuid.v4() (lib/
+  # pbxProject.js), which is unchanged in 11.x, and 11.1.1 still supports
+  # CommonJS require(). This is build-time only - xcode is reached through
+  # @expo/config-plugins while generating native projects.
+  uuid@<11.1.1: ">=11.1.1"
   fast-xml-builder@<1.1.7: ">=1.1.7"
   fast-xml-parser@<5.10.1: ">=5.10.1"
   lodash@>=4.0.0 <=4.17.22: ">=4.17.23"

package/templates/base-project/scripts/check-standards.mjs

@@ -15,6 +15,51 @@ const tsExtensions = new Set([".ts", ".tsx"]);
 const throwNewErrorPattern = /\bthrow new Error\s*\(/;
 const consolePattern = /\bconsole\.(?:log|warn|error|info)\s*\(/;
 
+/**
+ * `next-auth` and `@auth/core` declare nodemailer as an *optional* peer pinned to
+ * `^7.0.7 || ^8.0.5`. No version in that range is free of an advisory, so
+ * pnpm-workspace.yaml removes the peer edge entirely instead:
+ *
+ *   "next-auth>nodemailer": "-"
+ *   "@auth/core>nodemailer": "-"
+ *
+ * That is what clears 13 of the 21 advisories, and it is safe only while nothing
+ * imports Auth.js's Nodemailer provider. The failure mode if that changes is bad:
+ * `providers/nodemailer.js` does `import { createTransport } from "nodemailer"` at
+ * module scope, so the import throws ERR_MODULE_NOT_FOUND on the next server start -
+ * not at build time, and not with any hint that an override caused it.
+ *
+ * This check turns that into a build failure with the fix attached. It fires on the
+ * import specifier rather than on the override, so it stays correct if the override
+ * is ever reworded, and it covers both the monorepo and the scaffold template.
+ *
+ * The pattern has to accept every way a module specifier can be reached, because a
+ * guard that misses one spelling is worse than none: it reads as protection while
+ * letting the breakage through. All of these resolve the provider and so must fail:
+ *
+ *   import N from "next-auth/providers/nodemailer"        // static default
+ *   import "next-auth/providers/nodemailer"               // bare side-effect
+ *   export { default } from "next-auth/providers/nodemailer"
+ *   await import("next-auth/providers/nodemailer")        // dynamic
+ *   import("next-auth/providers/nodemailer").then(m => m.default)
+ *   require("next-auth/providers/nodemailer")             // CommonJS
+ *
+ * The optional `\(` is what the first version got wrong: dynamic `import(` puts a
+ * paren between the keyword and the quote, so an alternation of
+ * `from|import|require\s*\(` matched the static forms and silently missed every
+ * dynamic one.
+ *
+ * Each keyword carries a leading `\b` so an identifier that merely contains one -
+ * `important`, `myrequire` - cannot trigger it, and the specifier is anchored so
+ * only this exact module matches.
+ *
+ * If you genuinely want the provider: delete the two overrides above, then add
+ * `nodemailer` (>=10.0.6, past every advisory) to the app's own dependencies and
+ * allowlist this check for that file.
+ */
+const authNodemailerProviderPattern =
+	/\b(?:from|import|require)\s*\(?\s*["'`]next-auth\/providers\/nodemailer["'`]/;
+
 /**
  * Tailwind v4 removed the bare `[--var]` shorthand that v3 accepted. Under v4 a
  * class such as `text-[--navbar-text-muted]` is still a *valid* utility name, so
@@ -125,6 +170,36 @@ function findMatchingLines(content, pattern) {
 	return matches;
 }
 
+/**
+ * Same job as findMatchingLines, but matches against the whole file rather than one
+ * line at a time, and reports the line each match starts on.
+ *
+ * Needed for the nodemailer guard, whose pattern legitimately spans a line break:
+ * `import Nodemailer from\n  "next-auth/providers/nodemailer";` is valid JavaScript
+ * that the line-at-a-time version cannot see, because the keyword and the specifier
+ * land on different lines. Line-at-a-time is the right default for the other checks -
+ * they only ever match within one line - so this is opt-in.
+ *
+ * The match is retried with a lastIndex-aware scan because a pattern carrying the `g`
+ * flag would otherwise return only the first hit; `d` additionally keeps the index
+ * pointing at the start of the match rather than at a capture group.
+ */
+function findMatchingLinesMultiline(content, pattern) {
+	const scanner = new RegExp(
+		pattern.source,
+		pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`,
+	);
+	const matches = [];
+	let match = scanner.exec(content);
+	while (match !== null) {
+		matches.push(content.slice(0, match.index).split("\n").length);
+		// A zero-width match would otherwise loop forever.
+		scanner.lastIndex = match.index + (match[0].length || 1);
+		match = scanner.exec(content);
+	}
+	return matches;
+}
+
 async function collectFiles(directoryPath) {
 	const entries = await readdir(directoryPath, { withFileTypes: true });
 	const files = [];
@@ -213,6 +288,17 @@ async function main() {
 				);
 			}
 		}
+
+		if (isSourceFile(relativePath)) {
+			for (const lineNumber of findMatchingLinesMultiline(
+				content,
+				authNodemailerProviderPattern,
+			)) {
+				violations.push(
+					`${relativePath}:${lineNumber}: next-auth/providers/nodemailer cannot resolve - pnpm-workspace.yaml removes that peer edge to clear 13 nodemailer advisories, and the peer range (^7.0.7 || ^8.0.5) has no patched version. Delete the two nodemailer overrides and add nodemailer >=10.0.6 as a direct dependency to use this provider.`,
+				);
+			}
+		}
 	}
 
 	if (violations.length > 0) {

package/templates/base-project/skills/quark-skills/SKILL.md

@@ -14,18 +14,13 @@ Every skill below ships with this project and is always available. Skills are ab
 | add-model | `add-model/SKILL.md` | Add a new Prisma model, query helpers, and tests to the db package. |
 | add-endpoint | `add-endpoint/SKILL.md` | Add an API route (or Server Action) with Zod validation, CSRF, and role guards. |
 | add-dashboard | `add-dashboard/SKILL.md` | Add a metrics/overview dashboard page with metric cards and loading states. |
-| admin-dashboard | `admin-dashboard/SKILL.md` | Build a full admin/back-office area: guarded routes, CRUD screens, audit logging. |
 
 ## Domain starters
 
-These teach the AI to build a complete vertical on demand. No starter code is scaffolded - the AI generates it from the skill.
+These teach the AI to build a complete vertical on demand. No starter code is scaffolded; the AI generates it from the skill.
 
 | Skill | Path | Purpose |
 |---|---|---|
-| bookings | `bookings/SKILL.md` | Booking/reservation/appointment/scheduling systems. |
-| crm | `crm/SKILL.md` | Contact/pipeline/customer relationship systems. |
-| cms | `cms/SKILL.md` | Content modeling, authoring, and publishing systems. |
-| ai | `ai/SKILL.md` | AI assistant features (chat, completions) on app data. |
 | payment | `payment/SKILL.md` | Stripe payment integration, checkout, webhooks, fulfillment. |
 | ecommerce | `ecommerce/SKILL.md` | Product catalog, cart, checkout, orders, inventory. Sub-skills: `ecommerce-catalog`, `ecommerce-cart`, `ecommerce-checkout`. |
 | i18n | `i18n/SKILL.md` | Internationalization, locale routing, localized CMS content, hreflang SEO. |

package/templates/base-project/turbo.json

@@ -7,7 +7,8 @@
 		"npm_lifecycle_event",
 		"QUARK_SKIP_AUTO_CLEAN",
 		"QUARK_SKIP_DEV_PREFLIGHT",
-		"QUARK_SKIP_GIT_INIT"
+		"QUARK_SKIP_GIT_INIT",
+		"CHECK_AUDIT_FIXTURE"
 	],
 	"tasks": {
 		"clean": {

package/templates/ui/package.json

@@ -9,7 +9,7 @@
 	},
 	"dependencies": {
 		"lucide-react": "^1.48.0",
-		"next": "16.3.6"
+		"next": "16.3.8"
 	},
 	"devDependencies": {
 		"@types/react": "^19.3.0",