@ubean/cli 0.2.2 → 0.3.0

package/dist/cli.js

@@ -1,26 +1,30 @@
-import { E as createFsOps, S as renderTemplate, a as scaffold, c as scaffoldStarterTemplate, i as recoverScaffold, l as scaffoldUnifyTemplate, n as listScaffoldableFiles, o as scaffoldBlogTemplate, r as pageCommand, s as scaffoldMinimalTemplate, t as deleteScaffold } from "./page-DU64g_Lv.js";
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { A as summarizeBundle, D as compareBundleBaseline, E as createFsOps, O as findClientManifest, S as renderTemplate, a as scaffold, c as scaffoldStarterTemplate, i as recoverScaffold, j as writeBundleBaseline, k as readViteManifest, l as scaffoldUnifyTemplate, n as listScaffoldableFiles, o as scaffoldBlogTemplate, r as pageCommand, s as scaffoldMinimalTemplate, t as deleteScaffold } from "./page-BRUWKaig.js";
+import { existsSync, mkdirSync, readFileSync, watch } from "node:fs";
+import { basename, join, relative, resolve } from "pathe";
 import { extname, normalize } from "node:path";
-import { getLogger } from "@ubean/logger";
+import { getLogger } from "@ubean/shared/logger";
 import { defineCommand, runMain } from "citty";
+import { BUILTIN_MODULES, isBuiltinDisabled, loadUbeanConfig, resolveModules, resolvePrerenderConfig, resolveSsrConfig } from "@ubean/config";
 import { readFile, rm, stat } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
+import { generateOpenApiTypesFromServer, generateTypes } from "@ubean/build/codegen";
+import { prerender } from "@ubean/build/prerender";
 import { buildProduction } from "@ubean/build/production";
-import { generateOpenApiTypesFromServer, generateTypes } from "@ubean/codegen";
-import { loadUbeanConfig, resolvePrerenderConfig, resolveSsrConfig } from "@ubean/config";
-import { prerender } from "@ubean/prerender";
 import { NODE_REQUIREMENTS, createCapabilitySet, diagnoseCapabilities, registerBuiltinPresets, resolvePresetByName } from "@ubean/preset";
 import { scanProject } from "@ubean/scan";
-import { basename, join as join$1, resolve as resolve$1 } from "pathe";
-import { createUbeanApp } from "@ubean/app";
-import { createDevRunner, createDevWatcher, logDiagnostics } from "@ubean/dev-server";
+import { applyServerConfig, createUbeanApp } from "@ubean/app";
 import { bold, cyan, dim, green } from "kolorist";
-import { execSync, spawn } from "node:child_process";
-import { BUILTIN_MODULES, isBuiltinDisabled } from "@ubean/modules";
 import { createServer } from "node:http";
-import { findAvailablePort, waitForPort } from "@ubean/shared/node";
+import { createServer as createServer$1 } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { ubeanPlugin } from "@ubean/build/vite";
+import { VUE_PLUGIN_INCLUDE, ubeanVite } from "@ubean/build/vue";
+import { createVueRenderer } from "@ubean/client/ssr";
+import { ubeanIslandsPlugin } from "@ubean/islands/vite";
+import { findAvailablePort, findUserViteConfig, waitForPort } from "@ubean/shared/node";
+import { execSync, spawn } from "node:child_process";
 //#region src/config.ts
-const logger$8 = getLogger("cli");
+const logger$11 = getLogger("cli");
 const CONFIG_TEMPLATE = `import { defineConfig } from 'ubean';
 
 export default defineConfig({
@@ -104,17 +108,17 @@ const configCommand = {
 				const preset = args.preset;
 				const existing = await findConfigFile(fs);
 				if (existing && !args.force) {
-					logger$8.warn(`Config file already exists: ${existing} (use --force to overwrite)`);
+					logger$11.warn(`Config file already exists: ${existing} (use --force to overwrite)`);
 					return;
 				}
 				const content = renderTemplate(CONFIG_TEMPLATE, { variables: { preset } });
 				if (args.dry) {
-					logger$8.info("[dry-run] Would create ubean.config.ts");
-					logger$8.info(`\n${content}`);
+					logger$11.info("[dry-run] Would create ubean.config.ts");
+					logger$11.info(`\n${content}`);
 					return;
 				}
 				await fs.writeFile("ubean.config.ts", content);
-				logger$8.info("Created ubean.config.ts");
+				logger$11.info("Created ubean.config.ts");
 			}
 		},
 		show: {
@@ -127,13 +131,13 @@ const configCommand = {
 				const fs = createFsOps(cwd);
 				const configFile = await findConfigFile(fs);
 				if (!configFile) {
-					logger$8.warn("No ubean config file found. Run `ubean config init` to create one.");
+					logger$11.warn("No ubean config file found. Run `ubean config init` to create one.");
 					return;
 				}
-				logger$8.info(`Config file: ${configFile}`);
-				logger$8.info("");
+				logger$11.info(`Config file: ${configFile}`);
+				logger$11.info("");
 				const content = await fs.readFile(configFile);
-				logger$8.info(content);
+				logger$11.info(content);
 			}
 		},
 		example: {
@@ -142,7 +146,7 @@ const configCommand = {
 				description: "Show a full example configuration with all options"
 			},
 			async run() {
-				logger$8.info(CONFIG_EXAMPLE_FULL);
+				logger$11.info(CONFIG_EXAMPLE_FULL);
 			}
 		},
 		path: {
@@ -155,17 +159,112 @@ const configCommand = {
 				const fs = createFsOps(cwd);
 				const configFile = await findConfigFile(fs);
 				if (!configFile) {
-					logger$8.error("No config file found");
+					logger$11.error("No config file found");
 					process.exit(1);
 				}
-				logger$8.info(fs.resolve(configFile));
+				logger$11.info(fs.resolve(configFile));
 			}
 		}
 	}
 };
 //#endregion
+//#region src/analyze.ts
+const logger$10 = getLogger("cli");
+function readStringArg(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+const analyzeCommand = {
+	meta: {
+		name: "analyze",
+		description: "Report client JS budget from the Vite client manifest (run after `ubean build`)"
+	},
+	args: {
+		cwd: {
+			type: "string",
+			description: "Project root (defaults to process.cwd())"
+		},
+		write: {
+			type: "boolean",
+			description: "Write `.ubean/bundle-baseline.json`",
+			default: true
+		},
+		out: {
+			type: "string",
+			description: "Baseline JSON path (default: .ubean/bundle-baseline.json)"
+		},
+		check: {
+			type: "string",
+			description: "Committed baseline JSON to compare against (fails if gzip grows past --max-increase)"
+		},
+		maxIncrease: {
+			type: "string",
+			description: "Allowed relative gzip growth when using --check (default 0.05)"
+		}
+	},
+	async run({ args }) {
+		const cwd = resolve(typeof args.cwd === "string" ? args.cwd : process.cwd());
+		if (!existsSync(join(cwd, "package.json"))) throw new Error(`[ubean] analyze: ${cwd} is not a project root`);
+		await loadUbeanConfig(cwd).catch(() => void 0);
+		const found = findClientManifest(cwd);
+		if (!found) {
+			logger$10.error("No client Vite manifest found. Run `ubean build` first.");
+			throw new Error("missing client manifest");
+		}
+		const manifest = readViteManifest(found.manifestPath);
+		const baseline = summarizeBundle(found.outDir, manifest);
+		baseline.outDir = relative(cwd, found.outDir).replace(/\\/g, "/") || baseline.outDir;
+		logger$10.info(`client JS: ${(baseline.totalGzip / 1024).toFixed(1)} kB gzip (${baseline.entries.length} js chunks, entry ${(baseline.entryGzip / 1024).toFixed(1)} kB)`);
+		for (const entry of baseline.entries.slice(0, 12)) logger$10.info(`  ${entry.isEntry ? "[entry] " : ""}${entry.file}  ${(entry.gzip / 1024).toFixed(1)} kB gzip`);
+		if (args.write !== false) {
+			const outArg = readStringArg(args.out);
+			const out = outArg ? resolve(cwd, outArg) : join(cwd, ".ubean/bundle-baseline.json");
+			writeBundleBaseline(out, baseline);
+			logger$10.info(`wrote ${out}`);
+		}
+		const checkArg = readStringArg(args.check);
+		if (checkArg) {
+			const checkPath = resolve(cwd, checkArg);
+			if (!existsSync(checkPath)) {
+				logger$10.error(`baseline not found: ${checkPath}`);
+				throw new Error("missing budget baseline");
+			}
+			const committed = JSON.parse(readFileSync(checkPath, "utf8"));
+			const maxIncrease = Number(args.maxIncrease ?? .05);
+			const result = compareBundleBaseline(baseline, {
+				totalGzip: committed.totalGzip ?? 0,
+				entryGzip: committed.entryGzip ?? 0
+			}, { maxIncrease: Number.isFinite(maxIncrease) ? maxIncrease : .05 });
+			if (!result.ok) {
+				for (const message of result.messages) logger$10.error(message);
+				throw new Error("client JS budget exceeded");
+			}
+			logger$10.info(`budget ok (total ${(result.totalRatio * 100).toFixed(1)}%, entry ${(result.entryRatio * 100).toFixed(1)}% vs baseline, max ${(result.maxIncrease * 100).toFixed(0)}%)`);
+		}
+	}
+};
+//#endregion
 //#region src/build.ts
-const logger$7 = getLogger("cli");
+const logger$9 = getLogger("cli");
+async function loadContentForBuild(cwd, content) {
+	if (!content) return {
+		snapshot: void 0,
+		routes: []
+	};
+	try {
+		const mod = await import("@ubean/content");
+		const options = content === true ? {} : content;
+		const snapshot = mod.scanContentSources(cwd, options);
+		return {
+			snapshot,
+			routes: mod.extractContentPageRoutes(Object.values(snapshot).flat())
+		};
+	} catch {
+		return {
+			snapshot: void 0,
+			routes: []
+		};
+	}
+}
 /**
 * Creates a fetcher that invokes the built SSR entry to render real HTML.
 * Inspired by void's Node prerender runner: import the built `entry.mjs`,
@@ -177,16 +276,16 @@ const logger$7 = getLogger("cli");
 */
 async function createSsrFetcher(cwd, manifest) {
 	try {
-		const entryPath = resolve$1(cwd, manifest.serverDir, "entry.mjs");
+		const entryPath = resolve(cwd, manifest.serverDir, "entry.mjs");
 		const mod = await import(pathToFileURL(entryPath).href);
 		const createFetchHandler = mod.default ?? mod.createFetchHandler;
 		if (typeof createFetchHandler !== "function") {
-			logger$7.warn("SSR entry does not export createFetchHandler; falling back to placeholder prerender.");
+			logger$9.warn("SSR entry does not export createFetchHandler; falling back to placeholder prerender.");
 			return;
 		}
 		const fetch = await createFetchHandler();
 		if (typeof fetch !== "function") {
-			logger$7.warn("SSR entry did not return a fetch handler; falling back to placeholder prerender.");
+			logger$9.warn("SSR entry did not return a fetch handler; falling back to placeholder prerender.");
 			return;
 		}
 		return async (url) => {
@@ -198,7 +297,7 @@ async function createSsrFetcher(cwd, manifest) {
 			};
 		};
 	} catch (err) {
-		logger$7.warn(`Failed to load SSR entry for prerender: ${err instanceof Error ? err.message : String(err)}. Falling back to placeholder prerender.`);
+		logger$9.warn(`Failed to load SSR entry for prerender: ${err instanceof Error ? err.message : String(err)}. Falling back to placeholder prerender.`);
 		return;
 	}
 }
@@ -246,8 +345,8 @@ const buildCommand = {
 		}
 	},
 	async run({ args }) {
-		const cwd = resolve$1(args.cwd || process.cwd());
-		logger$7.info("Building ubean application...");
+		const cwd = resolve(args.cwd || process.cwd());
+		logger$9.info("Building ubean application...");
 		try {
 			registerBuiltinPresets();
 			const config = await loadUbeanConfig(cwd);
@@ -263,17 +362,17 @@ const buildCommand = {
 			} else if (args.prerender === false) config.prerender = resolvePrerenderConfig();
 			const presetName = args.preset || config.build.preset;
 			const preset = resolvePresetByName(presetName);
-			logger$7.info(`Using preset: ${preset.name}`);
-			logger$7.info(`App mode: ${config.mode}${config.mode === "fullstack" ? ` (ssr=${config.ssr.enabled})` : ""}`);
-			logger$7.info("Scanning project...");
+			logger$9.info(`Using preset: ${preset.name}`);
+			logger$9.info(`App mode: ${config.mode}${config.mode === "fullstack" ? ` (ssr=${config.ssr.enabled})` : ""}`);
+			logger$9.info("Scanning project...");
 			const result = await scanProject({
 				cwd,
 				srcDir: config.srcDir,
 				dirs: config.dir,
 				ignore: config.scanOptions?.ignore
 			});
-			logger$7.info(`Found ${result.apiRoutes.length} API routes, ${result.pages.length} pages, ${result.layouts.length} layouts`);
-			logger$7.info("Generating types...");
+			logger$9.info(`Found ${result.apiRoutes.length} API routes, ${result.pages.length} pages, ${result.layouts.length} layouts`);
+			logger$9.info("Generating types...");
 			await generateTypes(result, {
 				cwd,
 				srcDir: config.srcDir,
@@ -291,18 +390,20 @@ const buildCommand = {
 				preset: resolvedPreset,
 				config
 			});
-			logger$7.info("Building with Vite...");
+			logger$9.info("Building with Vite...");
+			const { snapshot: contentSnapshot, routes: contentRoutes } = await loadContentForBuild(cwd, config.content);
 			const manifest = await buildProduction({
 				cwd,
 				config,
 				preset: resolvedPreset,
 				scanResult: result,
 				minify: args.minify,
-				sourcemap: args.sourcemap
+				sourcemap: args.sourcemap,
+				contentSnapshot
 			});
 			const hasPrerenderRules = Object.values(config.routeRules || {}).some((r) => r?.prerender === true);
 			if (config.prerender.enabled || hasPrerenderRules) {
-				logger$7.info("Prerendering static pages...");
+				logger$9.info("Prerendering static pages...");
 				const fetcher = await createSsrFetcher(cwd, manifest);
 				await prerender({
 					cwd,
@@ -310,13 +411,14 @@ const buildCommand = {
 					pages: result.pages,
 					prerender: config.prerender,
 					routeRules: config.routeRules,
+					contentRoutes,
 					fetcher
 				});
 			}
 			if (config.mode === "ssg" && !process.env.UBEAN_KEEP_SSR) {
-				const serverDir = join$1(cwd, config.build.outputDir, "server");
+				const serverDir = join(cwd, config.build.outputDir, "server");
 				if (existsSync(serverDir)) {
-					logger$7.info("Cleaning temporary SSR bundle (SSG mode)...");
+					logger$9.info("Cleaning temporary SSR bundle (SSG mode)...");
 					await rm(serverDir, {
 						recursive: true,
 						force: true
@@ -330,18 +432,567 @@ const buildCommand = {
 				config,
 				manifest
 			});
-			logger$7.info(`Build complete for preset "${resolvedPreset.name}"!`);
-			logger$7.info(`  Output directory: ${resolve$1(cwd, config.build.outputDir)}`);
-			if (manifest.entry) logger$7.info(`  Server entry: ${manifest.entry}`);
-			logger$7.info(`  Client assets: ${manifest.assets.length} files`);
+			logger$9.info(`Build complete for preset "${resolvedPreset.name}"!`);
+			logger$9.info(`  Output directory: ${resolve(cwd, config.build.outputDir)}`);
+			if (manifest.entry) logger$9.info(`  Server entry: ${manifest.entry}`);
+			logger$9.info(`  Client assets: ${manifest.assets.length} files`);
 		} catch (err) {
-			logger$7.error(err instanceof Error ? err.message : String(err));
+			logger$9.error(err instanceof Error ? err.message : String(err));
 			process.exit(1);
 		}
 		process.exit(0);
 	}
 };
 //#endregion
+//#region src/dev-server/vite-server.ts
+const logger$8 = getLogger("dev-server");
+async function toWebRequest(req, host, protocol) {
+	const url = `${protocol}://${req.headers.host || host}${req.url || "/"}`;
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(req.headers)) if (value) {
+		if (Array.isArray(value)) for (const v of value) headers.append(key, v);
+		else headers.set(key, value);
+	}
+	const method = req.method || "GET";
+	return new Request(url, {
+		method,
+		headers,
+		body: method === "GET" || method === "HEAD" ? void 0 : req,
+		duplex: "half"
+	});
+}
+async function sendWebResponse(res, webRes) {
+	res.statusCode = webRes.status;
+	res.statusMessage = webRes.statusText;
+	webRes.headers.forEach((value, key) => {
+		res.setHeader(key, value);
+	});
+	if (webRes.body) {
+		const reader = webRes.body.getReader();
+		try {
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				res.write(value);
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	}
+	res.end();
+}
+function loadScaffoldOps() {
+	return {
+		createFsOps,
+		scaffold,
+		deleteScaffold,
+		recoverScaffold
+	};
+}
+async function createViteDevServer(options) {
+	const { cwd, config, app: initialApp, layouts: initialLayouts = [] } = options;
+	const host = options.host || "localhost";
+	const strictPort = options.strictPort ?? false;
+	let currentApp = initialApp;
+	let currentLayouts = initialLayouts;
+	let httpServer = null;
+	let viteServer = null;
+	let serverConfigApplied = false;
+	let serverReadyCalled = false;
+	let cachedServerConfig = null;
+	let refreshDevtools = null;
+	const requestedPort = options.port;
+	let actualPort;
+	try {
+		actualPort = await findAvailablePort(requestedPort, {
+			host,
+			strictPort
+		});
+	} catch (err) {
+		if (err?.code === "EADDRINUSE") throw new Error(`Port ${requestedPort} is already in use${host ? ` on ${host}` : ""}. Try a different port or remove the --strictPort flag.`, { cause: err });
+		throw err;
+	}
+	if (actualPort !== requestedPort) logger$8.warn(`Port ${requestedPort} is in use, trying ${actualPort} instead.`);
+	httpServer = createServer(async (req, res) => {
+		try {
+			const pathname = (req.url || "/").split("?")[0].split("#")[0];
+			if (devtoolsEnabled && (pathname === "/_devtools" || pathname === "/_devtools/")) {
+				res.statusCode = 302;
+				res.setHeader("Location", "/__devtools/");
+				res.end();
+				return;
+			}
+			await new Promise((resolve, reject) => {
+				viteServer.middlewares(req, res, (err) => {
+					if (err) reject(err);
+					else resolve();
+				});
+			});
+			if (res.writableEnded) return;
+			try {
+				await viteServer.ssrLoadModule("ubean:locales");
+			} catch (err) {
+				logger$8.warn("[ubean] Failed to resolve locales module:", err);
+			}
+			if (!serverConfigApplied) {
+				serverConfigApplied = true;
+				try {
+					const serverMod = await viteServer.ssrLoadModule("virtual:ubean-server");
+					if (serverMod?.resolveServerConfig) {
+						cachedServerConfig = serverMod.resolveServerConfig("dev");
+						await applyServerConfig(currentApp, cachedServerConfig);
+					}
+				} catch (err) {
+					logger$8.warn("[ubean] Failed to load server config:", err);
+				}
+			}
+			await currentApp.init();
+			if (!serverReadyCalled) {
+				serverReadyCalled = true;
+				if (cachedServerConfig?.onServerReady) try {
+					await cachedServerConfig.onServerReady(currentApp);
+				} catch (err) {
+					logger$8.warn("[ubean] onServerReady error:", err);
+				}
+			}
+			const protocol = req.socket?.encrypted ? "https" : "http";
+			const webReq = await toWebRequest(req, host, protocol);
+			const webRes = await currentApp.fetch(webReq);
+			const contentType = webRes.headers.get("content-type") || "";
+			const skipTransform = (req.url || "").startsWith("/_devtools");
+			if (contentType.includes("text/html") && webRes.body && !skipTransform) {
+				const html = await webRes.text();
+				const transformedHtml = await viteServer.transformIndexHtml(req.url || "/", html);
+				res.statusCode = webRes.status;
+				res.statusMessage = webRes.statusText;
+				webRes.headers.forEach((value, key) => {
+					res.setHeader(key, value);
+				});
+				res.end(transformedHtml);
+			} else await sendWebResponse(res, webRes);
+		} catch (err) {
+			if (viteServer) viteServer.ssrFixStacktrace(err);
+			if (!res.headersSent) {
+				res.statusCode = 500;
+				const errorHtml = `<!DOCTYPE html>
+<html>
+  <head>
+    <title>Server Error</title>
+    <style>
+      body { font-family: monospace; padding: 2rem; background: #1a1a1a; color: #ff6b6b; }
+      pre { background: #2d2d2d; padding: 1rem; border-radius: 4px; overflow-x: auto; }
+    </style>
+  </head>
+  <body>
+    <h1>Internal Server Error</h1>
+    <pre>${err.stack || err.message}</pre>
+  </body>
+</html>`;
+				res.setHeader("Content-Type", "text/html");
+				res.end(errorHtml);
+			} else if (!res.writableEnded) res.end(err instanceof Error ? err.message : "Internal Server Error");
+		}
+	});
+	const devtoolsEnabled = options.config.devtools.enabled;
+	let devtoolsPlugin = null;
+	if (devtoolsEnabled) try {
+		const { ubeanDevtoolsPlugin } = await import("@ubean/devtools");
+		const devtoolsOpts = options.devtools;
+		const scaffoldOps = await loadScaffoldOps();
+		devtoolsPlugin = ubeanDevtoolsPlugin({
+			getCwd: () => cwd,
+			getApp: () => currentApp,
+			...scaffoldOps ? { scaffoldOps } : {},
+			...devtoolsOpts?.getScanResult ? { getScanResult: devtoolsOpts.getScanResult } : {},
+			...devtoolsOpts?.getConfigMeta ? { getConfigMeta: devtoolsOpts.getConfigMeta } : {},
+			...devtoolsOpts?.getCustomTabs ? { getCustomTabs: devtoolsOpts.getCustomTabs } : {},
+			...devtoolsOpts?.ai ? { ai: devtoolsOpts.ai } : {},
+			...devtoolsOpts?.getApp ? { getApp: devtoolsOpts.getApp } : {},
+			...devtoolsOpts?.triggerRescan ? { triggerRescan: devtoolsOpts.triggerRescan } : {},
+			registerRefresh: (fn) => {
+				refreshDevtools = fn;
+			}
+		});
+	} catch {}
+	let viteDevtoolsPlugins = [];
+	if (devtoolsEnabled) try {
+		const { DevTools } = await import("@vitejs/devtools");
+		viteDevtoolsPlugins = await DevTools({ builtinDevTools: false });
+	} catch {}
+	const userViteConfig = findUserViteConfig(cwd);
+	const hasUserViteConfig = !!userViteConfig;
+	const isBackendMode = config.mode === "backend";
+	const builtinPlugins = [
+		{
+			name: "ubean:http-server-binder",
+			enforce: "pre",
+			configureServer(server) {
+				if (!server.httpServer && httpServer) server.httpServer = httpServer;
+			}
+		},
+		...isBackendMode ? [] : [vue({
+			include: VUE_PLUGIN_INCLUDE,
+			template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("ubean-") } }
+		})],
+		...hasUserViteConfig ? [] : [
+			ubeanPlugin({ config }),
+			...isBackendMode ? [] : ubeanVite({ config }),
+			...isBackendMode ? [] : [ubeanIslandsPlugin()]
+		],
+		...viteDevtoolsPlugins,
+		...devtoolsPlugin ? [devtoolsPlugin] : []
+	];
+	const { plugins } = await resolveModules({
+		cwd,
+		config,
+		builtinPlugins
+	});
+	if (devtoolsEnabled) process.env.VITE_DEVTOOLS_DISABLE_CLIENT_AUTH = "true";
+	viteServer = await createServer$1({
+		root: cwd,
+		configFile: userViteConfig ?? false,
+		server: {
+			middlewareMode: { server: httpServer },
+			hmr: { port: actualPort + 1e3 }
+		},
+		appType: "custom",
+		plugins,
+		devtools: {
+			enabled: devtoolsEnabled,
+			clientAuth: false
+		},
+		optimizeDeps: { exclude: [
+			"ubean",
+			"virtual:ubean-pages",
+			"virtual:ubean-app",
+			"virtual:ubean-server",
+			"virtual:ubean-client-entry",
+			"#ubean-pages",
+			"#ubean-app",
+			"#ubean-server",
+			"#ubean-client-entry"
+		] },
+		ssr: {
+			noExternal: ["ubean"],
+			external: ["@ubean/i18n"]
+		}
+	});
+	function enhanceAppWithVite(app, layouts = []) {
+		app.options.layouts = layouts;
+		const routeLoaders = {};
+		for (const route of app.options.routes || []) {
+			const fullPath = route.fullPath;
+			routeLoaders[route.relativePath] = () => viteServer.ssrLoadModule(fullPath);
+		}
+		app.options.routeLoaders = routeLoaders;
+		const pageLoaders = {};
+		const pageByName = /* @__PURE__ */ new Map();
+		for (const page of app.options.pages || []) pageByName.set(page.name, page);
+		for (const page of app.options.pages || []) {
+			const fullPath = (page.isReuse && page.reuseTarget ? pageByName.get(page.reuseTarget) : void 0)?.fullPath || page.fullPath;
+			pageLoaders[page.relativePath] = () => viteServer.ssrLoadModule(fullPath);
+		}
+		app.options.pageLoaders = pageLoaders;
+		const middlewareLoaders = {};
+		for (const mw of app.options.middleware || []) {
+			const fullPath = mw.fullPath;
+			middlewareLoaders[mw.relativePath] = () => viteServer.ssrLoadModule(fullPath);
+		}
+		app.options.middlewareLoaders = middlewareLoaders;
+		const cronFiles = app.options.crons || [];
+		if (cronFiles.length > 0) Promise.all(cronFiles.map((c) => viteServer.ssrLoadModule(c.fullPath))).then(async () => {
+			(await import("@ubean/server/cron")).startCronScheduler();
+		}).catch((err) => {
+			console.error("[ubean] Failed to load cron files:", err);
+		});
+		const layoutMap = /* @__PURE__ */ new Map();
+		for (const layout of layouts) layoutMap.set(layout.name, layout.fullPath);
+		const defaultLayout = layouts.find((l) => l.isDefault)?.name || null;
+		if (config.mode === "backend") {
+			app.resetInit();
+			return;
+		}
+		const scannedPages = app.options.pages || [];
+		const scannedPageByName = /* @__PURE__ */ new Map();
+		for (const p of scannedPages) scannedPageByName.set(p.name, p);
+		const routes = scannedPages.map((p) => {
+			const componentFullPath = (p.isReuse && p.reuseTarget ? scannedPageByName.get(p.reuseTarget) : void 0)?.fullPath || p.fullPath;
+			return {
+				path: p.route.replace(/\*\*:(\w[\w-]*)/g, ":$1(.*)*"),
+				name: p.name,
+				component: async () => {
+					const mod = await viteServer.ssrLoadModule(componentFullPath);
+					return mod.default || mod;
+				},
+				meta: {
+					layout: p.layout === false ? false : p.layout || defaultLayout,
+					pageName: p.name,
+					cache: p.cache === true ? true : void 0
+				}
+			};
+		});
+		let appConfigModule = null;
+		const getAppConfigModule = () => {
+			if (!appConfigModule) appConfigModule = viteServer.ssrLoadModule("virtual:ubean-app");
+			return appConfigModule;
+		};
+		app.options.pageRenderer = createVueRenderer({
+			routes,
+			async resolveLayoutComponent(name) {
+				if (name === false || name == null) return null;
+				const fullPath = layoutMap.get(name);
+				if (!fullPath) return null;
+				const mod = await viteServer.ssrLoadModule(fullPath);
+				return mod.default || mod;
+			},
+			defaultLayout,
+			async resolveAppConfig() {
+				return (await getAppConfigModule()).resolveAppConfig("server");
+			}
+		});
+		app.resetInit();
+	}
+	enhanceAppWithVite(currentApp, currentLayouts);
+	const getUrl = () => `http://${host}:${actualPort}`;
+	return {
+		get port() {
+			return actualPort;
+		},
+		get host() {
+			return host;
+		},
+		get url() {
+			return getUrl();
+		},
+		get viteServer() {
+			return viteServer;
+		},
+		async start() {
+			await new Promise((resolve, reject) => {
+				const tryListen = (port) => {
+					httpServer.removeAllListeners("error");
+					httpServer.once("error", (err) => {
+						if (err.code === "EADDRINUSE" && !strictPort) {
+							logger$8.warn(`Port ${port} is in use, trying ${port + 1} instead.`);
+							tryListen(port + 1);
+						} else reject(err);
+					});
+					httpServer.listen(port, host, () => {
+						const addr = httpServer.address();
+						actualPort = typeof addr === "object" && addr ? addr.port : port;
+						resolve();
+					});
+				};
+				tryListen(actualPort);
+			});
+			options.onListen?.({
+				port: actualPort,
+				host,
+				url: getUrl()
+			});
+		},
+		async stop() {
+			if (viteServer) {
+				await viteServer.close();
+				viteServer = null;
+			}
+			if (httpServer) {
+				await new Promise((res, rej) => {
+					httpServer.close((err) => err ? rej(err) : res());
+				});
+				httpServer = null;
+			}
+		},
+		updateApp(app, layouts) {
+			currentApp = app;
+			if (layouts) currentLayouts = layouts;
+			serverConfigApplied = false;
+			serverReadyCalled = false;
+			cachedServerConfig = null;
+			enhanceAppWithVite(app, currentLayouts);
+			refreshDevtools?.();
+		},
+		sendFullReload() {
+			if (viteServer) viteServer.ws.send({ type: "full-reload" });
+		}
+	};
+}
+//#endregion
+//#region src/dev-server/runner.ts
+var ViteNodeDevRunner = class {
+	viteDevServer = null;
+	currentApp;
+	currentLayouts;
+	options;
+	_port;
+	constructor(options) {
+		this.options = options;
+		this.currentApp = options.app;
+		this.currentLayouts = options.layouts || [];
+		this._port = options.port;
+	}
+	get port() {
+		return this._port;
+	}
+	get host() {
+		return this.options.host;
+	}
+	get url() {
+		return `http://${this.options.host}:${this._port}`;
+	}
+	get preset() {
+		return this.options.preset;
+	}
+	async start() {
+		this.viteDevServer = await createViteDevServer({
+			cwd: this.options.cwd,
+			port: this._port,
+			host: this.options.host,
+			strictPort: this.options.strictPort,
+			config: this.options.config,
+			app: this.currentApp,
+			layouts: this.currentLayouts,
+			devtools: this.options.devtools,
+			onListen: ({ port, host, url }) => {
+				this._port = port;
+				this.options.onListen?.({
+					port,
+					host,
+					url
+				});
+			}
+		});
+		await this.viteDevServer.start();
+	}
+	async stop() {
+		if (this.viteDevServer) {
+			await this.viteDevServer.stop();
+			this.viteDevServer = null;
+		}
+	}
+	async reload() {
+		await this.options.onBeforeReload?.();
+		if (this.viteDevServer) this.viteDevServer.updateApp(this.currentApp, this.currentLayouts);
+		await this.options.onAfterReload?.();
+	}
+	updateApp(app, layouts) {
+		this.currentApp = app;
+		if (layouts) this.currentLayouts = layouts;
+		if (this.viteDevServer) this.viteDevServer.updateApp(app, this.currentLayouts);
+	}
+	sendFullReload() {
+		this.viteDevServer?.sendFullReload();
+	}
+};
+const runners = [{
+	name: "vite-node",
+	isAvailable() {
+		return typeof process !== "undefined" && !!process.versions?.node;
+	},
+	async createRunner(options) {
+		return new ViteNodeDevRunner(options);
+	}
+}];
+async function selectRunner(_preset) {
+	for (const runner of runners) if (await runner.isAvailable()) return runner;
+	return null;
+}
+async function createDevRunner(options) {
+	const runner = await selectRunner(options.preset);
+	if (!runner) throw new Error(`No compatible dev runner found for preset "${options.preset.name}". Ensure you are running in a supported environment (Node.js).`);
+	return runner.createRunner(options);
+}
+//#endregion
+//#region src/dev-server/watcher.ts
+function createDevWatcher(options) {
+	const { cwd, dirs, ignore = [], debounceMs = 100 } = options;
+	const watchers = [];
+	const watchedDirs = /* @__PURE__ */ new Set();
+	let pendingEvents = [];
+	let debounceTimer = null;
+	function isIgnored(relPath) {
+		return ignore.some((pattern) => {
+			if (pattern.includes("*")) return new RegExp(`^${pattern.replace(/\*/g, ".*").replace(/\?/g, ".")}$`).test(relPath);
+			return relPath.startsWith(pattern) || relPath === pattern;
+		});
+	}
+	function queueEvent(type, fullPath) {
+		const relPath = relative(cwd, fullPath).replace(/\\/g, "/");
+		if (isIgnored(relPath)) return;
+		if (relPath.startsWith("node_modules/") || relPath.startsWith(".git/")) return;
+		if (relPath.endsWith(".bak") || relPath.startsWith(".ubean/")) return;
+		pendingEvents.push({
+			type,
+			path: fullPath,
+			relativePath: relPath
+		});
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			const events = pendingEvents;
+			pendingEvents = [];
+			debounceTimer = null;
+			options.onChange?.(events);
+		}, debounceMs);
+	}
+	function watchDir(dir) {
+		if (watchedDirs.has(dir)) return;
+		watchedDirs.add(dir);
+		try {
+			const w = watch(dir, { recursive: true }, (eventType, filename) => {
+				if (!filename) return;
+				const fullPath = join(dir, filename);
+				queueEvent(eventType === "rename" ? "unlink" : "change", fullPath);
+			});
+			watchers.push(w);
+		} catch {}
+	}
+	function start() {
+		for (const dir of dirs) watchDir(join(cwd, dir));
+	}
+	function stop() {
+		for (const w of watchers) w.close();
+		watchers.length = 0;
+		watchedDirs.clear();
+		if (debounceTimer) {
+			clearTimeout(debounceTimer);
+			debounceTimer = null;
+		}
+	}
+	function addDir(dir) {
+		watchDir(join(cwd, dir));
+	}
+	return {
+		start,
+		stop,
+		addDir
+	};
+}
+//#endregion
+//#region src/dev-server/index.ts
+const logger$7 = getLogger("dev-server");
+function formatDiagnostics(diagnostics) {
+	const errors = [];
+	const warnings = [];
+	for (const err of diagnostics.diagnostics.filter((d) => !d.supported && d.required)) errors.push(`  ✗ ${err.capability}: ${err.message}`);
+	for (const warn of diagnostics.diagnostics.filter((d) => !d.supported && !d.required)) warnings.push(`  ! ${warn.capability}: ${warn.message}`);
+	return {
+		errors,
+		warnings
+	};
+}
+function logDiagnostics(diagnostics) {
+	const { errors, warnings } = formatDiagnostics(diagnostics);
+	if (errors.length > 0) {
+		logger$7.error(`Capability errors (${errors.length}):`);
+		for (const e of errors) logger$7.error(e);
+	}
+	if (warnings.length > 0) {
+		logger$7.warn(`Capability warnings (${warnings.length}):`);
+		for (const w of warnings) logger$7.warn(w);
+	}
+	if (errors.length === 0 && warnings.length === 0) logger$7.info("All capability checks passed");
+}
+//#endregion
 //#region src/dev.ts
 const logger$6 = getLogger("cli");
 /**
@@ -393,7 +1044,7 @@ const devCommand = {
 		}
 	},
 	async run({ args }) {
-		const cwd = resolve$1(args.cwd || process.cwd());
+		const cwd = resolve(args.cwd || process.cwd());
 		logger$6.info("Starting ubean dev server...");
 		registerBuiltinPresets();
 		const config = await loadUbeanConfig(cwd);
@@ -465,7 +1116,7 @@ const devCommand = {
 				if (config.devtools.enabled) lines.push(`  → ${label("DevTools:")}   ${cyan(`${url}${config.devtools.route}`)}`);
 				lines.push(`  → ${dim("Press Ctrl+C to stop")}`);
 				logger$6.info(lines.join("\n"));
-				generateOpenApiTypesFromServer(url, { outDir: resolve$1(cwd, ".ubean") }).then((filePath) => {
+				generateOpenApiTypesFromServer(url, { outDir: resolve(cwd, ".ubean") }).then((filePath) => {
 					logger$6.info(`OpenAPI types generated: ${filePath}`);
 				}).catch((err) => {
 					logger$6.warn(`Failed to generate OpenAPI types: ${err instanceof Error ? err.message : String(err)}`);
@@ -556,7 +1207,12 @@ async function buildApp(cwd, config) {
 		i18nConfig: config.i18n,
 		ssrExclude: config.ssr.exclude,
 		streaming: config.ssr.streaming,
-		notFoundPage: result.notFoundPage
+		notFoundPage: result.notFoundPage,
+		csrf: config.security === false ? false : config.security?.csrf ?? true,
+		securityHeaders: config.security === false ? false : config.security?.headers === false ? false : config.security?.headers ?? true,
+		dataCache: config.dataCache,
+		cache: config.cache,
+		seoConventions: { srcDir: resolve(cwd, config.srcDir) }
 	});
 	app.hooks.hook("request:start", (c) => {
 		logger$6.info(`${c.req.method} ${c.req.path}`);
@@ -955,7 +1611,7 @@ function isNonInteractive() {
 	return !process.stdin.isTTY || process.env.CI !== void 0 || process.env.NONINTERACTIVE !== void 0;
 }
 async function scaffoldProject(options) {
-	const targetDir = resolve$1(options.cwd, options.dir);
+	const targetDir = resolve(options.cwd, options.dir);
 	const fs = createFsOps(targetDir);
 	const projectName = options.name || (options.dir === "." ? basename(options.cwd) : basename(options.dir));
 	const pm = options.packageManager || "npm";
@@ -1084,7 +1740,7 @@ const initCommand = {
 //#region src/prepare.ts
 const logger$2 = getLogger("cli");
 async function ensureBuildDir(cwd, buildDir) {
-	const fullPath = join$1(cwd, buildDir);
+	const fullPath = join(cwd, buildDir);
 	if (!existsSync(fullPath)) mkdirSync(fullPath, { recursive: true });
 }
 /**
@@ -1094,9 +1750,9 @@ async function ensureBuildDir(cwd, buildDir) {
 * 导出供单测复用（OPT-04 4c）。
 */
 function detectPackageManager(cwd) {
-	if (existsSync(join$1(cwd, "pnpm-lock.yaml"))) return "pnpm";
-	if (existsSync(join$1(cwd, "yarn.lock"))) return "yarn";
-	if (existsSync(join$1(cwd, "bun.lockb")) || existsSync(join$1(cwd, "bun.lock"))) return "bun";
+	if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
+	if (existsSync(join(cwd, "bun.lockb")) || existsSync(join(cwd, "bun.lock"))) return "bun";
 	return "npm";
 }
 /**
@@ -1147,7 +1803,7 @@ function extractPackageName(modulePath) {
 */
 function getUbeanVersion(cwd) {
 	try {
-		const pkgPath = join$1(cwd, "package.json");
+		const pkgPath = join(cwd, "package.json");
 		if (!existsSync(pkgPath)) return null;
 		const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
 		const spec = pkg.dependencies?.ubean || pkg.devDependencies?.ubean;
@@ -1199,7 +1855,7 @@ async function ensureBuiltinModules(cwd, config, autoInstall) {
 	const pm = detectPackageManager(cwd);
 	const ubeanVersion = getUbeanVersion(cwd);
 	const packagesToInstall = missing.map((m) => ubeanVersion ? `${m.packageName}@^${ubeanVersion}` : m.packageName);
-	if (!autoInstall || !existsSync(join$1(cwd, "package.json"))) {
+	if (!autoInstall || !existsSync(join(cwd, "package.json"))) {
 		for (const m of missing) {
 			const versionSuffix = ubeanVersion ? `@^${ubeanVersion}` : "";
 			logger$2.warn(`Built-in module "${m.key}" is enabled but \`${m.packageName}\` is not installed. Run: ${pm} add ${m.packageName}${versionSuffix}`);
@@ -1242,7 +1898,7 @@ const prepareCommand = {
 		}
 	},
 	async run({ args }) {
-		const cwd = resolve$1(args.cwd || process.cwd());
+		const cwd = resolve(args.cwd || process.cwd());
 		logger$2.info(`Preparing ubean project at ${cwd}...`);
 		const config = await loadUbeanConfig(cwd);
 		await ensureBuiltinModules(cwd, config, args.install !== false);
@@ -1314,17 +1970,17 @@ function startStaticServer(opts) {
 				res.end("Bad Request");
 				return;
 			}
-			let filePath = join$1(root, pathname);
+			let filePath = join(root, pathname);
 			let fileExists = existsSync(filePath) && (await stat(filePath)).isFile();
 			if (!fileExists && existsSync(filePath) && (await stat(filePath)).isDirectory()) {
-				const indexPath = join$1(filePath, "index.html");
+				const indexPath = join(filePath, "index.html");
 				if (existsSync(indexPath)) {
 					filePath = indexPath;
 					fileExists = true;
 				}
 			}
 			if (!fileExists && mode === "ssg") {
-				const indexPath = join$1(filePath, "index.html");
+				const indexPath = join(filePath, "index.html");
 				if (existsSync(indexPath) && (await stat(indexPath)).isFile()) {
 					filePath = indexPath;
 					fileExists = true;
@@ -1338,7 +1994,7 @@ function startStaticServer(opts) {
 				}
 			}
 			if (!fileExists && spaFallback) {
-				const fallbackPath = join$1(root, "index.html");
+				const fallbackPath = join(root, "index.html");
 				if (existsSync(fallbackPath)) {
 					filePath = fallbackPath;
 					fileExists = true;
@@ -1391,7 +2047,7 @@ const previewCommand = {
 		}
 	},
 	async run({ args }) {
-		const cwd = resolve$1(args.cwd || process.cwd());
+		const cwd = resolve(args.cwd || process.cwd());
 		logger$1.info("Starting ubean preview server...");
 		registerBuiltinPresets();
 		const config = await loadUbeanConfig(cwd);
@@ -1420,7 +2076,7 @@ const previewCommand = {
 			logger$1.info(`${green(bold("🚀 ubean preview server ready"))}\n\n  → ${label("Local:")}      ${cyan(bannerUrl)}\n  → ${label("Mode:")}       ${dim(modeLabel)}\n  → ${label("Preset:")}     ${cyan(preset.name)}\n  → ${dim("Press Ctrl+C to stop")}`);
 		};
 		if (mode === "spa" || mode === "ssg") {
-			const staticRoot = join$1(cwd, outputDir, "public");
+			const staticRoot = join(cwd, outputDir, "public");
 			if (!existsSync(staticRoot)) {
 				logger$1.error(`Build output not found: ${staticRoot}`);
 				logger$1.info("Run `ubean build` first to create a production build.");
@@ -1455,7 +2111,7 @@ const previewCommand = {
 			serverFile = "handler.mjs";
 			logger$1.warn(`Preset "${presetName}" uses a fetch handler entry. Preview may not work as a standalone server.`);
 		}
-		const serverPath = join$1(cwd, outputDir, "server", serverFile);
+		const serverPath = join(cwd, outputDir, "server", serverFile);
 		if (!existsSync(serverPath)) {
 			logger$1.error(`Build output not found: ${serverPath}`);
 			logger$1.info("Run `ubean build` first to create a production build.");
@@ -1727,7 +2383,24 @@ const main = defineCommand({
 		layout: layoutCommand,
 		middleware: middlewareCommand,
 		cron: cronCommand,
-		plugin: pluginCommand
+		plugin: pluginCommand,
+		scaffold: {
+			meta: {
+				name: "scaffold",
+				description: "Machine-readable scaffold catalog (studio / IDE plugins)"
+			},
+			subCommands: { describe: {
+				meta: {
+					name: "describe",
+					description: "Print the scaffold JSON manifest (RM-S01)"
+				},
+				async run() {
+					const { getScaffoldManifest } = await import("./scaffold-manifest-TrH6OCX8.js").then((n) => n.r);
+					process.stdout.write(`${JSON.stringify(getScaffoldManifest(), null, 2)}\n`);
+				}
+			} }
+		},
+		analyze: analyzeCommand
 	}
 });
 runMain(main);