@ubean/cli 0.5.1 → 0.6.0-beta.1

package/dist/cli.js

@@ -1,29 +1,22 @@
-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-Um0fHKa9.js";
-import { existsSync, mkdirSync, readFileSync, watch } from "node:fs";
+import { A as readViteManifest, D as compareBundleBaseline, E as createFsOps, M as writeBundleBaseline, O as findClientManifest, S as renderTemplate, a as scaffold, c as scaffoldStarterTemplate, i as recoverScaffold, j as summarizeBundle, k as formatKilobytes, l as scaffoldUnifyTemplate, n as listScaffoldableFiles, o as scaffoldBlogTemplate, r as pageCommand, s as scaffoldMinimalTemplate, t as deleteScaffold } from "./page-C2Bde9EG.js";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, join, relative, resolve } from "pathe";
-import { extname, normalize, sep } from "node:path";
-import { getLogger, setDebugLogging } from "@ubean/shared/logger";
+import { getLogger, setDebugLogging, setMinLevel } from "@ubean/shared/logger";
 import { defineCommand, runMain } from "citty";
 import { BUILTIN_MODULES, isBuiltinDisabled, loadUbeanConfig, resolveModules, resolvePrerenderConfig, resolveSsrConfig } from "@ubean/config";
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { pathToFileURL } from "node:url";
+import { readFile, rm } from "node:fs/promises";
 import { generateOpenApiTypesFromServer, generateTypes } from "@ubean/build/codegen";
-import { prerender } from "@ubean/build/prerender";
-import { buildProduction } from "@ubean/build/production";
-import { createStaticSsgRenderer } from "@ubean/build/static-render";
-import { NODE_REQUIREMENTS, createCapabilitySet, diagnoseCapabilities, registerBuiltinPresets, resolvePresetByName } from "@ubean/preset";
+import { buildWithEnvironments } from "@ubean/build/production";
+import { NODE_REQUIREMENTS, diagnoseCapabilities, registerBuiltinPresets, resolvePresetByName } from "@ubean/preset";
 import { scanProject } from "@ubean/scan";
-import { applyServerConfig, createUbeanApp } from "@ubean/app";
 import { bold, cyan, dim, green } from "kolorist";
 import { createServer } from "node:http";
-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 { getVueLocaleParam, toVueRouterLocalePath } from "@ubean/i18n";
+import { DEVTOOLS_PASS_THROUGH_PREFIXES, createCloudflarePreviewRunner, createVirtualRegistry, getDevApp, onDevScan, peekDevScanCoordinator, previewMimeType, resolvePreviewFile, ubeanDevRequestPlugin, ubeanPlugin, ubeanPreviewPlugin } from "@ubean/build/vite";
+import { createServer as createServer$1, preview } from "vite";
+import { ubeanVite } from "@ubean/build/vue";
 import { ubeanIslandsPlugin } from "@ubean/islands/vite";
-import { findAvailablePort, findUserViteConfig, getLanAddresses, isLoopbackHost, isWildcardHost, waitForPort } from "@ubean/shared/node";
-import { execSync, spawn } from "node:child_process";
+import { findAvailablePort, findUserViteConfig, getLanAddresses, isLoopbackHost, isWildcardHost } from "@ubean/shared/node";
+import { execSync } from "node:child_process";
 //#region src/config.ts
 const logger$11 = getLogger("cli");
 const CONFIG_TEMPLATE = `import { defineConfig } from 'ubean';
@@ -174,6 +167,14 @@ const logger$10 = getLogger("cli");
 function readStringArg(value) {
 	return typeof value === "string" && value.length > 0 ? value : void 0;
 }
+/** Absolute ceilings are given in kB on the CLI; the budget API works in bytes. */
+function readKilobyteArg(value, flag) {
+	const raw = readStringArg(value);
+	if (raw === void 0) return void 0;
+	const kb = Number(raw);
+	if (!Number.isFinite(kb) || kb < 0) throw new Error(`[ubean] analyze: ${flag} must be a non-negative number of kB`);
+	return Math.round(kb * 1024);
+}
 const analyzeCommand = {
 	meta: {
 		name: "analyze",
@@ -200,6 +201,18 @@ const analyzeCommand = {
 		maxIncrease: {
 			type: "string",
 			description: "Allowed relative gzip growth when using --check (default 0.05)"
+		},
+		maxTotalKb: {
+			type: "string",
+			description: "Absolute ceiling for total client JS gzip in kB (checked against this build alone)"
+		},
+		maxEntryKb: {
+			type: "string",
+			description: "Absolute ceiling for entry chunk gzip in kB"
+		},
+		maxChunkKb: {
+			type: "string",
+			description: "Absolute ceiling for any single chunk gzip in kB"
 		}
 	},
 	async run({ args }) {
@@ -214,7 +227,7 @@ const analyzeCommand = {
 		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)`);
+		logger$10.info(`client JS: ${formatKilobytes(baseline.totalGzip)} gzip / ${formatKilobytes(baseline.totalBrotli ?? 0)} brotli (${baseline.entries.length} js chunks, entry ${formatKilobytes(baseline.entryGzip)} gzip)`);
 		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);
@@ -223,23 +236,40 @@ const analyzeCommand = {
 			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 absoluteBudget = {
+			maxTotalGzip: readKilobyteArg(args.maxTotalKb, "--max-total-kb"),
+			maxEntryGzip: readKilobyteArg(args.maxEntryKb, "--max-entry-kb"),
+			maxChunkGzip: readKilobyteArg(args.maxChunkKb, "--max-chunk-kb")
+		};
+		const hasAbsoluteBudget = Object.values(absoluteBudget).some((value) => value !== void 0);
+		if (checkArg || hasAbsoluteBudget) {
+			let committed;
+			if (checkArg) {
+				const checkPath = resolve(cwd, checkArg);
+				if (!existsSync(checkPath)) {
+					logger$10.error(`baseline not found: ${checkPath}`);
+					throw new Error("missing budget baseline");
+				}
+				const parsed = JSON.parse(readFileSync(checkPath, "utf8"));
+				committed = {
+					totalGzip: parsed.totalGzip ?? 0,
+					entryGzip: parsed.entryGzip ?? 0
+				};
+			} else committed = {
+				totalGzip: baseline.totalGzip,
+				entryGzip: baseline.entryGzip
+			};
 			const maxIncrease = Number(args.maxIncrease ?? .05);
-			const result = compareBundleBaseline(baseline, {
-				totalGzip: committed.totalGzip ?? 0,
-				entryGzip: committed.entryGzip ?? 0
-			}, { maxIncrease: Number.isFinite(maxIncrease) ? maxIncrease : .05 });
+			const result = compareBundleBaseline(baseline, committed, {
+				maxIncrease: Number.isFinite(maxIncrease) ? maxIncrease : .05,
+				...absoluteBudget
+			});
 			if (!result.ok) {
 				for (const message of result.messages) logger$10.error(message);
-				throw new Error("client JS budget exceeded");
+				throw new Error(result.violations.some((v) => v.kind === "missing") ? "client JS budget check failed" : "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)}%)`);
+			const relativeSummary = checkArg ? `total ${(result.totalRatio * 100).toFixed(1)}%, entry ${(result.entryRatio * 100).toFixed(1)}% vs baseline, max ${(result.maxIncrease * 100).toFixed(0)}%` : "no baseline comparison";
+			logger$10.info(`budget ok (${relativeSummary})`);
 		}
 	}
 };
@@ -275,33 +305,9 @@ async function loadContentForBuild(cwd, content) {
 * If the SSR entry cannot be loaded (e.g. missing dependencies), returns
 * `undefined` so the caller falls back to the existing placeholder behavior.
 */
-async function createSsrFetcher(cwd, manifest) {
-	try {
-		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$9.warn("SSR entry does not export createFetchHandler; falling back to placeholder prerender.");
-			return;
-		}
-		const fetch = await createFetchHandler();
-		if (typeof fetch !== "function") {
-			logger$9.warn("SSR entry did not return a fetch handler; falling back to placeholder prerender.");
-			return;
-		}
-		return async (url) => {
-			const req = new Request(`http://localhost${url || "/"}`, { headers: { "x-ubean-prerender": "1" } });
-			const res = await fetch(req);
-			return {
-				html: typeof res.text === "function" ? await res.text() : String(res.body ?? ""),
-				statusCode: res.status ?? 200
-			};
-		};
-	} catch (err) {
-		logger$9.warn(`Failed to load SSR entry for prerender: ${err instanceof Error ? err.message : String(err)}. Falling back to placeholder prerender.`);
-		return;
-	}
-}
+/**
+* RM-V21：`createSsrFetcher` 已随预渲染逻辑下沉到 `@ubean/build` 的 `prerender-step.ts`。
+*/
 const buildCommand = {
 	meta: {
 		name: "build",
@@ -325,6 +331,10 @@ const buildCommand = {
 			description: "Shortcut for --mode ssg",
 			default: false
 		},
+		outDir: {
+			type: "string",
+			description: "Output directory (overrides ubean.config.ts build.outputDir)"
+		},
 		minify: {
 			type: "boolean",
 			description: "Minify output",
@@ -390,8 +400,12 @@ const buildCommand = {
 				config
 			});
 			logger$9.info("Building with Vite...");
-			const { snapshot: contentSnapshot, routes: contentRoutes } = await loadContentForBuild(cwd, config.content);
-			const manifest = await buildProduction({
+			const nodeEnv = process.env.NODE_ENV;
+			if (nodeEnv && nodeEnv !== "production") logger$9.warn(`NODE_ENV=${nodeEnv}：客户端产物会包含开发态代码（如 Vue dev runtime 与开发警告）。生产构建请设置 NODE_ENV=production，或不要设置该变量。`);
+			if (args.outDir) config.build.outputDir = String(args.outDir);
+			process.env.UBEAN_BUILD_PRESET = resolvedPreset.name;
+			const { snapshot: contentSnapshot } = await loadContentForBuild(cwd, config.content);
+			const manifest = await buildWithEnvironments({
 				cwd,
 				config,
 				preset: resolvedPreset,
@@ -400,64 +414,6 @@ const buildCommand = {
 				sourcemap: args.sourcemap,
 				contentSnapshot
 			});
-			const hasPrerenderRules = Object.values(config.routeRules || {}).some((r) => r?.prerender === true);
-			if (config.prerender.enabled || hasPrerenderRules) {
-				logger$9.info("Prerendering static pages...");
-				let fetcher;
-				let notFoundRoute = false;
-				let expandRoutes;
-				if (config.mode === "ssg") {
-					const staticRenderer = await createStaticSsgRenderer(cwd, manifest, {
-						pages: result.pages,
-						notFoundPage: result.notFoundPage ?? null,
-						i18n: config.i18n
-					});
-					if (staticRenderer) {
-						fetcher = staticRenderer.fetcher;
-						expandRoutes = staticRenderer.expandRoutes;
-						notFoundRoute = Boolean(result.notFoundPage);
-						logger$9.info("Using static SSG renderer (direct render, no HTTP pipeline)");
-					}
-				} else fetcher = await createSsrFetcher(cwd, manifest);
-				await prerender({
-					cwd,
-					outputDir: config.build.outputDir,
-					pages: result.pages,
-					prerender: config.prerender,
-					routeRules: config.routeRules,
-					contentRoutes,
-					fetcher,
-					notFoundRoute,
-					expandRoutes
-				});
-				if (contentSnapshot) try {
-					const contentMod = await import("@ubean/content");
-					const searchConfig = contentMod.resolveContentSearchConfig(config.content, { ssg: config.mode === "ssg" });
-					const staticDir = resolve(cwd, resolvePrerenderConfig(config.prerender).staticDir);
-					if (searchConfig.sections) {
-						const payload = contentMod.generateSearchSectionsSnapshot(contentSnapshot);
-						await mkdir(staticDir, { recursive: true });
-						await writeFile(join(staticDir, "__search.json"), JSON.stringify(payload), "utf-8");
-						const sectionCount = Object.values(payload).reduce((sum, sections) => sum + sections.length, 0);
-						logger$9.info(`Search: wrote __search.json (${sectionCount} sections)`);
-					}
-					if (searchConfig.pagefind) {
-						const res = await contentMod.runPagefindIndex({
-							siteDir: staticDir,
-							createIndexOptions: searchConfig.pagefindOptions,
-							logger: {
-								info: (msg) => logger$9.info(msg),
-								warn: (msg) => logger$9.warn(msg)
-							}
-						});
-						if (res.indexed) logger$9.info("Search: pagefind index generated");
-						else if (res.reason === "pagefind-not-installed") logger$9.info("Search: pagefind is not installed — skipping index. Run `pnpm add -D pagefind` to enable.");
-						else logger$9.warn(`Search: pagefind indexing failed — ${res.error ?? res.reason}`);
-					}
-				} catch (err) {
-					logger$9.warn(`Search index generation skipped: ${err instanceof Error ? err.message : String(err)}`);
-				}
-			}
 			if (config.mode === "ssg" && !process.env.UBEAN_KEEP_SSR) {
 				const serverDir = join(cwd, config.build.outputDir, "server");
 				if (existsSync(serverDir)) {
@@ -487,283 +443,99 @@ const buildCommand = {
 	}
 };
 //#endregion
-//#region src/dev-server/vite-server.ts
-const logger$8 = getLogger("dev-server");
-/**
-* Compute the vue-router locale param (e.g. `:locale(zh)?`) from the resolved
-* i18n routing config, mirroring `localeVueParamFromI18n` (`@ubean/build`).
-* Returns `''` when i18n is disabled or no prefix is needed.
-*/
-function resolveLocaleVueParam(config) {
-	if (!config?.enabled || !config.locales?.length) return "";
-	return getVueLocaleParam({
-		defaultLocale: config.defaultLocale,
-		locales: config.locales.map((l) => l.code),
-		strategy: config.strategy
-	});
-}
-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
-	};
-}
-/** Vite's browser-facing prefix for virtual module ids (see `wrapId`). */
-const VALID_ID_PREFIX = "/@id/";
-/** Vite's URL-safe encoding of the `\0` virtual-module marker. */
-const NULL_BYTE_PLACEHOLDER = "__x00__";
+//#region src/dev-server/dev-vite.ts
 /**
-* Encode a module-graph URL into a browser-servable path.
+* dev 的 Vite 装配（RM-V14：取代 `vite-server.ts` + `runner.ts`）。
+*
+* CLI 不再自建 app、不再持有 HTTP server、也不再管热重载：
+* - **请求路由**与**宿主 app** 由 `@ubean/build` 的 `ubeanDevRequestPlugin` 负责（自举 +
+*   随扫描重建）；
+* - **文件监听与重载顺序**由 `dev-scan` 协调器负责；
+* - CLI 只装配插件、起 Vite server、打印 banner，并订阅扫描做命令级事务（类型生成、
+*   DevTools 数据上报）。
 *
-* Virtual module ids carry a raw `\0` marker in the module graph (e.g.
-* UnoCSS's `\0/__uno.css`). A literal NUL is invalid inside HTML — parse5
-* rejects it with `unexpected-null-character`, which surfaces as a warning
-* in `transformIndexHtml`. Mirror Vite's own import-analysis rewriting
-* (`wrapId`: `/@id/` prefix + `\0` → `__x00__`) so the href stays valid
-* and resolvable by the dev server.
+* 保留两处 CLI 专有接线（无法下沉）：`@ubean/devtools` / `@vitejs/devtools` 的按需加载
+* （可选依赖 + `config.devtools.enabled` 闸门），以及 DevTools 的 scaffold CRUD
+* （页面增删改是 CLI 的能力）。
 */
-function toDevCssHref(url) {
-	return url.includes("\0") ? `${VALID_ID_PREFIX}${url.replace(/\0/g, NULL_BYTE_PLACEHOLDER)}` : url;
-}
+const logger$8 = getLogger("dev-server");
 /**
-* Collect render-blocking CSS URLs from the Vite dev module graph.
-*
-* In dev, CSS imported from JS (virtual uno.css entry, global.css, font css)
-* is only applied once the client entry module graph has fully loaded and
-* executed — SSR HTML paints unstyled for that gap (FOUC). Injecting the same
-* CSS modules as blocking `<link>` tags lets the browser fetch them in
-* parallel with the JS graph, so the first paint is styled.
-*
-* `?direct` tells Vite's transform middleware to return raw CSS
-* (`Content-Type: text/css`) instead of the JS style-injection wrapper.
-* Modules whose URL already carries a query (SFC `<style>` blocks such as
-* `*.vue?vue&type=style&...`) cannot be served this way and are skipped.
+* 收编 Vite 原生日志到 ubean 分类闸门：`lifecycle` 关闭时（默认）info 降为 debug，
+* warn/error 原样保留（这两级永远可见）。
 */
-function collectDevCssLinks(moduleGraph) {
-	const links = /* @__PURE__ */ new Set();
-	for (const mod of moduleGraph.idToModuleMap.values()) {
-		const { url, id } = mod;
-		if (!url || url.includes("?")) continue;
-		if (id?.endsWith(".css") || url.endsWith(".css")) links.add(`${toDevCssHref(url)}?direct`);
-	}
-	return [...links];
-}
-/** Inject blocking stylesheet links right before `</head>`. */
-function injectStylesheetLinks(html, hrefs) {
-	if (!hrefs.length || !html.includes("</head>")) return html;
-	const tags = hrefs.map((href) => `<link rel="stylesheet" href="${href}">`).join("");
-	return html.replace("</head>", `${tags}</head>`);
+function createGatedViteLogger(logging) {
+	return {
+		info: (msg) => logger$8.debug(msg),
+		warn: (msg) => logger$8.warn(msg),
+		warnOnce: (msg) => logger$8.warn(msg),
+		error: (msg, options) => logger$8.error(options?.error ? `${msg} ${options.error}` : msg),
+		clearScreen: () => {},
+		hasWarned: false,
+		...logging.lifecycle ? { info: (msg) => logger$8.info(msg) } : {}
+	};
 }
-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;
-			}
-			if (!viteServer) {
-				res.statusCode = 503;
-				res.setHeader("Content-Type", "text/plain; charset=utf-8");
-				res.end("ubean dev server is shutting down");
-				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 htmlWithCss = injectStylesheetLinks(await webRes.text(), collectDevCssLinks(viteServer.moduleGraph));
-				const transformedHtml = await viteServer.transformIndexHtml(req.url || "/", htmlWithCss);
-				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");
-		// @vitejs/devtools 也解析到含 @vitejs+devtools peer 上下文的 vite-plus-core
-		viteDevtoolsPlugins = await DevTools({ builtinDevTools: false });
-	} catch {}
+async function createDevViteServer(options) {
+	const { cwd, config, host, strictPort = false } = options;
+	const devtoolsEnabled = config.devtools.enabled;
 	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] : []
-	];
+	let viteServer = null;
+	const rescanDev = () => peekDevScanCoordinator(viteServer)?.rescan();
+	const builtinPlugins = [...hasUserViteConfig ? [] : [ubeanDevRequestPlugin({
+		passThrough: devtoolsEnabled ? [...DEVTOOLS_PASS_THROUGH_PREFIXES] : [],
+		devtoolsRedirect: devtoolsEnabled
+	})], ...hasUserViteConfig ? [] : [
+		ubeanPlugin({
+			config,
+			registry: createVirtualRegistry()
+		}),
+		...isBackendMode ? [] : ubeanVite({
+			config,
+			registry: createVirtualRegistry()
+		}),
+		...isBackendMode ? [] : [ubeanIslandsPlugin()]
+	]];
+	if (devtoolsEnabled) {
+		process.env.VITE_DEVTOOLS_DISABLE_CLIENT_AUTH = "true";
+		try {
+			const { ubeanDevtoolsPlugin } = await import("@ubean/devtools");
+			builtinPlugins.push(ubeanDevtoolsPlugin({
+				getScanResult: options.devtools?.getScanResult,
+				getConfigMeta: options.devtools?.getConfigMeta,
+				getCustomTabs: options.devtools?.getCustomTabs,
+				getCwd: () => cwd,
+				scaffoldOps: {
+					createFsOps,
+					scaffold,
+					deleteScaffold,
+					recoverScaffold
+				},
+				getApp: () => getDevApp(viteServer) ?? void 0,
+				triggerRescan: async () => {
+					await rescanDev();
+				}
+			}));
+		} catch {}
+		try {
+			const { DevTools } = await import("@vitejs/devtools");
+			builtinPlugins.push(...await DevTools({ builtinDevTools: false }));
+		} catch {}
+	}
 	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,
+		customLogger: createGatedViteLogger({ lifecycle: config.logging.lifecycle }),
 		resolve: { dedupe: ["vue", "vue-router"] },
 		server: {
-			middlewareMode: { server: httpServer },
-			hmr: { port: actualPort + 1e3 }
+			host,
+			port: options.port,
+			strictPort
 		},
 		appType: "custom",
 		plugins,
@@ -778,98 +550,29 @@ async function createViteDevServer(options) {
 			"virtual:ubean-app",
 			"virtual:ubean-server",
 			"virtual:ubean-client-entry",
-			"#ubean-pages",
-			"#ubean-app",
-			"#ubean-server",
-			"#ubean-client-entry"
+			"ubean:locales",
+			"ubean:pages",
+			"ubean:routes",
+			"ubean:meta",
+			"ubean:app-config"
 		] },
 		ssr: {
 			noExternal: ["ubean", /^@ubean\//],
 			external: ["@ubean/i18n"]
 		}
 	});
-	const { createVueRenderer } = await viteServer.ssrLoadModule("@ubean/client/ssr");
-	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 ssrLocaleParam = resolveLocaleVueParam(config.i18n);
-		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;
-			const routePath = p.route.replace(/\*\*:(\w[\w-]*)/g, ":$1(.*)*");
-			return {
-				path: ssrLocaleParam ? toVueRouterLocalePath(routePath, ssrLocaleParam) : routePath,
-				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 displayHost = isWildcardHost(host) ? "localhost" : host;
-	const getNetworkUrls = () => isLoopbackHost(host) ? [] : getLanAddresses().map((address) => `http://${address}:${actualPort}`);
-	const getUrl = () => `http://${displayHost}:${actualPort}`;
+	if (options.onScan) onDevScan(viteServer, options.onScan);
+	await viteServer.listen();
+	const address = viteServer.httpServer?.address();
+	const actualPort = address && typeof address === "object" ? address.port : options.port;
+	const url = `http://${isWildcardHost(host) ? "localhost" : host}:${actualPort}`;
+	const networkUrls = isLoopbackHost(host) ? [] : getLanAddresses().map((lanAddress) => `http://${lanAddress}:${actualPort}`);
+	options.onListen?.({
+		port: actualPort,
+		host,
+		url,
+		networkUrls
+	});
 	return {
 		get port() {
 			return actualPort;
@@ -878,213 +581,19 @@ async function createViteDevServer(options) {
 			return host;
 		},
 		get url() {
-			return getUrl();
+			return url;
 		},
 		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(),
-				networkUrls: getNetworkUrls()
-			});
+		async rescan() {
+			await rescanDev();
 		},
 		async stop() {
-			if (httpServer) {
-				const server = httpServer;
-				httpServer = null;
-				await new Promise((resolve) => {
-					server.close(() => resolve());
-					server.closeAllConnections();
-				});
-			}
-			if (viteServer) {
-				await viteServer.close();
-				viteServer = 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, networkUrls }) => {
-				this._port = port;
-				this.options.onListen?.({
-					port,
-					host,
-					url,
-					networkUrls
-				});
-			}
-		});
-		await this.viteDevServer.start();
-	}
-	async stop() {
-		if (this.viteDevServer) {
-			await this.viteDevServer.stop();
-			this.viteDevServer = null;
+			const server = viteServer;
+			viteServer = null;
+			await server?.close();
 		}
-	}
-	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
@@ -1100,7 +609,13 @@ function formatDiagnostics(diagnostics) {
 		warnings
 	};
 }
-function logDiagnostics(diagnostics) {
+/**
+* 输出能力诊断结果。
+*
+* `'auto'` 语义(默认):健康时静默 —— "All capability checks passed" 仅在
+* `verbose` 时输出;告警/错误属于 warn/error 级别,始终输出。
+*/
+function logDiagnostics(diagnostics, options = {}) {
 	const { errors, warnings } = formatDiagnostics(diagnostics);
 	if (errors.length > 0) {
 		logger$7.error(`Capability errors (${errors.length}):`);
@@ -1110,7 +625,7 @@ function logDiagnostics(diagnostics) {
 		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");
+	if (errors.length === 0 && warnings.length === 0 && options.verbose) logger$7.info("All capability checks passed");
 }
 //#endregion
 //#region src/dev.ts
@@ -1131,20 +646,6 @@ import("@ubean/devtools").then((mod) => {
 function getCustomTabs() {
 	return _customTabsGetter();
 }
-/**
-* dev 环境 SecurityHeaders 解析（ADR-0011）。
-*
-* ssg 模式默认关闭：静态产物不携带框架注入的安全头（响应头由托管平台
-* 控制），dev 默认关闭以对齐生产行为，消除「dev 有 CSP / 线上没有」的
-* 偏差。显式配置（`headers: true` 或对象）仍会被尊重，作为 CSP 调试
-* 入口。其余模式默认开启不变。
-*/
-function resolveDevSecurityHeaders(config) {
-	if (config.security === false) return false;
-	if (config.security?.headers === false) return false;
-	if (config.security?.headers !== void 0) return config.security.headers;
-	return config.mode !== "ssg";
-}
 const devCommand = {
 	meta: {
 		name: "dev",
@@ -1164,6 +665,14 @@ const devCommand = {
 			description: "Exit if the port is already in use, instead of auto-incrementing",
 			default: false
 		},
+		verbose: {
+			type: "boolean",
+			description: "Show detailed startup logs (directories, scan, codegen, diagnostics, reload events)"
+		},
+		logRequests: {
+			type: "boolean",
+			description: "Log each request (GET /path 200 12ms). Ignored in ssg/spa modes."
+		},
 		open: {
 			type: "boolean",
 			description: "Open browser on startup"
@@ -1176,142 +685,142 @@ const devCommand = {
 	},
 	async run({ args }) {
 		const cwd = resolve(args.cwd || process.cwd());
-		logger$6.info("Starting ubean dev server...");
 		registerBuiltinPresets();
 		const config = await loadUbeanConfig(cwd);
+		const logging = config.logging;
+		if (args.verbose) {
+			logging.scan = true;
+			logging.lifecycle = true;
+			logging.diagnostics = true;
+		}
+		if (args.logRequests) {
+			logging.request = true;
+			logging.requestSuppressed = false;
+		}
+		const backendCapable = config.mode === "fullstack" || config.mode === "backend";
+		if (logging.request && !backendCapable) {
+			logging.request = false;
+			logging.requestSuppressed = true;
+		}
+		if (logging.requestSuppressed) logger$6.warn(`Request logging is not applicable in "${config.mode}" mode — skipping.`);
+		setMinLevel(logging.level);
+		const startedAt = Date.now();
+		if (logging.lifecycle) logger$6.info("Starting ubean dev server...");
 		const port = Number(args.port) || config.dev.port;
 		const host = args.host || config.dev.host;
-		logger$6.info(`Root directory: ${config.rootDir}`);
-		logger$6.info(`Source directory: ${config.srcDir}`);
 		const preset = resolvePresetByName(config.build.preset);
-		logger$6.info(`Preset: ${preset.name}`);
-		const capabilities = createCapabilitySet(preset.capabilities || {});
-		logger$6.info("Running capability diagnostics...");
+		if (logging.scan) {
+			logger$6.info(`Root directory: ${config.rootDir}`);
+			logger$6.info(`Source directory: ${config.srcDir}`);
+			logger$6.info(`Preset: ${preset.name}`);
+		}
+		if (logging.scan) logger$6.info("Running capability diagnostics...");
 		const diagnostics = diagnoseCapabilities(preset.name, preset.capabilities || {}, NODE_REQUIREMENTS);
-		logDiagnostics(diagnostics);
+		logDiagnostics(diagnostics, { verbose: logging.diagnostics });
 		if (!diagnostics.valid) logger$6.warn("Some capability requirements are not met. Dev server may not function correctly.");
-		let { app: currentApp, layouts: currentLayouts, scanResult: currentScanResult } = await buildApp(cwd, config);
-		let rescanInProgress = false;
-		async function rescan() {
-			if (rescanInProgress) return;
-			rescanInProgress = true;
+		let currentScanResult = await initialScan(cwd, config, logging);
+		/**
+		* 扫描后的命令级事务（RM-V13：扫描由 dev-scan 协调器驱动）。
+		*
+		* app 的重建不在这里 —— 它归 `ubeanDevRequestPlugin`（RM-V14）。CLI 负责把类型定义重新
+		* 生成，并把新扫描结果交给 DevTools。**重载不由 CLI 发**：协调器会在所有订阅者完成后统一发
+		* `full-reload`，因此浏览器不会带着旧的 `definePage` 元数据刷新。
+		*/
+		async function onScan(result, changed) {
+			if (changed.length > 0) {
+				lastChangedFile = relative(cwd, changed[0]).replace(/\\/g, "/");
+				if (logging.lifecycle) logger$6.info(`File change detected: ${lastChangedFile}`);
+			}
+			currentScanResult = result;
 			try {
-				const { app: newApp, layouts: newLayouts, scanResult } = await buildApp(cwd, config);
-				currentApp = newApp;
-				currentLayouts = newLayouts;
-				currentScanResult = scanResult;
-				runner.updateApp(currentApp, currentLayouts);
-				await runner.reload();
-				runner.sendFullReload();
+				await generateTypes(result, {
+					cwd,
+					srcDir: config.srcDir,
+					buildDir: ".ubean",
+					dirs: config.dir,
+					autoImports: config.autoImports,
+					components: config.components
+				});
 			} catch (err) {
 				logger$6.error(`Rescan failed: ${err instanceof Error ? err.message : String(err)}`);
-			} finally {
-				rescanInProgress = false;
 			}
 		}
-		const runner = await createDevRunner({
-			cwd,
-			srcDir: config.srcDir,
-			port,
-			host,
-			strictPort: args.strictPort,
-			preset,
-			config,
-			capabilities,
-			app: currentApp,
-			layouts: currentLayouts,
-			devtools: {
-				getScanResult: () => currentScanResult,
-				getConfigMeta: () => ({
-					preset: config.build.preset,
-					rootDir: config.rootDir,
-					srcDir: config.srcDir,
-					openAPI: {
-						enabled: true,
-						scalarPath: "/_scalar",
-						openAPIPath: "/_openapi.json"
-					},
-					dir: config.dir
-				}),
-				getCustomTabs: () => getCustomTabs(),
-				triggerRescan: () => rescan()
-			},
-			onListen({ url, networkUrls }) {
-				const label = (text) => dim(text);
-				const lines = [
-					`${green(bold("🚀 ubean dev server ready"))}\n`,
-					`  → ${label("Local:")}      ${cyan(url)}`,
-					...(networkUrls || []).map((n) => `  → ${label("Network:")}    ${cyan(n)}`)
-				];
-				const hasBackend = config.mode !== "ssg" && config.mode !== "spa";
-				if (hasBackend) lines.push(`  → ${label("Scalar UI:")}  ${cyan(`${url}/_scalar`)}`, `  → ${label("OpenAPI:")}    ${cyan(`${url}/_openapi.json`)}`);
-				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"));
-				if (hasBackend) generateOpenApiTypesFromServer(url, { outDir: resolve(cwd, ".ubean") }).then((filePath) => {
-					if (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)}`);
-				});
-			},
-			onBeforeReload() {
-				logger$6.info("Reloading...");
-			},
-			onAfterReload() {
-				logger$6.info("Reloaded");
-			}
-		});
+		let lastChangedFile = null;
+		let devServer = null;
 		try {
-			await runner.start();
+			devServer = await createDevViteServer({
+				cwd,
+				port,
+				host,
+				strictPort: args.strictPort,
+				config,
+				onScan,
+				devtools: {
+					getScanResult: () => currentScanResult,
+					getConfigMeta: () => ({
+						preset: config.build.preset,
+						rootDir: config.rootDir,
+						srcDir: config.srcDir,
+						openAPI: {
+							enabled: true,
+							scalarPath: "/_scalar",
+							openAPIPath: "/_openapi.json"
+						},
+						dir: config.dir
+					}),
+					getCustomTabs: () => getCustomTabs()
+				},
+				onListen({ url, networkUrls }) {
+					const label = (text) => dim(text);
+					const modeSuffix = dim(` (${config.mode} · ${preset.name})`);
+					const lines = [
+						`${green(bold(`🚀 ubean dev server ready in ${Date.now() - startedAt}ms`))}${modeSuffix}\n`,
+						`  → ${label("Local:")}      ${cyan(url)}`,
+						...(networkUrls || []).map((n) => `  → ${label("Network:")}    ${cyan(n)}`)
+					];
+					const hasBackend = config.mode !== "ssg" && config.mode !== "spa";
+					if (hasBackend) lines.push(`  → ${label("Scalar UI:")}  ${cyan(`${url}/_scalar`)}`, `  → ${label("OpenAPI:")}    ${cyan(`${url}/_openapi.json`)}`);
+					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"));
+					if (hasBackend) generateOpenApiTypesFromServer(url, { outDir: resolve(cwd, ".ubean") }).then((filePath) => {
+						if (filePath && logging.scan) logger$6.info(`OpenAPI types generated: ${filePath}`);
+					}).catch((err) => {
+						logger$6.warn(`Failed to generate OpenAPI types: ${err instanceof Error ? err.message : String(err)}`);
+					});
+				}
+			});
 		} catch (err) {
 			logger$6.error(err?.stack || err?.message || String(err));
 			process.exit(1);
 		}
-		const watcher = createDevWatcher({
-			cwd,
-			dirs: [
-				"api",
-				"pages",
-				"middleware",
-				"layouts",
-				"plugins",
-				"app",
-				"routes"
-			].map((d) => `${config.srcDir}/${d}`),
-			ignore: [
-				"**/node_modules/**",
-				"**/.git/**",
-				"**/.ubean/**"
-			],
-			debounceMs: 150,
-			async onChange(events) {
-				const relevantEvents = events.filter((e) => /\.(ts|js|vue|mjs|cjs|json)$/.test(e.relativePath) && !e.relativePath.includes(".bak"));
-				if (relevantEvents.length === 0) return;
-				logger$6.info(`File change detected: ${relevantEvents[0].relativePath}`);
-				await rescan();
-			}
-		});
-		watcher.start();
 		const cleanup = async () => {
-			logger$6.info("\nShutting down...");
-			watcher.stop();
-			await runner.stop();
+			if (logging.lifecycle) logger$6.info("\nShutting down...");
+			await devServer?.stop();
 			process.exit(0);
 		};
 		process.on("SIGINT", cleanup);
 		process.on("SIGTERM", cleanup);
 	}
 };
-async function buildApp(cwd, config) {
-	logger$6.info("Scanning project files...");
+/**
+* 初始扫描 + 类型生成。
+*
+* RM-V14 起 CLI 不在这里建 app（由 `ubeanDevRequestPlugin` 自举），只负责扫描与 codegen；
+* 扫描结果交给 DevTools 作启动数据，并在每次文件变更后由 `onScan` 刷新。
+*/
+async function initialScan(cwd, config, logging) {
+	if (logging.scan) logger$6.info("Scanning project files...");
 	const result = await scanProject({
 		cwd,
 		srcDir: config.srcDir,
 		dirs: config.dir,
 		ignore: config.scanOptions?.ignore
 	});
-	logger$6.info(`Found ${result.apiRoutes.length} API routes, ${result.pages.length} pages, ${result.layouts.length} layouts, ${result.middlewares.length} middlewares, ${result.plugins.length} plugins`);
-	logger$6.info("Generating type definitions...");
+	if (logging.scan) {
+		logger$6.info(`Found ${result.apiRoutes.length} API routes, ${result.pages.length} pages, ${result.layouts.length} layouts, ${result.middlewares.length} middlewares, ${result.plugins.length} plugins`);
+		logger$6.info("Generating type definitions...");
+	}
 	await generateTypes(result, {
 		cwd,
 		srcDir: config.srcDir,
@@ -1320,39 +829,12 @@ async function buildApp(cwd, config) {
 		autoImports: config.autoImports,
 		components: config.components
 	});
-	const app = createUbeanApp({
-		rootDir: cwd,
-		routes: result.apiRoutes,
-		middleware: result.middlewares,
-		pages: result.pages,
-		crons: result.crons,
-		routeRules: config.routeRules || {},
-		publicDir: config.dir.public,
-		pageAssetTags: config.favicon ? { favicon: config.favicon } : void 0,
-		openAPI: {
-			title: "UBEAN Dev API",
-			scalarPath: "/_scalar",
-			openAPIPath: "/_openapi.json"
-		},
-		i18nConfig: config.i18n,
-		ssrExclude: config.ssr.exclude,
-		streaming: config.ssr.streaming,
-		notFoundPage: result.notFoundPage,
-		csrf: config.security === false ? false : config.security?.csrf ?? true,
-		securityHeaders: resolveDevSecurityHeaders(config),
-		dataCache: config.dataCache,
-		cache: config.cache,
-		seoConventions: { srcDir: resolve(cwd, config.srcDir) }
-	});
-	app.hooks.hook("request:start", (c) => {
-		logger$6.debug(`${c.req.method} ${c.req.path}`);
-	});
-	return {
-		app,
-		layouts: result.layouts,
-		scanResult: result
-	};
+	return result;
 }
+/**
+* RM-V14：请求日志（`logging.request`）不再由 CLI 实现 —— 见 `@ubean/build` 的
+* `createDevApp({ logger })`。配置域行为放 builder，两条 dev 路径输出一致。
+*/
 //#endregion
 //#region src/devtools.ts
 const logger$5 = getLogger("cli");
@@ -2057,89 +1539,38 @@ const prepareCommand = {
 };
 //#endregion
 //#region src/preview.ts
-const MIME_TYPES = {
-	".html": "text/html; charset=utf-8",
-	".js": "text/javascript; charset=utf-8",
-	".mjs": "text/javascript; charset=utf-8",
-	".css": "text/css; charset=utf-8",
-	".json": "application/json; charset=utf-8",
-	".svg": "image/svg+xml",
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".webp": "image/webp",
-	".ico": "image/x-icon",
-	".woff": "font/woff",
-	".woff2": "font/woff2",
-	".ttf": "font/ttf",
-	".otf": "font/otf",
-	".wasm": "application/wasm",
-	".txt": "text/plain; charset=utf-8",
-	".map": "application/json; charset=utf-8"
-};
 /**
-* 启动静态文件服务器,用于 spa / ssg 模式预览。
+* 静态文件服务器（spa / ssg 的降级路径）。
 *
-* - ssg 模式:优先查找 `<path>/index.html` 或 `<path>.html`,找不到时返回 404
-* - spa 模式:所有非文件路由回退到 `index.html`(客户端路由接管)
+* RM-V25：判定规则不再自己写一份，改用 `@ubean/build/vite` 的 `resolvePreviewFile` —— 插件接管
+* `vite preview` 时用的是同一个函数，两套方言必然分叉（文件名含合法 `...` 的产物曾被
+* `includes('..')` 判成路径穿越）。
 *
-* 使用 Node 内置 `http` + `fs`,避免引入 `sirv` 等依赖。
+* 主路径已改为 `vite preview` + 插件中间件（RM-V24）；本函数保留给「Vite 预览起不来」的
+* spa / ssg 场景（静态产物不需要服务端能力），以及既有回归测试。
 */
 function startStaticServer(opts) {
 	const { root, port, host, mode } = opts;
-	const spaFallback = mode === "spa";
 	return createServer(async (req, res) => {
 		try {
 			const url = new URL(req.url || "/", `http://${host}`);
 			const pathname = decodeURIComponent(url.pathname);
-			let filePath = normalize(join(root, pathname));
-			const rootPath = resolve(root);
-			if (filePath !== rootPath && !filePath.startsWith(rootPath + sep)) {
+			const resolvedFile = resolvePreviewFile(root, pathname, mode);
+			if (resolvedFile.kind === "forbidden") {
 				res.statusCode = 400;
+				res.setHeader("Content-Type", "text/plain; charset=utf-8");
 				res.end("Bad Request");
 				return;
 			}
-			let fileExists = existsSync(filePath) && (await stat(filePath)).isFile();
-			if (!fileExists && existsSync(filePath) && (await stat(filePath)).isDirectory()) {
-				const indexPath = join(filePath, "index.html");
-				if (existsSync(indexPath)) {
-					filePath = indexPath;
-					fileExists = true;
-				}
-			}
-			if (!fileExists && mode === "ssg") {
-				const indexPath = join(filePath, "index.html");
-				if (existsSync(indexPath) && (await stat(indexPath)).isFile()) {
-					filePath = indexPath;
-					fileExists = true;
-				}
-			}
-			if (!fileExists && mode === "ssg") {
-				const htmlPath = `${filePath}.html`;
-				if (existsSync(htmlPath) && (await stat(htmlPath)).isFile()) {
-					filePath = htmlPath;
-					fileExists = true;
-				}
-			}
-			if (!fileExists && spaFallback) {
-				const fallbackPath = join(root, "index.html");
-				if (existsSync(fallbackPath)) {
-					filePath = fallbackPath;
-					fileExists = true;
-				}
-			}
-			if (!fileExists) {
+			if (resolvedFile.kind === "missing") {
 				res.statusCode = 404;
 				res.setHeader("Content-Type", "text/plain; charset=utf-8");
 				res.end("Not Found");
 				return;
 			}
-			const ext = extname(filePath).toLowerCase();
-			const contentType = MIME_TYPES[ext] || "application/octet-stream";
-			const body = await readFile(filePath);
+			const body = await readFile(resolvedFile.path);
 			res.statusCode = 200;
-			res.setHeader("Content-Type", contentType);
+			res.setHeader("Content-Type", previewMimeType(resolvedFile.path));
 			res.setHeader("Content-Length", body.length);
 			res.end(body);
 		} catch (err) {
@@ -2173,6 +1604,10 @@ const previewCommand = {
 			type: "string",
 			description: "Project root directory",
 			default: "."
+		},
+		outDir: {
+			type: "string",
+			description: "Output directory to preview (overrides ubean.config.ts build.outputDir)"
 		}
 	},
 	async run({ args }) {
@@ -2182,6 +1617,7 @@ const previewCommand = {
 		const config = await loadUbeanConfig(cwd);
 		const preset = resolvePresetByName(config.build.preset);
 		logger$1.info(`Preset: ${preset.name}`);
+		if (args.outDir) config.build.outputDir = String(args.outDir);
 		const outputDir = config.build.outputDir || "dist";
 		const mode = config.mode;
 		const host = args.host || config.preview.host;
@@ -2204,110 +1640,71 @@ const previewCommand = {
 			const bannerUrl = `http://${host}:${port}`;
 			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(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.");
+		const staticMode = mode === "spa" || mode === "ssg";
+		const isCloudflare = preset.name === "cloudflare";
+		const staticRoot = join(cwd, outputDir, "public");
+		const requiredArtifact = staticMode ? join(staticRoot, "index.html") : isCloudflare ? join(cwd, outputDir, "server", "worker.mjs") : join(cwd, outputDir, "server", "entry.mjs");
+		if (!existsSync(requiredArtifact)) {
+			logger$1.error(`Build output not found: ${requiredArtifact}`);
+			logger$1.info("Run `ubean build` first to create a production build.");
+			process.exit(1);
+		}
+		if (isCloudflare) {
+			const probe = await createCloudflarePreviewRunner({ workerPath: requiredArtifact });
+			if (!probe.ok) {
+				logger$1.error(probe.message);
+				process.exit(1);
+			}
+			await probe.runner.dispose();
+		}
+		const userViteConfig = findUserViteConfig(cwd);
+		let server;
+		try {
+			server = await preview({
+				root: cwd,
+				configFile: userViteConfig ?? false,
+				mode: "production",
+				logLevel: "warn",
+				preview: {
+					port: actualPort,
+					host,
+					strictPort
+				},
+				...userViteConfig ? {} : { plugins: [ubeanPreviewPlugin({
+					config,
+					host
+				})] }
+			});
+		} catch (err) {
+			if (!staticMode) {
+				logger$1.error(`Failed to start the preview server: ${err instanceof Error ? err.message : String(err)}`);
 				process.exit(1);
 			}
-			const server = startStaticServer({
+			logger$1.warn(`Vite preview unavailable (${err instanceof Error ? err.message : String(err)}); falling back to the built-in static server.`);
+			const fallback = startStaticServer({
 				root: staticRoot,
 				port: actualPort,
 				host,
 				mode
 			});
 			printBanner(actualPort, `static (${mode})`);
-			const cleanup = () => {
-				server.close(() => process.exit(0));
+			const cleanupFallback = () => {
+				fallback.close(() => process.exit(0));
 				setTimeout(() => process.exit(0), 1e3).unref();
 			};
-			process.on("SIGINT", cleanup);
-			process.on("SIGTERM", cleanup);
-			server.on("error", (err) => {
-				logger$1.error(`Preview server error: ${err.message || err}`);
-				process.exit(1);
-			});
+			process.on("SIGINT", cleanupFallback);
+			process.on("SIGTERM", cleanupFallback);
 			return;
 		}
-		const presetName = preset.name;
-		let serverFile;
-		if (presetName === "node" || presetName === "bun" || presetName === "deno") serverFile = "server.mjs";
-		else if (presetName === "cloudflare") {
-			logger$1.error("Cloudflare preset preview is not supported yet. Use `wrangler dev` instead.");
-			process.exit(1);
-		} else {
-			serverFile = "handler.mjs";
-			logger$1.warn(`Preset "${presetName}" uses a fetch handler entry. Preview may not work as a standalone server.`);
-		}
-		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.");
-			process.exit(1);
-		}
-		const { child, exited } = spawnPreviewServer({
-			serverPath,
-			cwd,
-			port: actualPort,
-			host,
-			strictPort
-		});
-		try {
-			await waitForPort(actualPort, {
-				host,
-				retries: 40,
-				delay: 250
-			});
-		} catch {
-			if (exited.value) logger$1.error(`Preview server exited before becoming ready on port ${actualPort}.`);
-			else logger$1.warn(`Preview server on port ${actualPort} is not responding yet, the banner may be premature.`);
-		}
-		printBanner(actualPort, "production");
+		printBanner(actualPort, staticMode ? `static (${mode})` : "production");
 		const cleanup = () => {
-			child.kill("SIGTERM");
-			process.exit(0);
+			server?.close().catch(() => void 0).finally(() => process.exit(0));
+			setTimeout(() => process.exit(0), 1e3).unref();
 		};
 		process.on("SIGINT", cleanup);
 		process.on("SIGTERM", cleanup);
-		child.on("exit", (code) => {
-			if (code !== 0 && code !== null) logger$1.error(`Preview server exited with code ${code}`);
-			process.exit(code ?? 0);
-		});
 	}
 };
-function spawnPreviewServer(opts) {
-	const exited = { value: false };
-	const child = spawn("node", [opts.serverPath], {
-		cwd: opts.cwd,
-		env: {
-			...process.env,
-			PORT: String(opts.port),
-			HOST: opts.host
-		},
-		stdio: [
-			"inherit",
-			"inherit",
-			"pipe"
-		]
-	});
-	let addrInUseReported = false;
-	child.stderr?.on("data", (chunk) => {
-		const text = chunk.toString();
-		process.stderr.write(text);
-		if (!addrInUseReported && /EADDRINUSE/.test(text)) {
-			addrInUseReported = true;
-			logger$1.error(`Port ${opts.port} is already in use${opts.host ? ` on ${opts.host}` : ""}. Try a different port${opts.strictPort ? " or remove the --strictPort flag" : ""}.`);
-		}
-	});
-	child.on("exit", () => {
-		exited.value = true;
-	});
-	return {
-		child,
-		exited
-	};
-}
 //#endregion
 //#region src/scaffold-commands.ts
 const logger = getLogger("cli");