create-questpie 2.0.3 → 2.1.0

package/dist/index.mjs

@@ -1,19 +1,111 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { Command } from "commander";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { execFileSync, execSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { execFileSync, execSync, spawn } from "node:child_process";
+import { cp, readFile, readdir, rename, writeFile } from "node:fs/promises";
+
+//#region src/modules.ts
+/** Runtimes that ship a render layer (admin UI can mount). */
+const RENDER_RUNTIMES = ["tanstack-start", "next"];
+/**
+* The three already-wired modules. Import paths + symbols are copied verbatim
+* from the proven scaffolder emission (`buildServerModules` / `buildAdminModules`)
+* and the tanstack-start template's `server/modules.ts` + `admin/modules.ts`.
+*/
+const modules = [
+	{
+		id: "admin",
+		label: "Admin",
+		hint: "admin UI panel",
+		group: "Core",
+		defaultFor: ["tanstack-start", "next"],
+		requiresRender: true,
+		deps: { "@questpie/admin": "latest" },
+		serverImport: "@questpie/admin/modules/admin",
+		serverSymbol: "adminModule",
+		clientImport: "@questpie/admin/client/modules/admin",
+		clientSymbol: "adminClientModule"
+	},
+	{
+		id: "openapi",
+		label: "OpenAPI",
+		hint: "REST + Scalar docs at /api/docs",
+		group: "Core",
+		defaultFor: [
+			"tanstack-start",
+			"next",
+			"hono",
+			"elysia"
+		],
+		deps: { "@questpie/openapi": "latest" },
+		serverImport: "@questpie/openapi",
+		serverSymbol: "openApiModule"
+	},
+	{
+		id: "workflows",
+		label: "Workflows",
+		hint: "durable workflow engine",
+		group: "Optional",
+		deps: { "@questpie/workflows": "latest" },
+		serverImport: "@questpie/workflows/modules/workflows",
+		serverSymbol: "workflowsModule",
+		clientImport: "@questpie/workflows/client/modules/workflows",
+		clientSymbol: "workflowsClientModule"
+	}
+];
+function getModule(id) {
+	return modules.find((m) => m.id === id);
+}
+/** Default module ids for a runtime posture (drives prompt pre-selection). */
+function defaultModuleIds(runtime) {
+	return modules.filter((m) => m.defaultFor?.includes(runtime)).map((m) => m.id);
+}
+/**
+* Compatibility oracle — single source of truth for "can this module run on
+* this runtime?". Reused by the prompt filter AND flag validation so there is
+* zero rule duplication. Pure, no side effects.
+*
+* Rule (v1): a `requiresRender` module (admin) needs a render-layer runtime
+* (tanstack-start | next). Headless runtimes (hono | elysia) reject it.
+*/
+function isModuleAllowed(moduleId, runtimeId) {
+	const mod = getModule(moduleId);
+	if (!mod) return false;
+	if (mod.requiresRender) return RENDER_RUNTIMES.includes(runtimeId);
+	return true;
+}
 
+//#endregion
 //#region src/templates.ts
-const templates = [{
-	id: "tanstack-start",
-	label: "TanStack Start",
-	hint: "recommended",
-	description: "Full-stack React with TanStack Start, Vite, Tailwind CSS, and Nitro server"
-}];
+const templates = [
+	{
+		id: "tanstack-start",
+		label: "TanStack Start",
+		hint: "recommended",
+		description: "Full-stack React with TanStack Start, Vite, Tailwind CSS, and Nitro server"
+	},
+	{
+		id: "hono",
+		label: "Hono",
+		hint: "headless api",
+		description: "Headless REST API with Hono on Bun, OpenAPI/Scalar docs, and a typed client (no admin UI)"
+	},
+	{
+		id: "elysia",
+		label: "Elysia",
+		hint: "headless api",
+		description: "Headless REST API with Elysia on Bun, OpenAPI/Scalar docs, and a typed client (no admin UI)"
+	},
+	{
+		id: "next",
+		label: "Next.js",
+		hint: "fullstack",
+		description: "Full-stack React with Next.js App Router (Turbopack), admin UI, OpenAPI/Scalar docs, and a typed client"
+	}
+];
 function getTemplate(id) {
 	return templates.find((t) => t.id === id);
 }
@@ -86,19 +178,81 @@ const label = {
 
 //#endregion
 //#region src/prompts.ts
+const queueAdapters = [
+	"pg-boss",
+	"bullmq",
+	"none"
+];
+const emailAdapters = [
+	"console",
+	"smtp",
+	"resend",
+	"plunk"
+];
+const realtimeAdapters = [
+	"none",
+	"pg-notify",
+	"redis-streams"
+];
+const kvAdapters = ["memory", "redis"];
+function assertChoice(name, value, choices) {
+	if (value === void 0) return void 0;
+	if (choices.includes(value)) return value;
+	throw new Error(`Invalid ${name}: ${value}. Expected one of: ${choices.join(", ")}.`);
+}
+function withOptionDefaults(options) {
+	return {
+		...options,
+		queueAdapter: options.queueAdapter ?? "pg-boss",
+		emailAdapter: options.emailAdapter ?? "console",
+		realtimeAdapter: options.realtimeAdapter ?? "none",
+		kvAdapter: options.kvAdapter ?? "memory"
+	};
+}
+/**
+* Resolve the module ids for a non-interactive run (flags / --yes). Explicit
+* `--module(s)` win; otherwise fall back to the runtime defaults. Every id is
+* validated through the same `isModuleAllowed` oracle the prompt filter uses,
+* so a flag combo cannot bypass the compatibility rule.
+*/
+function resolveModuleIds(runtime, requested) {
+	const allowed = modules.filter((m) => isModuleAllowed(m.id, runtime));
+	const allowedIds = new Set(allowed.map((m) => m.id));
+	if (requested && requested.length > 0) {
+		for (const id of requested) if (!allowedIds.has(id)) {
+			const known = modules.some((m) => m.id === id);
+			throw new Error(known ? `Module "${id}" is not available for runtime "${runtime}".` : `Unknown module: ${id}. Expected one of: ${modules.map((m) => m.id).join(", ")}.`);
+		}
+		const wanted = new Set(requested);
+		return allowed.filter((m) => wanted.has(m.id)).map((m) => m.id);
+	}
+	return defaultModuleIds(runtime).filter((id) => allowedIds.has(id));
+}
 async function runPrompts(args) {
-	if (!Boolean(process.stdin.isTTY && process.stdout.isTTY)) {
+	const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !args.fillDefaults;
+	const queueAdapter = assertChoice("queue adapter", args.queueAdapter, queueAdapters);
+	const emailAdapter = assertChoice("email adapter", args.emailAdapter, emailAdapters);
+	const realtimeAdapter = assertChoice("realtime adapter", args.realtimeAdapter, realtimeAdapters);
+	const kvAdapter = assertChoice("KV adapter", args.kvAdapter, kvAdapters);
+	if (!isInteractive) {
 		if (!args.projectName) throw new Error("Project name is required in non-interactive mode.");
 		if (!isValidPackageName(args.projectName)) throw new Error("Invalid package name (use lowercase, hyphens, no spaces).");
-		return {
+		const templateId = args.templateId ?? templates[0].id;
+		return withOptionDefaults({
 			projectName: args.projectName,
-			templateId: args.templateId ?? templates[0].id,
+			templateId,
 			databaseName: args.databaseName ?? toDbName(args.projectName),
+			modules: args.modules ?? resolveModuleIds(templateId, args.requestedModules),
 			installDeps: args.installDeps ?? true,
 			initGit: args.initGit ?? true,
 			installSkills: args.installSkills ?? true,
-			runCodegen: args.runCodegen ?? true
-		};
+			runCodegen: args.runCodegen ?? true,
+			continueOnError: args.continueOnError ?? false,
+			queueAdapter,
+			emailAdapter,
+			realtimeAdapter,
+			kvAdapter
+		});
 	}
 	p.intro(pc.bgCyan(pc.black(" QUESTPIE — Create a new project ")));
 	const questions = await p.group({
@@ -120,7 +274,7 @@ async function runPrompts(args) {
 			if (args.templateId) return Promise.resolve(args.templateId);
 			if (templates.length === 1) return Promise.resolve(templates[0].id);
 			return p.select({
-				message: "Select a template",
+				message: "Runtime",
 				options: templates.map((t) => ({
 					value: t.id,
 					label: t.label,
@@ -128,6 +282,23 @@ async function runPrompts(args) {
 				}))
 			});
 		},
+		modules: ({ results }) => {
+			const runtime = results.templateId;
+			if (args.modules) return Promise.resolve(args.modules);
+			if (args.requestedModules) return Promise.resolve(resolveModuleIds(runtime, args.requestedModules));
+			const available = modules.filter((m) => isModuleAllowed(m.id, runtime));
+			const defaults = new Set(defaultModuleIds(runtime));
+			return p.multiselect({
+				message: "Modules",
+				required: false,
+				initialValues: available.filter((m) => defaults.has(m.id)).map((m) => m.id),
+				options: available.map((m) => ({
+					value: m.id,
+					label: m.group ? `${m.group} · ${m.label}` : m.label,
+					hint: m.hint
+				}))
+			});
+		},
 		databaseName: ({ results }) => {
 			if (args.databaseName) return Promise.resolve(args.databaseName);
 			const defaultDb = toDbName(results.projectName);
@@ -170,21 +341,147 @@ async function runPrompts(args) {
 		p.cancel("Operation cancelled.");
 		process.exit(0);
 	} });
-	return {
+	return withOptionDefaults({
 		projectName: questions.projectName,
 		templateId: questions.templateId,
 		databaseName: questions.databaseName,
+		modules: questions.modules,
 		installDeps: questions.installDeps,
 		initGit: questions.initGit,
 		installSkills: questions.installSkills,
-		runCodegen: questions.runCodegen
-	};
+		runCodegen: questions.runCodegen,
+		continueOnError: args.continueOnError ?? false,
+		queueAdapter,
+		emailAdapter,
+		realtimeAdapter,
+		kvAdapter
+	});
 }
 
 //#endregion
 //#region src/scaffolder.ts
 const TEMPLATE_VAR_REGEX = /\{\{(\w+)\}\}/g;
 /**
+* Central pinned dependency versions. One place to bump every package the
+* scaffolder can add. Module deps reference these keys too — `depVersion`
+* resolves a package name to its pinned version (falling back to the version
+* declared on the module entry, then "latest").
+*/
+const dependencyVersionMap = {
+	"@questpie/admin": "latest",
+	"@questpie/openapi": "latest",
+	"@questpie/workflows": "latest",
+	bullmq: "^5.0.0",
+	redis: "^5.0.0"
+};
+function depVersion(name, fallback = "latest") {
+	return dependencyVersionMap[name] ?? fallback;
+}
+/** Stable de-duplication preserving first-seen order. */
+function dedupe(lines) {
+	return Array.from(new Set(lines));
+}
+const REDIS_URL_ENV = `\t\tREDIS_URL: z.string().url().default("redis://localhost:6379"),`;
+const features = {
+	queue: {
+		"pg-boss": {
+			configImports: [`import { pgBossAdapter } from "questpie/adapters/pg-boss";`],
+			configEntry: () => [
+				`\tqueue: {`,
+				`\t\tadapter: pgBossAdapter({ connectionString: env.DATABASE_URL }),`,
+				`\t},`
+			]
+		},
+		bullmq: {
+			deps: {
+				bullmq: depVersion("bullmq"),
+				redis: depVersion("redis")
+			},
+			envVars: [REDIS_URL_ENV],
+			configImports: [`import { bullMQAdapter } from "questpie/adapters/bullmq";`],
+			configEntry: () => [
+				`\tqueue: {`,
+				`\t\tadapter: bullMQAdapter({ connection: { url: env.REDIS_URL } }),`,
+				`\t},`
+			]
+		},
+		none: {}
+	},
+	realtime: {
+		none: {},
+		"pg-notify": {
+			configImports: [`import { pgNotifyAdapter } from "questpie/adapters/pg-notify";`],
+			configEntry: () => [
+				`\trealtime: {`,
+				`\t\tadapter: pgNotifyAdapter({ connectionString: env.DATABASE_URL }),`,
+				`\t},`
+			]
+		},
+		"redis-streams": {
+			deps: { redis: depVersion("redis") },
+			envVars: [REDIS_URL_ENV],
+			configImports: [`import { redisStreamsAdapter } from "questpie/adapters/redis-streams";`],
+			configEntry: () => [
+				`\trealtime: {`,
+				`\t\tadapter: redisStreamsAdapter({ url: env.REDIS_URL }),`,
+				`\t},`
+			]
+		}
+	},
+	kv: {
+		memory: {},
+		redis: {
+			deps: { redis: depVersion("redis") },
+			envVars: [REDIS_URL_ENV],
+			configImports: [`import { redisKVAdapter } from "questpie/adapters/redis-kv";`, `import { createClient } from "redis";`],
+			configHelper: [
+				`async function getRedis() {`,
+				`\tconst redis = createClient({ url: env.REDIS_URL });`,
+				`\tawait redis.connect();`,
+				`\treturn redis;`,
+				`}`,
+				``
+			],
+			configEntry: (options) => [
+				`\tkv: {`,
+				`\t\tadapter: redisKVAdapter({ client: getRedis, keyPrefix: "${options.projectName}:" }),`,
+				`\t},`
+			]
+		}
+	}
+};
+/** The adapter selection for each feature axis, with the same defaults the generators assume. */
+function selectedFeatureOptions(options) {
+	return [
+		{
+			axis: "queue",
+			option: options.queueAdapter ?? "pg-boss"
+		},
+		{
+			axis: "realtime",
+			option: options.realtimeAdapter ?? "none"
+		},
+		{
+			axis: "kv",
+			option: options.kvAdapter ?? "memory"
+		}
+	];
+}
+/** Resolve the selected feature descriptors (skips unknown/missing entries). */
+function selectedFeatures(options) {
+	return selectedFeatureOptions(options).map(({ axis, option }) => features[axis]?.[option]).filter((f) => Boolean(f));
+}
+/**
+* The modules selected for this project. The selection is resolved upstream
+* (prompts / flags, validated through the `isModuleAllowed` oracle) and threaded
+* through `options.modules`; here we just project it onto registry entries,
+* preserving registry order.
+*/
+function selectedModules(options) {
+	const ids = new Set(options.modules);
+	return modules.filter((m) => ids.has(m.id));
+}
+/**
 * Resolves the path to the templates directory.
 * Works both in dev (src/) and built (dist/) contexts.
 */
@@ -247,63 +544,199 @@ async function createLocalEnv(targetDir) {
 	const envPath = join(targetDir, ".env");
 	if (existsSync(examplePath) && !existsSync(envPath)) await cp(examplePath, envPath);
 }
-function getSkillSources(targetDir) {
-	return [{
-		name: "questpie",
-		candidates: [
-			resolve(import.meta.dirname, "..", "skills", "questpie"),
-			join(targetDir, "node_modules", "questpie", "skills", "questpie"),
-			resolve(import.meta.dirname, "..", "..", "questpie", "skills", "questpie"),
-			resolve(import.meta.dirname, "..", "..", "..", "skills", "questpie")
-		]
-	}, {
-		name: "questpie-admin",
-		candidates: [
-			resolve(import.meta.dirname, "..", "skills", "questpie-admin"),
-			join(targetDir, "node_modules", "@questpie", "admin", "skills", "questpie-admin"),
-			resolve(import.meta.dirname, "..", "..", "admin", "skills", "questpie-admin"),
-			resolve(import.meta.dirname, "..", "..", "..", "skills", "questpie-admin")
-		]
-	}];
-}
-async function installProjectSkills(targetDir) {
-	const installed = [];
-	const skillsDir = join(targetDir, ".agents", "skills");
-	for (const skill of getSkillSources(targetDir)) {
-		const source = skill.candidates.find((candidate) => existsSync(candidate));
-		if (!source) continue;
-		const destination = join(skillsDir, skill.name);
-		await mkdir(skillsDir, { recursive: true });
-		await rm(destination, {
-			recursive: true,
-			force: true
-		});
-		await cp(source, destination, {
-			recursive: true,
-			dereference: true
+function handleFatalStepFailure(message, error, continueOnError) {
+	if (continueOnError) return;
+	const cause = error instanceof Error ? error.message : typeof error === "string" ? error : String(error);
+	throw new Error(`${message}: ${cause}`);
+}
+async function applyProjectOptions(targetDir, options) {
+	await updatePackageJson(targetDir, options);
+	await writeFile(join(targetDir, "src", "lib", "env.ts"), buildEnvFile(options), "utf-8");
+	await writeFile(join(targetDir, "src", "questpie", "server", "questpie.config.ts"), buildRuntimeConfig(options), "utf-8");
+	await writeFile(join(targetDir, "src", "questpie", "server", "modules.ts"), buildServerModules(options), "utf-8");
+	const adminDir = join(targetDir, "src", "questpie", "admin");
+	if (options.modules.includes("admin") && existsSync(adminDir)) await writeFile(join(adminDir, "modules.ts"), buildAdminModules(options), "utf-8");
+}
+async function updatePackageJson(targetDir, options) {
+	const packageJsonPath = join(targetDir, "package.json");
+	const packageJson = JSON.parse(await readFile(packageJsonPath, "utf-8"));
+	for (const mod of selectedModules(options)) for (const [name, version] of Object.entries(mod.deps)) packageJson.dependencies[name] = depVersion(name, version);
+	for (const feature of selectedFeatures(options)) for (const [name, version] of Object.entries(feature.deps ?? {})) packageJson.dependencies[name] = version;
+	await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, "	")}\n`);
+}
+function buildEnvFile(options) {
+	const mailAdapters = Array.from(new Set(["console", options.emailAdapter ?? "console"]));
+	const lines = [
+		`import { createEnv } from "@t3-oss/env-core";`,
+		`import { z } from "zod";`,
+		``,
+		`export const env = createEnv({`,
+		`\tserver: {`,
+		`\t\tDATABASE_URL: z.string().url(),`,
+		`\t\tAPP_URL: z.string().url().default("http://localhost:3000"),`,
+		`\t\tPORT: z`,
+		`\t\t\t.string()`,
+		`\t\t\t.transform(Number)`,
+		`\t\t\t.pipe(z.number().int().positive())`,
+		`\t\t\t.default(3000),`,
+		`\t\tBETTER_AUTH_SECRET: z.string().min(1).default("change-me-in-production"),`,
+		`\t\tMAIL_ADAPTER: z.enum(${JSON.stringify(mailAdapters)}).default("console"),`
+	];
+	if (options.emailAdapter === "smtp") lines.push(`\t\tSMTP_HOST: z.string().optional(),`, `\t\tSMTP_PORT: z`, `\t\t\t.string()`, `\t\t\t.transform(Number)`, `\t\t\t.pipe(z.number().int().positive())`, `\t\t\t.optional(),`);
+	if (options.emailAdapter === "resend") lines.push(`\t\tRESEND_API_KEY: z.string().optional(),`);
+	if (options.emailAdapter === "plunk") lines.push(`\t\tPLUNK_SECRET_KEY: z.string().optional(),`);
+	for (const line of dedupe(selectedFeatures(options).flatMap((f) => f.envVars ?? []))) lines.push(line);
+	lines.push(`\t},`, `\truntimeEnv: process.env,`, `\temptyStringAsUndefined: true,`, `});`, ``);
+	return lines.join("\n");
+}
+function buildRuntimeConfig(options) {
+	const queueImports = features.queue?.[options.queueAdapter ?? "pg-boss"]?.configImports ?? [];
+	const realtimeImports = features.realtime?.[options.realtimeAdapter ?? "none"]?.configImports ?? [];
+	const kvImports = features.kv?.[options.kvAdapter ?? "memory"]?.configImports ?? [];
+	const imports = [
+		`import { runtimeConfig } from "questpie/app";`,
+		`import { ConsoleAdapter } from "questpie/adapters/console";`,
+		...dedupe([
+			...queueImports,
+			...buildEmailConfigImports(options),
+			...realtimeImports,
+			...kvImports
+		])
+	];
+	imports.push(``, `import { env } from "@/lib/env.js";`, ``);
+	const kvHelper = features.kv?.[options.kvAdapter ?? "memory"]?.configHelper;
+	const helpers = [...buildEmailConfigHelper(options), ...kvHelper ?? []];
+	const configEntries = [
+		`\tapp: { url: env.APP_URL },`,
+		`\tdb: { url: env.DATABASE_URL },`,
+		`\tstorage: { basePath: "/api" },`,
+		`\temail: {`,
+		`\t\tadapter: ${buildEmailAdapterExpression(options)},`,
+		`\t},`
+	];
+	for (const { axis, option } of selectedFeatureOptions(options)) {
+		const entry = features[axis]?.[option]?.configEntry;
+		if (entry) configEntries.push(...entry(options));
+	}
+	return [
+		`/**`,
+		` * QUESTPIE Runtime Configuration`,
+		` *`,
+		` * Runtime-only configuration: database, adapters, secrets.`,
+		` * Entity definitions are codegen-generated.`,
+		` */`,
+		``,
+		...imports,
+		...helpers,
+		`export default runtimeConfig({`,
+		...configEntries,
+		`});`,
+		``
+	].join("\n");
+}
+function buildEmailAdapterExpression(options) {
+	if (options.emailAdapter === "smtp") return `env.MAIL_ADAPTER === "smtp"\n\t\t\t? new SmtpAdapter({\n\t\t\t\t\ttransport: {\n\t\t\t\t\t\thost: env.SMTP_HOST || "localhost",\n\t\t\t\t\t\tport: env.SMTP_PORT || 1025,\n\t\t\t\t\t\tsecure: false,\n\t\t\t\t\t},\n\t\t\t\t})\n\t\t\t: new ConsoleAdapter({ logHtml: false })`;
+	if (options.emailAdapter === "resend") return `env.MAIL_ADAPTER === "resend"\n\t\t\t? new ResendAdapter({ apiKey: requiredEnv(env.RESEND_API_KEY, "RESEND_API_KEY") })\n\t\t\t: new ConsoleAdapter({ logHtml: false })`;
+	if (options.emailAdapter === "plunk") return `env.MAIL_ADAPTER === "plunk"\n\t\t\t? new PlunkAdapter({ apiKey: requiredEnv(env.PLUNK_SECRET_KEY, "PLUNK_SECRET_KEY") })\n\t\t\t: new ConsoleAdapter({ logHtml: false })`;
+	return `new ConsoleAdapter({ logHtml: false })`;
+}
+/** Email adapter import lines for `questpie.config.ts` (ConsoleAdapter is always imported separately). */
+function buildEmailConfigImports(options) {
+	if (options.emailAdapter === "smtp") return [`import { SmtpAdapter } from "questpie/adapters/smtp";`];
+	if (options.emailAdapter === "resend") return [`import { ResendAdapter } from "questpie/adapters/resend";`];
+	if (options.emailAdapter === "plunk") return [`import { PlunkAdapter } from "questpie/adapters/plunk";`];
+	return [];
+}
+/** Email helper block (`requiredEnv`) for adapters that read required secrets. */
+function buildEmailConfigHelper(options) {
+	if (options.emailAdapter === "resend" || options.emailAdapter === "plunk") return [
+		`function requiredEnv(value: string | undefined, name: string): string {`,
+		`\tif (!value) throw new Error(\`Missing required environment variable: \${name}\`);`,
+		`\treturn value;`,
+		`}`,
+		``
+	];
+	return [];
+}
+function buildServerModules(options) {
+	const selected = selectedModules(options);
+	return [
+		...[
+			`/**`,
+			` * Modules — static module dependencies for this project.`,
+			` */`,
+			...selected.map((mod) => `import { ${mod.serverSymbol} } from "${mod.serverImport}";`)
+		],
+		``,
+		`const modules = [`,
+		...selected.map((mod) => `\t${mod.serverSymbol},`),
+		`] as const;`,
+		``,
+		`export default modules;`,
+		``
+	].join("\n");
+}
+function buildAdminModules(options) {
+	const clientModules = selectedModules(options).filter((mod) => mod.clientImport && mod.clientSymbol);
+	const imports = clientModules.map((mod) => `import { ${mod.clientSymbol} } from "${mod.clientImport}";`);
+	const symbols = clientModules.map((mod) => mod.clientSymbol);
+	return [
+		...imports,
+		``,
+		`export default [${symbols.join(", ")}] as const;`,
+		``
+	].join("\n");
+}
+/**
+* Spawn `bunx skills add questpie/questpie` detached in the target project so
+* the scaffold can complete without blocking on the (network-bound) install.
+* Returns false when the process can't even be spawned (no `bunx` on PATH etc.)
+* so the caller can fall back to printing the manual command.
+*/
+function startSkillsInstall(targetDir) {
+	try {
+		const child = spawn("bunx", [
+			"skills",
+			"add",
+			"questpie/questpie"
+		], {
+			cwd: targetDir,
+			detached: true,
+			stdio: "ignore"
 		});
-		installed.push(skill.name);
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
 	}
-	return installed;
 }
 async function scaffold(options) {
+	const resolvedOptions = {
+		...options,
+		queueAdapter: options.queueAdapter ?? "pg-boss",
+		emailAdapter: options.emailAdapter ?? "console",
+		realtimeAdapter: options.realtimeAdapter ?? "none",
+		kvAdapter: options.kvAdapter ?? "memory"
+	};
 	const spinner = p.spinner();
-	const targetDir = resolve(process.cwd(), options.projectName);
+	const targetDir = resolve(process.cwd(), resolvedOptions.projectName);
+	const continueOnError = resolvedOptions.continueOnError === true;
 	if (existsSync(targetDir)) {
-		p.log.error(`Directory ${options.projectName} already exists.`);
+		p.log.error(`Directory ${resolvedOptions.projectName} already exists.`);
 		process.exit(1);
 	}
 	const vars = {
-		projectName: options.projectName,
-		databaseName: options.databaseName,
-		databaseUser: options.databaseName,
+		projectName: resolvedOptions.projectName,
+		databaseName: resolvedOptions.databaseName,
+		databaseUser: resolvedOptions.databaseName,
 		databasePassword: generatePassword(),
 		authSecret: generatePassword(48)
 	};
 	spinner.start("Copying template files");
-	const templateDir = join(getTemplatesDir(), options.templateId);
+	const templateDir = join(getTemplatesDir(), resolvedOptions.templateId);
 	if (!existsSync(templateDir)) {
-		spinner.stop(label.error(`Template "${options.templateId}" not found`));
+		spinner.stop(label.error(`Template "${resolvedOptions.templateId}" not found`));
 		process.exit(1);
 	}
 	await cp(templateDir, targetDir, { recursive: true });
@@ -313,37 +746,32 @@ async function scaffold(options) {
 	await renameEnvExample(targetDir);
 	await processDirectory(targetDir, vars);
 	await createLocalEnv(targetDir);
+	await applyProjectOptions(targetDir, resolvedOptions);
 	spinner.stop(label.success("Processed template variables"));
 	const pm = detectPackageManager();
-	if (options.installDeps) {
+	if (resolvedOptions.installDeps) {
 		spinner.start(`Installing dependencies with ${pm}`);
 		try {
 			installDependencies(targetDir, pm);
 			spinner.stop(label.success("Installed dependencies"));
-		} catch {
-			spinner.stop(label.warn("Failed to install dependencies — run manually"));
+		} catch (error) {
+			spinner.stop(label.warn("Failed to install dependencies"));
+			handleFatalStepFailure("Dependency installation failed", error, continueOnError);
 		}
 	}
-	if (options.installSkills) {
-		spinner.start("Installing QUESTPIE agent skills");
-		try {
-			const installedSkills = await installProjectSkills(targetDir);
-			if (installedSkills.length > 0) spinner.stop(label.success(`Installed skills: ${installedSkills.join(", ")}`));
-			else spinner.stop(label.warn("Could not find packaged skills — run `bunx skill add questpie/questpie` manually if available"));
-		} catch {
-			spinner.stop(label.warn("Failed to install skills — continuing"));
-		}
-	}
-	if (options.installDeps && options.runCodegen) {
+	if (resolvedOptions.installSkills) if (startSkillsInstall(targetDir)) p.log.info(label.info("Installing QUESTPIE agent skills in the background (`bunx skills add questpie/questpie`)"));
+	else p.log.warn(label.warn("Could not start skills install — run `bunx skills add questpie/questpie` in the project"));
+	if (resolvedOptions.installDeps && resolvedOptions.runCodegen) {
 		spinner.start("Generating QUESTPIE app");
 		try {
 			runPackageScript(targetDir, pm, "scaffold:generate");
 			spinner.stop(label.success("Generated QUESTPIE app"));
-		} catch {
-			spinner.stop(label.warn("Failed to run codegen — run manually"));
+		} catch (error) {
+			spinner.stop(label.warn("Failed to run codegen"));
+			handleFatalStepFailure("QUESTPIE codegen failed", error, continueOnError);
 		}
 	}
-	if (options.initGit && isGitInstalled()) {
+	if (resolvedOptions.initGit && isGitInstalled()) {
 		spinner.start("Initializing git repository");
 		try {
 			gitInit(targetDir);
@@ -355,7 +783,7 @@ async function scaffold(options) {
 	const runScript = (script) => pm === "npm" ? `npm run ${script}` : `${pm} run ${script}`;
 	const questpieBin = pm === "npm" ? "npx questpie" : "bunx questpie";
 	p.note([
-		`cd ${options.projectName}`,
+		`cd ${resolvedOptions.projectName}`,
 		"",
 		"# Review the generated environment",
 		"# .env has already been created from .env.example",
@@ -366,8 +794,8 @@ async function scaffold(options) {
 		"# Regenerate and type-check the scaffold",
 		runScript("scaffold:verify"),
 		"",
-		"# Run migrations",
-		runScript("migrate"),
+		"# Create local database tables",
+		runScript("db:push"),
 		"",
 		"# Start dev server",
 		runScript("dev"),
@@ -377,24 +805,53 @@ async function scaffold(options) {
 		`${questpieBin} add global marketing`,
 		"",
 		"# If you create files manually",
-		runScript("questpie:generate")
+		runScript("questpie:generate"),
+		"",
+		"# For production migrations",
+		runScript("migrate:create"),
+		runScript("migrate")
 	].join("\n"), "Next steps");
 	p.outro(`${label.success("Done!")} Happy building with QUESTPIE!`);
 }
 
 //#endregion
 //#region src/index.ts
-new Command().name("create-questpie").description("Create a new QUESTPIE project").version("2.0.1").argument("[project-name]", "Name of the project").option("-t, --template <name>", "Template to use (default: tanstack-start)").option("--database <name>", "Database name (default: derived from project name)").option("--no-install", "Skip dependency installation").option("--no-git", "Skip git initialization").option("--no-skills", "Skip installing project-local QUESTPIE agent skills").option("--no-generate", "Skip running QUESTPIE codegen after install").action(async (projectName, opts) => {
+/** Collect a repeatable `--module <name>` flag into an array. */
+function collectModule(value, previous) {
+	return [...previous, value];
+}
+function readPackageVersion() {
+	for (const candidate of [resolve(import.meta.dirname, "..", "package.json"), resolve(import.meta.dirname, "..", "..", "package.json")]) {
+		if (!existsSync(candidate)) continue;
+		const packageJson = JSON.parse(readFileSync(candidate, "utf-8"));
+		if (packageJson.version) return packageJson.version;
+	}
+	return "0.0.0";
+}
+new Command().name("create-questpie").description("Create a new QUESTPIE project").version(readPackageVersion()).argument("[project-name]", "Name of the project").option("-t, --template <name>", "Template to use (default: tanstack-start)").option("--runtime <id>", "Runtime to use (alias of --template)").option("--module <name>", "Module to enable (repeatable, e.g. --module admin --module openapi)", collectModule, []).option("--modules <a,b,c>", "Comma-separated modules to enable (e.g. --modules admin,openapi)").option("-y, --yes", "Skip prompts and accept all defaults").option("--database <name>", "Database name (default: derived from project name)").option("--no-install", "Skip dependency installation").option("--no-git", "Skip git initialization").option("--no-skills", "Skip installing project-local QUESTPIE agent skills").option("--no-generate", "Skip running QUESTPIE codegen after install").option("--queue <adapter>", "Queue adapter: pg-boss, bullmq, none (default: pg-boss)").option("--email <adapter>", "Email adapters to scaffold: console, smtp, resend, plunk (default: console)").option("--realtime <adapter>", "Realtime adapter: none, pg-notify, redis-streams (default: none)").option("--kv <adapter>", "KV adapter: memory, redis (default: memory)").option("--continue-on-error", "Keep scaffold files when dependency install or codegen fails").action(async (projectName, opts) => {
 	try {
-		if (opts.template && !getTemplate(opts.template)) throw new Error(`Unknown template: ${opts.template}`);
+		const templateId = opts.template ?? opts.runtime;
+		if (templateId && !getTemplate(templateId)) throw new Error(`Unknown ${opts.runtime ? "runtime" : "template"}: ${templateId}`);
+		const requestedModules = [...opts.module ?? [], ...typeof opts.modules === "string" ? opts.modules.split(",").map((m) => m.trim()).filter(Boolean) : []];
+		if (requestedModules.length > 0 && templateId) for (const id of requestedModules) {
+			if (!modules.some((m) => m.id === id)) throw new Error(`Unknown module: ${id}. Available: ${modules.map((m) => m.id).join(", ")}.`);
+			if (!isModuleAllowed(id, templateId)) throw new Error(`Module "${id}" is not available for runtime "${templateId}".`);
+		}
 		await scaffold(await runPrompts({
 			projectName,
-			templateId: opts.template,
+			templateId,
 			databaseName: opts.database,
+			requestedModules: requestedModules.length > 0 ? requestedModules : void 0,
+			fillDefaults: opts.yes === true,
 			installDeps: opts.install === false ? false : void 0,
 			initGit: opts.git === false ? false : void 0,
 			installSkills: opts.skills === false ? false : void 0,
-			runCodegen: opts.generate === false ? false : void 0
+			runCodegen: opts.generate === false ? false : void 0,
+			continueOnError: opts.continueOnError === true,
+			queueAdapter: opts.queue,
+			emailAdapter: opts.email,
+			realtimeAdapter: opts.realtime,
+			kvAdapter: opts.kv
 		}));
 	} catch (error) {
 		console.error(error instanceof Error ? error.message : String(error));