@usequark/quark-create-app 1.25.1 → 1.25.3

package/package.json

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

package/src/deploy/adapters/iac.js

@@ -2,6 +2,29 @@ import { execa } from "execa";
 
 const RAILWAY = "railway";
 
+/**
+ * Every helper `railway/iac` exports that can appear in a generated body.
+ *
+ * The import list is derived from the helpers the body actually calls, rather
+ * than hardcoded. A helper that is called but not imported is a ReferenceError
+ * when the CLI evaluates the file, and that evaluation only happens later, in
+ * the user's `railway config apply` — so nothing in this repo ever surfaced it.
+ * Deriving the list makes the two impossible to drift apart.
+ */
+const IAC_HELPERS = [
+	"bucket",
+	"database",
+	"defineRailway",
+	"group",
+	"image",
+	"postgres",
+	"preserve",
+	"project",
+	"redis",
+	"service",
+	"volume",
+];
+
 /**
  * Escapes a string for safe embedding in a TypeScript string literal.
  * Handles backslashes, quotes, newlines, and template literal interpolation.
@@ -65,9 +88,6 @@ export async function generateIacFile({
 	const { default: fs } = await import("fs-extra");
 	const { dirname } = await import("node:path");
 
-	const imports = new Set();
-	imports.add(`import { defineRailway, project, service } from "railway/iac";`);
-
 	const resourceLines = [];
 
 	for (const svc of services) {
@@ -116,17 +136,25 @@ export async function generateIacFile({
 
 	const resources = services.map((s) => toIdentifier(s.name)).join(", ");
 
-	const content = `${Array.from(imports).join("\n")}
-
-export default defineRailway(() => {
+	const body = `export default defineRailway(() => {
 ${resourceLines.join("\n\n")}
 
-\treturn project("${escapeTsString(projectName)}", {
-\t\tresources: [${resources}],
-\t});
+	return project("${escapeTsString(projectName)}", {
+		resources: [${resources}],
+	});
 });
 `;
 
+	// Derive the import list from the body so a helper can never be called
+	// without being in scope. See IAC_HELPERS.
+	const used = IAC_HELPERS.filter((helper) =>
+		new RegExp(`\\b${helper}\\s*\\(`).test(body),
+	).sort();
+
+	const content = `import { ${used.join(", ")} } from "railway/iac";
+
+${body}`;
+
 	await fs.ensureDir(dirname(iacPath));
 	await fs.writeFile(iacPath, content, "utf8");
 }

package/src/index.js

@@ -1530,6 +1530,10 @@ STORAGE_PROVIDER=local
 				__QUARK_SCOPE__: scope,
 				__QUARK_PROJECT_NAME__: projectName,
 				__QUARK_SCAFFOLD_DATE__: scaffoldDate,
+				// The web port is resolved in Step 9 (findAvailablePort), so the
+				// docs can point at the port the app will actually bind rather
+				// than always claiming 3000.
+				__QUARK_WEB_PORT__: String(webPort),
 				__QUARK_OPTIONAL_APPS__: optionalAppLines,
 				__QUARK_OPTIONAL_PACKAGES__: optionalBlock,
 				__QUARK_FEATURE_ROWS__: featureRows,

package/templates/base-project/.railway/railway.ts

@@ -1,4 +1,4 @@
-import { defineRailway, project, service } from "railway/iac";
+import { defineRailway, preserve, project, service } from "railway/iac";
 
 export default defineRailway(() => {
 	const web = service("web", {

package/templates/base-project/MAIN.md

@@ -6,8 +6,7 @@
 
 1. `CLAUDE.md` - project rules and conventions (keep this updated)
 2. `docs/` - guides and walkthroughs
-3. `openapi.yaml` - API contract
-4. `.opencode/skills/` - embedded skills (how to build bookings, CRM, CMS, AI, and more on this project)
+3. `.opencode/skills/` - embedded skills (how to build bookings, CRM, CMS, AI, and more on this project)
 
 ## Quick start
 
@@ -18,4 +17,4 @@ pnpm db:migrate        # Apply migrations
 pnpm dev               # Start the app (and worker, if included)
 ```
 
-Open [http://localhost:3000](http://localhost:3000).
+Open [http://localhost:__QUARK_WEB_PORT__](http://localhost:__QUARK_WEB_PORT__).

package/templates/base-project/README.md

@@ -19,7 +19,7 @@ pnpm db:seed           # Seed the database (admin user + sample data)
 pnpm dev               # Start the app (and worker, if included)
 ```
 
-Open [http://localhost:3000](http://localhost:3000)
+Open [http://localhost:__QUARK_WEB_PORT__](http://localhost:__QUARK_WEB_PORT__)
 
 ## UI References
 

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

@@ -10,37 +10,39 @@
  * 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.
+ *
+ * The probing itself lives in `@usequark/quark-core/health`. This route is the
+ * thin HTTP shell around it: it wires the app's probes in and renders the
+ * report. Projects hand-rolled their own copy of this orchestration, which is
+ * what the core module replaces.
  */
 
 import {
+	checkQueues,
+	checkStorage,
 	createLogger,
-	createStorage,
 	getRegisteredQueues,
 	pingRedis,
+	runHealthChecks,
 } from "@usequark/quark-core";
 import { pingDatabase } from "@usequark/quark-db";
 import { NextResponse } from "next/server";
 
 const logger = createLogger("health");
 
-/** 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 runHealthChecks();
+		// `pingDatabase` is passed in rather than imported by the core module:
+		// `@usequark/quark-db` depends on `@usequark/quark-core`, so core cannot
+		// import it back without a cycle.
+		const result = await runHealthChecks({
+			probes: {
+				database: pingDatabase,
+				redis: pingRedis,
+				storage: checkStorage,
+				queues: () => checkQueues(getRegisteredQueues),
+			},
+		});
 
 		// Always 200 — see the module comment. An orchestrator restarting this
 		// service is what turns a dependency blip into an outage.
@@ -67,197 +69,3 @@ export async function GET() {
 		);
 	}
 }
-
-/**
- * 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 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(),
-		durationMs: Math.round(performance.now() - startedAt),
-		checks,
-	};
-}
-
-/**
- * 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";
-	}
-
-	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: error?.message,
-		});
-	} finally {
-		clearTimeout(timer);
-	}
-}
-
-/**
- * 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;
-
-	const { message, ...rest } = result;
-	return { ...rest, status: "error", message: safeMessage(name, message) };
-}
-
-/**
- * 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 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 }>}
- */
-async function checkStorage() {
-	const provider = process.env.STORAGE_PROVIDER || "local";
-	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/scripts/run-tests.mjs

@@ -60,6 +60,35 @@ function collectTests(targetPath) {
 
 const files = roots.flatMap((rootPath) => collectTests(path.resolve(rootPath)));
 
+/**
+ * Escapes glob metacharacters so `node --test` treats the path as a literal
+ * path rather than a pattern.
+ *
+ * Next.js dynamic route segments are directories of the form `[id]` and
+ * `[...slug]`, and `node --test` matches its file arguments as globs. An
+ * unescaped `[id]` is read as a character class matching a single `i` or `d`,
+ * so the path matches nothing. The failure is silent — the runner reports
+ * zero tests and exits 0 — which meant every test co-located in a dynamic
+ * segment (`api/files/[id]/route.test.js`, and `users/[id]` and
+ * `[...nextauth]` which have none) was collected here and then silently
+ * dropped at the `node --test` boundary.
+ *
+ * Only `[` and `]` need escaping: a literal `*`, `?`, `{`, `}`, `+`, `@` or
+ * `!` in a directory name is resolved as itself once no glob metacharacter
+ * remains to give it meaning. `[[]` and `[]]` are the character-class escapes
+ * for the literal characters; a backslash is *not* honoured here, so it
+ * silently fails to escape anything.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+function escapeGlobChars(filePath) {
+	// Single pass. Two `replaceAll` calls in sequence do not work: the `[` of
+	// `[[]` introduces a `]` that the second call then escapes again, yielding
+	// `[[[]]` for one literal `[`.
+	return filePath.replace(/[[\]]/g, (char) => (char === "[" ? "[[]" : "[]]"));
+}
+
 if (files.length === 0) {
 	// An empty suite is not a failure. `node --test` exits 0 when it matches no
 	// files, so exiting 1 here made a freshly scaffolded project fail its own
@@ -75,7 +104,7 @@ const result = spawnSync(
 		"tsx/esm",
 		"--experimental-test-module-mocks",
 		"--test",
-		...files,
+		...files.map(escapeGlobChars),
 	],
 	{
 		stdio: "inherit",