@techstream/quark-create-app 1.5.2 → 1.5.3

package/README.md

@@ -24,12 +24,50 @@ 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,6 +1,6 @@
 {
   "name": "@techstream/quark-create-app",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "type": "module",
   "bin": {
     "quark-create-app": "src/index.js",
@@ -29,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
 			}
@@ -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);

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/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/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/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/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"),
+});