@techstream/quark-create-app 1.7.0 → 1.9.0

package/README.md

@@ -42,6 +42,67 @@ Aliases:
 - `create-quark-app`
 - `quark-update`
 
+## Usage with Flags
+
+The CLI supports non-interactive mode with custom options for automation and CI/CD workflows.
+
+### Non-Interactive Mode
+
+Skip all interactive prompts and use defaults:
+
+```bash
+# Create project without prompts
+npx @techstream/quark-create-app my-app --no-prompts
+```
+
+### Custom Features
+
+Specify which optional packages to include (default: `ui,jobs`):
+
+```bash
+# Only include UI package
+npx @techstream/quark-create-app my-app --no-prompts --features ui
+
+# Include both UI and Jobs
+npx @techstream/quark-create-app my-app --no-prompts --features ui,jobs
+
+# Minimal setup (no optional packages)
+npx @techstream/quark-create-app my-app --no-prompts --features ""
+```
+
+### Skip Installation Steps
+
+Create the project structure without running package installation:
+
+```bash
+# Create project but skip pnpm install
+npx @techstream/quark-create-app my-app --no-prompts --skip-install
+
+# Useful for CI/CD where you'll install dependencies separately
+```
+
+### Docker Cleanup
+
+Control whether to remove Docker volumes from previous cleanup:
+
+```bash
+# Keep Docker working directories (useful in CI/CD)
+npx @techstream/quark-create-app my-app --no-prompts --skip-docker
+```
+
+### Complete Example: Full Automation
+
+```bash
+# Create, install, and setup everything automatically
+npx @techstream/quark-create-app my-app \
+  --no-prompts \
+  --features ui,jobs \
+  && cd my-app \
+  && docker compose up -d \
+  && pnpm db:migrate \
+  && pnpm dev
+```
+
 ## Common Tasks
 
 - **Update Quark packages**: `quark-update` or `pnpm update @techstream/quark-*`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techstream/quark-create-app",
-  "version": "1.7.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,10 +30,13 @@
   "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",
     "test:integration": "node test-integration.js",
-    "test:all": "node test-all.js"
+    "test:flags": "node --test test-flags.js",
+    "test:all": "node test-all.js",
+    "check:perf": "node scripts/check-e2e-perf.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");
@@ -254,7 +255,15 @@ function validateProjectName(name) {
 
 program
 	.argument("<project-name>", "Name of the project to create")
-	.action(async (projectName) => {
+	.option(
+		"--no-prompts",
+		"Skip interactive prompts and use default/provided values",
+	)
+	.option(
+		"--features <features>",
+		"Comma-separated list of optional features to include (ui,jobs)",
+	)
+	.action(async (projectName, options) => {
 		console.log(
 			chalk.blue.bold(
 				`\n\uD83D\uDE80 Creating your new Quark project: ${projectName}\n`,
@@ -263,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".
@@ -314,16 +325,25 @@ program
 
 		// Check if directory already exists
 		if (await fs.pathExists(targetDir)) {
-			const { overwrite } = await prompts({
-				type: "confirm",
-				name: "overwrite",
-				message: `Directory "${projectName}" already exists. Remove it and recreate?`,
-				initial: false,
-			});
+			if (!options.prompts) {
+				// In non-interactive mode, automatically remove existing directory
+				console.log(
+					chalk.yellow(
+						`  Directory "${projectName}" already exists. Removing... (non-interactive mode)`,
+					),
+				);
+			} else {
+				const { overwrite } = await prompts({
+					type: "confirm",
+					name: "overwrite",
+					message: `Directory "${projectName}" already exists. Remove it and recreate?`,
+					initial: false,
+				});
 
-			if (!overwrite) {
-				console.log(chalk.yellow("Aborted."));
-				process.exit(1);
+				if (!overwrite) {
+					console.log(chalk.yellow("Aborted."));
+					process.exit(1);
+				}
 			}
 
 			// Stop any running Docker containers for this project
@@ -379,35 +399,72 @@ program
 			}
 
 			// Step 5: Ask which optional features to eject
-			console.log(chalk.cyan("\n  🎯 Configuring optional features...\n"));
-			const response = await prompts([
-				{
-					type: "multiselect",
-					name: "features",
-					message: "Which optional packages would you like to include?",
-					instructions: false,
-					choices: [
-						{
-							title: "UI Components (packages/ui)",
-							value: "ui",
-							selected: true,
-						},
-						{
-							title: "Job Definitions (packages/jobs)",
-							value: "jobs",
-							selected: true,
-						},
-					],
-				},
-			]);
+			let features;
+			if (!options.prompts && options.features) {
+				// Parse features from CLI flag
+				console.log(chalk.cyan("\n  🎯 Configuring optional features..."));
+				const validFeatures = ["ui", "jobs"];
+				features = options.features
+					.split(",")
+					.map((f) => f.trim())
+					.filter((f) => f.length > 0);
+
+				// Validate features
+				const invalidFeatures = features.filter(
+					(f) => !validFeatures.includes(f),
+				);
+				if (invalidFeatures.length > 0) {
+					throw new Error(
+						`Invalid features: ${invalidFeatures.join(", ")}. Valid options are: ${validFeatures.join(", ")}`,
+					);
+				}
+
+				console.log(
+					chalk.green(
+						`  Selected features: ${features.join(", ") || "none"} (non-interactive mode)`,
+					),
+				);
+			} else if (!options.prompts) {
+				// Use defaults when --no-prompts is set without --features
+				console.log(chalk.cyan("\n  🎯 Configuring optional features..."));
+				features = ["ui", "jobs"]; // Default to both
+				console.log(
+					chalk.green(
+						`  Using default features: ${features.join(", ")} (non-interactive mode)`,
+					),
+				);
+			} else {
+				// Interactive prompt
+				console.log(chalk.cyan("\n  🎯 Configuring optional features...\n"));
+				const response = await prompts([
+					{
+						type: "multiselect",
+						name: "features",
+						message: "Which optional packages would you like to include?",
+						instructions: false,
+						choices: [
+							{
+								title: "UI Components (packages/ui)",
+								value: "ui",
+								selected: true,
+							},
+							{
+								title: "Job Definitions (packages/jobs)",
+								value: "jobs",
+								selected: true,
+							},
+						],
+					},
+				]);
 
-			const { features } = response;
+				features = response.features;
 
-			// Handle prompt cancellation (Ctrl+C)
-			if (!features) {
-				console.log(chalk.yellow("\n\u26A0\uFE0F  Setup cancelled."));
-				await fs.remove(targetDir);
-				process.exit(0);
+				// Handle prompt cancellation (Ctrl+C)
+				if (!features) {
+					console.log(chalk.yellow("\n\u26A0\uFE0F  Setup cancelled."));
+					await fs.remove(targetDir);
+					process.exit(0);
+				}
 			}
 
 			// Step 6: Copy selected optional packages
@@ -474,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
 
@@ -490,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
@@ -497,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
@@ -509,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
 
@@ -525,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
@@ -633,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/railway.json

@@ -6,6 +6,7 @@
 		"watchPatterns": ["apps/web/**", "packages/**"]
 	},
 	"deploy": {
+		"releaseCommand": "pnpm --filter @techstream/quark-db exec prisma migrate deploy",
 		"startCommand": "node apps/web/.next/standalone/server.js",
 		"healthcheckPath": "/api/health",
 		"healthcheckTimeout": 30,

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 };
+	}
+}