@techstream/quark-create-app 1.5.2 → 1.6.0

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.6.0",
   "type": "module",
   "bin": {
     "quark-create-app": "src/index.js",
@@ -14,7 +14,7 @@
   ],
   "dependencies": {
     "chalk": "^5.6.2",
-    "commander": "^12.1.0",
+    "commander": "^14.0.3",
     "execa": "^9.6.1",
     "fs-extra": "^11.3.3",
     "prompts": "^2.4.2"
@@ -28,7 +28,10 @@
   },
   "license": "ISC",
   "scripts": {
+    "sync-templates": "node scripts/sync-templates.js",
+    "sync-templates:check": "node scripts/sync-templates.js --check",
     "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
 			}
@@ -426,7 +474,11 @@ program
 
 			// Step 8: Create .env.example file
 			console.log(chalk.cyan("\n  📋 Creating environment configuration..."));
-			const envExampleTemplate = `# --- Database Configuration ---
+			const envExampleTemplate = `# --- Environment ---
+# Supported: development, test, staging, production (default: development)
+# NODE_ENV=development
+
+# --- Database Configuration ---
 # These map to the service names in docker-compose.yml
 # ⚠️  SECURITY WARNING: Change these default passwords in production!
 # Generate strong passwords with: openssl rand -base64 32
@@ -444,13 +496,30 @@ REDIS_PORT=6379
 # Optional: Set REDIS_URL to override the dynamic construction above
 # REDIS_URL="redis://localhost:6379"
 
-# --- Mail Configuration (Mailpit in development) ---
+# --- Mail Configuration ---
+# Development: Mailpit local SMTP (defaults below work with docker-compose)
 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"
 
+# Production SMTP: Set these instead of MAIL_* when using a real SMTP relay
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_SECURE=true
+# SMTP_USER=your_smtp_user
+# SMTP_PASSWORD=your_smtp_password
+
+# --- Email Provider ---
+# Provider: "smtp" (default) or "resend"
+# EMAIL_PROVIDER=smtp
+# EMAIL_FROM=App Name <noreply@yourdomain.com>
+
+# Resend (only when EMAIL_PROVIDER=resend)
+# Get your API key at: https://resend.com/api-keys
+# RESEND_API_KEY=re_xxxxxxxxxxxxx
+
 # --- Application URL ---
 # In development, APP_URL is derived automatically from PORT — no need to set it.
 # In production, set this to your real domain:
@@ -476,23 +545,36 @@ PORT=3000
 # --- Worker Configuration ---
 WORKER_CONCURRENCY=5
 
-# --- File Storage Configuration ---
-# Storage provider: "local" (default) or "s3" (S3-compatible, e.g. Cloudflare R2)
+# --- File Storage ---
+# Provider: "local" (default) or "s3" (S3-compatible: AWS S3, Cloudflare R2, MinIO)
 STORAGE_PROVIDER=local
-# Local storage directory (only used when STORAGE_PROVIDER=local)
+# Local storage directory (only when STORAGE_PROVIDER=local)
 # STORAGE_LOCAL_DIR=./uploads
 
-# S3 / Cloudflare R2 Configuration (only used when STORAGE_PROVIDER=s3)
+# S3 / Cloudflare R2 (only when STORAGE_PROVIDER=s3)
 # S3_BUCKET=your-bucket-name
-# S3_REGION=auto
+# S3_REGION=auto                  # Use "auto" for Cloudflare R2
 # S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
 # S3_ACCESS_KEY_ID=your-access-key
 # S3_SECRET_ACCESS_KEY=your-secret-key
 # S3_PUBLIC_URL=https://your-public-bucket-domain.com
 
 # --- Upload Limits ---
-# UPLOAD_MAX_SIZE=10485760
+# UPLOAD_MAX_SIZE=10485760   # Max file size in bytes (default: 10MB)
 # UPLOAD_ALLOWED_TYPES=image/jpeg,image/png,image/gif,image/webp,image/avif,image/svg+xml,application/pdf
+
+# --- Rate Limiting & Security ---
+# RATE_LIMIT_MAX=100           # Max requests per window (default: 1000 dev, 100 prod)
+# RATE_LIMIT_WINDOW_MS=900000  # Window in ms (default: 15 minutes)
+# API_BODY_SIZE_LIMIT=2097152  # 2MB (default)
+# UPLOAD_SIZE_LIMIT=10485760   # 10MB proxy-level limit (default)
+
+# --- Logging & Cache ---
+# LOG_LEVEL=debug              # debug, info, warn, error (default: debug dev, info prod)
+# CACHE_TTL=60                 # Default cache TTL in seconds (default: 60 dev, 600 prod)
+
+# --- Database Seeding ---
+# SEED_PROFILE=dev             # Options: dev (default, includes audit logs + sample job), minimal (users only)
 `;
 			await fs.writeFile(
 				path.join(targetDir, ".env.example"),
@@ -561,6 +643,9 @@ WORKER_CONCURRENCY=5
 
 # --- File Storage ---
 STORAGE_PROVIDER=local
+
+# --- Database Seeding ---
+# SEED_PROFILE=dev             # Options: dev (default), minimal (users only — use for production initial seed)
 `;
 			await fs.writeFile(path.join(targetDir, ".env"), envContent);
 			console.log(
@@ -581,6 +666,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);
@@ -638,7 +762,13 @@ STORAGE_PROVIDER=local
 			console.log(chalk.white(`  1. cd ${projectName}`));
 			console.log(chalk.white(`  2. docker compose up -d`));
 			console.log(chalk.white(`  3. pnpm db:migrate`));
-			console.log(chalk.white(`  4. pnpm dev\n`));
+			console.log(chalk.white(`  4. pnpm db:seed`));
+			console.log(chalk.white(`  5. pnpm dev\n`));
+			console.log(
+				chalk.dim(
+					`  Tip: set SEED_PROFILE=minimal in .env for a lean seed (admin user only)\n`,
+				),
+			);
 
 			console.log(chalk.cyan("Important:"));
 			console.log(

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/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      production:
+        dependency-type: production
+      development:
+        dependency-type: development
+    open-pull-requests-limit: 10

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/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm lint
+
+  test:
+    runs-on: ubuntu-latest
+    name: Test
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: app_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U postgres"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=5
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd="redis-cli ping"
+          --health-interval=5s
+          --health-timeout=5s
+          --health-retries=5
+    env:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_HOST: localhost
+      POSTGRES_PORT: "5432"
+      POSTGRES_DB: app_test
+      REDIS_HOST: localhost
+      REDIS_PORT: "6379"
+      NEXTAUTH_SECRET: ci-test-secret-must-be-at-least-32-characters-long
+      NODE_ENV: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      - run: pnpm test
+
+  build:
+    name: Build
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm db:generate
+
+      - run: pnpm build

package/templates/base-project/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,22 @@
+name: Auto-merge Dependabot
+
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dependabot/fetch-metadata@v2
+        id: meta
+
+      - name: Auto-merge patch updates
+        if: steps.meta.outputs.update-type == 'version-update:semver-patch'
+        run: gh pr merge "$PR_URL" --auto --squash
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/templates/base-project/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      notes:
+        description: "Release notes (optional — auto-generated if blank)"
+        required: false
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Tag & Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate date-based tag
+        id: tag
+        run: |
+          BASE="v$(date +%Y.%m.%d)"
+          EXISTING=$(git tag -l "${BASE}*" | wc -l | tr -d ' ')
+          if [ "$EXISTING" -eq "0" ]; then
+            echo "tag=${BASE}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${BASE}.${EXISTING}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.tag }}
+          generate_release_notes: ${{ github.event.inputs.notes == '' }}
+          body: ${{ github.event.inputs.notes }}

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

@@ -0,0 +1,7 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.0/schema.json",
+	"extends": ["../../biome.json"],
+	"files": {
+		"includes": ["*.{js,ts,mjs,cjs,json}", "src/**", "scripts/**"]
+	}
+}

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

@@ -0,0 +1,10 @@
+{
+	"compilerOptions": {
+		"baseUrl": "./src",
+		"paths": {
+			"@/*": ["./*"]
+		},
+		"jsx": "preserve"
+	},
+	"include": ["next.config.js"]
+}