@techstream/quark-create-app 1.8.0 → 1.10.0

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");
@@ -189,13 +190,42 @@ function replaceDepsScope(deps, scope, selectedPackages) {
 	}
 }
 
+/**
+ * Remove unselected optional feature entries from next.config.js transpilePackages.
+ * Must run AFTER replaceImportsInSourceFiles so package names are already scoped.
+ */
+async function patchNextConfig(webDir, scope, selectedFeatures) {
+	const configPath = path.join(webDir, "next.config.js");
+	if (!(await fs.pathExists(configPath))) return;
+
+	let content = await fs.readFile(configPath, "utf-8");
+
+	const optionalEntries = {
+		ui: `@${scope}/ui`,
+		jobs: `@${scope}/jobs`,
+		admin: `@${scope}/admin`,
+	};
+
+	for (const [feature, pkg] of Object.entries(optionalEntries)) {
+		if (!selectedFeatures.includes(feature)) {
+			// Remove the line containing this package from transpilePackages
+			content = content.replace(
+				new RegExp(`[ \\t]*"${pkg.replace("/", "\\/")}",?\\n`, "g"),
+				"",
+			);
+		}
+	}
+
+	await fs.writeFile(configPath, content);
+}
+
 /**
  * Replace @techstream/quark-* import paths in all .js source files
  * for workspace packages (db, jobs, ui, config) with @scope/* equivalents.
  * Registry packages (@techstream/quark-core) are left untouched.
  */
 async function replaceImportsInSourceFiles(dir, scope) {
-	const workspacePackages = ["db", "jobs", "ui", "config"];
+	const workspacePackages = ["db", "jobs", "ui", "config", "admin"];
 	const entries = await fs.readdir(dir, { withFileTypes: true });
 
 	for (const entry of entries) {
@@ -260,8 +290,10 @@ program
 	)
 	.option(
 		"--features <features>",
-		"Comma-separated list of optional features to include (ui,jobs)",
+		"Comma-separated list of optional features to include (ui,jobs,admin)",
 	)
+	.option("--skip-install", "Skip pnpm install and Prisma generate steps")
+	.option("--skip-docker", "Skip Docker orphan-volume cleanup")
 	.action(async (projectName, options) => {
 		console.log(
 			chalk.blue.bold(
@@ -271,54 +303,57 @@ 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".
 		// 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",
+		if (!options.skipDocker)
+			try {
+				const volumePrefix = `${projectName}_`;
+				const { stdout } = await execa("docker", [
+					"volume",
+					"ls",
 					"--filter",
-					`name=${projectName}`,
+					`name=${volumePrefix}`,
 					"--format",
-					"{{.ID}}",
+					"{{.Name}}",
 				]);
-				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]);
+				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"));
 				}
-				console.log(chalk.green("  ✓ Cleaned up orphaned Docker volumes"));
+			} catch {
+				// Docker not available — fine
 			}
-		} catch {
-			// Docker not available — fine
-		}
 
 		// Check if directory already exists
 		if (await fs.pathExists(targetDir)) {
@@ -400,7 +435,7 @@ program
 			if (!options.prompts && options.features) {
 				// Parse features from CLI flag
 				console.log(chalk.cyan("\n  🎯 Configuring optional features..."));
-				const validFeatures = ["ui", "jobs"];
+				const validFeatures = ["ui", "jobs", "admin"];
 				features = options.features
 					.split(",")
 					.map((f) => f.trim())
@@ -416,6 +451,11 @@ program
 					);
 				}
 
+				// Enforce admin dependencies: admin requires ui
+				if (features.includes("admin") && !features.includes("ui")) {
+					features.push("ui");
+				}
+
 				console.log(
 					chalk.green(
 						`  Selected features: ${features.join(", ") || "none"} (non-interactive mode)`,
@@ -424,7 +464,7 @@ program
 			} 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
+				features = ["ui", "jobs"]; // Default to ui + jobs (not admin)
 				console.log(
 					chalk.green(
 						`  Using default features: ${features.join(", ")} (non-interactive mode)`,
@@ -446,10 +486,15 @@ program
 								selected: true,
 							},
 							{
-								title: "Job Definitions (packages/jobs)",
+								title: "Background Jobs (packages/jobs + apps/worker)",
 								value: "jobs",
 								selected: true,
 							},
+							{
+								title: "Admin Dashboard (packages/admin) [requires: ui]",
+								value: "admin",
+								selected: false,
+							},
 						],
 					},
 				]);
@@ -462,6 +507,14 @@ program
 					await fs.remove(targetDir);
 					process.exit(0);
 				}
+
+				// Enforce admin dependencies: admin requires ui
+				if (features.includes("admin") && !features.includes("ui")) {
+					features.push("ui");
+					console.log(
+						chalk.yellow("    ℹ  Admin requires UI — automatically included."),
+					);
+				}
 			}
 
 			// Step 6: Copy selected optional packages
@@ -469,6 +522,17 @@ program
 				console.log(chalk.cyan("\n  📋 Setting up optional packages..."));
 
 				for (const feature of features) {
+					// admin is a package template — skip if no template exists yet
+					const templatePath = path.join(templatesDir, feature);
+					if (!(await fs.pathExists(templatePath))) {
+						console.log(
+							chalk.yellow(
+								`    ⚠ ${feature} (template not yet available — skipped)`,
+							),
+						);
+						continue;
+					}
+
 					const packageDir = path.join(targetDir, "packages", feature);
 					await fs.ensureDir(packageDir);
 					await copyTemplate(feature, packageDir);
@@ -479,6 +543,14 @@ program
 
 					console.log(chalk.green(`    ✓ ${feature}`));
 				}
+
+				// If jobs selected, also scaffold apps/worker from its template
+				if (features.includes("jobs")) {
+					const workerDir = path.join(targetDir, "apps", "worker");
+					await fs.ensureDir(workerDir);
+					await copyTemplate("worker", workerDir);
+					console.log(chalk.green(`    ✓ worker (paired with jobs)`));
+				}
 			}
 
 			// Step 7: Update all package.json dependencies to use correct scope
@@ -487,7 +559,10 @@ program
 			// Collect all package.json files that need scope replacement (apps + packages)
 			const allPkgPaths = [
 				path.join(targetDir, "apps", "web", "package.json"),
-				path.join(targetDir, "apps", "worker", "package.json"),
+				// Worker is only present when jobs is selected
+				...(features.includes("jobs")
+					? [path.join(targetDir, "apps", "worker", "package.json")]
+					: []),
 				// Also update cross-dependencies in scaffolded packages (e.g. db → config)
 				...["db", ...features].map((pkg) =>
 					path.join(targetDir, "packages", pkg, "package.json"),
@@ -526,9 +601,52 @@ program
 			await replaceImportsInSourceFiles(targetDir, scope);
 			console.log(chalk.green(`    ✓ Import paths updated`));
 
+			// Step 7c: Patch next.config.js to remove unselected feature transpilePackages entries
+			await patchNextConfig(
+				path.join(targetDir, "apps", "web"),
+				scope,
+				features,
+			);
+			console.log(chalk.green(`    ✓ next.config.js patched`));
+
+			// Step 7d: Strip jobs-related code from register route when jobs not selected
+			if (!features.includes("jobs")) {
+				const registerPath = path.join(
+					targetDir,
+					"apps",
+					"web",
+					"src",
+					"app",
+					"api",
+					"auth",
+					"register",
+					"route.js",
+				);
+				if (await fs.pathExists(registerPath)) {
+					let content = await fs.readFile(registerPath, "utf-8");
+					// Remove the jobs import line
+					content = content.replace(
+						/import\s*\{[^}]*\}\s*from\s*["']@[^/]+\/jobs["'];?\n/,
+						"",
+					);
+					// Remove createQueue from the core import if present
+					content = content.replace(/\tcreateQueue,\n/, "");
+					// Remove the @quark:start:jobs ... @quark:end:jobs block (inclusive)
+					content = content.replace(
+						/[ \t]*\/\/ @quark:start:jobs[\s\S]*?\/\/ @quark:end:jobs\n?/,
+						"",
+					);
+					await fs.writeFile(registerPath, content);
+				}
+			}
+
 			// 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 +662,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 +673,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 +688,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 +712,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 +827,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}
@@ -718,6 +861,8 @@ STORAGE_PROVIDER=local
 				scaffoldedDate: new Date().toISOString(),
 				requiredPackages: ["db", "config"],
 				packages: features,
+				// Track that worker is paired with jobs (not independently selectable)
+				hasWorker: features.includes("jobs"),
 			};
 			await fs.writeFile(
 				path.join(targetDir, ".quark-link.json"),
@@ -725,8 +870,24 @@ 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..."));
+			// Step 10b + 10c: Generate all AI coding tool context files
+			console.log(chalk.cyan("\n  🤖 Generating AI context files..."));
+
+			// Build shared variable map (used by SKILL.md, CLAUDE.md, .cursor/rules, copilot-instructions)
+			const scaffoldDate = new Date().toISOString().split("T")[0];
+			const optionalLines = features
+				.map((f) => {
+					const labels = {
+						ui: "Shared UI components",
+						jobs: "Job queue definitions",
+						admin: "Auto-generated admin dashboard",
+					};
+					return `│   ├── ${f}/           # ${labels[f] || f}`;
+				})
+				.join("\n");
+			const optionalBlock = optionalLines ? `${optionalLines}\n` : "";
+
+			// Step 10b: Substitute variables in project-context SKILL.md
 			const skillPath = path.join(
 				targetDir,
 				".github",
@@ -736,34 +897,38 @@ STORAGE_PROVIDER=local
 			);
 			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_SCAFFOLD_DATE__/g, scaffoldDate)
 					.replace(/__QUARK_OPTIONAL_PACKAGES__/g, optionalBlock);
-
 				await fs.writeFile(skillPath, skillContent);
 				console.log(
 					chalk.green(`    ✓ .github/skills/project-context/SKILL.md`),
 				);
 			}
 
+			// Step 10c: Substitute variables in all AI coding tool context files
+			const aiContextFiles = [
+				"README.md",
+				"CLAUDE.md",
+				".cursor/rules/quark.mdc",
+				".github/copilot-instructions.md",
+			];
+			for (const relPath of aiContextFiles) {
+				const filePath = path.join(targetDir, relPath);
+				if (await fs.pathExists(filePath)) {
+					let content = await fs.readFile(filePath, "utf-8");
+					content = content
+						.replace(/__QUARK_SCOPE__/g, scope)
+						.replace(/__QUARK_PROJECT_NAME__/g, projectName)
+						.replace(/__QUARK_SCAFFOLD_DATE__/g, scaffoldDate)
+						.replace(/__QUARK_OPTIONAL_PACKAGES__/g, optionalBlock);
+					await fs.writeFile(filePath, content);
+					console.log(chalk.green(`    ✓ ${relPath}`));
+				}
+			}
+
 			// Step 11: Initialize git repository
 			console.log(chalk.cyan("\n  📝 Initializing git repository..."));
 			const gitInitialized = await initializeGit(targetDir);
@@ -772,41 +937,45 @@ STORAGE_PROVIDER=local
 			}
 
 			// Step 12: Run pnpm install
-			console.log(chalk.cyan("\n  📦 Installing dependencies..."));
-			try {
-				await execa("pnpm", ["install"], {
-					cwd: targetDir,
-					stdio: "inherit",
-				});
-				console.log(chalk.green(`\n    ✓ Dependencies installed`));
-			} catch (installError) {
-				console.warn(
-					chalk.yellow(`\n    ⚠️  pnpm install failed: ${installError.message}`),
-				);
-				console.warn(
-					chalk.yellow(
-						`    Run 'pnpm install' manually after resolving the issue.`,
-					),
-				);
-			}
+			if (!options.skipInstall) {
+				console.log(chalk.cyan("\n  📦 Installing dependencies..."));
+				try {
+					await execa("pnpm", ["install"], {
+						cwd: targetDir,
+						stdio: "inherit",
+					});
+					console.log(chalk.green(`\n    ✓ Dependencies installed`));
+				} catch (installError) {
+					console.warn(
+						chalk.yellow(
+							`\n    ⚠️  pnpm install failed: ${installError.message}`,
+						),
+					);
+					console.warn(
+						chalk.yellow(
+							`    Run 'pnpm install' manually after resolving the issue.`,
+						),
+					);
+				}
 
-			// Step 13: Generate Prisma client
-			console.log(chalk.cyan("\n  🗄️  Generating Prisma client..."));
-			try {
-				await execa("pnpm", ["--filter", "db", "db:generate"], {
-					cwd: targetDir,
-					stdio: "inherit",
-				});
-				console.log(chalk.green(`    ✓ Prisma client generated`));
-			} catch (generateError) {
-				console.warn(
-					chalk.yellow(
-						`\n    ⚠️  Prisma generate failed: ${generateError.message}`,
-					),
-				);
-				console.warn(
-					chalk.yellow(`    Run 'pnpm --filter db db:generate' manually.`),
-				);
+				// Step 13: Generate Prisma client
+				console.log(chalk.cyan("\n  🗄️  Generating Prisma client..."));
+				try {
+					await execa("pnpm", ["--filter", "db", "db:generate"], {
+						cwd: targetDir,
+						stdio: "inherit",
+					});
+					console.log(chalk.green(`    ✓ Prisma client generated`));
+				} catch (generateError) {
+					console.warn(
+						chalk.yellow(
+							`\n    ⚠️  Prisma generate failed: ${generateError.message}`,
+						),
+					);
+					console.warn(
+						chalk.yellow(`    Run 'pnpm --filter db db:generate' manually.`),
+					);
+				}
 			}
 
 			// Success message
@@ -817,7 +986,7 @@ STORAGE_PROVIDER=local
 			);
 
 			console.log(chalk.white(`📂 Project location: ${targetDir}\n`));
-			console.log(chalk.cyan("Next steps:"));
+			console.log(chalk.cyan("Start here:"));
 			console.log(chalk.white(`  1. cd ${projectName}`));
 			console.log(chalk.white(`  2. docker compose up -d`));
 			console.log(chalk.white(`  3. pnpm db:migrate`));
@@ -829,20 +998,20 @@ STORAGE_PROVIDER=local
 				),
 			);
 
-			console.log(chalk.cyan("Important:"));
+			console.log(chalk.cyan("Build with AI:"));
 			console.log(
-				chalk.white(
-					`  • Update Quark core with: pnpm update @techstream/quark-core`,
-				),
+				chalk.white(`  Open CLAUDE.md in your AI tool, then tell it:`),
 			);
 			console.log(
-				chalk.white(`  • Or run: npx @techstream/quark-create-app update\n`),
+				chalk.white(
+					`  "I'm building ${projectName} — [what it does]. Review CLAUDE.md and let's start."\n`,
+				),
 			);
 
-			console.log(chalk.cyan("Learn more:"));
-			console.log(chalk.white(`  📖 Docs: https://github.com/Bobnoddle/quark`));
 			console.log(
-				chalk.white(`  💬 Issues: https://github.com/Bobnoddle/quark/issues\n`),
+				chalk.dim(
+					`  📖 github.com/Bobnoddle/quark  •  Updates: npx @techstream/quark-create-app update\n`,
+				),
 			);
 		} catch (error) {
 			console.error(chalk.red(`\n✗ Error creating project: ${error.message}`));
@@ -857,13 +1026,55 @@ STORAGE_PROVIDER=local
 		}
 	});
 
+/**
+ * Read the installed version of a package from node_modules.
+ * Returns null if the package is not installed.
+ * @param {string} cwd - Project root
+ * @param {string} packageName - e.g. "@techstream/quark-core"
+ * @returns {Promise<string|null>}
+ */
+async function getInstalledVersion(cwd, packageName) {
+	try {
+		const pkgPath = path.join(
+			cwd,
+			"node_modules",
+			...packageName.split("/"),
+			"package.json",
+		);
+		const { version } = await fs.readJSON(pkgPath);
+		return version ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Fetch the latest published version of a package from the npm registry.
+ * Returns null on network failure so the caller can degrade gracefully.
+ * @param {string} packageName
+ * @returns {Promise<string|null>}
+ */
+async function getLatestNpmVersion(packageName) {
+	try {
+		const { stdout } = await execa("npm", [
+			"view",
+			packageName,
+			"version",
+			"--json",
+		]);
+		return JSON.parse(stdout);
+	} catch {
+		return null;
+	}
+}
+
 /**
  * quark-update command
  * Updates Quark core infrastructure in a scaffolded project
  */
 program
 	.command("update")
-	.description("Update Quark core infrastructure in the current project")
+	.description("Update Quark packages in the current project")
 	.option("--check", "Check for updates without applying")
 	.option("--force", "Skip safety checks")
 	.action(async (options) => {
@@ -879,23 +1090,60 @@ program
 		}
 
 		const quarkLink = await fs.readJSON(quarkLinkPath);
-		console.log(chalk.cyan(`Current Quark version: ${quarkLink.quarkVersion}`));
-		console.log(chalk.cyan(`Scaffolded: ${quarkLink.scaffoldedDate}\n`));
+
+		// The packages this command manages
+		const MANAGED_PACKAGES = [
+			"@techstream/quark-core",
+			"@techstream/quark-create-app",
+		];
+
+		// Snapshot installed versions before any update
+		const before = {};
+		for (const name of MANAGED_PACKAGES) {
+			before[name] = await getInstalledVersion(process.cwd(), name);
+		}
+
+		console.log(chalk.cyan(`Scaffolded:      ${quarkLink.scaffoldedDate}`));
+		console.log(
+			chalk.cyan(
+				`Installed core:  ${before["@techstream/quark-core"] ?? quarkLink.quarkVersion ?? "unknown"}\n`,
+			),
+		);
 
 		if (options.check) {
-			console.log(chalk.yellow("Checking for updates..."));
-			console.log(
-				chalk.white("Run 'pnpm update @techstream/quark-*' to apply updates."),
-			);
+			// Query npm for latest versions and report the delta
+			console.log(chalk.yellow("Checking npm registry for updates...\n"));
+			let anyUpdates = false;
+			for (const name of MANAGED_PACKAGES) {
+				const installed = before[name];
+				const latest = await getLatestNpmVersion(name);
+				if (!latest) {
+					console.log(chalk.dim(`  ${name}: registry unreachable`));
+					continue;
+				}
+				if (!installed || installed === latest) {
+					console.log(chalk.green(`  ✓ ${name} ${latest} — up to date`));
+				} else {
+					console.log(
+						chalk.yellow(`  ↑ ${name}: ${installed} → ${chalk.bold(latest)}`),
+					);
+					anyUpdates = true;
+				}
+			}
+			if (anyUpdates) {
+				console.log(chalk.white("\n  Run without --check to apply updates.\n"));
+			} else {
+				console.log(chalk.dim("\n  Nothing to update.\n"));
+			}
 			return;
 		}
 
 		try {
-			// Warn if git has uncommitted changes
+			// Guard: check for both unstaged and staged changes
 			if (!options.force) {
-				console.log(chalk.yellow("⚠️  Checking for uncommitted changes..."));
 				try {
-					await execa("git", ["diff", "--exit-code"], {
+					await execa("git", ["diff", "--exit-code"], { cwd: process.cwd() });
+					await execa("git", ["diff", "--cached", "--exit-code"], {
 						cwd: process.cwd(),
 					});
 				} catch {
@@ -911,43 +1159,60 @@ program
 				}
 			}
 
-			// Run pnpm update
-			console.log(chalk.cyan("\n📦 Updating Quark core infrastructure...\n"));
-			await execa("pnpm", ["update", "@techstream/quark-core"], {
+			// Run pnpm update for all managed packages
+			console.log(chalk.cyan("📦 Updating Quark packages...\n"));
+			await execa("pnpm", ["update", ...MANAGED_PACKAGES], {
 				cwd: process.cwd(),
 				stdio: "inherit",
 			});
 
-			// Update .quark-link.json
-			let updatedVersion = "updated";
+			// Snapshot installed versions after update
+			const after = {};
+			for (const name of MANAGED_PACKAGES) {
+				after[name] = await getInstalledVersion(process.cwd(), name);
+			}
+
+			// Report the delta
+			console.log(chalk.cyan("\n📋 Update summary:\n"));
+			for (const name of MANAGED_PACKAGES) {
+				const was = before[name];
+				const now = after[name];
+				if (!now) continue;
+				if (was && was !== now) {
+					console.log(chalk.green(`  ✓ ${name}: ${was} → ${chalk.bold(now)}`));
+				} else {
+					console.log(chalk.dim(`  · ${name}: ${now} (already current)`));
+				}
+			}
+
+			// Persist the new core version — keep previous on failure, never write garbage
+			const newCoreVersion =
+				after["@techstream/quark-core"] ?? quarkLink.quarkVersion;
+			quarkLink.quarkVersion = newCoreVersion;
+			quarkLink.updatedDate = new Date().toISOString();
+			await fs.writeFile(quarkLinkPath, JSON.stringify(quarkLink, null, 2));
+
+			// Run lint to surface any API breakage from the update
+			console.log(chalk.cyan("\n🔍 Running lint to check for breakage...\n"));
 			try {
-				const corePkg = await fs.readJSON(
-					path.join(
-						process.cwd(),
-						"node_modules",
-						"@techstream",
-						"quark-core",
-						"package.json",
+				await execa("pnpm", ["lint"], {
+					cwd: process.cwd(),
+					stdio: "inherit",
+				});
+				console.log(chalk.green("\n  ✓ Lint passed\n"));
+			} catch {
+				console.log(
+					chalk.yellow(
+						"\n  ⚠️  Lint reported issues — review before committing.\n",
 					),
 				);
-				updatedVersion = corePkg.version;
-			} catch {}
-			quarkLink.quarkVersion = updatedVersion;
-			quarkLink.updatedDate = new Date().toISOString();
-			await fs.writeFile(quarkLinkPath, JSON.stringify(quarkLink, null, 2));
+			}
 
-			console.log(
-				chalk.green("\n✅ Quark core infrastructure updated successfully!\n"),
-			);
-			console.log(
-				chalk.cyan("Note: This updates @techstream/quark-core only.\n"),
-			);
+			console.log(chalk.green("✅ Quark updated successfully!\n"));
 			console.log(chalk.cyan("Next steps:"));
-			console.log(chalk.white(`  1. pnpm install (if prompted)`));
-			console.log(chalk.white(`  2. pnpm lint`));
-			console.log(chalk.white(`  3. pnpm test`));
+			console.log(chalk.white(`  1. pnpm test`));
 			console.log(
-				chalk.white(`  4. git add . && git commit -m "chore: update Quark"\n`),
+				chalk.white(`  2. git add . && git commit -m "chore: update Quark"\n`),
 			);
 		} catch (error) {
 			console.error(chalk.red(`\n✗ Update failed: ${error.message}\n`));