@usequark/quark-create-app 1.25.2 → 1.25.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequark/quark-create-app",
-  "version": "1.25.2",
+  "version": "1.25.4",
   "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

@@ -2,6 +2,48 @@ 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",
+];
+
+/**
+ * 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.
@@ -53,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,
@@ -65,9 +110,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) {
@@ -88,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),
@@ -102,33 +155,61 @@ 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(", ");
 
-	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");
+
+	// `.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 };
 }
 
 /**
@@ -153,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/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/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", {