@techstream/quark-create-app 1.5.3 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techstream/quark-create-app",
-  "version": "1.5.3",
+  "version": "1.7.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,6 +28,8 @@
   },
   "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",

package/src/index.js

@@ -474,17 +474,21 @@ 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
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
-POSTGRES_USER=quark_user
+POSTGRES_USER=${scope}_user
 POSTGRES_PASSWORD=CHANGE_ME_TO_STRONG_PASSWORD
 POSTGRES_DB=${scope}_dev
 # Optional: Set DATABASE_URL to override the dynamic construction above
-# DATABASE_URL="postgresql://quark_user:CHANGE_ME_TO_STRONG_PASSWORD@localhost:5432/${scope}_dev?schema=public"
+# DATABASE_URL="postgresql://${scope}_user:CHANGE_ME_TO_STRONG_PASSWORD@localhost:5432/${scope}_dev?schema=public"
 
 # --- Redis Configuration ---
 REDIS_HOST=localhost
@@ -492,18 +496,37 @@ 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:
 # APP_URL=https://yourdomain.com
 
+# --- Application Identity ---
+# APP_NAME is used in metadata, emails, and page titles.
+APP_NAME=${projectName}
+
 # --- NextAuth Configuration ---
 # ⚠️  CRITICAL: Generate a secure secret with: openssl rand -base64 32
 # This secret is used to encrypt JWT tokens and session data
@@ -524,23 +547,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"),
@@ -583,7 +619,7 @@ STORAGE_PROVIDER=local
 			const envContent = `# --- Database Configuration ---
 POSTGRES_HOST=localhost
 POSTGRES_PORT=${postgresPort}
-POSTGRES_USER=quark_user
+POSTGRES_USER=${scope}_user
 POSTGRES_PASSWORD=${dbPassword}
 POSTGRES_DB=${scope}_dev
 
@@ -596,6 +632,9 @@ MAIL_HOST=localhost
 MAIL_SMTP_PORT=${mailSmtpPort}
 MAIL_UI_PORT=${mailUiPort}
 
+# --- Application Identity ---
+APP_NAME=${projectName}
+
 # --- NextAuth Configuration ---
 NEXTAUTH_SECRET=${nextAuthSecret}
 
@@ -609,6 +648,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(
@@ -725,7 +767,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/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/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

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

package/templates/base-project/apps/web/next.config.js

@@ -1,6 +1,95 @@
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-	// No TypeScript configuration needed for JS-only projects
+	// Required for Railway deployment — produces a self-contained build
+	// at .next/standalone that can run without node_modules.
+	output: "standalone",
+
+	// Support workspace package resolution (including @techstream/quark-db which uses
+	// the Prisma driver-adapter pattern — pure JS, no native engine binary)
+	transpilePackages: [
+		"@techstream/quark-core",
+		"@techstream/quark-db",
+		"@techstream/quark-ui",
+		"@techstream/quark-jobs",
+	],
+
+	// Security headers
+	// NOTE: These are also applied by proxy.js for proxy-matched routes.
+	// Keeping them here as a fallback for routes the proxy doesn't match.
+	async headers() {
+		return [
+			{
+				source: "/:path*",
+				headers: [
+					{
+						key: "X-DNS-Prefetch-Control",
+						value: "on",
+					},
+					{
+						key: "X-Frame-Options",
+						value: "SAMEORIGIN",
+					},
+					{
+						key: "X-Content-Type-Options",
+						value: "nosniff",
+					},
+					{
+						key: "Referrer-Policy",
+						value: "strict-origin-when-cross-origin",
+					},
+					{
+						key: "Permissions-Policy",
+						value: "camera=(), microphone=(), geolocation=()",
+					},
+					{
+						key: "Content-Security-Policy",
+						value:
+							"default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';",
+					},
+				],
+			},
+		];
+	},
+
+	// Environment variables validation
+	env: {
+		APP_URL: process.env.APP_URL,
+		NEXTAUTH_URL: process.env.NEXTAUTH_URL || process.env.APP_URL,
+		NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET,
+	},
+
+	// Request body size limits (security)
+	experimental: {
+		// Limit request body size to prevent DoS attacks
+		// Default is 4MB, we're being explicit here
+		// Adjust based on your needs (e.g., larger for file uploads)
+		serverActions: {
+			bodySizeLimit: "2mb", // For Server Actions
+		},
+	},
+
+	// API route configuration
+	async rewrites() {
+		return [];
+	},
+
+	// Compiler options for production optimization
+	compiler: {
+		removeConsole:
+			process.env.NODE_ENV === "production"
+				? { exclude: ["error", "warn"] }
+				: false,
+	},
+
+	// Image optimization configuration
+	images: {
+		domains: [],
+		formats: ["image/avif", "image/webp"],
+	},
+
+	// Production-only settings
+	poweredByHeader: false,
+	compress: true,
 };
 
 export default nextConfig;

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

@@ -16,18 +16,18 @@
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
 		"@techstream/quark-ui": "workspace:*",
-		"@prisma/client": "^7.3.0",
+		"@prisma/client": "^7.4.0",
 		"next": "16.1.6",
 		"next-auth": "5.0.0-beta.30",
 		"pg": "^8.18.0",
-		"react": "19.2.0",
-		"react-dom": "19.2.0",
+		"react": "19.2.4",
+		"react-dom": "19.2.4",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@techstream/quark-config": "workspace:*",
-		"@tailwindcss/postcss": "^4",
-		"@types/node": "^20",
-		"tailwindcss": "^4"
+		"@tailwindcss/postcss": "^4.2.0",
+		"@types/node": "^25.2.3",
+		"tailwindcss": "^4.2.0",
+		"@techstream/quark-config": "workspace:*"
 	}
 }

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

@@ -0,0 +1,15 @@
+{
+	"$schema": "https://railway.com/railway.schema.json",
+	"build": {
+		"builder": "RAILPACK",
+		"buildCommand": "pnpm install --frozen-lockfile && pnpm db:generate && pnpm build",
+		"watchPatterns": ["apps/web/**", "packages/**"]
+	},
+	"deploy": {
+		"startCommand": "node apps/web/.next/standalone/server.js",
+		"healthcheckPath": "/api/health",
+		"healthcheckTimeout": 30,
+		"restartPolicyType": "ON_FAILURE",
+		"restartPolicyMaxRetries": 5
+	}
+}

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

@@ -35,20 +35,19 @@ export const POST = withCsrfProtection(async (request) => {
 			password: hashedPassword,
 		});
 
-		// Enqueue welcome email (fire-and-forget)
+		// Don't return the password
+		const { password: _, ...safeUser } = newUser;
+
+		// Enqueue welcome email (fire-and-forget — don't block the response)
 		try {
 			const emailQueue = createQueue(JOB_QUEUES.EMAIL);
 			await emailQueue.add(JOB_NAMES.SEND_WELCOME_EMAIL, {
 				userId: newUser.id,
 			});
-		} catch (emailError) {
-			// Don't fail registration if email enqueue fails
-			console.error("Failed to enqueue welcome email:", emailError);
+		} catch {
+			// Non-critical — user is created even if email fails to enqueue
 		}
 
-		// Don't return the password
-		const { password: _, ...safeUser } = newUser;
-
 		return NextResponse.json(safeUser, { status: 201 });
 	} catch (error) {
 		return handleError(error);

package/templates/base-project/apps/web/src/app/layout.js

@@ -1,7 +1,6 @@
-export const metadata = {
-	title: "Quark",
-	description: "A modern monorepo with Next.js, React, and Prisma",
-};
+import { getSiteMetadata } from "../lib/seo/site-metadata.js";
+
+export const metadata = getSiteMetadata();
 
 export default function RootLayout({ children }) {
 	return (

package/templates/base-project/apps/web/src/app/manifest.js

@@ -0,0 +1,12 @@
+import { config, getAppUrl } from "@techstream/quark-config";
+
+export default function manifest() {
+	return {
+		name: config.appName,
+		short_name: config.appName,
+		description: config.appDescription,
+		start_url: "/",
+		display: "standalone",
+		id: getAppUrl(),
+	};
+}

package/templates/base-project/apps/web/src/app/robots.js

@@ -0,0 +1,21 @@
+import { getAppUrl } from "@techstream/quark-config";
+import { isWebsiteIndexable } from "../lib/seo/indexing.js";
+
+export default function robots() {
+	const appUrl = getAppUrl();
+	const indexable = isWebsiteIndexable();
+
+	return {
+		rules: indexable
+			? {
+					userAgent: "*",
+					allow: "/",
+					disallow: ["/api/"],
+				}
+			: {
+					userAgent: "*",
+					disallow: "/",
+				},
+		sitemap: indexable ? `${appUrl}/sitemap.xml` : undefined,
+	};
+}

package/templates/base-project/apps/web/src/app/sitemap.js

@@ -0,0 +1,20 @@
+import { getAppUrl } from "@techstream/quark-config";
+import { isWebsiteIndexable } from "../lib/seo/indexing.js";
+
+const STATIC_ROUTES = [{ path: "/", changeFrequency: "daily", priority: 1 }];
+
+export default function sitemap() {
+	if (!isWebsiteIndexable()) {
+		return [];
+	}
+
+	const appUrl = getAppUrl();
+	const lastModified = new Date();
+
+	return STATIC_ROUTES.map((route) => ({
+		url: `${appUrl}${route.path}`,
+		lastModified,
+		changeFrequency: route.changeFrequency,
+		priority: route.priority,
+	}));
+}

package/templates/base-project/apps/web/src/lib/seo/indexing.js

@@ -0,0 +1,23 @@
+export function isWebsiteIndexable(env = process.env) {
+	return (env.NODE_ENV || "").toLowerCase() === "production";
+}
+
+export function getMetadataRobots(env = process.env) {
+	if (isWebsiteIndexable(env)) {
+		return {
+			index: true,
+			follow: true,
+		};
+	}
+
+	return {
+		index: false,
+		follow: false,
+		nocache: true,
+		googleBot: {
+			index: false,
+			follow: false,
+			noimageindex: true,
+		},
+	};
+}

package/templates/base-project/apps/web/src/lib/seo/site-metadata.js

@@ -0,0 +1,33 @@
+import { config, getAppUrl } from "@techstream/quark-config";
+import { getMetadataRobots } from "./indexing.js";
+
+const appUrl = getAppUrl();
+const { appName, appDescription } = config;
+
+export function getSiteMetadata() {
+	return {
+		metadataBase: new URL(appUrl),
+		title: {
+			default: appName,
+			template: `%s | ${appName}`,
+		},
+		description: appDescription,
+		applicationName: appName,
+		alternates: {
+			canonical: "/",
+		},
+		openGraph: {
+			type: "website",
+			url: appUrl,
+			title: appName,
+			description: appDescription,
+			siteName: appName,
+		},
+		twitter: {
+			card: "summary",
+			title: appName,
+			description: appDescription,
+		},
+		robots: getMetadataRobots(),
+	};
+}

package/templates/base-project/apps/web/src/proxy.js

@@ -151,8 +151,7 @@ export function proxy(request) {
 
 	// Apply rate limiting to API routes only
 	if (pathname.startsWith("/api/")) {
-		const ip =
-			request.ip || request.headers.get("x-forwarded-for") || "unknown";
+		const ip = request.ip || "unknown";
 		const rateLimitResult = checkRateLimit(ip, pathname);
 
 		if (rateLimitResult.limited) {