@usequark/quark-create-app 1.23.11

package/src/deploy/adapters/railway.test.js

@@ -0,0 +1,318 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: this file exists to
+// exercise Railway's own `${{Service.VAR}}` template syntax and the escaper that
+// neutralises a literal `${}`. Both are plain strings by design, and the rule
+// cannot tell them apart from a missed template interpolation.
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { after, test } from "node:test";
+
+const temporaryDirectories = [];
+
+after(async () => {
+	await Promise.all(
+		temporaryDirectories.map((dir) =>
+			fs.rm(dir, { recursive: true, force: true }),
+		),
+	);
+});
+
+async function makeTempDir() {
+	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "railway-test-"));
+	temporaryDirectories.push(dir);
+	return dir;
+}
+
+// --- Mock execa ---
+// We inject a mock by rewriting the module's execa reference via
+// import.meta mocking. Since node:test doesn't support that natively,
+// we test the adapter functions by providing our own execa replacement.
+// The module imports execa from "execa"; for testing we verify behavior
+// by calling internal helpers with mocked execa.
+
+// Instead, test the CLI wrapper functions using a utility that replaces execa.
+// We'll test the public interface by calling the real functions against
+// a fixture directory and testing the helper functions.
+
+test("checkRailwayCLI returns null when railway is not installed", async () => {
+	const { checkRailwayCLI } = await import("./railway.js");
+	// On a system without railway, this returns null.
+	// On a system with railway, it returns a version string.
+	// We just verify it returns either null or a non-empty string.
+	const result = await checkRailwayCLI();
+	if (result === null) {
+		assert.equal(result, null);
+	} else {
+		assert.ok(typeof result === "string" && result.length > 0);
+	}
+});
+
+test("checkRailwayLogin returns null when not logged in", async () => {
+	const { checkRailwayLogin } = await import("./railway.js");
+	const result = await checkRailwayLogin();
+	if (result === null) {
+		assert.equal(result, null);
+	} else {
+		assert.ok(typeof result === "string" && result.length > 0);
+	}
+});
+
+test("isProjectLinked returns false when .railway directory does not exist", async () => {
+	const { isProjectLinked } = await import("./railway.js");
+	const tmpDir = await makeTempDir();
+	const result = await isProjectLinked(tmpDir);
+	assert.equal(result, false);
+});
+
+test("isProjectLinked returns true when .railway directory contains config", async () => {
+	const { isProjectLinked } = await import("./railway.js");
+	const tmpDir = await makeTempDir();
+	const railwayDir = path.join(tmpDir, ".railway");
+	await fs.mkdir(railwayDir, { recursive: true });
+	await fs.writeFile(
+		path.join(railwayDir, "config.json"),
+		JSON.stringify({ projectId: "test" }),
+	);
+	const result = await isProjectLinked(tmpDir);
+	assert.equal(result, true);
+});
+
+test("isProjectLinked returns false when .railway directory is empty", async () => {
+	const { isProjectLinked } = await import("./railway.js");
+	const tmpDir = await makeTempDir();
+	const railwayDir = path.join(tmpDir, ".railway");
+	await fs.mkdir(railwayDir, { recursive: true });
+	const result = await isProjectLinked(tmpDir);
+	assert.equal(result, false);
+});
+
+test("RailwayError has correct shape", async () => {
+	const { RailwayError, DIAGNOSTIC_CODES } = await import("./railway.js");
+	const error = new RailwayError(
+		"test error",
+		DIAGNOSTIC_CODES.RAILWAY_CLI_NOT_FOUND,
+		{ detail: "x" },
+	);
+	assert.equal(error.name, "RailwayError");
+	assert.equal(error.code, DIAGNOSTIC_CODES.RAILWAY_CLI_NOT_FOUND);
+	assert.equal(error.message, "test error");
+	assert.deepEqual(error.meta, { detail: "x" });
+});
+
+test("DIAGNOSTIC_CODES are frozen", async () => {
+	const { DIAGNOSTIC_CODES } = await import("./railway.js");
+	assert.throws(() => {
+		DIAGNOSTIC_CODES.NEW_CODE = "test";
+	});
+});
+
+// --- IaC adapter tests ---
+
+test("generateIacFile creates .railway/railway.ts with preserve() for secrets", async () => {
+	const { generateIacFile } = await import("./iac.js");
+	const tmpDir = await makeTempDir();
+	const iacPath = path.join(tmpDir, ".railway", "railway.ts");
+
+	await generateIacFile({
+		iacPath,
+		services: [
+			{ name: "web", kind: "web", relativeRootDir: "apps/web" },
+			{ name: "worker", kind: "worker", relativeRootDir: "apps/worker" },
+		],
+		secrets: {
+			AUTH_SECRET: "preserve()",
+			NEXTAUTH_SECRET: "preserve()",
+		},
+		variableRefs: {
+			DATABASE_URL: "${{Postgres.DATABASE_URL}}",
+			REDIS_URL: "${{Redis.REDIS_URL}}",
+		},
+		serviceVars: {
+			worker: { WORKER_CONCURRENCY: '"5"' },
+		},
+		projectName: "test-project",
+	});
+
+	const content = await fs.readFile(iacPath, "utf8");
+	assert.ok(content.includes("import { defineRailway"));
+	assert.ok(content.includes('service("web"'));
+	assert.ok(content.includes('service("worker"'));
+	assert.ok(content.includes("preserve()"));
+	assert.ok(content.includes("${{Postgres.DATABASE_URL}}"));
+	assert.ok(content.includes("${{Redis.REDIS_URL}}"));
+	assert.ok(content.includes("pnpm db:migrate:deploy"));
+	assert.ok(content.includes("/api/health"));
+	assert.ok(content.includes("WORKER_CONCURRENCY"));
+	assert.ok(content.includes('"test-project"'));
+	// Must NOT contain github() source — CLI deploys manage settings, not sources
+	assert.ok(
+		!content.includes("github("),
+		"Generated IaC must not reference github()",
+	);
+	assert.ok(
+		!content.includes("source:"),
+		"Generated IaC must not include source field",
+	);
+});
+
+test("escapeTsString escapes dangerous characters", async () => {
+	const { escapeTsString } = await import("./iac.js");
+
+	assert.strictEqual(escapeTsString('hello"world'), 'hello\\"world');
+	assert.strictEqual(escapeTsString("back\\slash"), "back\\\\slash");
+	assert.strictEqual(escapeTsString("line\nbreak"), "line\\nbreak");
+	assert.strictEqual(escapeTsString("dollar${}"), "dollar\\${}");
+	assert.strictEqual(escapeTsString("cr\rreturn"), "cr\\rreturn");
+	assert.strictEqual(escapeTsString("safe-value"), "safe-value");
+});
+
+test("generateIacFile escapes service names with special chars", async () => {
+	const { generateIacFile } = await import("./iac.js");
+	const tmpDir = await makeTempDir();
+	const iacPath = path.join(tmpDir, ".railway", "railway.ts");
+
+	await generateIacFile({
+		iacPath,
+		services: [
+			{ name: 'my "web" app', kind: "web", relativeRootDir: "apps/web" },
+		],
+		projectName: 'project "name"',
+	});
+
+	const content = await fs.readFile(iacPath, "utf8");
+	// Variable name uses sanitized identifier (underscores, not escaped quotes)
+	assert.ok(content.includes('const my_web_app = service("my \\"web\\" app"'));
+	// Project name is escaped in string, not double-escaped
+	assert.ok(content.includes('project("project \\"name\\""'));
+	// Resources list uses identifiers
+	assert.ok(content.includes("resources: [my_web_app]"));
+});
+
+// --- Environment flag forwarding tests ---
+// These use a mock railway CLI on PATH to verify --environment is
+// forwarded to execa for each function that supports it.
+
+async function withMockRailway(fn) {
+	const tmpDir = await makeTempDir();
+	const railwayPath = path.join(tmpDir, "railway");
+	const argsLog = path.join(tmpDir, "args.log");
+
+	await fs.writeFile(
+		railwayPath,
+		`#!/bin/sh
+echo "$*" >> "${argsLog}"
+case "$*" in
+  *"deployment list"*)
+    echo '[{"id":"dep_mock_123","status":"SUCCESS"}]'
+    ;;
+  *"list"*)
+    echo '[]'
+    ;;
+  *)
+    echo '{"deploymentId":"dep_mock_123"}'
+    ;;
+esac
+`,
+	);
+	await fs.chmod(railwayPath, 0o755);
+
+	const origPath = process.env.PATH;
+	process.env.PATH = `${tmpDir}:${origPath}`;
+
+	try {
+		await fn(tmpDir, argsLog);
+	} finally {
+		process.env.PATH = origPath;
+	}
+}
+
+test("deployService forwards --environment flag", async () => {
+	await withMockRailway(async (tmpDir, argsLog) => {
+		const { deployService } = await import("./railway.js");
+
+		await deployService("web", { cwd: tmpDir, environment: "staging" });
+
+		const log = await fs.readFile(argsLog, "utf-8");
+		assert.ok(
+			log.includes("--environment"),
+			`Expected --environment in args: ${log}`,
+		);
+		assert.ok(log.includes("staging"), `Expected staging in args: ${log}`);
+	});
+});
+
+test("setProjectVariable forwards --environment flag", async () => {
+	await withMockRailway(async (tmpDir, argsLog) => {
+		const { setProjectVariable } = await import("./railway.js");
+
+		await setProjectVariable("KEY", "val", {
+			cwd: tmpDir,
+			environment: "staging",
+			serviceName: "web",
+		});
+
+		const log = await fs.readFile(argsLog, "utf-8");
+		assert.ok(
+			log.includes("--environment"),
+			`Expected --environment in args: ${log}`,
+		);
+		assert.ok(log.includes("staging"), `Expected staging in args: ${log}`);
+	});
+});
+
+test("setProjectVariables forwards --environment flag", async () => {
+	await withMockRailway(async (tmpDir, argsLog) => {
+		const { setProjectVariables } = await import("./railway.js");
+
+		await setProjectVariables(
+			[
+				{ key: "A", value: "1" },
+				{ key: "B", value: "2" },
+			],
+			{ cwd: tmpDir, environment: "staging", serviceName: "web" },
+		);
+
+		const log = await fs.readFile(argsLog, "utf-8");
+		assert.ok(
+			log.includes("--environment"),
+			`Expected --environment in args: ${log}`,
+		);
+		assert.ok(log.includes("staging"), `Expected staging in args: ${log}`);
+	});
+});
+
+test("getExistingVariable forwards --environment flag", async () => {
+	await withMockRailway(async (tmpDir, argsLog) => {
+		const { getExistingVariable } = await import("./railway.js");
+
+		// Mock returns empty JSON array for variable list
+		await getExistingVariable("AUTH_SECRET", {
+			cwd: tmpDir,
+			environment: "staging",
+			serviceName: "web",
+		});
+
+		const log = await fs.readFile(argsLog, "utf-8");
+		assert.ok(
+			log.includes("--environment"),
+			`Expected --environment in args: ${log}`,
+		);
+		assert.ok(log.includes("staging"), `Expected staging in args: ${log}`);
+	});
+});
+
+test("deleteService forwards --environment flag", async () => {
+	await withMockRailway(async (tmpDir, argsLog) => {
+		const { deleteService } = await import("./railway.js");
+
+		await deleteService("web", { cwd: tmpDir, environment: "staging" });
+
+		const log = await fs.readFile(argsLog, "utf-8");
+		assert.ok(
+			log.includes("--environment"),
+			`Expected --environment in args: ${log}`,
+		);
+		assert.ok(log.includes("staging"), `Expected staging in args: ${log}`);
+	});
+});

package/src/deploy/contract.js

@@ -0,0 +1,59 @@
+export const QUARK_DEPLOY_PROJECT_KIND = "quark";
+
+export const QUARK_SERVICE_KINDS = Object.freeze({
+	WEB: "web",
+	WORKER: "worker",
+	OPENCODE: "opencode",
+});
+
+const webServiceContract = Object.freeze({
+	kind: QUARK_SERVICE_KINDS.WEB,
+	name: "web",
+	required: true,
+	relativeRootDir: "apps/web",
+	relativePackageJsonPath: "apps/web/package.json",
+	relativeIacPath: ".railway/railway.ts",
+	runtime: Object.freeze({
+		type: "node",
+		relativeEntrypoint: "apps/web/.next/standalone/apps/web/server.js",
+		healthcheckPath: "/api/health",
+	}),
+});
+
+const workerServiceContract = Object.freeze({
+	kind: QUARK_SERVICE_KINDS.WORKER,
+	name: "worker",
+	required: false,
+	relativeRootDir: "apps/worker",
+	relativePackageJsonPath: "apps/worker/package.json",
+	relativeIacPath: ".railway/railway.ts",
+	runtime: Object.freeze({
+		type: "node",
+		relativeEntrypoint: "apps/worker/src/index.js",
+	}),
+});
+
+const opencodeServiceContract = Object.freeze({
+	kind: QUARK_SERVICE_KINDS.OPENCODE,
+	name: "opencode",
+	required: false,
+	relativeRootDir: "apps/opencode",
+	relativePackageJsonPath: "apps/opencode/package.json",
+	relativeIacPath: ".railway/railway.ts",
+	runtime: Object.freeze({
+		type: "node",
+		relativeEntrypoint: "apps/opencode/Dockerfile",
+	}),
+});
+
+export const QUARK_SERVICE_CONTRACTS = Object.freeze({
+	[QUARK_SERVICE_KINDS.WEB]: webServiceContract,
+	[QUARK_SERVICE_KINDS.WORKER]: workerServiceContract,
+	[QUARK_SERVICE_KINDS.OPENCODE]: opencodeServiceContract,
+});
+
+export const SUPPORTED_QUARK_SERVICE_KINDS = Object.freeze([
+	QUARK_SERVICE_KINDS.WEB,
+	QUARK_SERVICE_KINDS.WORKER,
+	QUARK_SERVICE_KINDS.OPENCODE,
+]);

package/src/deploy/deploy.integration.test.js

@@ -0,0 +1,183 @@
+import assert from "node:assert/strict";
+import { execSync } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { after, test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const temporaryDirectories = [];
+
+after(async () => {
+	await Promise.all(
+		temporaryDirectories.map((dir) =>
+			fs.rm(dir, { recursive: true, force: true, maxRetries: 3 }),
+		),
+	);
+});
+
+async function makeTempDir() {
+	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "deploy-int-"));
+	temporaryDirectories.push(dir);
+	return dir;
+}
+
+async function writeJson(filePath, value) {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	await fs.writeFile(filePath, JSON.stringify(value, null, "\t"));
+}
+
+/**
+ * Create a fixture that looks like a Quark project with web + worker.
+ */
+async function createQuarkFixture() {
+	const projectDir = await makeTempDir();
+
+	await writeJson(path.join(projectDir, "package.json"), {
+		name: "@test/quark-app",
+		private: true,
+		type: "module",
+	});
+
+	await writeJson(path.join(projectDir, "apps", "web", "package.json"), {
+		name: "@test/quark-web",
+		private: true,
+		type: "module",
+	});
+
+	await writeJson(path.join(projectDir, "apps", "worker", "package.json"), {
+		name: "@test/quark-worker",
+		private: true,
+		type: "module",
+	});
+
+	return projectDir;
+}
+
+function runQuarkCli(args) {
+	const cliEntry = path.join(__dirname, "../../src/index.js");
+	try {
+		const result = execSync(
+			`${process.execPath} ${cliEntry} ${args.join(" ")}`,
+			{
+				encoding: "utf8",
+				timeout: 10_000,
+				stdio: ["ignore", "pipe", "pipe"],
+			},
+		);
+		return result;
+	} catch (error) {
+		// execSync throws on non-zero exit — return stdout if available
+		if (error.stdout) return error.stdout.toString("utf8");
+		throw error;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Level 2: Integration - deployToRailway with missing Railway CLI
+// ---------------------------------------------------------------------------
+
+test("checkRailwayCLI returns null when railway is not on PATH", async () => {
+	const { checkRailwayCLI } = await import("./adapters/railway.js");
+	const origPath = process.env.PATH;
+	process.env.PATH = "/dev/null";
+	try {
+		const result = await checkRailwayCLI();
+		assert.equal(result, null);
+	} finally {
+		process.env.PATH = origPath;
+	}
+});
+
+// ---------------------------------------------------------------------------
+// Level 2: Integration - adapter functions with mocked project
+// ---------------------------------------------------------------------------
+
+test("isProjectLinked returns false for unlinked project", async () => {
+	const { isProjectLinked } = await import("./adapters/railway.js");
+	const projectDir = await createQuarkFixture();
+	const result = await isProjectLinked(projectDir);
+	assert.equal(result, false);
+});
+
+test("isProjectLinked returns true after creating .railway directory with config", async () => {
+	const { isProjectLinked } = await import("./adapters/railway.js");
+	const projectDir = await createQuarkFixture();
+	const railwayDir = path.join(projectDir, ".railway");
+	await fs.mkdir(railwayDir, { recursive: true });
+	await fs.writeFile(
+		path.join(railwayDir, "config.json"),
+		JSON.stringify({ projectId: "test-123" }),
+	);
+	const result = await isProjectLinked(projectDir);
+	assert.equal(result, true);
+});
+
+// ---------------------------------------------------------------------------
+// Level 2: Integration - resolveQuarkDeployProject with fixtures
+// ---------------------------------------------------------------------------
+
+test("resolveQuarkDeployProject discovers web + worker in fixture", async () => {
+	const { resolveQuarkDeployProject } = await import("./discovery.js");
+	const projectDir = await createQuarkFixture();
+	const discovery = await resolveQuarkDeployProject(projectDir);
+
+	assert.equal(discovery.kind, "quark");
+	assert.equal(discovery.services.length, 2);
+	assert.equal(discovery.services[0].kind, "web");
+	assert.equal(discovery.services[1].kind, "worker");
+});
+
+test("resolveQuarkDeployProject fails when web is missing", async () => {
+	const { resolveQuarkDeployProject } = await import("./discovery.js");
+	const projectDir = await makeTempDir();
+
+	await writeJson(path.join(projectDir, "package.json"), {
+		name: "@test/quark-app",
+		private: true,
+	});
+
+	await assert.rejects(() => resolveQuarkDeployProject(projectDir), {
+		code: "QUARK_DEPLOY_DISCOVERY_FAILED",
+	});
+});
+
+// ---------------------------------------------------------------------------
+// Level 2: Integration - inspectProject with fixture
+// ---------------------------------------------------------------------------
+
+test("inspectProject loads and inspects fixture without error", async () => {
+	const { inspectProject } = await import("./inspect.js");
+	const projectDir = await createQuarkFixture();
+
+	// Suppress stdout — inspectProject prints a report via console.log, and
+	// unstructured text on the test runner's stdout pipe can corrupt the
+	// binary v8-serialized result frames (nodejs/node#64061), flaking CI.
+	await inspectProject({ cwd: projectDir, output: () => {} });
+});
+
+// ---------------------------------------------------------------------------
+// Level 2: CLI command routing
+// ---------------------------------------------------------------------------
+
+test("quark deploy --help shows subcommands", () => {
+	const stdout = runQuarkCli(["deploy", "--help"]);
+
+	assert.match(stdout, /railway/);
+	assert.match(stdout, /inspect/);
+});
+
+test("quark deploy railway --help shows options", () => {
+	const stdout = runQuarkCli(["deploy", "railway", "--help"]);
+
+	assert.match(stdout, /project-name/);
+	assert.match(stdout, /project-id/);
+	assert.match(stdout, /dry-run/);
+});
+
+test("quark deploy inspect --help shows help", () => {
+	const stdout = runQuarkCli(["deploy", "inspect", "--help"]);
+
+	assert.ok(stdout.length > 0);
+});