create-questpie 2.0.4 → 2.1.0

package/dist/index.mjs

@@ -4,16 +4,108 @@ 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 { cp, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+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);
 }
@@ -114,12 +206,30 @@ function withOptionDefaults(options) {
 		queueAdapter: options.queueAdapter ?? "pg-boss",
 		emailAdapter: options.emailAdapter ?? "console",
 		realtimeAdapter: options.realtimeAdapter ?? "none",
-		kvAdapter: options.kvAdapter ?? "memory",
-		includeWorkflows: options.includeWorkflows ?? false
+		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) {
-	const isInteractive = 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);
@@ -127,10 +237,12 @@ async function runPrompts(args) {
 	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).");
+		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,
@@ -139,8 +251,7 @@ async function runPrompts(args) {
 			queueAdapter,
 			emailAdapter,
 			realtimeAdapter,
-			kvAdapter,
-			includeWorkflows: args.includeWorkflows ?? false
+			kvAdapter
 		});
 	}
 	p.intro(pc.bgCyan(pc.black(" QUESTPIE — Create a new project ")));
@@ -163,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,
@@ -171,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);
@@ -217,6 +345,7 @@ async function runPrompts(args) {
 		projectName: questions.projectName,
 		templateId: questions.templateId,
 		databaseName: questions.databaseName,
+		modules: questions.modules,
 		installDeps: questions.installDeps,
 		initGit: questions.initGit,
 		installSkills: questions.installSkills,
@@ -225,8 +354,7 @@ async function runPrompts(args) {
 		queueAdapter,
 		emailAdapter,
 		realtimeAdapter,
-		kvAdapter,
-		includeWorkflows: args.includeWorkflows ?? false
+		kvAdapter
 	});
 }
 
@@ -234,6 +362,126 @@ async function runPrompts(args) {
 //#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.
 */
@@ -296,45 +544,6 @@ 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
-		});
-		installed.push(skill.name);
-	}
-	return installed;
-}
 function handleFatalStepFailure(message, error, continueOnError) {
 	if (continueOnError) return;
 	const cause = error instanceof Error ? error.message : typeof error === "string" ? error : String(error);
@@ -345,14 +554,14 @@ async function applyProjectOptions(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");
-	await writeFile(join(targetDir, "src", "questpie", "admin", "modules.ts"), buildAdminModules(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"));
-	if (options.queueAdapter === "bullmq") packageJson.dependencies.bullmq = "^5.0.0";
-	if (options.queueAdapter === "bullmq" || options.realtimeAdapter === "redis-streams" || options.kvAdapter === "redis") packageJson.dependencies.redis = "^5.0.0";
-	if (options.includeWorkflows) packageJson.dependencies["@questpie/workflows"] = "latest";
+	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) {
@@ -376,27 +585,27 @@ function buildEnvFile(options) {
 	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(),`);
-	if (options.queueAdapter === "bullmq" || options.realtimeAdapter === "redis-streams" || options.kvAdapter === "redis") lines.push(`\t\tREDIS_URL: z.string().url().default("redis://localhost:6379"),`);
+	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 imports = [`import { runtimeConfig } from "questpie/app";`, `import { ConsoleAdapter } from "questpie/adapters/console";`];
-	if (options.queueAdapter === "pg-boss") imports.push(`import { pgBossAdapter } from "questpie/adapters/pg-boss";`);
-	if (options.queueAdapter === "bullmq") imports.push(`import { bullMQAdapter } from "questpie/adapters/bullmq";`);
-	if (options.emailAdapter === "smtp") imports.push(`import { SmtpAdapter } from "questpie/adapters/smtp";`);
-	if (options.emailAdapter === "resend") imports.push(`import { ResendAdapter } from "questpie/adapters/resend";`);
-	if (options.emailAdapter === "plunk") imports.push(`import { PlunkAdapter } from "questpie/adapters/plunk";`);
-	if (options.realtimeAdapter === "pg-notify") imports.push(`import { pgNotifyAdapter } from "questpie/adapters/pg-notify";`);
-	if (options.realtimeAdapter === "redis-streams") imports.push(`import { redisStreamsAdapter } from "questpie/adapters/redis-streams";`);
-	if (options.kvAdapter === "redis") {
-		imports.push(`import { redisKVAdapter } from "questpie/adapters/redis-kv";`);
-		imports.push(`import { createClient } from "redis";`);
-	}
+	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 helpers = [];
-	if (options.emailAdapter === "resend" || options.emailAdapter === "plunk") helpers.push(`function requiredEnv(value: string | undefined, name: string): string {`, `\tif (!value) throw new Error(\`Missing required environment variable: \${name}\`);`, `\treturn value;`, `}`, ``);
-	if (options.kvAdapter === "redis") helpers.push(`async function getRedis() {`, `\tconst redis = createClient({ url: env.REDIS_URL });`, `\tawait redis.connect();`, `\treturn redis;`, `}`, ``);
+	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 },`,
@@ -405,11 +614,10 @@ function buildRuntimeConfig(options) {
 		`\t\tadapter: ${buildEmailAdapterExpression(options)},`,
 		`\t},`
 	];
-	if (options.queueAdapter === "pg-boss") configEntries.push(`\tqueue: {`, `\t\tadapter: pgBossAdapter({ connectionString: env.DATABASE_URL }),`, `\t},`);
-	if (options.queueAdapter === "bullmq") configEntries.push(`\tqueue: {`, `\t\tadapter: bullMQAdapter({ connection: { url: env.REDIS_URL } }),`, `\t},`);
-	if (options.realtimeAdapter === "pg-notify") configEntries.push(`\trealtime: {`, `\t\tadapter: pgNotifyAdapter({ connectionString: env.DATABASE_URL }),`, `\t},`);
-	if (options.realtimeAdapter === "redis-streams") configEntries.push(`\trealtime: {`, `\t\tadapter: redisStreamsAdapter({ url: env.REDIS_URL }),`, `\t},`);
-	if (options.kvAdapter === "redis") configEntries.push(`\tkv: {`, `\t\tadapter: redisKVAdapter({ client: getRedis, keyPrefix: "${options.projectName}:" }),`, `\t},`);
+	for (const { axis, option } of selectedFeatureOptions(options)) {
+		const entry = features[axis]?.[option]?.configEntry;
+		if (entry) configEntries.push(...entry(options));
+	}
 	return [
 		`/**`,
 		` * QUESTPIE Runtime Configuration`,
@@ -432,24 +640,36 @@ function buildEmailAdapterExpression(options) {
 	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 })`;
 }
-function buildServerModules(options) {
-	const imports = [
-		`/**`,
-		` * Modules — static module dependencies for this project.`,
-		` */`,
-		`import { adminModule } from "@questpie/admin/modules/admin";`,
-		`import { openApiModule } from "@questpie/openapi";`
+/** 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;`,
+		`}`,
+		``
 	];
-	const modules = ["adminModule", "openApiModule"];
-	if (options.includeWorkflows) {
-		imports.push(`import { workflowsModule } from "@questpie/workflows/modules/workflows";`);
-		modules.push("workflowsModule");
-	}
+	return [];
+}
+function buildServerModules(options) {
+	const selected = selectedModules(options);
 	return [
-		...imports,
+		...[
+			`/**`,
+			` * Modules — static module dependencies for this project.`,
+			` */`,
+			...selected.map((mod) => `import { ${mod.serverSymbol} } from "${mod.serverImport}";`)
+		],
 		``,
 		`const modules = [`,
-		...modules.map((mod) => `\t${mod},`),
+		...selected.map((mod) => `\t${mod.serverSymbol},`),
 		`] as const;`,
 		``,
 		`export default modules;`,
@@ -457,27 +677,47 @@ function buildServerModules(options) {
 	].join("\n");
 }
 function buildAdminModules(options) {
-	const imports = [`import { adminClientModule } from "@questpie/admin/client/modules/admin";`];
-	const modules = ["adminClientModule"];
-	if (options.includeWorkflows) {
-		imports.push(`import { workflowsClientModule } from "@questpie/workflows/client/modules/workflows";`);
-		modules.push("workflowsClientModule");
-	}
+	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 [${modules.join(", ")}] as const;`,
+		`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"
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}
 async function scaffold(options) {
 	const resolvedOptions = {
 		...options,
 		queueAdapter: options.queueAdapter ?? "pg-boss",
 		emailAdapter: options.emailAdapter ?? "console",
 		realtimeAdapter: options.realtimeAdapter ?? "none",
-		kvAdapter: options.kvAdapter ?? "memory",
-		includeWorkflows: options.includeWorkflows ?? false
+		kvAdapter: options.kvAdapter ?? "memory"
 	};
 	const spinner = p.spinner();
 	const targetDir = resolve(process.cwd(), resolvedOptions.projectName);
@@ -519,16 +759,8 @@ async function scaffold(options) {
 			handleFatalStepFailure("Dependency installation failed", error, continueOnError);
 		}
 	}
-	if (resolvedOptions.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 (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 {
@@ -584,6 +816,10 @@ async function scaffold(options) {
 
 //#endregion
 //#region src/index.ts
+/** 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;
@@ -592,13 +828,21 @@ function readPackageVersion() {
 	}
 	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("--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("--workflows", "Install and register @questpie/workflows").option("--continue-on-error", "Keep scaffold files when dependency install or codegen fails").action(async (projectName, opts) => {
+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,
@@ -607,8 +851,7 @@ new Command().name("create-questpie").description("Create a new QUESTPIE project
 			queueAdapter: opts.queue,
 			emailAdapter: opts.email,
 			realtimeAdapter: opts.realtime,
-			kvAdapter: opts.kv,
-			includeWorkflows: opts.workflows === true
+			kvAdapter: opts.kv
 		}));
 	} catch (error) {
 		console.error(error instanceof Error ? error.message : String(error));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-questpie",
-	"version": "2.0.4",
+	"version": "2.1.0",
 	"description": "Create a new QUESTPIE project",
 	"keywords": [
 		"create",
@@ -20,8 +20,7 @@
 	},
 	"files": [
 		"dist",
-		"templates",
-		"skills"
+		"templates"
 	],
 	"type": "module",
 	"publishConfig": {