@usequark/quark-create-app 1.23.11

package/templates/base-project/packages/db/src/connection.js

@@ -0,0 +1,44 @@
+/**
+ * Shared connection string builder for PostgreSQL.
+ * Used by both the Prisma client (client.js) and Prisma CLI (prisma.config.js).
+ *
+ * Priority: DATABASE_URL env var → assembled from POSTGRES_* env vars.
+ *
+ * @param {{ throwOnMissing?: boolean }} [options]
+ *   - throwOnMissing=true  (default) - runtime: throws if credentials are missing.
+ *   - throwOnMissing=false - CLI/CI: returns a placeholder URL so `prisma generate` works.
+ * @returns {string} PostgreSQL connection string
+ */
+export function getConnectionString({ throwOnMissing = true } = {}) {
+	// 1. Prefer an explicit DATABASE_URL if set
+	if (process.env.DATABASE_URL) {
+		return process.env.DATABASE_URL;
+	}
+
+	// 2. Assemble from individual POSTGRES_* vars
+	const user = process.env.POSTGRES_USER;
+	const password = process.env.POSTGRES_PASSWORD;
+	const host = process.env.POSTGRES_HOST || "localhost";
+	const port = process.env.POSTGRES_PORT || "5432";
+	const db = process.env.POSTGRES_DB;
+
+	const hasCredentials = user && password && db;
+
+	if (!hasCredentials) {
+		if (throwOnMissing) {
+			const missing = [];
+			if (!user) missing.push("POSTGRES_USER");
+			if (!password) missing.push("POSTGRES_PASSWORD");
+			if (!db) missing.push("POSTGRES_DB");
+			throw new Error(
+				`Missing required database environment variables: ${missing.join(", ")}. ` +
+					"Set DATABASE_URL or the individual POSTGRES_* variables.",
+			);
+		}
+
+		// Placeholder for prisma generate / CI - will fail at connect time, not at config time.
+		return "postgresql://placeholder:placeholder@localhost:5432/placeholder?schema=public";
+	}
+
+	return `postgresql://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${host}:${port}/${encodeURIComponent(db)}?schema=public`;
+}

package/templates/base-project/packages/db/src/context.js

@@ -0,0 +1,275 @@
+/**
+ * Context Retrieval Utility
+ *
+ * Generic, project-agnostic utility for retrieving relevant business context.
+ * Designed to be portable - can be copied to any Quark project with minimal changes.
+ *
+ * Features:
+ *  - getRelevantContext(question, records) - filters context by keyword relevance
+ *  - summarizeContext(records) - brief category overview
+ *  - shouldProcess(input, previousHash) - dedup check for extraction
+ */
+
+// ── Default Keyword Map ──────────────────────────────────────────────────────
+// Maps question keywords to BusinessContext categories.
+// Generic enough for any project - customize by extending or replacing.
+const DEFAULT_KEYWORD_MAP = {
+	billing: [
+		"billing",
+		"invoice",
+		"pay",
+		"payment",
+		"money",
+		"cost",
+		"revenue",
+		"price",
+		"$",
+		"rate",
+		"fee",
+		"subscription",
+		"plan",
+		"charge",
+	],
+	client: [
+		"client",
+		"customer",
+		"company",
+		"business",
+		"organization",
+		"project",
+		"account",
+		"partner",
+		"vendor",
+	],
+	task: [
+		"task",
+		"todo",
+		"overdue",
+		"blocked",
+		"progress",
+		"status",
+		"assign",
+		"priority",
+		"deadline",
+		"due",
+		"complete",
+		"pipeline",
+	],
+	tech_note: [
+		"tech",
+		"config",
+		"deploy",
+		"server",
+		"integration",
+		"api",
+		"code",
+		"bug",
+		"fix",
+		"setup",
+		"migration",
+		"database",
+	],
+	process: [
+		"process",
+		"policy",
+		"rule",
+		"workflow",
+		"how",
+		"procedure",
+		"guideline",
+		"step",
+		"method",
+		"standard",
+	],
+	preference: [
+		"prefer",
+		"like",
+		"want",
+		"style",
+		"format",
+		"communication",
+		"contact",
+		"schedule",
+		"frequency",
+	],
+};
+
+// ── Relevance Scoring ────────────────────────────────────────────────────────
+
+/**
+ * Scores a context record's relevance to a question.
+ * @param {Object} record - { key, value, category }
+ * @param {string} question - The user's question (lowercased)
+ * @param {Object} keywordMap - Custom keyword map (optional)
+ * @returns {number} Relevance score (0 = irrelevant, higher = more relevant)
+ */
+function scoreRelevance(record, question, keywordMap = DEFAULT_KEYWORD_MAP) {
+	let score = 0;
+	const lowerQuestion = question;
+
+	// Score 1: Category matches question keywords
+	const categoryKeywords = keywordMap[record.category];
+	if (categoryKeywords) {
+		for (const kw of categoryKeywords) {
+			if (lowerQuestion.includes(kw)) {
+				score += 2;
+			}
+		}
+	}
+
+	// Score 2: Key words match question
+	const keyWords = record.key.toLowerCase().split(/[.\s_-]+/);
+	for (const word of keyWords) {
+		if (word.length > 2 && lowerQuestion.includes(word)) {
+			score += 3;
+		}
+	}
+
+	// Score 3: Value contains question keywords (partial match)
+	const valueLower = (record.value || "").toLowerCase();
+	const questionWords = lowerQuestion.split(/\s+/).filter((w) => w.length > 3);
+	for (const word of questionWords) {
+		if (valueLower.includes(word)) {
+			score += 1;
+		}
+	}
+
+	return score;
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Filters context records to only those relevant to a question.
+ * Returns records with score > 0, sorted by relevance (highest first).
+ * If no records score > 0, returns a summary instead.
+ *
+ * @param {string} question - The user's question
+ * @param {Array<Object>} records - BusinessContext records [{ key, value, category, source }]
+ * @param {Object} [options]
+ * @param {number} [options.maxRecords=15] - Max records to return
+ * @param {number} [options.minScore=1] - Minimum relevance score
+ * @param {Object} [options.keywordMap] - Custom keyword map
+ * @returns {Object} { records: Array, summary: string|null }
+ */
+export function getRelevantContext(question, records, options = {}) {
+	const {
+		maxRecords = 15,
+		minScore = 1,
+		keywordMap = DEFAULT_KEYWORD_MAP,
+	} = options;
+
+	if (!question || !records || records.length === 0) {
+		return { records: [], summary: "No business context available." };
+	}
+
+	const lowerQuestion = question.toLowerCase();
+
+	// Score all records
+	const scored = records.map((r) => ({
+		...r,
+		_score: scoreRelevance(r, lowerQuestion, keywordMap),
+	}));
+
+	// Filter by minimum score
+	const relevant = scored
+		.filter((r) => r._score >= minScore)
+		.sort((a, b) => b._score - a._score)
+		.slice(0, maxRecords);
+
+	// Clean up internal score field
+	const cleanRecords = relevant.map(({ _score, ...r }) => r);
+
+	if (cleanRecords.length > 0) {
+		return { records: cleanRecords, summary: null };
+	}
+
+	// No relevant records found - return a summary instead
+	return {
+		records: [],
+		summary: summarizeContext(records),
+	};
+}
+
+/**
+ * Creates a brief category summary of all context records.
+ * Tells the AI what's available without overwhelming it with details.
+ *
+ * @param {Array<Object>} records
+ * @returns {string}
+ */
+export function summarizeContext(records) {
+	if (!records || records.length === 0) {
+		return "No business context available.";
+	}
+
+	const byCategory = {};
+	for (const r of records) {
+		if (!byCategory[r.category]) byCategory[r.category] = [];
+		byCategory[r.category].push(r);
+	}
+
+	const totalManual = records.filter((r) => r.source === "manual").length;
+	const totalSeed = records.filter((r) => r.source === "seed").length;
+
+	let summary = `Available business context (${records.length} records, ${totalSeed} curated + ${totalManual} manual):\n`;
+
+	for (const [category, entries] of Object.entries(byCategory)) {
+		const label = category.charAt(0).toUpperCase() + category.slice(1);
+		const manual = entries.filter((e) => e.source === "manual").length;
+		const seed = entries.filter((e) => e.source === "seed").length;
+		summary += `- **${label}**: ${entries.length} records`;
+		if (seed > 0) summary += ` (${seed} curated, ${manual} manual)`;
+		summary += "\n";
+	}
+
+	summary +=
+		"\nUse `getRelevantContext` with a specific question to retrieve detailed context.";
+
+	return summary;
+}
+
+/**
+ * Creates a deterministic hash of input data for dedup checking.
+ * Returns null if input is empty.
+ *
+ * @param {string} input - The data to hash (e.g., conversation text, task data)
+ * @returns {string|null} Hex hash string, or null if empty
+ */
+export function hashInput(input) {
+	if (!input || typeof input !== "string" || input.trim().length === 0) {
+		return null;
+	}
+
+	// Simple hash function (no crypto dependency needed)
+	let hash = 0;
+	const str = input.trim();
+	for (let i = 0; i < str.length; i++) {
+		const char = str.charCodeAt(i);
+		hash = (hash << 5) - hash + char;
+		hash |= 0; // Convert to 32bit integer
+	}
+	return Math.abs(hash).toString(16);
+}
+
+/**
+ * Checks whether an input should be processed, based on a previous hash.
+ * Useful for skipping extraction when nothing has changed.
+ *
+ * @param {string} input - The current input data
+ * @param {string|null} previousHash - The hash from the last successful processing
+ * @returns {Object} { shouldProcess: boolean, hash: string|null }
+ */
+export function shouldProcess(input, previousHash) {
+	const currentHash = hashInput(input);
+
+	if (!currentHash) {
+		return { shouldProcess: false, hash: null };
+	}
+
+	if (currentHash === previousHash) {
+		return { shouldProcess: false, hash: currentHash };
+	}
+
+	return { shouldProcess: true, hash: currentHash };
+}

package/templates/base-project/packages/db/src/index.js

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./context.js";
+export * from "./ping.js";
+export * from "./queries.js";
+export * from "./schemas.js";

package/templates/base-project/packages/db/src/ping.js

@@ -0,0 +1,66 @@
+import { getConnectionString } from "./connection.js";
+
+/**
+ * Pings PostgreSQL to verify connectivity.
+ * Uses a raw `pg.Client` directly so the check is immune to Prisma
+ * adapter quirks - in particular, Prisma 7 + @prisma/adapter-pg surfaces
+ * connection failures as a misleading "Invalid invocation" error rather
+ * than a proper ECONNREFUSED.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeout=3000] - Connection/query timeout in milliseconds.
+ * @returns {Promise<{ status: "ok", latencyMs: number } | { status: "error", message: string }>}
+ */
+export async function pingDatabase({ timeout = 3000 } = {}) {
+	/** @type {import("pg").Client | null} */
+	let client = null;
+	let connectionString;
+
+	try {
+		const { default: pg } = await import("pg");
+		connectionString = getConnectionString();
+
+		client = new pg.Client({
+			connectionString,
+			connectionTimeoutMillis: timeout,
+			query_timeout: timeout,
+		});
+
+		await client.connect();
+
+		const start = performance.now();
+		await client.query("SELECT 1");
+		const latencyMs = Math.round(performance.now() - start);
+
+		return { status: "ok", latencyMs };
+	} catch (/** @type {any} */ error) {
+		let message;
+		if (
+			error?.code === "MODULE_NOT_FOUND" ||
+			error?.code === "ERR_MODULE_NOT_FOUND"
+		) {
+			message = "pg is not installed";
+		} else if (
+			error?.code === "ECONNREFUSED" ||
+			/ECONNREFUSED/i.test(error?.message ?? "")
+		) {
+			try {
+				const { hostname, port } = new URL(connectionString);
+				message = `PostgreSQL unreachable at ${hostname}:${port || "5432"}`;
+			} catch {
+				message = "PostgreSQL unreachable";
+			}
+		} else if (error?.code === "ENOTFOUND") {
+			message = `PostgreSQL host not found: ${error.hostname ?? "unknown"}`;
+		} else {
+			message = error?.message ?? String(error);
+		}
+		return { status: "error", message };
+	} finally {
+		try {
+			await client?.end();
+		} catch {
+			// ignore disconnect errors
+		}
+	}
+}

package/templates/base-project/packages/db/src/queries.js

@@ -0,0 +1,292 @@
+import { prisma } from "./client.js";
+
+/**
+ * Safe select for user queries - excludes sensitive fields (password).
+ * Use this on any query whose result is returned to the client.
+ */
+const USER_SAFE_SELECT = {
+	id: true,
+	email: true,
+	emailVerified: true,
+	name: true,
+	image: true,
+	role: true,
+	createdAt: true,
+	updatedAt: true,
+};
+
+export { USER_SAFE_SELECT };
+
+// User queries
+export const user = {
+	findById: (id) => {
+		return prisma.user.findUnique({
+			where: { id },
+			select: USER_SAFE_SELECT,
+		});
+	},
+
+	/**
+	 * findByEmail returns ALL fields including password.
+	 * Only use for internal auth - never expose the result directly to clients.
+	 */
+	findByEmail: (email) => {
+		return prisma.user.findUnique({
+			where: { email },
+		});
+	},
+	findAll: (options = {}) => {
+		const { skip = 0, take = 10 } = options;
+		return prisma.user.findMany({
+			skip,
+			take,
+			select: USER_SAFE_SELECT,
+			orderBy: { createdAt: "desc" },
+		});
+	},
+	create: (data) => {
+		return prisma.user.create({
+			data,
+			select: USER_SAFE_SELECT,
+		});
+	},
+	update: (id, data) => {
+		return prisma.user.update({
+			where: { id },
+			data,
+			select: USER_SAFE_SELECT,
+		});
+	},
+	delete: (id) => {
+		return prisma.user.delete({
+			where: { id },
+		});
+	},
+	count: () => {
+		return prisma.user.count();
+	},
+};
+
+// Job queries
+export const job = {
+	findAll: (options = {}) => {
+		const { skip = 0, take = 50, where = {} } = options;
+		return prisma.job.findMany({
+			skip,
+			take,
+			where,
+			orderBy: { createdAt: "desc" },
+		});
+	},
+
+	findById: (id) => {
+		return prisma.job.findUnique({ where: { id } });
+	},
+
+	upsert: (id, data) => {
+		return prisma.job.upsert({
+			where: { id },
+			create: { id, ...data },
+			update: data,
+		});
+	},
+};
+
+// Account queries (NextAuth)
+export const account = {
+	findById: (id) => {
+		return prisma.account.findUnique({
+			where: { id },
+		});
+	},
+	findByUserIdAndProvider: (userId, provider) => {
+		return prisma.account.findFirst({
+			where: { userId, provider },
+		});
+	},
+	findByUser: (userId) => {
+		return prisma.account.findMany({
+			where: { userId },
+		});
+	},
+	create: (data) => {
+		return prisma.account.create({
+			data,
+		});
+	},
+	delete: (id) => {
+		return prisma.account.delete({
+			where: { id },
+		});
+	},
+};
+
+// Session queries (NextAuth)
+export const session = {
+	findByToken: (sessionToken) => {
+		return prisma.session.findUnique({
+			where: { sessionToken },
+			include: { user: { select: USER_SAFE_SELECT } },
+		});
+	},
+	findByUserId: (userId) => {
+		return prisma.session.findMany({
+			where: { userId },
+		});
+	},
+	create: (data) => {
+		return prisma.session.create({
+			data,
+			include: { user: { select: USER_SAFE_SELECT } },
+		});
+	},
+	update: (sessionToken, data) => {
+		return prisma.session.update({
+			where: { sessionToken },
+			data,
+		});
+	},
+	delete: (sessionToken) => {
+		return prisma.session.delete({
+			where: { sessionToken },
+		});
+	},
+	deleteByUserId: (userId) => {
+		return prisma.session.deleteMany({
+			where: { userId },
+		});
+	},
+};
+
+// Verification Token queries (NextAuth)
+export const verificationToken = {
+	findByToken: (token) => {
+		return prisma.verificationToken.findUnique({
+			where: { token },
+		});
+	},
+	findByIdentifierAndToken: (identifier, token) => {
+		return prisma.verificationToken.findUnique({
+			where: { identifier_token: { identifier, token } },
+		});
+	},
+	create: (data) => {
+		return prisma.verificationToken.create({
+			data,
+		});
+	},
+	delete: (identifier, token) => {
+		return prisma.verificationToken.deleteMany({
+			where: { identifier, token },
+		});
+	},
+	deleteExpired: () => {
+		return prisma.verificationToken.deleteMany({
+			where: { expires: { lt: new Date() } },
+		});
+	},
+};
+
+// AuditLog queries
+export const auditLog = {
+	findAll: (options = {}) => {
+		const { skip = 0, take = 50 } = options;
+		return prisma.auditLog.findMany({
+			skip,
+			take,
+			include: { user: { select: { id: true, email: true, name: true } } },
+			orderBy: { createdAt: "desc" },
+		});
+	},
+	findByUserId: (userId, options = {}) => {
+		const { skip = 0, take = 50 } = options;
+		return prisma.auditLog.findMany({
+			where: { userId },
+			skip,
+			take,
+			include: { user: { select: { id: true, email: true, name: true } } },
+			orderBy: { createdAt: "desc" },
+		});
+	},
+	findByEntity: (entity, options = {}) => {
+		const { skip = 0, take = 50 } = options;
+		return prisma.auditLog.findMany({
+			where: { entity },
+			skip,
+			take,
+			include: { user: { select: { id: true, email: true, name: true } } },
+			orderBy: { createdAt: "desc" },
+		});
+	},
+	findByAction: (action, options = {}) => {
+		const { skip = 0, take = 50 } = options;
+		return prisma.auditLog.findMany({
+			where: { action },
+			skip,
+			take,
+			include: { user: { select: { id: true, email: true, name: true } } },
+			orderBy: { createdAt: "desc" },
+		});
+	},
+	create: (data) => {
+		return prisma.auditLog.create({
+			data,
+			include: { user: { select: { id: true, email: true, name: true } } },
+		});
+	},
+};
+
+// File queries
+export const file = {
+	create: (data) => {
+		return prisma.file.create({ data });
+	},
+	findById: (id) => {
+		return prisma.file.findUnique({
+			where: { id },
+			include: {
+				uploadedBy: { select: { id: true, email: true, name: true } },
+			},
+		});
+	},
+	findByStorageKey: (storageKey) => {
+		return prisma.file.findUnique({ where: { storageKey } });
+	},
+	findByUploader: (uploadedById, options = {}) => {
+		const { skip = 0, take = 50 } = options;
+		return prisma.file.findMany({
+			where: { uploadedById },
+			skip,
+			take,
+			orderBy: { createdAt: "desc" },
+		});
+	},
+	findOrphaned: (options = {}) => {
+		const { take = 100 } = options;
+		return prisma.file.findMany({
+			where: { uploadedById: null },
+			take,
+			orderBy: { createdAt: "asc" },
+		});
+	},
+	findOlderThan: (date, options = {}) => {
+		const { take = 100 } = options;
+		return prisma.file.findMany({
+			where: {
+				uploadedById: null,
+				createdAt: { lt: date },
+			},
+			take,
+			orderBy: { createdAt: "asc" },
+		});
+	},
+	delete: (id) => {
+		return prisma.file.delete({ where: { id } });
+	},
+	deleteMany: (ids) => {
+		return prisma.file.deleteMany({ where: { id: { in: ids } } });
+	},
+	count: (where = {}) => {
+		return prisma.file.count({ where });
+	},
+};

package/templates/base-project/packages/db/src/schemas.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+export const userCreateSchema = z.object({
+	email: z.string().email(),
+	name: z.string().optional(),
+	image: z.string().url().optional(),
+});
+
+export const userRegisterSchema = z.object({
+	email: z.string().email("Invalid email address"),
+	password: z
+		.string()
+		.min(8, "Password must be at least 8 characters")
+		.regex(/[A-Z]/, "Password must contain at least one uppercase letter")
+		.regex(/[a-z]/, "Password must contain at least one lowercase letter")
+		.regex(/[0-9]/, "Password must contain at least one number"),
+	name: z.string().min(2, "Name must be at least 2 characters").optional(),
+});
+
+export const userUpdateSchema = z.object({
+	email: z.string().email().optional(),
+	name: z.string().optional(),
+	image: z.string().url().optional(),
+});
+
+export const fileUploadSchema = z.object({
+	filename: z.string().min(1, "Filename is required"),
+	mimeType: z.string().min(1, "MIME type is required"),
+	size: z.number().int().positive("File size must be positive"),
+});