@techstream/quark-create-app 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techstream/quark-create-app",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "type": "module",
   "bin": {
     "quark-create-app": "src/index.js",
@@ -16,7 +16,7 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "execa": "^9.6.1",
-    "fs-extra": "^11.3.3",
+    "fs-extra": "^11.3.4",
     "prompts": "^2.4.2"
   },
   "publishConfig": {
@@ -30,7 +30,7 @@
   "scripts": {
     "sync-templates": "node scripts/sync-templates.js",
     "sync-templates:check": "node scripts/sync-templates.js --check",
-    "test": "node test-cli.js",
+    "test": "node test-cli.js && node --test src/utils.test.js",
     "test:build": "node test-build.js",
     "test:e2e": "node test-e2e.js",
     "test:e2e:full": "node test-e2e-full.js",

package/src/index.js

@@ -8,6 +8,7 @@ import { Command } from "commander";
 import { execa } from "execa";
 import fs from "fs-extra";
 import prompts from "prompts";
+import { formatProjectDisplayName } from "./utils.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const templatesDir = path.join(__dirname, "../templates");
@@ -271,6 +272,8 @@ program
 
 		const targetDir = validateProjectName(projectName);
 		const scope = projectName.toLowerCase().replace(/[^a-z0-9-]/g, "");
+		const appDisplayName = formatProjectDisplayName(projectName);
+		const appDescription = `${appDisplayName} application`;
 
 		// Clean up orphaned Docker volumes from a previous project with the same name.
 		// Docker Compose names volumes as "<project>_postgres_data", "<project>_redis_data".
@@ -528,7 +531,11 @@ program
 
 			// Step 8: Create .env.example file
 			console.log(chalk.cyan("\n  📋 Creating environment configuration..."));
-			const envExampleTemplate = `# --- Environment ---
+			const envExampleTemplate = `# ⚠️  IMPORTANT: Copy this file to .env and fill in the values for your environment.
+# NEVER commit the .env file to version control — it contains secrets!
+# $ cp .env.example .env
+
+# --- Environment ---
 # Supported: development, test, staging, production (default: development)
 # NODE_ENV=development
 
@@ -544,6 +551,10 @@ POSTGRES_DB=${scope}_dev
 # Optional: Set DATABASE_URL to override the dynamic construction above
 # DATABASE_URL="postgresql://${scope}_user:CHANGE_ME_TO_STRONG_PASSWORD@localhost:5432/${scope}_dev?schema=public"
 
+# --- Database Pool Configuration ---
+# Connection pool settings are managed automatically. Customize if needed:
+# For advanced tuning, see Prisma connection pool documentation.
+
 # --- Redis Configuration ---
 REDIS_HOST=localhost
 REDIS_PORT=6379
@@ -551,6 +562,9 @@ REDIS_PORT=6379
 # REDIS_URL="redis://localhost:6379"
 
 # --- Mail Configuration ---
+# Email can be sent via SMTP (local or production), Resend, or Zeptomail.
+# Choose one provider below based on your needs.
+
 # Development: Mailpit local SMTP (defaults below work with docker-compose)
 MAIL_HOST=localhost
 MAIL_SMTP_PORT=1025
@@ -563,12 +577,20 @@ MAIL_UI_PORT=8025
 # SMTP_USER=your_smtp_user
 # SMTP_PASSWORD=your_smtp_password
 
-# --- Email Provider ---
-# Provider: "smtp" (default) or "resend"
+# --- Email Provider Selection ---
+# Choose one: "smtp" (default), "resend", or "zeptomail"
 # EMAIL_PROVIDER=smtp
 # EMAIL_FROM=App Name <noreply@yourdomain.com>
 
-# Resend (only when EMAIL_PROVIDER=resend)
+# Zeptomail (recommended for production)
+# Get started at: https://www.zoho.com/zeptomail/
+# Your token is shown in Zeptomail console and includes the "Zoho-enczapikey" prefix:
+# e.g. ZEPTOMAIL_TOKEN=Zoho-enczapikey <your_key_here>
+# ZEPTOMAIL_TOKEN=Zoho-enczapikey your_zeptomail_api_key
+# ZEPTOMAIL_URL=https://api.zeptomail.com  # Base URL; /v1.1/email is appended in code
+# ZEPTOMAIL_BOUNCE_EMAIL=bounce@yourdomain.com  # optional
+
+# Resend (alternative provider)
 # Get your API key at: https://resend.com/api-keys
 # RESEND_API_KEY=re_xxxxxxxxxxxxx
 
@@ -579,14 +601,21 @@ MAIL_UI_PORT=8025
 
 # --- Application Identity ---
 # APP_NAME is used in metadata, emails, and page titles.
-APP_NAME=${projectName}
+# ⚠️  APP_DESCRIPTION affects SEO snippets — update before production.
+APP_NAME=${appDisplayName}
+APP_DESCRIPTION=${appDescription}
 
 # --- NextAuth Configuration ---
 # ⚠️  CRITICAL: Generate a secure secret with: openssl rand -base64 32
 # This secret is used to encrypt JWT tokens and session data
 NEXTAUTH_SECRET=CHANGE_ME_TO_STRONG_SECRET
 
-# --- OAuth Providers (Optional) ---
+# NextAuth callback URL (auto-derived from APP_URL in development)
+# In production, explicitly set this to your domain:
+# NEXTAUTH_URL=https://yourdomain.com/api/auth
+
+# --- OAuth Providers (Not Yet Implemented) ---
+# OAuth support is planned for a future release.
 # GitHub OAuth - Get credentials at: https://github.com/settings/developers
 # GITHUB_ID=your_github_client_id
 # GITHUB_SECRET=your_github_client_secret
@@ -687,7 +716,10 @@ MAIL_SMTP_PORT=${mailSmtpPort}
 MAIL_UI_PORT=${mailUiPort}
 
 # --- Application Identity ---
-APP_NAME=${projectName}
+# APP_NAME is used in metadata, emails, and page titles.
+# ⚠️  APP_DESCRIPTION affects SEO snippets — update before production.
+APP_NAME=${appDisplayName}
+APP_DESCRIPTION=${appDescription}
 
 # --- NextAuth Configuration ---
 NEXTAUTH_SECRET=${nextAuthSecret}

package/src/utils.js

@@ -0,0 +1,36 @@
+/**
+ * Shared utilities for @techstream/quark-create-app
+ */
+
+/**
+ * Format a project slug into a human-friendly application name.
+ *
+ * - Hyphens, underscores, and dots are treated as word separators
+ * - Each word is title-cased
+ * - Degenerate inputs (all separators) fall back to "Quark App"
+ *
+ * @param {string} projectName - Raw project slug (e.g. "my-cool-app")
+ * @returns {string} Title-cased display name (e.g. "My Cool App")
+ *
+ * @example
+ * formatProjectDisplayName("my-cool-app")   // "My Cool App"
+ * formatProjectDisplayName("my.app")         // "My App"
+ * formatProjectDisplayName("my_app_v2")      // "My App V2"
+ * formatProjectDisplayName("myapp")          // "Myapp"
+ * formatProjectDisplayName("---")            // "Quark App"
+ */
+export function formatProjectDisplayName(projectName) {
+	const normalized = projectName
+		.replace(/[-_.]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+
+	if (!normalized) {
+		return "Quark App";
+	}
+
+	return normalized
+		.split(" ")
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+		.join(" ");
+}

package/src/utils.test.js

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { formatProjectDisplayName } from "./utils.js";
+
+// ---------------------------------------------------------------------------
+// Happy path — common slug patterns
+// ---------------------------------------------------------------------------
+
+test("formatProjectDisplayName - hyphen-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my-cool-app"), "My Cool App");
+});
+
+test("formatProjectDisplayName - underscore-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my_app_v2"), "My App V2");
+});
+
+test("formatProjectDisplayName - dot-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my.app"), "My App");
+});
+
+test("formatProjectDisplayName - single word (no separators)", () => {
+	assert.strictEqual(formatProjectDisplayName("myapp"), "Myapp");
+});
+
+test("formatProjectDisplayName - already title-cased input", () => {
+	// slice(1) preserves remaining chars as-is — only the first char is forced uppercase
+	assert.strictEqual(formatProjectDisplayName("MyApp"), "MyApp");
+});
+
+test("formatProjectDisplayName - mixed separators", () => {
+	assert.strictEqual(formatProjectDisplayName("my-app_v2.0"), "My App V2 0");
+});
+
+test("formatProjectDisplayName - consecutive separators collapse to single space", () => {
+	assert.strictEqual(formatProjectDisplayName("my--app"), "My App");
+	assert.strictEqual(formatProjectDisplayName("my___app"), "My App");
+	assert.strictEqual(formatProjectDisplayName("my-._app"), "My App");
+});
+
+test("formatProjectDisplayName - numbers preserved in words", () => {
+	assert.strictEqual(formatProjectDisplayName("app-v2"), "App V2");
+	assert.strictEqual(formatProjectDisplayName("project-123"), "Project 123");
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases — degenerate / boundary inputs
+// ---------------------------------------------------------------------------
+
+test("formatProjectDisplayName - all separators returns fallback", () => {
+	assert.strictEqual(formatProjectDisplayName("---"), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("___"), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("..."), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("-._-"), "Quark App");
+});
+
+test("formatProjectDisplayName - preserves casing of rest of word", () => {
+	// The function only forces the first char uppercase; the remainder is untouched
+	assert.strictEqual(formatProjectDisplayName("myApp"), "MyApp");
+});
+
+test("formatProjectDisplayName - short single-char name", () => {
+	assert.strictEqual(formatProjectDisplayName("a"), "A");
+});

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

@@ -3,9 +3,13 @@ name: Release
 on:
   workflow_dispatch:
     inputs:
-      notes:
-        description: "Release notes (optional — auto-generated if blank)"
+      prerelease:
+        description: "Tag as pre-release (staging-only, skips production deploy)"
         required: false
+        default: false
+        type: boolean
+
+concurrency: ${{ github.workflow }}
 
 permissions:
   contents: write
@@ -17,22 +21,47 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
+          ref: main
           fetch-depth: 0
 
-      - name: Generate date-based tag
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Push to production branch
+        if: ${{ !inputs.prerelease }}
+        run: |
+          git fetch origin
+          if git ls-remote --exit-code --heads origin production > /dev/null; then
+            git checkout production && git merge --ff-only origin/main
+          else
+            git checkout -b production origin/main
+          fi
+          git push origin production
+          git checkout main
+
+      - name: Generate tag
         id: tag
         run: |
           BASE="v$(date +%Y.%m.%d)"
-          EXISTING=$(git tag -l "${BASE}*" | wc -l | tr -d ' ')
+          SUFFIX="${{ inputs.prerelease && '-rc' || '' }}"
+          # Count only exact-format matches to avoid rc tags polluting production counts
+          EXISTING=$(git tag -l | grep -cE "^${BASE}${SUFFIX}(\.[0-9]+)?$" || true)
           if [ "$EXISTING" -eq "0" ]; then
-            echo "tag=${BASE}" >> "$GITHUB_OUTPUT"
+            echo "tag=${BASE}${SUFFIX}" >> "$GITHUB_OUTPUT"
           else
-            echo "tag=${BASE}.${EXISTING}" >> "$GITHUB_OUTPUT"
+            echo "tag=${BASE}${SUFFIX}.${EXISTING}" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Tag release
+        run: |
+          git tag -a "${{ steps.tag.outputs.tag }}" -m "Release ${{ steps.tag.outputs.tag }}"
+          git push origin "${{ steps.tag.outputs.tag }}"
+
       - 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 }}
+          generate_release_notes: true
+          prerelease: ${{ inputs.prerelease }}

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

@@ -12,22 +12,24 @@
 	},
 	"dependencies": {
 		"@auth/prisma-adapter": "^2.11.1",
+		"@aws-sdk/client-s3": "^3.1002.0",
+		"@aws-sdk/s3-request-presigner": "^3.1002.0",
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
 		"@techstream/quark-ui": "workspace:*",
-		"@prisma/client": "^7.4.0",
+		"@prisma/client": "^7.4.2",
 		"next": "16.1.6",
 		"next-auth": "5.0.0-beta.30",
-		"pg": "^8.18.0",
+		"pg": "^8.20.0",
 		"react": "19.2.4",
 		"react-dom": "19.2.4",
 		"zod": "^4.3.6"
 	},
 	"devDependencies": {
-		"@tailwindcss/postcss": "^4.2.0",
-		"@types/node": "^25.2.3",
-		"tailwindcss": "^4.2.0",
+		"@tailwindcss/postcss": "^4.2.1",
+		"@types/node": "^25.3.3",
+		"tailwindcss": "^4.2.1",
 		"@techstream/quark-config": "workspace:*"
 	}
 }

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

@@ -4,7 +4,7 @@
  * Times out after 5 seconds to prevent hanging.
  */
 
-import { createLogger, pingRedis } from "@techstream/quark-core";
+import { createLogger, createStorage, pingRedis } from "@techstream/quark-core";
 import { prisma } from "@techstream/quark-db";
 import { NextResponse } from "next/server";
 
@@ -79,5 +79,33 @@ async function runHealthChecks() {
 		health.status = "degraded";
 	}
 
+	// Check storage connectivity
+	const storageResult = await checkStorage();
+	health.checks.storage = storageResult;
+	if (storageResult.status === "error") {
+		health.status = "degraded";
+	}
+
 	return health;
 }
+
+/**
+ * Verifies storage is reachable and writable by writing then deleting a
+ * small sentinel object. Uses whichever provider is configured via
+ * STORAGE_PROVIDER (defaults to "local" when unset).
+ * @returns {Promise<{ status: string, provider: string, message?: string }>}
+ */
+async function checkStorage() {
+	const provider = process.env.STORAGE_PROVIDER || "local";
+	try {
+		const storage = createStorage();
+		const sentinelKey = ".health-check-sentinel";
+		await storage.put(sentinelKey, Buffer.from("ok"), {
+			contentType: "text/plain",
+		});
+		await storage.delete(sentinelKey);
+		return { status: "ok", provider };
+	} catch (error) {
+		return { status: "error", provider, message: error.message };
+	}
+}

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

@@ -20,10 +20,10 @@
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
-		"bullmq": "^5.69.3"
+		"bullmq": "^5.70.2"
 	},
 	"devDependencies": {
-		"@types/node": "^25.2.3",
+		"@types/node": "^25.3.3",
 		"tsx": "^4.21.0"
 	}
 }

package/templates/base-project/package.json

@@ -15,7 +15,18 @@
 		"db:migrate": "turbo run db:migrate",
 		"db:push": "turbo run db:push",
 		"db:seed": "turbo run db:seed",
-		"db:studio": "turbo run db:studio"
+		"db:studio": "turbo run db:studio",
+		"prepare": "simple-git-hooks"
+	},
+	"simple-git-hooks": {
+		"pre-commit": "pnpm nano-staged",
+		"pre-push": "pnpm test"
+	},
+	"nano-staged": {
+		"**/*.{js,mjs,ts,tsx,json,css}": [
+			"biome format --write",
+			"biome check --write"
+		]
 	},
 	"keywords": [],
 	"author": "",
@@ -39,6 +50,8 @@
 		"@biomejs/biome": "^2.4.0",
 		"@types/node": "^24.10.9",
 		"dotenv-cli": "^11.0.0",
+		"nano-staged": "^0.9.0",
+		"simple-git-hooks": "^2.13.1",
 		"tsx": "^4.21.0",
 		"turbo": "^2.8.1"
 	}

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

@@ -21,12 +21,12 @@
 		"@faker-js/faker": "^10.3.0",
 		"@techstream/quark-config": "workspace:*",
 		"bcryptjs": "^3.0.3",
-		"prisma": "^7.4.0"
+		"prisma": "^7.4.2"
 	},
 	"dependencies": {
-		"@prisma/adapter-pg": "^7.4.0",
-		"@prisma/client": "^7.4.0",
-		"pg": "^8.18.0",
+		"@prisma/adapter-pg": "^7.4.2",
+		"@prisma/client": "^7.4.2",
+		"pg": "^8.20.0",
 		"zod": "^4.3.6"
 	}
 }

package/templates/config/src/index.js

@@ -1,8 +1,6 @@
 export const config = {
 	appName: process.env.APP_NAME || "Quark",
-	appDescription:
-		process.env.APP_DESCRIPTION ||
-		"A modern monorepo with Next.js, React, and Prisma",
+	appDescription: process.env.APP_DESCRIPTION || "A Quark-powered application",
 };
 
 export { getAllowedOrigins, getAppUrl, syncNextAuthUrl } from "./app-url.js";

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

@@ -37,10 +37,16 @@ const envSchema = {
 	// Email provider
 	EMAIL_PROVIDER: {
 		required: false,
-		description: 'Email provider — "smtp" (default) or "resend"',
+		description: 'Email provider — "smtp" (default), "resend", or "zeptomail"',
 	},
 	EMAIL_FROM: { required: false, description: "Sender email address" },
 	RESEND_API_KEY: { required: false, description: "Resend API key" },
+	ZEPTOMAIL_TOKEN: { required: false, description: "Zeptomail API token" },
+	ZEPTOMAIL_URL: { required: false, description: "Zeptomail API base URL" },
+	ZEPTOMAIL_BOUNCE_EMAIL: {
+		required: false,
+		description: "Zeptomail bounce email address",
+	},
 
 	// NextAuth
 	NEXTAUTH_SECRET: {
@@ -58,6 +64,11 @@ const envSchema = {
 		required: false,
 		description: "Application name — used in metadata, emails, and page titles",
 	},
+	APP_DESCRIPTION: {
+		required: false,
+		description:
+			"Application description — used for SEO metadata and social previews",
+	},
 	APP_URL: {
 		required: false,
 		description:
@@ -69,6 +80,12 @@ const envSchema = {
 	},
 	PORT: { required: false, description: "Web server port" },
 
+	// Worker
+	WORKER_CONCURRENCY: {
+		required: false,
+		description: "Number of concurrent jobs per queue (default: 5)",
+	},
+
 	// Storage
 	STORAGE_PROVIDER: {
 		required: false,
@@ -80,10 +97,19 @@ const envSchema = {
 	},
 	S3_BUCKET: { required: false, description: "S3 bucket name" },
 	S3_REGION: { required: false, description: "S3 region" },
-	S3_ENDPOINT: { required: false, description: "S3-compatible endpoint URL" },
+	S3_ENDPOINT: {
+		required: false,
+		description:
+			"S3-compatible endpoint URL (required for non-AWS providers: R2, MinIO, etc.)",
+	},
 	S3_ACCESS_KEY_ID: { required: false, description: "S3 access key" },
 	S3_SECRET_ACCESS_KEY: { required: false, description: "S3 secret key" },
 	S3_PUBLIC_URL: { required: false, description: "S3 public URL prefix" },
+	ASSET_CDN_URL: {
+		required: false,
+		description:
+			"Public CDN base URL for asset delivery — provider-agnostic (CloudFront, Cloudflare, Bunny, etc.). Falls back to /api/files when unset.",
+	},
 };
 
 /**
@@ -129,6 +155,25 @@ export function validateEnv(service = "web") {
 
 	// --- Cross-field validation ---
 
+	// Placeholder value security check
+	const placeholderPattern = /^CHANGE_ME_/i;
+	const criticalKeys = [
+		"NEXTAUTH_SECRET",
+		"POSTGRES_PASSWORD",
+		"RESEND_API_KEY",
+		"ZEPTOMAIL_TOKEN",
+		"S3_SECRET_ACCESS_KEY",
+		"SMTP_PASSWORD",
+	];
+	for (const key of criticalKeys) {
+		const value = process.env[key];
+		if (value && placeholderPattern.test(value)) {
+			errors.push(
+				`${key} contains a placeholder value — replace with a real secret (${envSchema[key]?.description || ""})`,
+			);
+		}
+	}
+
 	// Database: either DATABASE_URL or POSTGRES_USER must be set (skip in test)
 	if (!isTest) {
 		const hasDbUrl = !!process.env.DATABASE_URL;
@@ -141,16 +186,33 @@ export function validateEnv(service = "web") {
 	}
 
 	// Redis: warn if not configured (defaults to localhost in dev, will fail in prod)
+	const currentEnv = (process.env.NODE_ENV || "").toLowerCase();
 	if (
 		!process.env.REDIS_URL &&
 		!process.env.REDIS_HOST &&
-		process.env.NODE_ENV === "production"
+		(currentEnv === "production" || currentEnv === "staging")
 	) {
 		warnings.push(
 			"Redis not configured: set REDIS_URL or REDIS_HOST (defaults to localhost)",
 		);
 	}
 
+	// SEO metadata: APP_DESCRIPTION should be explicitly set before production
+	const isProductionLike =
+		currentEnv === "production" || currentEnv === "staging";
+	if (!isTest && isProductionLike) {
+		const appDescription = process.env.APP_DESCRIPTION;
+		if (!appDescription) {
+			warnings.push(
+				"APP_DESCRIPTION not set: metadata description will fall back to a generic value. Set APP_DESCRIPTION before production.",
+			);
+		} else if (/^CHANGE_ME_|^TODO_/i.test(appDescription)) {
+			warnings.push(
+				"APP_DESCRIPTION appears to be a placeholder value. Update it before production.",
+			);
+		}
+	}
+
 	// Conditional: S3 storage requires bucket + credentials
 	if (process.env.STORAGE_PROVIDER === "s3") {
 		for (const key of [
@@ -171,6 +233,20 @@ export function validateEnv(service = "web") {
 		errors.push("Missing RESEND_API_KEY — required when EMAIL_PROVIDER=resend");
 	}
 
+	// Conditional: Zeptomail provider requires token and URL
+	if (process.env.EMAIL_PROVIDER === "zeptomail") {
+		if (!process.env.ZEPTOMAIL_TOKEN) {
+			errors.push(
+				"Missing ZEPTOMAIL_TOKEN — required when EMAIL_PROVIDER=zeptomail",
+			);
+		}
+		if (!process.env.ZEPTOMAIL_URL) {
+			errors.push(
+				"Missing ZEPTOMAIL_URL — required when EMAIL_PROVIDER=zeptomail",
+			);
+		}
+	}
+
 	// Log warnings (non-fatal)
 	for (const warning of warnings) {
 		console.warn(`[env] ⚠️  ${warning}`);

package/templates/jobs/package.json

@@ -3,6 +3,6 @@
 	"version": "1.0.0",
 	"type": "module",
 	"dependencies": {
-		"bullmq": "^5.69.3"
+		"bullmq": "^5.70.2"
 	}
 }