@usequark/quark-create-app 1.23.11

package/templates/base-project/scripts/prepare.js

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+/**
+ * Cross-platform git hooks setup script.
+ *
+ * Handles two layouts:
+ * - Project at the git root: installs hooks via simple-git-hooks (as before).
+ * - Project nested inside a larger repository (monorepo, Conductor workspace):
+ *   git always runs hooks from the repository root, so plain `pnpm nano-staged`
+ *   hooks would run in the wrong directory. Instead, the project registers
+ *   itself in a shared dispatcher that runs each project's command from its own
+ *   directory. Multiple nested Quark projects compose instead of overwriting
+ *   each other, and hooks owned by other tools are never overwritten or deleted.
+ */
+import { execFileSync, execSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const PROJECT_DIR = path.resolve(path.dirname(SCRIPT_PATH), "..");
+
+// Marks hook files generated by this script so they can be safely replaced.
+const HOOK_MARKER = "quark:scoped-git-hook";
+
+// Directory (inside the git hooks dir) holding the dispatcher and one entry
+// file per project and hook.
+const SCOPED_HOOKS_DIR = "quark-scoped-hooks";
+const ENTRIES_DIR = "entries";
+
+// Hook names accepted by git (same list simple-git-hooks supports).
+const VALID_HOOKS = new Set([
+	"applypatch-msg",
+	"pre-applypatch",
+	"post-applypatch",
+	"pre-commit",
+	"pre-merge-commit",
+	"prepare-commit-msg",
+	"commit-msg",
+	"post-commit",
+	"pre-rebase",
+	"post-checkout",
+	"post-merge",
+	"pre-push",
+	"pre-receive",
+	"update",
+	"proc-receive",
+	"post-receive",
+	"post-update",
+	"reference-transaction",
+	"push-to-checkout",
+	"pre-auto-gc",
+	"post-rewrite",
+	"sendemail-validate",
+	"fsmonitor-watchman",
+	"p4-changelist",
+	"p4-prepare-changelist",
+	"p4-post-changelist",
+	"p4-pre-submit",
+	"post-index-change",
+]);
+
+function git(args, cwd) {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	}).trim();
+}
+
+/**
+ * Resolve symlinks so paths reported by git and paths reported by the caller
+ * can be compared and combined reliably (macOS tmpdirs are symlinked).
+ */
+function realpath(dir) {
+	try {
+		return fs.realpathSync(dir);
+	} catch {
+		return path.resolve(dir);
+	}
+}
+
+function projectEntryName(relativeProjectPath, hook) {
+	const hash = crypto
+		.createHash("sha256")
+		.update(relativeProjectPath)
+		.digest("hex")
+		.slice(0, 16);
+	return `${hash}.${hook}`;
+}
+
+/**
+ * Absolute path of the repository root, or null when not inside a git repo.
+ */
+export function getGitRoot(projectDir = PROJECT_DIR) {
+	try {
+		const root = git(["rev-parse", "--show-toplevel"], projectDir);
+		return root ? realpath(path.resolve(projectDir, root)) : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Absolute path of the hooks directory git uses for this project. Respects
+ * core.hooksPath and resolves to the shared hooks directory in worktrees.
+ */
+export function getHooksDir(projectDir = PROJECT_DIR) {
+	try {
+		const hooks = git(["rev-parse", "--git-path", "hooks"], projectDir);
+		return hooks ? path.resolve(realpath(projectDir), hooks) : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Reads the simple-git-hooks config from <dir>/package.json, if present.
+ */
+export function readHookConfig(dir) {
+	try {
+		const packageJson = JSON.parse(
+			fs.readFileSync(path.join(dir, "package.json"), "utf8"),
+		);
+		const config = packageJson["simple-git-hooks"];
+		return config && typeof config === "object" && !Array.isArray(config)
+			? config
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Hooks installed by simple-git-hooks or by this script may be replaced.
+ * Hooks owned by anything else are left alone.
+ */
+function isManagedHook(contents) {
+	return (
+		contents.includes(HOOK_MARKER) || contents.includes("SKIP_SIMPLE_GIT_HOOKS")
+	);
+}
+
+/**
+ * Shell shim installed as the actual git hook. It only delegates to the
+ * dispatcher; all per-project state lives in quark-scoped-hooks/.
+ */
+export function buildHookShim(hook) {
+	return `#!/bin/sh
+# ${HOOK_MARKER} - generated by scripts/prepare.js. Do not edit.
+# Runs the "${hook}" command of every nested Quark project that the current
+# operation affects. See quark-scoped-hooks/dispatch.js.
+if [ "$SKIP_SIMPLE_GIT_HOOKS" = "1" ] || [ "$SKIP_QUARK_GIT_HOOKS" = "1" ]; then
+    exit 0
+fi
+if [ -f "$SIMPLE_GIT_HOOKS_RC" ]; then
+    . "$SIMPLE_GIT_HOOKS_RC"
+fi
+exec node "$(dirname "$0")/${SCOPED_HOOKS_DIR}/dispatch.js" ${hook}
+`;
+}
+
+/**
+ * Node dispatcher installed once per hooks directory. It reads the project
+ * entries, works out which projects the current commit or push affects, and
+ * runs each project's hook command from that project's directory.
+ */
+const DISPATCHER_SOURCE = `#!/usr/bin/env node
+/**
+ * ${HOOK_MARKER} dispatcher.
+ * Generated by scripts/prepare.js - do not edit.
+ *
+ * Git runs hooks from the repository root. This dispatcher finds the nested
+ * Quark projects registered in ./${ENTRIES_DIR}, works out which of them the
+ * current commit or push affects, and runs each project's hook command from
+ * its own directory.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ENTRIES_DIR = path.join(SCRIPT_DIR, "${ENTRIES_DIR}");
+const ZERO_OID = /^0+$/;
+
+const hook = process.argv[2];
+if (!hook) process.exit(0);
+
+if (
+	process.env.SKIP_SIMPLE_GIT_HOOKS === "1" ||
+	process.env.SKIP_QUARK_GIT_HOOKS === "1"
+) {
+	process.exit(0);
+}
+
+function git(args) {
+	return execFileSync("git", args, {
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "ignore"],
+	}).trim();
+}
+
+function readEntries() {
+	let names;
+	try {
+		names = fs.readdirSync(ENTRIES_DIR);
+	} catch {
+		return [];
+	}
+	const entries = [];
+	for (const name of names) {
+		if (!name.endsWith("." + hook)) continue;
+		try {
+			const entry = JSON.parse(
+				fs.readFileSync(path.join(ENTRIES_DIR, name), "utf8"),
+			);
+			if (
+				entry &&
+				typeof entry.project === "string" &&
+				typeof entry.command === "string"
+			) {
+				entries.push(entry);
+			}
+		} catch {
+			// Ignore malformed entries.
+		}
+	}
+	return entries;
+}
+
+function filesUnderProject(files, project) {
+	return files.some(
+		(file) => file === project || file.startsWith(project + "/"),
+	);
+}
+
+function stagedFiles() {
+	try {
+		return git(["diff", "--cached", "--name-only", "-z"])
+			.split("\\0")
+			.filter(Boolean);
+	} catch {
+		return [];
+	}
+}
+
+function prePushProjects(entries) {
+	let input = "";
+	try {
+		input = fs.readFileSync(0, "utf8");
+	} catch {
+		input = "";
+	}
+	const relevant = new Set();
+	for (const line of input.split("\\n")) {
+		const parts = line.trim().split(/\\s+/);
+		if (parts.length < 4) continue;
+		const localOid = parts[1];
+		const remoteOid = parts[3];
+		if (!localOid || ZERO_OID.test(localOid)) continue; // deleted ref
+		if (!remoteOid || ZERO_OID.test(remoteOid)) {
+			// New branch: there is nothing to diff against, run every project.
+			for (const entry of entries) relevant.add(entry.project);
+			continue;
+		}
+		let changed;
+		try {
+			changed = git(["diff", "--name-only", "-z", remoteOid + ".." + localOid])
+				.split("\\0")
+				.filter(Boolean);
+		} catch {
+			// Unknown remote commit: run every project to stay safe.
+			for (const entry of entries) relevant.add(entry.project);
+			continue;
+		}
+		for (const entry of entries) {
+			if (filesUnderProject(changed, entry.project)) {
+				relevant.add(entry.project);
+			}
+		}
+	}
+	return relevant;
+}
+
+function relevantProjects(entries) {
+	if (hook === "pre-commit") {
+		const staged = stagedFiles();
+		return new Set(
+			entries
+				.filter((entry) => filesUnderProject(staged, entry.project))
+				.map((entry) => entry.project),
+		);
+	}
+	if (hook === "pre-push") {
+		return prePushProjects(entries);
+	}
+	// Other hooks run for every registered project that is present.
+	return new Set(entries.map((entry) => entry.project));
+}
+
+const entries = readEntries();
+if (entries.length === 0) process.exit(0);
+
+let root;
+try {
+	root = git(["rev-parse", "--show-toplevel"]);
+} catch {
+	process.exit(0);
+}
+
+const relevant = relevantProjects(entries);
+let failed = false;
+
+for (const entry of entries) {
+	if (!relevant.has(entry.project)) continue;
+	const projectDir = path.join(root, entry.project);
+	if (!fs.existsSync(path.join(projectDir, "package.json"))) continue;
+	try {
+		execFileSync("sh", ["-c", entry.command], {
+			cwd: projectDir,
+			stdio: "inherit",
+		});
+	} catch {
+		failed = true;
+	}
+}
+
+process.exit(failed ? 1 : 0);
+`;
+
+/**
+ * Registers this project for every hook defined in its simple-git-hooks
+ * config, then installs the shared dispatcher and hook shims. Entries from
+ * other nested projects are left untouched. Returns which hooks were
+ * installed or skipped.
+ */
+export function installScopedHooks({
+	projectDir = PROJECT_DIR,
+	gitRoot = getGitRoot(projectDir),
+	hooksDir = getHooksDir(projectDir),
+	logger = console,
+} = {}) {
+	if (!gitRoot || !hooksDir) {
+		return { installed: [], skipped: [], reason: "no-git-repo" };
+	}
+
+	if (realpath(gitRoot) === realpath(projectDir)) {
+		// The project is the repository root - simple-git-hooks handles it.
+		return { installed: [], skipped: [], reason: "project-is-git-root" };
+	}
+
+	const config = readHookConfig(projectDir);
+	if (!config) {
+		return { installed: [], skipped: [], reason: "no-config" };
+	}
+
+	const relativeProjectPath = path
+		.relative(realpath(gitRoot), realpath(projectDir))
+		.split(path.sep)
+		.join("/");
+
+	const scopedHooksDir = path.join(hooksDir, SCOPED_HOOKS_DIR);
+	const entriesDir = path.join(scopedHooksDir, ENTRIES_DIR);
+
+	const configuredHooks = new Set(
+		Object.entries(config)
+			.filter(
+				([hook, command]) =>
+					VALID_HOOKS.has(hook) && typeof command === "string",
+			)
+			.map(([hook]) => hook),
+	);
+
+	const installed = [];
+	const skipped = [];
+
+	// The dispatcher is shared by every project and every hook.
+	fs.mkdirSync(entriesDir, { recursive: true });
+	const dispatcherPath = path.join(scopedHooksDir, "dispatch.js");
+	let dispatcher = "";
+	try {
+		dispatcher = fs.readFileSync(dispatcherPath, "utf8");
+	} catch {
+		// Not installed yet.
+	}
+	if (dispatcher !== DISPATCHER_SOURCE) {
+		fs.writeFileSync(dispatcherPath, DISPATCHER_SOURCE);
+	}
+
+	for (const hook of configuredHooks) {
+		const hookPath = path.join(hooksDir, hook);
+		let existing = "";
+		try {
+			existing = fs.readFileSync(hookPath, "utf8");
+		} catch {
+			// No existing hook - safe to create.
+		}
+
+		if (existing && !isManagedHook(existing)) {
+			skipped.push(hook);
+			logger.warn(
+				`[quark] Skipping ${hook}: an existing hook not managed by Quark is present in ${hooksDir}`,
+			);
+			continue;
+		}
+
+		const entryPath = path.join(
+			entriesDir,
+			projectEntryName(relativeProjectPath, hook),
+		);
+		fs.writeFileSync(
+			entryPath,
+			`${JSON.stringify(
+				{ project: relativeProjectPath, command: config[hook] },
+				null,
+				"\t",
+			)}\n`,
+		);
+
+		const shim = buildHookShim(hook);
+		if (existing !== shim) {
+			fs.writeFileSync(hookPath, shim);
+		}
+		fs.chmodSync(hookPath, 0o755);
+		installed.push(hook);
+		logger.log(
+			`[quark] Registered scoped git hook "${hook}" for ${relativeProjectPath}/`,
+		);
+	}
+
+	// Drop entries for hooks this project no longer configures, without
+	// touching entries that belong to other projects.
+	for (const name of fs.readdirSync(entriesDir)) {
+		const separator = name.lastIndexOf(".");
+		if (separator === -1) continue;
+		const hook = name.slice(separator + 1);
+		if (configuredHooks.has(hook)) continue;
+
+		const entryPath = path.join(entriesDir, name);
+		try {
+			const entry = JSON.parse(fs.readFileSync(entryPath, "utf8"));
+			if (entry.project === relativeProjectPath) {
+				fs.unlinkSync(entryPath);
+			}
+		} catch {
+			// Malformed entry - leave it alone.
+		}
+	}
+
+	return { installed, skipped, reason: null };
+}
+
+export function main({ projectDir = PROJECT_DIR, logger = console } = {}) {
+	const gitRoot = getGitRoot(projectDir);
+	if (!gitRoot) {
+		// Not inside a git repo (e.g. npx install, CI without checkout) - skip.
+		return;
+	}
+
+	if (gitRoot === realpath(projectDir)) {
+		try {
+			execSync("npx simple-git-hooks", { stdio: "inherit" });
+		} catch {
+			// Hooks setup failed - non-fatal, do not block installs.
+		}
+		return;
+	}
+
+	// A project nested in a larger repository must not take over hooks that
+	// repository already manages for its own root project.
+	if (readHookConfig(gitRoot)) {
+		logger.warn(
+			`[quark] The repository at ${gitRoot} manages its own git hooks - skipping hook setup for this nested project.`,
+		);
+		return;
+	}
+
+	try {
+		installScopedHooks({ projectDir, gitRoot, logger });
+	} catch (error) {
+		logger.warn(
+			`[quark] Could not install scoped git hooks: ${error.message}`,
+		);
+	}
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === SCRIPT_PATH) {
+	main();
+}

package/templates/base-project/scripts/run-tests.mjs

@@ -0,0 +1,71 @@
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const roots = [];
+const excludes = [];
+
+for (const arg of args) {
+	if (arg.startsWith("--exclude=")) {
+		excludes.push(arg.slice("--exclude=".length));
+		continue;
+	}
+
+	roots.push(arg);
+}
+
+if (roots.length === 0) {
+	roots.push("src");
+}
+
+function collectTests(targetPath) {
+	const stats = [];
+
+	function walk(currentPath) {
+		for (const entry of readdirSync(currentPath, { withFileTypes: true })) {
+			const fullPath = path.join(currentPath, entry.name);
+
+			if (entry.isDirectory()) {
+				walk(fullPath);
+				continue;
+			}
+
+			if (!entry.isFile() || !entry.name.endsWith(".test.js")) {
+				continue;
+			}
+
+			if (excludes.some((exclude) => fullPath.endsWith(exclude))) {
+				continue;
+			}
+
+			stats.push(fullPath);
+		}
+	}
+
+	walk(targetPath);
+	return stats;
+}
+
+const files = roots.flatMap((rootPath) => collectTests(path.resolve(rootPath)));
+
+if (files.length === 0) {
+	console.error(`No test files found in: ${roots.join(", ")}`);
+	process.exit(1);
+}
+
+const result = spawnSync(
+	process.execPath,
+	[
+		"--import",
+		"tsx/esm",
+		"--experimental-test-module-mocks",
+		"--test",
+		...files,
+	],
+	{
+		stdio: "inherit",
+	},
+);
+
+process.exit(result.status ?? 1);

package/templates/base-project/skills/add-dashboard/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: add-dashboard
+description: Add a decision dashboard to the admin on Quark. Use when the user wants a dashboard, metrics, or admin overview page.
+---
+
+# Add Dashboard Skill
+
+Add a decision dashboard in admin: metric cards showing decision-relevant values for a domain, backed by query helpers and a Server Action.
+
+## Framework context (build on Quark)
+
+- **Admin** is an operations shell — show decision-relevant values (counts, totals, statuses), not raw CRUD tables.
+- **Server Actions** are `"use server"`, validate with Zod, and use `createLogger()`.
+- **Data access** goes through query helpers in `packages/db/src/queries.js` — never call `prisma.*` directly.
+
+## Workflow
+
+1. Create `apps/web/src/app/admin/<feature>/page.js` with metric cards.
+2. Create `apps/web/src/app/admin/<feature>/_actions/<feature>.js` (Server Actions that load the metrics).
+3. Add a sibling `loading.js` using `<Skeleton>`.
+4. Add `export const metadata` (title + description).
+
+## Patterns to follow
+
+- Metric cards show decision-relevant values (counts, totals, statuses), not raw tables.
+- Server Actions are `"use server"`, validate with Zod, and use `createLogger()`.
+- Every async page that fetches from the database needs a sibling `loading.js` using `<Skeleton>`.
+- Add `export const metadata` (title + description) to the page.

package/templates/base-project/skills/add-endpoint/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: add-endpoint
+description: Add a REST CRUD endpoint on Quark. Use when the user wants an API route, endpoint, or REST resource.
+---
+
+# Add Endpoint Skill
+
+Add a REST CRUD endpoint for an existing model: list/create on the collection route, and read/update/delete on the `[id]` route.
+
+## Framework context (build on Quark)
+
+- **API routes** live in `apps/web/src/app/api/<resource>/`.
+- **Data access** goes through query helpers in `packages/db/src/queries.js` — never call `prisma.*` directly.
+- **Auth** via `requireRole` from `@/lib/auth-middleware`; **validation** via Zod `validateBody`; **CSRF** via `withCsrfProtection` from `@techstream/quark-core`.
+
+## Workflow
+
+1. Create `apps/web/src/app/api/<resource>/route.js` (GET list + POST create).
+2. Create `apps/web/src/app/api/<resource>/[id]/route.js` (GET read + PATCH update + DELETE).
+3. Add a test near the changed code.
+
+## Patterns to follow
+
+- Use `NextResponse` from `next/server` and `handleError` from `../error-handler`.
+- Guard with `requireRole("admin")` (or the appropriate role).
+- Validate the body with Zod via `validateBody(request, schema)`.
+- Wrap mutations in `withCsrfProtection`.
+- Return `404` when a record is not found; `201` on create.
+- Follow `apps/web/src/app/api/users/route.js` and `apps/web/src/app/api/users/[id]/route.js` as reference.

package/templates/base-project/skills/add-model/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: add-model
+description: Add a new Prisma model and query helpers on Quark. Use when the user wants to add a data model, entity, or table.
+---
+
+# Add Model Skill
+
+Add a new Prisma model plus the query helpers to read and write it. This is the foundation for any feature that stores data.
+
+## Framework context (build on Quark)
+
+- **Models** live in `packages/db/prisma/schema.prisma`.
+- **Data access** goes through query helpers in `packages/db/src/queries.js` — never call `prisma.*` directly in pages/actions.
+- After any schema change: `pnpm db:generate` then `pnpm db:migrate`.
+
+## Workflow
+
+1. Add the model to `packages/db/prisma/schema.prisma`.
+2. Add query helpers to `packages/db/src/queries.js` — start with `findAll`, `findById`, `create`; add `update`/`delete` when needed.
+3. Run `pnpm db:generate` then `pnpm db:migrate`.
+4. Add a test near the changed code.
+
+## Patterns to follow
+
+- Every model includes `id String @id @default(cuid())`, `createdAt DateTime @default(now())`, and `updatedAt DateTime @updatedAt`.
+- If the data belongs to a signed-in user, relate it to `User` with `onDelete: Cascade` (or `SetNull` when optional).
+- Add indexes on fields you query by (`@@index([...])`).
+- Do not call `prisma.*` directly in pages or Server Actions — use the query helpers.