@usequark/quark-create-app 1.23.11

package/src/scaffold-output.test.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+
+/**
+ * Scaffold output regression tests.
+ *
+ * A freshly scaffolded project must not contain any un-substituted
+ * __QUARK_* placeholders or @myquark package scopes. This guards the whole
+ * class of template-substitution bugs, including files outside the
+ * AI-context substitution list (docs, Railway config, embedded skills).
+ *
+ * Run with: node --test packages/cli/src/scaffold-output.test.js
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs, { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { after, before, describe, it } from "node:test";
+
+const CLI = path.join(import.meta.dirname, "index.js");
+const PROJECT_NAME = "placeholder-app";
+
+let tempDir;
+let projectDir;
+
+function runCLI(args, cwd) {
+	return spawnSync(process.execPath, [CLI, ...args], {
+		cwd,
+		encoding: "utf8",
+		timeout: 120_000,
+		env: { ...process.env, QUARK_SKIP_GIT_INIT: "true" },
+	});
+}
+
+function collectFiles(dir, files = []) {
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name === "node_modules" || entry.name === ".git") continue;
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			collectFiles(fullPath, files);
+		} else {
+			files.push(fullPath);
+		}
+	}
+	return files;
+}
+
+before(() => {
+	tempDir = mkdtempSync(path.join(tmpdir(), "quark-scaffold-output-"));
+	const result = runCLI(
+		[
+			PROJECT_NAME,
+			"--no-prompts",
+			"--packages",
+			"ui",
+			"--skip-install",
+			"--skip-docker",
+		],
+		tempDir,
+	);
+	assert.strictEqual(
+		result.status,
+		0,
+		`scaffold failed\nstdout: ${result.stdout}\nstderr: ${result.stderr}`,
+	);
+	projectDir = path.join(tempDir, PROJECT_NAME);
+});
+
+after(() => {
+	if (tempDir) {
+		rmSync(tempDir, { recursive: true, force: true });
+	}
+});
+
+describe("scaffold output placeholders", () => {
+	it("contains no un-substituted __QUARK_* or @myquark placeholders", () => {
+		const offenders = [];
+
+		for (const file of collectFiles(projectDir)) {
+			let content;
+			try {
+				content = fs.readFileSync(file, "utf-8");
+			} catch {
+				continue;
+			}
+			if (/__QUARK_|@myquark/.test(content)) {
+				offenders.push(path.relative(projectDir, file));
+			}
+		}
+
+		assert.deepStrictEqual(
+			offenders,
+			[],
+			`placeholder leaks found in: ${offenders.join(", ")}`,
+		);
+	});
+
+	it("rewrites the DB import in AI prompts to the project scope", () => {
+		const page = fs.readFileSync(
+			path.join(projectDir, "apps/web/src/app/page.js"),
+			"utf-8",
+		);
+		assert.ok(
+			page.includes(`@${PROJECT_NAME}/db`),
+			"AI prompt must reference @<scope>/db",
+		);
+		assert.ok(
+			!page.includes("@__QUARK_SCOPE__"),
+			"AI prompt must not keep the scope placeholder",
+		);
+	});
+
+	it("substitutes the project name in docs and Railway config", () => {
+		const mainMd = fs.readFileSync(path.join(projectDir, "MAIN.md"), "utf-8");
+		assert.ok(
+			mainMd.startsWith(`# ${PROJECT_NAME}`),
+			"MAIN.md title must use the project name",
+		);
+
+		const envExample = fs.readFileSync(
+			path.join(projectDir, ".env.railway.example"),
+			"utf-8",
+		);
+		assert.ok(
+			envExample.includes(`APP_NAME=${PROJECT_NAME}`),
+			".env.railway.example must use the project name",
+		);
+
+		const railway = fs.readFileSync(
+			path.join(projectDir, ".railway/railway.ts"),
+			"utf-8",
+		);
+		assert.ok(
+			railway.includes(`project("${PROJECT_NAME}"`),
+			".railway/railway.ts must use the project name",
+		);
+	});
+
+	it("substitutes placeholders in embedded skills", () => {
+		const skill = fs.readFileSync(
+			path.join(projectDir, ".opencode/skills/payment/SKILL.md"),
+			"utf-8",
+		);
+		assert.ok(
+			skill.includes(`@${PROJECT_NAME}/db`),
+			"embedded skills must use the project scope",
+		);
+	});
+
+	it("generates a migration.sql that Postgres can execute", () => {
+		const migrationSql = fs.readFileSync(
+			path.join(
+				projectDir,
+				"packages/db/prisma/migrations/20260202061128_initial/migration.sql",
+			),
+			"utf-8",
+		);
+
+		// Regression: capturing `prisma migrate diff --script` with a plain `>`
+		// also writes Prisma's stdout log line into the SQL. Postgres rejects the
+		// whole migration with `42601 syntax error at or near "Loaded"`, so every
+		// scaffolded project failed its first `db:migrate:deploy`.
+		const lines = migrationSql
+			.split("\n")
+			.map((line) => line.trim())
+			.filter((line) => line.length > 0);
+
+		assert.ok(
+			!lines.some((line) => /^Loaded Prisma config/.test(line)),
+			"migration.sql must not contain Prisma's stdout log line",
+		);
+
+		const firstStatement = lines.find((line) => !line.startsWith("--"));
+		assert.ok(
+			/^(CREATE|ALTER|DROP|INSERT|UPDATE)\b/.test(firstStatement),
+			`migration.sql must begin with a SQL statement (got: ${firstStatement})`,
+		);
+	});
+
+	it("scaffolds the PWA manifest as manifest.js, not a conflicting manifest.json", () => {
+		const appDir = path.join(projectDir, "apps/web/src/app");
+
+		// Next.js serves app/manifest.js at /manifest.webmanifest. A sibling
+		// app/manifest.json (what the PWA feature used to write) makes the build
+		// fail with "Cannot find module for page: /manifest.webmanifest".
+		assert.ok(
+			!fs.existsSync(path.join(appDir, "manifest.json")),
+			"app/manifest.json must not be scaffolded alongside app/manifest.js",
+		);
+
+		const manifest = fs.readFileSync(path.join(appDir, "manifest.js"), "utf-8");
+		assert.ok(
+			!manifest.includes("@__QUARK_SCOPE__"),
+			"PWA manifest must use the project scope, not __QUARK_SCOPE__",
+		);
+		assert.ok(
+			manifest.includes(`@${PROJECT_NAME}/config`),
+			"PWA manifest must import config from the project scope",
+		);
+	});
+
+	it("generates a valid auth section in .env.example", () => {
+		const envExample = fs.readFileSync(
+			path.join(projectDir, ".env.example"),
+			"utf-8",
+		);
+
+		const secretLine = envExample
+			.split("\n")
+			.find((line) => line.startsWith("NEXTAUTH_SECRET="));
+		assert.ok(secretLine, ".env.example must define NEXTAUTH_SECRET");
+		const secret = secretLine.slice("NEXTAUTH_SECRET=".length);
+		assert.ok(
+			secret.length >= 32,
+			`NEXTAUTH_SECRET placeholder must be at least 32 characters (got ${secret.length}) - startup validation rejects shorter values`,
+		);
+
+		assert.ok(
+			!/NEXTAUTH_URL=.*\/api\/auth/.test(envExample),
+			"NEXTAUTH_URL must be a bare origin, never include a path",
+		);
+		assert.ok(
+			!envExample.includes("derived automatically from PORT"),
+			"APP_URL is not derived from PORT - do not claim it is",
+		);
+	});
+});

package/src/template-scripts.test.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+
+/**
+ * Behavior tests for scripts shipped in the scaffolded base project.
+ *
+ * These run the template copies directly against synthetic project layouts,
+ * so they catch drift between the template scripts and what scaffolded
+ * projects actually need.
+ *
+ * Run with: node --test packages/cli/src/template-scripts.test.js
+ */
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs, { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { after, describe, it } from "node:test";
+
+const TEMPLATE_DIR = path.join(
+	import.meta.dirname,
+	"../templates/base-project",
+);
+const tempDirs = [];
+
+function makeTempDir() {
+	const dir = mkdtempSync(path.join(tmpdir(), "quark-template-scripts-"));
+	tempDirs.push(dir);
+	return dir;
+}
+
+function writeFile(root, relPath, content) {
+	const fullPath = path.join(root, relPath);
+	fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+	fs.writeFileSync(fullPath, content);
+}
+
+function copyScript(root, relPath) {
+	const dest = path.join(root, relPath);
+	fs.mkdirSync(path.dirname(dest), { recursive: true });
+	fs.copyFileSync(path.join(TEMPLATE_DIR, relPath), dest);
+	return dest;
+}
+
+function runScript(root, relPath) {
+	return spawnSync(process.execPath, [path.join(root, relPath)], {
+		cwd: root,
+		encoding: "utf8",
+		timeout: 30_000,
+	});
+}
+
+after(() => {
+	for (const dir of tempDirs) {
+		rmSync(dir, { recursive: true, force: true });
+	}
+});
+
+describe("check-loading.mjs", () => {
+	it("flags a DB-backed page without a sibling loading.js", () => {
+		const dir = makeTempDir();
+		copyScript(dir, "scripts/check-loading.mjs");
+		writeFile(
+			dir,
+			"apps/web/src/app/orders/page.js",
+			'import { prisma } from "@demo/db";\n\nexport default function Page() {\n\treturn null;\n}\n',
+		);
+
+		const result = runScript(dir, "scripts/check-loading.mjs");
+
+		assert.strictEqual(
+			result.status,
+			1,
+			"audit must exit 1 when loading.js is missing",
+		);
+		assert.match(result.stderr, /MISSING loading\.js/);
+	});
+
+	it("passes when the DB-backed page has a sibling loading.js", () => {
+		const dir = makeTempDir();
+		copyScript(dir, "scripts/check-loading.mjs");
+		writeFile(
+			dir,
+			"apps/web/src/app/orders/page.js",
+			'import { prisma } from "@demo/db";\n\nexport default function Page() {\n\treturn null;\n}\n',
+		);
+		writeFile(
+			dir,
+			"apps/web/src/app/orders/loading.js",
+			"export default null;\n",
+		);
+
+		const result = runScript(dir, "scripts/check-loading.mjs");
+
+		assert.strictEqual(result.status, 0, result.stderr);
+	});
+
+	it("ignores pages that do not import a db package", () => {
+		const dir = makeTempDir();
+		copyScript(dir, "scripts/check-loading.mjs");
+		writeFile(
+			dir,
+			"apps/web/src/app/about/page.js",
+			'import { Button } from "@demo/ui";\n\nexport default function Page() {\n\treturn null;\n}\n',
+		);
+
+		const result = runScript(dir, "scripts/check-loading.mjs");
+
+		assert.strictEqual(result.status, 0, result.stderr);
+	});
+
+	it("also recognizes the monorepo db package name", () => {
+		const dir = makeTempDir();
+		copyScript(dir, "scripts/check-loading.mjs");
+		writeFile(
+			dir,
+			"apps/web/src/app/metrics/page.js",
+			'import { prisma } from "@techstream/quark-db";\n\nexport default function Page() {\n\treturn null;\n}\n',
+		);
+
+		const result = runScript(dir, "scripts/check-loading.mjs");
+
+		assert.strictEqual(
+			result.status,
+			1,
+			"audit must exit 1 when loading.js is missing",
+		);
+	});
+});
+
+describe("check-standards.mjs", () => {
+	it("allows TypeScript in apps/mobile after quark add mobile", () => {
+		const dir = makeTempDir();
+		copyScript(dir, "scripts/check-standards.mjs");
+		writeFile(
+			dir,
+			"apps/mobile/app/(app)/index.tsx",
+			"export default function Home() {\n\treturn null;\n}\n",
+		);
+
+		const result = runScript(dir, "scripts/check-standards.mjs");
+
+		assert.strictEqual(result.status, 0, result.stderr);
+	});
+
+	it("still flags console.* in web app runtime code", () => {
+		const dir = makeTempDir();
+		copyScript(dir, "scripts/check-standards.mjs");
+		writeFile(
+			dir,
+			"apps/web/src/app/orders/page.js",
+			'export default function Page() {\n\tconsole.log("orders");\n\treturn null;\n}\n',
+		);
+
+		const result = runScript(dir, "scripts/check-standards.mjs");
+
+		assert.strictEqual(result.status, 1, "console.* must be flagged");
+		assert.match(result.stderr, /createLogger\(\)/);
+	});
+});

package/src/utils.js

@@ -0,0 +1,77 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { execa } from "execa";
+
+/**
+ * Shared utilities for @techstream/quark-create-app
+ */
+
+export function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Find the root of the git work tree that contains `dir`, if any.
+ *
+ * Used to avoid scaffolding a project into a nested git repository: running
+ * `git init` inside an existing work tree creates a second, independent
+ * repository that shadows the outer one and breaks commits at the repo root.
+ *
+ * @param {string} dir - Directory to inspect (must already exist)
+ * @returns {Promise<string|null>} Absolute path to the enclosing repository
+ *   root, or null when `dir` is not inside a git work tree (or git is not
+ *   available)
+ */
+export async function findEnclosingGitRepo(dir) {
+	try {
+		const { stdout } = await execa("git", ["rev-parse", "--show-toplevel"], {
+			cwd: dir,
+		});
+		const topLevel = stdout.trim();
+		return topLevel ? path.resolve(topLevel) : null;
+	} catch {
+		// Not inside a work tree, or git is not installed
+		return null;
+	}
+}
+
+export function generateSecret(length = 32) {
+	return crypto
+		.randomBytes(length)
+		.toString("base64")
+		.replace(/[/+=]/g, "")
+		.substring(0, length);
+}
+
+/**
+ * Format a project slug into a human-friendly application name.
+ *
+ * - Hyphens, underscores, and dots are treated as word separators
+ * - Each word is title-cased
+ * - Degenerate inputs (all separators) fall back to "Quark App"
+ *
+ * @param {string} projectName - Raw project slug (e.g. "my-cool-app")
+ * @returns {string} Title-cased display name (e.g. "My Cool App")
+ *
+ * @example
+ * formatProjectDisplayName("my-cool-app")   // "My Cool App"
+ * formatProjectDisplayName("my.app")         // "My App"
+ * formatProjectDisplayName("my_app_v2")      // "My App V2"
+ * formatProjectDisplayName("myapp")          // "Myapp"
+ * formatProjectDisplayName("---")            // "Quark App"
+ */
+export function formatProjectDisplayName(projectName) {
+	const normalized = projectName
+		.replace(/[-_.]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+
+	if (!normalized) {
+		return "Quark App";
+	}
+
+	return normalized
+		.split(" ")
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+		.join(" ");
+}

package/src/utils.test.js

@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, realpath, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import { execa } from "execa";
+import { findEnclosingGitRepo, formatProjectDisplayName } from "./utils.js";
+
+// ---------------------------------------------------------------------------
+// Happy path - common slug patterns
+// ---------------------------------------------------------------------------
+
+test("formatProjectDisplayName - hyphen-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my-cool-app"), "My Cool App");
+});
+
+test("formatProjectDisplayName - underscore-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my_app_v2"), "My App V2");
+});
+
+test("formatProjectDisplayName - dot-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my.app"), "My App");
+});
+
+test("formatProjectDisplayName - single word (no separators)", () => {
+	assert.strictEqual(formatProjectDisplayName("myapp"), "Myapp");
+});
+
+test("formatProjectDisplayName - already title-cased input", () => {
+	// slice(1) preserves remaining chars as-is - only the first char is forced uppercase
+	assert.strictEqual(formatProjectDisplayName("MyApp"), "MyApp");
+});
+
+test("formatProjectDisplayName - mixed separators", () => {
+	assert.strictEqual(formatProjectDisplayName("my-app_v2.0"), "My App V2 0");
+});
+
+test("formatProjectDisplayName - consecutive separators collapse to single space", () => {
+	assert.strictEqual(formatProjectDisplayName("my--app"), "My App");
+	assert.strictEqual(formatProjectDisplayName("my___app"), "My App");
+	assert.strictEqual(formatProjectDisplayName("my-._app"), "My App");
+});
+
+test("formatProjectDisplayName - numbers preserved in words", () => {
+	assert.strictEqual(formatProjectDisplayName("app-v2"), "App V2");
+	assert.strictEqual(formatProjectDisplayName("project-123"), "Project 123");
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases - degenerate / boundary inputs
+// ---------------------------------------------------------------------------
+
+test("formatProjectDisplayName - all separators returns fallback", () => {
+	assert.strictEqual(formatProjectDisplayName("---"), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("___"), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("..."), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("-._-"), "Quark App");
+});
+
+test("formatProjectDisplayName - preserves casing of rest of word", () => {
+	// The function only forces the first char uppercase; the remainder is untouched
+	assert.strictEqual(formatProjectDisplayName("myApp"), "MyApp");
+});
+
+test("formatProjectDisplayName - short single-char name", () => {
+	assert.strictEqual(formatProjectDisplayName("a"), "A");
+});
+
+// ---------------------------------------------------------------------------
+// findEnclosingGitRepo
+// ---------------------------------------------------------------------------
+
+test("findEnclosingGitRepo - returns null outside a git work tree", async () => {
+	const dir = await mkdtemp(path.join(os.tmpdir(), "quark-utils-"));
+	try {
+		assert.strictEqual(await findEnclosingGitRepo(dir), null);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+});
+
+test("findEnclosingGitRepo - returns the repository root for any nested dir", async () => {
+	const dir = await mkdtemp(path.join(os.tmpdir(), "quark-utils-"));
+	try {
+		await execa("git", ["init"], { cwd: dir });
+		const nested = path.join(dir, "some", "nested", "dir");
+		await mkdir(nested, { recursive: true });
+
+		const expected = await realpath(dir);
+		assert.strictEqual(await findEnclosingGitRepo(dir), expected);
+		assert.strictEqual(await findEnclosingGitRepo(nested), expected);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+});

package/src/worker-dockerfile.test.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * Worker Dockerfile guards.
+ *
+ * `pnpm deploy --prod` drops devDependencies but keeps the peer subtrees pnpm
+ * auto-installed *for* them. `prisma` (a devDependency of packages/db) declares
+ * `typescript` as an optional peer, so the hoisted store gains typescript@7 -
+ * the native Go build, which ships a ~100 MB Go `tsc` carrying 10 HIGH CVEs.
+ * The runtime worker image runs compiled JS and does not need it.
+ *
+ * These assertions run against the monorepo Dockerfile AND the scaffold
+ * template, so a regression cannot reappear in newly generated projects.
+ *
+ * Run with: node --test packages/cli/src/worker-dockerfile.test.js
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "../../..");
+
+const DOCKERFILES = [
+	["monorepo", "apps/worker/Dockerfile"],
+	["scaffold template", "packages/cli/templates/worker/Dockerfile"],
+];
+
+describe("worker Dockerfile strips dev-only native binaries", () => {
+	for (const [label, relativePath] of DOCKERFILES) {
+		it(`${label} removes the auto-installed typescript subtree`, () => {
+			const dockerfile = fs.readFileSync(
+				path.join(REPO_ROOT, relativePath),
+				"utf-8",
+			);
+
+			assert.match(
+				dockerfile,
+				/\/app\/deploy\/node_modules\/\.pnpm\/typescript@\*/,
+				"must strip the auto-installed typescript subtree from the deploy output",
+			);
+			assert.match(
+				dockerfile,
+				/@typescript\+typescript-\*/,
+				"must strip the @typescript platform binaries (the Go tsc)",
+			);
+			assert.match(
+				dockerfile,
+				/\*_typescript@\*/,
+				"must strip peer-suffixed directories such as valibot@1.4.2_typescript@7.0.2",
+			);
+			assert.match(
+				dockerfile,
+				/dev-only TypeScript binary leaked/,
+				"must fail the build if a dev-only binary reappears",
+			);
+		});
+
+		it(`${label} keeps the pruning after the deploy step`, () => {
+			const dockerfile = fs.readFileSync(
+				path.join(REPO_ROOT, relativePath),
+				"utf-8",
+			);
+
+			const deployIndex = dockerfile.indexOf("prod deploy");
+			const pruneIndex = dockerfile.indexOf("node_modules/.pnpm/typescript@*");
+			const copyIndex = dockerfile.lastIndexOf(
+				"COPY --from=builder /app/deploy/",
+			);
+
+			assert.ok(
+				deployIndex > -1,
+				"Dockerfile must still use `pnpm deploy --prod`",
+			);
+			assert.ok(pruneIndex > deployIndex, "pruning must run after the deploy");
+			assert.ok(
+				pruneIndex < copyIndex,
+				"pruning must run before the deploy output is copied into the runtime stage",
+			);
+		});
+	}
+});