@techstream/quark-create-app 1.5.1 → 1.5.3

package/README.md

@@ -12,7 +12,7 @@ The CLI scaffolds a complete project structure with:
 - **Next.js** web application
 - **Prisma** database schema and migrations
 - **BullMQ** job queues
-- **Docker Compose** setup (PostgreSQL, Redis, Mailhog)
+- **Docker Compose** setup (PostgreSQL, Redis, Mailpit)
 - **JavaScript** monorepo with `pnpm` workspaces
 
 ## Quick Setup
@@ -20,17 +20,54 @@ The CLI scaffolds a complete project structure with:
 ```bash
 cd my-awesome-app
 docker compose up -d
-pnpm db:generate
 pnpm db:migrate
 pnpm dev
 ```
 
+## Commands
+
+```bash
+# Create a new project
+npx @techstream/quark-create-app@latest my-awesome-app
+
+# Update Quark core in an existing project
+npx @techstream/quark-create-app update
+
+# Check for updates without applying
+npx @techstream/quark-create-app update --check
+```
+
+Aliases:
+- `quark-create-app`
+- `create-quark-app`
+- `quark-update`
+
 ## Common Tasks
 
 - **Update Quark packages**: `quark-update` or `pnpm update @techstream/quark-*`
 - **Check for updates**: `quark-update --check`
 - **Configure environment**: Edit `.env` file (see `.env.example`)
 
+## CLI Testing
+
+```bash
+# Lightweight template checks
+pnpm test
+
+# E2E scaffold simulation
+pnpm test:e2e
+
+# Full build verification (opt-in)
+QUARK_CLI_BUILD_TEST=1 pnpm test:build
+```
+
+## Troubleshooting
+
+- **pnpm install fails**: Ensure `pnpm` is installed and Node.js >= 22.
+- **Prisma generate fails**: Run `pnpm --filter db db:generate` inside the project.
+- **Docker ports conflict**: The CLI auto-selects free ports. Check `.env` for assigned values.
+- **Missing env vars**: Copy `.env.example` to `.env` and fill required values.
+
 ## Support
 
 For issues, questions, and discussions:

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@techstream/quark-create-app",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "type": "module",
   "bin": {
     "quark-create-app": "src/index.js",
-    "create-quark-app": "src/index.js"
+    "create-quark-app": "src/index.js",
+    "quark-update": "src/index.js"
   },
   "files": [
     "src",
@@ -28,6 +29,7 @@
   "license": "ISC",
   "scripts": {
     "test": "node test-cli.js",
+    "test:build": "node test-build.js",
     "test:e2e": "node test-e2e.js",
     "test:integration": "node test-integration.js",
     "test:all": "node test-all.js"

package/src/index.js

@@ -264,6 +264,54 @@ program
 		const targetDir = validateProjectName(projectName);
 		const scope = projectName.toLowerCase().replace(/[^a-z0-9-]/g, "");
 
+		// Clean up orphaned Docker volumes from a previous project with the same name.
+		// Docker Compose names volumes as "<project>_postgres_data", "<project>_redis_data".
+		// These persist even if the project directory is manually deleted, causing
+		// authentication failures when the new project generates different credentials.
+		// We also need to stop any running containers that reference these volumes.
+		try {
+			const volumePrefix = `${projectName}_`;
+			const { stdout } = await execa("docker", [
+				"volume",
+				"ls",
+				"--filter",
+				`name=${volumePrefix}`,
+				"--format",
+				"{{.Name}}",
+			]);
+			const orphanedVolumes = stdout
+				.split("\n")
+				.filter((v) => v.startsWith(volumePrefix));
+			if (orphanedVolumes.length > 0) {
+				// Stop and remove any containers using these volumes first
+				const { stdout: containerOut } = await execa("docker", [
+					"ps",
+					"-a",
+					"--filter",
+					`name=${projectName}`,
+					"--format",
+					"{{.ID}}",
+				]);
+				const containers = containerOut.split("\n").filter(Boolean);
+				if (containers.length > 0) {
+					await execa("docker", ["rm", "-f", ...containers]);
+				}
+				// Remove the Docker network if it exists
+				try {
+					await execa("docker", ["network", "rm", `${projectName}_default`]);
+				} catch {
+					// Network may not exist — fine
+				}
+				// Now remove the orphaned volumes
+				for (const vol of orphanedVolumes) {
+					await execa("docker", ["volume", "rm", "-f", vol]);
+				}
+				console.log(chalk.green("  ✓ Cleaned up orphaned Docker volumes"));
+			}
+		} catch {
+			// Docker not available — fine
+		}
+
 		// Check if directory already exists
 		if (await fs.pathExists(targetDir)) {
 			const { overwrite } = await prompts({
@@ -278,13 +326,13 @@ program
 				process.exit(1);
 			}
 
-			// Clean up Docker resources (volumes hold old credentials)
+			// Stop any running Docker containers for this project
 			try {
-				await execa("docker", ["compose", "down", "-v"], {
+				await execa("docker", ["compose", "down"], {
 					cwd: targetDir,
 					stdio: "ignore",
 				});
-				console.log(chalk.green("  ✓ Cleaned up Docker volumes"));
+				console.log(chalk.green("  ✓ Stopped existing Docker containers"));
 			} catch {
 				// No docker-compose file or Docker not running — fine
 			}
@@ -444,12 +492,12 @@ REDIS_PORT=6379
 # Optional: Set REDIS_URL to override the dynamic construction above
 # REDIS_URL="redis://localhost:6379"
 
-# --- Mailhog Configuration ---
-MAILHOG_HOST=localhost
-MAILHOG_SMTP_PORT=1025
-MAILHOG_UI_PORT=8025
-# Optional: Set MAILHOG_SMTP_URL to override the dynamic construction above
-# MAILHOG_SMTP_URL="smtp://localhost:1025"
+# --- Mail Configuration (Mailpit in development) ---
+MAIL_HOST=localhost
+MAIL_SMTP_PORT=1025
+MAIL_UI_PORT=8025
+# Optional: Set MAIL_SMTP_URL to override the dynamic construction above
+# MAIL_SMTP_URL="smtp://localhost:1025"
 
 # --- Application URL ---
 # In development, APP_URL is derived automatically from PORT — no need to set it.
@@ -544,9 +592,9 @@ REDIS_HOST=localhost
 REDIS_PORT=${redisPort}
 
 # --- Mail Configuration ---
-MAILHOG_HOST=localhost
-MAILHOG_SMTP_PORT=${mailSmtpPort}
-MAILHOG_UI_PORT=${mailUiPort}
+MAIL_HOST=localhost
+MAIL_SMTP_PORT=${mailSmtpPort}
+MAIL_UI_PORT=${mailUiPort}
 
 # --- NextAuth Configuration ---
 NEXTAUTH_SECRET=${nextAuthSecret}
@@ -581,6 +629,45 @@ STORAGE_PROVIDER=local
 			);
 			console.log(chalk.green(`    ✓ .quark-link.json`));
 
+			// Step 10b: Generate project-context skill with actual values
+			console.log(chalk.cyan("\n  🤖 Generating project-context skill..."));
+			const skillPath = path.join(
+				targetDir,
+				".github",
+				"skills",
+				"project-context",
+				"SKILL.md",
+			);
+			if (await fs.pathExists(skillPath)) {
+				let skillContent = await fs.readFile(skillPath, "utf-8");
+
+				// Build optional packages section
+				const optionalLines = features
+					.map((f) => {
+						const labels = {
+							ui: "Shared UI components",
+							jobs: "Job queue definitions",
+						};
+						return `│   ├── ${f}/           # ${labels[f] || f}`;
+					})
+					.join("\n");
+				const optionalBlock = optionalLines ? `${optionalLines}\n` : "";
+
+				skillContent = skillContent
+					.replace(/__QUARK_SCOPE__/g, scope)
+					.replace(/__QUARK_PROJECT_NAME__/g, projectName)
+					.replace(
+						/__QUARK_SCAFFOLD_DATE__/g,
+						new Date().toISOString().split("T")[0],
+					)
+					.replace(/__QUARK_OPTIONAL_PACKAGES__/g, optionalBlock);
+
+				await fs.writeFile(skillPath, skillContent);
+				console.log(
+					chalk.green(`    ✓ .github/skills/project-context/SKILL.md`),
+				);
+			}
+
 			// Step 11: Initialize git repository
 			console.log(chalk.cyan("\n  📝 Initializing git repository..."));
 			const gitInitialized = await initializeGit(targetDir);
@@ -637,7 +724,7 @@ STORAGE_PROVIDER=local
 			console.log(chalk.cyan("Next steps:"));
 			console.log(chalk.white(`  1. cd ${projectName}`));
 			console.log(chalk.white(`  2. docker compose up -d`));
-			console.log(chalk.white(`  3. pnpm --filter db db:push`));
+			console.log(chalk.white(`  3. pnpm db:migrate`));
 			console.log(chalk.white(`  4. pnpm dev\n`));
 
 			console.log(chalk.cyan("Important:"));
@@ -647,7 +734,7 @@ STORAGE_PROVIDER=local
 				),
 			);
 			console.log(
-				chalk.white(`  • Use 'quark-update' to upgrade Quark packages\n`),
+				chalk.white(`  • Or run: npx @techstream/quark-create-app update\n`),
 			);
 
 			console.log(chalk.cyan("Learn more:"));

package/templates/base-project/.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+<skills>
+<skill>
+<name>project-context</name>
+<description>Project-specific context and conventions. This skill evolves with your project — update it as your architecture grows.</description>
+<file>.github/skills/project-context/SKILL.md</file>
+</skill>
+</skills>

package/templates/base-project/.github/skills/project-context/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: project-context
+description: Project-specific context and conventions. This skill evolves with your project — update it as your architecture grows.
+---
+
+# Project Context
+
+## Overview
+
+This is a Quark-based full-stack JavaScript application.
+
+| Property | Value |
+|---|---|
+| **Scope** | `@__QUARK_SCOPE__` |
+| **Framework** | Quark (scaffolded from `@techstream/quark-create-app`) |
+| **Scaffolded** | __QUARK_SCAFFOLD_DATE__ |
+
+## Project Structure
+
+```
+__QUARK_PROJECT_NAME__/
+├── apps/
+│   ├── web/          # Next.js (App Router, Server Actions)
+│   └── worker/       # BullMQ background worker
+├── packages/
+│   ├── db/           # Prisma schema, client, queries
+│   ├── config/       # Environment validation & shared config
+__QUARK_OPTIONAL_PACKAGES__├── docker-compose.yml
+├── .env              # Local environment (git-ignored)
+└── .env.example      # Template for environment variables
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Runtime | Node.js 24, ES Modules |
+| Package manager | pnpm (workspaces) |
+| Monorepo | Turborepo |
+| Web | Next.js 16 (App Router) |
+| Database | PostgreSQL 16 + Prisma 7 |
+| Queue | BullMQ + Redis 7 |
+| Auth | NextAuth v5 |
+| Validation | Zod 4 |
+| UI | Tailwind CSS + Shadcn |
+| Email | Nodemailer |
+| Linting | Biome |
+| Testing | Node.js built-in test runner |
+
+## Coding Conventions
+
+- **ESM only** — use `import`/`export`, never `require`.
+- **No TypeScript** — plain `.js` and `.jsx` files.
+- **Imports:** Use `@techstream/quark-core` for published utilities. Use `@__QUARK_SCOPE__/*` for local packages (db, config, ui, jobs).
+- **Tests:** Co-located `*.test.js` files, run with `node --test`.
+- **Validation:** Zod schemas for all Server Actions and API routes.
+- **Errors:** Use `AppError` / `ValidationError` from `@techstream/quark-core/errors`.
+- **Database models:** Always include `createdAt`/`updatedAt`.
+- **Environment:** All env vars validated in `packages/config/src/validate-env.js`.
+
+## Common Commands
+
+```bash
+pnpm dev              # Start all apps in dev mode
+pnpm build            # Build everything
+pnpm test             # Run all tests
+pnpm lint             # Lint with Biome
+pnpm db:generate      # Regenerate Prisma client
+pnpm db:push          # Push schema changes
+pnpm db:migrate       # Run database migrations
+docker compose up -d  # Start infrastructure
+```
+
+## Key Files to Know
+
+- `packages/db/prisma/schema.prisma` — Database schema (edit this to add models)
+- `packages/db/src/queries.js` — Database query functions
+- `packages/config/src/validate-env.js` — Environment variable validation
+- `apps/web/src/app/` — Next.js App Router pages and API routes
+- `apps/web/src/lib/auth.js` — Authentication configuration
+- `apps/worker/src/handlers/` — Background job handlers
+
+## Updating Quark Core
+
+```bash
+npx @techstream/quark-create-app update   # Update core infrastructure
+pnpm update @techstream/quark-core        # Or update directly
+```
+
+---
+
+## Maintaining This Skill
+
+> **Important:** When you make changes that affect this project's architecture,
+> conventions, or structure — such as adding new packages, models, API patterns,
+> environment variables, deployment targets, or team conventions — **update this
+> skill file** to reflect those changes. This ensures future AI interactions
+> always have accurate, up-to-date context.
+>
+> Examples of when to update this file:
+> - Adding a new Prisma model or database table
+> - Introducing a new API route pattern or middleware
+> - Adding or removing a workspace package
+> - Changing deployment infrastructure or CI/CD steps
+> - Establishing new coding conventions or architectural decisions
+> - Adding third-party integrations or services

package/templates/base-project/README.md

@@ -6,15 +6,19 @@ A modern, scalable monorepo built with Quark.
 
 ```bash
 pnpm install
+docker compose up -d
+pnpm db:migrate
 pnpm dev
 ```
 
+Open http://localhost:3000
+
 ## Services
 
 - **Docker**: `docker compose up -d`
-- **Database**: PostgreSQL on port 5432
-- **Cache**: Redis on port 6379
-- **Email**: Mailhog UI on port 8025
+- **Database**: PostgreSQL
+- **Cache**: Redis
+- **Email**: Mailpit
 
 ## Development
 
@@ -29,6 +33,16 @@ pnpm test
 pnpm lint
 ```
 
+## Database
+
+| Task | Command |
+|------|--------|
+| Run migrations | `pnpm db:migrate` |
+| Push schema (no migration) | `pnpm db:push` |
+| Generate Prisma client | `pnpm db:generate` |
+| Seed database | `pnpm db:seed` |
+| Open Prisma Studio | `pnpm db:studio` |
+
 ## Structure
 
 - `apps/` - Applications (web, worker, etc.)

package/templates/base-project/apps/web/jsconfig.json

@@ -0,0 +1,10 @@
+{
+	"compilerOptions": {
+		"baseUrl": ".",
+		"paths": {
+			"@/*": ["./src/*"]
+		}
+	},
+	"include": ["next.env.d.ts", "**/*.js", "**/*.jsx"],
+	"exclude": ["node_modules"]
+}

package/templates/base-project/apps/web/package.json

@@ -21,7 +21,8 @@
 		"next-auth": "5.0.0-beta.30",
 		"pg": "^8.18.0",
 		"react": "19.2.0",
-		"react-dom": "19.2.0"
+		"react-dom": "19.2.0",
+		"zod": "^4.3.6"
 	},
 	"devDependencies": {
 		"@techstream/quark-config": "workspace:*",

package/templates/base-project/apps/web/src/app/api/auth/register/route.js

@@ -2,13 +2,14 @@ import {
 	createQueue,
 	hashPassword,
 	validateBody,
+	withCsrfProtection,
 } from "@techstream/quark-core";
 import { user, userRegisterSchema } from "@techstream/quark-db";
 import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
 import { NextResponse } from "next/server";
 import { handleError } from "../../error-handler";
 
-export async function POST(request) {
+export const POST = withCsrfProtection(async (request) => {
 	try {
 		const data = await validateBody(request, userRegisterSchema);
 
@@ -52,4 +53,4 @@ export async function POST(request) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});

package/templates/base-project/apps/web/src/app/api/files/route.js

@@ -9,6 +9,7 @@ import {
 	generateStorageKey,
 	parseMultipart,
 	validateFile,
+	withCsrfProtection,
 } from "@techstream/quark-core";
 import { file } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
@@ -26,7 +27,7 @@ const paginationSchema = z.object({
  * Upload one or more files via multipart/form-data.
  * Requires authentication.
  */
-export async function POST(request) {
+export const POST = withCsrfProtection(async (request) => {
 	try {
 		const session = await requireAuth();
 
@@ -94,7 +95,7 @@ export async function POST(request) {
 	} catch (error) {
 		return handleError(error);
 	}
-}
+});
 
 /**
  * GET /api/files

package/templates/base-project/apps/web/src/app/api/posts/route.js

@@ -1,4 +1,8 @@
-import { validateBody, withCsrfProtection } from "@techstream/quark-core";
+import {
+	createQueryBuilder,
+	validateBody,
+	withCsrfProtection,
+} from "@techstream/quark-core";
 import { post, postCreateSchema } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
 import { z } from "zod";
@@ -10,16 +14,65 @@ const paginationSchema = z.object({
 	limit: z.coerce.number().int().min(1).max(100).default(10),
 });
 
+const querySchema = paginationSchema.extend({
+	search: z.string().optional(),
+	status: z.enum(["draft", "published"]).optional(),
+	authorId: z.string().optional(),
+	sort: z.enum(["createdAt", "updatedAt", "title"]).optional(),
+	order: z.enum(["asc", "desc"]).default("desc"),
+});
+
 export async function GET(request) {
 	try {
 		const { searchParams } = new URL(request.url);
-		const { page, limit } = paginationSchema.parse({
-			page: searchParams.get("page") ?? undefined,
-			limit: searchParams.get("limit") ?? undefined,
-		});
+		const { page, limit, search, status, authorId, sort, order } =
+			querySchema.parse({
+				page: searchParams.get("page") ?? undefined,
+				limit: searchParams.get("limit") ?? undefined,
+				search: searchParams.get("search") ?? undefined,
+				status: searchParams.get("status") ?? undefined,
+				authorId: searchParams.get("authorId") ?? undefined,
+				sort: searchParams.get("sort") ?? undefined,
+				order: searchParams.get("order") ?? undefined,
+			});
+
 		const skip = (page - 1) * limit;
 
-		const posts = await post.findAll({ skip, take: limit });
+		// Build query with filters, search, and sort
+		const qb = createQueryBuilder({
+			filterableFields: ["published", "authorId"],
+			searchFields: ["title", "content"],
+			sortableFields: ["createdAt", "updatedAt", "title"],
+		});
+
+		// Apply filters
+		if (status === "published") {
+			qb.filter("published", "eq", true);
+		} else if (status === "draft") {
+			qb.filter("published", "eq", false);
+		}
+
+		if (authorId) {
+			qb.filter("authorId", "eq", authorId);
+		}
+
+		// Apply search
+		if (search) {
+			qb.search(search);
+		}
+
+		// Apply sort
+		if (sort) {
+			qb.sort(sort, order);
+		}
+
+		const posts = await post.findAll({
+			skip,
+			take: limit,
+			where: qb.toWhere(),
+			orderBy: qb.toOrderBy(),
+		});
+
 		return NextResponse.json(posts);
 	} catch (error) {
 		return handleError(error);

package/templates/base-project/apps/worker/package.json

@@ -2,6 +2,7 @@
 	"name": "@techstream/quark-worker",
 	"version": "1.0.0",
 	"type": "module",
+	"private": true,
 	"description": "",
 	"main": "index.js",
 	"scripts": {

package/templates/base-project/apps/worker/src/index.js

@@ -56,6 +56,20 @@ function createQueueWorker(queueName) {
 		);
 	});
 
+	queueWorker.on("stalled", (jobId) => {
+		logger.warn(`Job ${jobId} in queue "${queueName}" has stalled`, {
+			queueName,
+			jobId,
+		});
+	});
+
+	queueWorker.on("error", (error) => {
+		logger.error(`Worker error in queue "${queueName}"`, {
+			error: error.message,
+			queueName,
+		});
+	});
+
 	logger.info(
 		`Queue "${queueName}" worker started (concurrency: ${queueWorker.opts.concurrency})`,
 	);

package/templates/base-project/docker-compose.yml

@@ -11,6 +11,11 @@ services:
       POSTGRES_DB: ${POSTGRES_DB}
     volumes:
       - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-quark_user}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
 
   # --- 2. Redis Cache & Job Queue ---
   redis:
@@ -21,6 +26,11 @@ services:
     command: redis-server --appendonly yes
     volumes:
       - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
 
   # --- 3. Mailpit (Local SMTP Server) ---
   mailpit:
@@ -28,9 +38,14 @@ services:
     restart: always
     ports:
       # SMTP port (used by application to send mail)
-      - "${MAILHOG_SMTP_PORT:-1025}:1025"
+      - "${MAIL_SMTP_PORT:-1025}:1025"
       # Web UI port (to view sent emails)
-      - "${MAILHOG_UI_PORT:-8025}:8025"
+      - "${MAIL_UI_PORT:-8025}:8025"
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8025"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
 
 volumes:
   postgres_data:

package/templates/base-project/package.json

@@ -11,7 +11,11 @@
 		"test": "turbo run test",
 		"docker:up": "docker compose up -d",
 		"docker:down": "docker compose down",
-		"db:generate": "turbo run db:generate"
+		"db:generate": "turbo run db:generate",
+		"db:migrate": "turbo run db:migrate",
+		"db:push": "turbo run db:push",
+		"db:seed": "turbo run db:seed",
+		"db:studio": "turbo run db:studio"
 	},
 	"keywords": [],
 	"author": "",

package/templates/base-project/packages/db/package.json

@@ -23,11 +23,11 @@
 	"devDependencies": {
 		"@techstream/quark-config": "workspace:*",
 		"bcryptjs": "^3.0.3",
-		"prisma": "^7.3.0"
+		"prisma": "^7.4.0"
 	},
 	"dependencies": {
-		"@prisma/adapter-pg": "^7.3.0",
-		"@prisma/client": "^7.3.0",
+		"@prisma/adapter-pg": "^7.4.0",
+		"@prisma/client": "^7.4.0",
 		"dotenv": "^17.2.4",
 		"pg": "^8.18.0",
 		"zod": "^4.3.6"

package/templates/base-project/packages/db/prisma/migrations/20260202061128_initial/migration.sql

@@ -43,6 +43,8 @@ CREATE TABLE "Account" (
     "scope" TEXT,
     "id_token" TEXT,
     "session_state" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
 
     CONSTRAINT "Account_pkey" PRIMARY KEY ("id")
 );
@@ -86,6 +88,22 @@ CREATE TABLE "Job" (
     CONSTRAINT "Job_pkey" PRIMARY KEY ("id")
 );
 
+-- CreateTable
+CREATE TABLE "File" (
+    "id" TEXT NOT NULL,
+    "filename" TEXT NOT NULL,
+    "originalName" TEXT NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "size" INTEGER NOT NULL,
+    "storageKey" TEXT NOT NULL,
+    "storageProvider" TEXT NOT NULL DEFAULT 'local',
+    "uploadedById" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "File_pkey" PRIMARY KEY ("id")
+);
+
 -- CreateTable
 CREATE TABLE "AuditLog" (
     "id" TEXT NOT NULL,
@@ -130,6 +148,9 @@ CREATE UNIQUE INDEX "Session_sessionToken_key" ON "Session"("sessionToken");
 -- CreateIndex
 CREATE INDEX "Session_userId_idx" ON "Session"("userId");
 
+-- CreateIndex
+CREATE INDEX "Session_expires_idx" ON "Session"("expires");
+
 -- CreateIndex
 CREATE UNIQUE INDEX "VerificationToken_token_key" ON "VerificationToken"("token");
 
@@ -139,6 +160,9 @@ CREATE INDEX "VerificationToken_token_idx" ON "VerificationToken"("token");
 -- CreateIndex
 CREATE UNIQUE INDEX "VerificationToken_identifier_token_key" ON "VerificationToken"("identifier", "token");
 
+-- CreateIndex
+CREATE INDEX "VerificationToken_expires_idx" ON "VerificationToken"("expires");
+
 -- CreateIndex
 CREATE INDEX "Job_queue_idx" ON "Job"("queue");
 
@@ -148,9 +172,24 @@ CREATE INDEX "Job_status_idx" ON "Job"("status");
 -- CreateIndex
 CREATE INDEX "Job_runAt_idx" ON "Job"("runAt");
 
+-- CreateIndex
+CREATE INDEX "Job_status_runAt_idx" ON "Job"("status", "runAt");
+
 -- CreateIndex
 CREATE INDEX "Job_createdAt_idx" ON "Job"("createdAt");
 
+-- CreateIndex
+CREATE UNIQUE INDEX "File_storageKey_key" ON "File"("storageKey");
+
+-- CreateIndex
+CREATE INDEX "File_uploadedById_idx" ON "File"("uploadedById");
+
+-- CreateIndex
+CREATE INDEX "File_mimeType_idx" ON "File"("mimeType");
+
+-- CreateIndex
+CREATE INDEX "File_createdAt_idx" ON "File"("createdAt");
+
 -- CreateIndex
 CREATE INDEX "AuditLog_userId_idx" ON "AuditLog"("userId");
 
@@ -172,5 +211,8 @@ ALTER TABLE "Account" ADD CONSTRAINT "Account_userId_fkey" FOREIGN KEY ("userId"
 -- AddForeignKey
 ALTER TABLE "Session" ADD CONSTRAINT "Session_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
 
+-- AddForeignKey
+ALTER TABLE "File" ADD CONSTRAINT "File_uploadedById_fkey" FOREIGN KEY ("uploadedById") REFERENCES "User"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
 -- AddForeignKey
 ALTER TABLE "AuditLog" ADD CONSTRAINT "AuditLog_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/templates/base-project/packages/db/prisma/schema.prisma

@@ -28,6 +28,7 @@ model User {
   accounts      Account[]
   sessions      Session[]
   auditLogs     AuditLog[]
+  files         File[]
 
   @@index([email])
   @@index([createdAt])
@@ -127,6 +128,25 @@ enum JobStatus {
   CANCELLED
 }
 
+// File Model
+model File {
+  id              String   @id @default(cuid())
+  filename        String
+  originalName    String
+  mimeType        String
+  size            Int
+  storageKey      String   @unique
+  storageProvider String   @default("local")
+  uploadedById    String?
+  uploadedBy      User?    @relation(fields: [uploadedById], references: [id], onDelete: SetNull)
+  createdAt       DateTime @default(now())
+  updatedAt       DateTime @updatedAt
+
+  @@index([uploadedById])
+  @@index([mimeType])
+  @@index([createdAt])
+}
+
 // Audit Log Model
 model AuditLog {
   id        String   @id @default(cuid())

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

@@ -81,12 +81,13 @@ export const post = {
 		});
 	},
 	findAll: (options = {}) => {
-		const { skip = 0, take = 10 } = options;
+		const { skip = 0, take = 10, where, orderBy } = options;
 		return prisma.post.findMany({
+			where,
 			skip,
 			take,
 			include: AUTHOR_SAFE_INCLUDE,
-			orderBy: { createdAt: "desc" },
+			orderBy: orderBy || { createdAt: "desc" },
 		});
 	},
 	findPublished: (options = {}) => {
@@ -230,6 +231,61 @@ export const verificationToken = {
 	},
 };
 
+// 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 });
+	},
+};
+
 // AuditLog queries
 export const auditLog = {
 	findAll: (options = {}) => {

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

@@ -34,3 +34,9 @@ export const postUpdateSchema = z.object({
 	content: z.string().optional(),
 	published: z.boolean().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"),
+});

package/templates/base-project/turbo.json

@@ -2,7 +2,7 @@
 	"$schema": "https://turbo.build/schema.json",
 	"tasks": {
 		"build": {
-			"dependsOn": ["^build"],
+			"dependsOn": ["^build", "db:generate"],
 			"outputs": ["dist/**", ".next/**"],
 			"env": ["NODE_ENV"]
 		},
@@ -17,6 +17,19 @@
 			"cache": false,
 			"outputs": ["node_modules/.prisma/client"]
 		},
+		"db:migrate": {
+			"cache": false
+		},
+		"db:push": {
+			"cache": false
+		},
+		"db:seed": {
+			"cache": false
+		},
+		"db:studio": {
+			"cache": false,
+			"persistent": true
+		},
 		"dev": {
 			"cache": false,
 			"persistent": true,
@@ -29,9 +42,9 @@
 				"POSTGRES_DB",
 				"REDIS_HOST",
 				"REDIS_PORT",
-				"MAILHOG_HOST",
-				"MAILHOG_SMTP_PORT",
-				"MAILHOG_UI_PORT",
+				"MAIL_HOST",
+				"MAIL_SMTP_PORT",
+				"MAIL_UI_PORT",
 				"NEXTAUTH_SECRET",
 				"APP_URL",
 				"WORKER_CONCURRENCY",

package/templates/config/src/index.js

@@ -14,7 +14,7 @@ export const config = {
 	},
 	email: {
 		from: process.env.EMAIL_FROM || "noreply@myquarkapp.com",
-		provider: process.env.EMAIL_PROVIDER || "mailhog",
+		provider: process.env.EMAIL_PROVIDER || "smtp",
 	},
 };
 

package/templates/config/src/validate-env.js

@@ -22,11 +22,11 @@ const envSchema = {
 	REDIS_HOST: { required: false, description: "Redis host" },
 	REDIS_PORT: { required: false, description: "Redis port" },
 
-	// Mailhog
-	MAILHOG_SMTP_URL: { required: false, description: "Mailhog SMTP URL" },
-	MAILHOG_HOST: { required: false, description: "Mailhog host" },
-	MAILHOG_SMTP_PORT: { required: false, description: "Mailhog SMTP port" },
-	MAILHOG_UI_PORT: { required: false, description: "Mailhog UI port" },
+	// Mail (local SMTP server)
+	MAIL_SMTP_URL: { required: false, description: "Mail SMTP URL" },
+	MAIL_HOST: { required: false, description: "Mail host" },
+	MAIL_SMTP_PORT: { required: false, description: "Mail SMTP port" },
+	MAIL_UI_PORT: { required: false, description: "Mail UI port" },
 
 	// NextAuth
 	NEXTAUTH_SECRET: {