@ubean/devtools 0.1.2 → 0.1.3

package/dist/index.js

@@ -0,0 +1,1894 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHooks } from "hookable";
+import { execSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+//#region src/shared/env.ts
+const SENSITIVE_KEY_FRAGMENTS = [
+	"KEY",
+	"SECRET",
+	"TOKEN",
+	"PASSWORD",
+	"AUTH",
+	"CREDENTIAL"
+];
+function isSensitiveKey(key) {
+	const upper = key.toUpperCase();
+	return SENSITIVE_KEY_FRAGMENTS.some((fragment) => upper.includes(fragment));
+}
+function maskSensitiveEnv(env) {
+	return Object.fromEntries(Object.entries(env).map(([key, value]) => [key, isSensitiveKey(key) ? "***" : value]));
+}
+//#endregion
+//#region src/server/hooks.ts
+function createDevToolsHooks() {
+	const hooks = createHooks();
+	function registerHook(type, handler) {
+		hooks.hook(type, handler);
+	}
+	async function runHook(type, ctx) {
+		await hooks.callHook(type, ctx);
+	}
+	function removeHook(type, handler) {
+		hooks.removeHook(type, handler);
+	}
+	function removeAllHooks() {
+		hooks.removeAllHooks();
+	}
+	return {
+		registerHook,
+		runHook,
+		removeHook,
+		removeAllHooks,
+		hook: hooks.hook,
+		callHook: hooks.callHook
+	};
+}
+const DEEPSEEK_PROVIDER_NAME = "deepseek";
+const SYSTEM_PROMPT = `You are ubean Assistant, an AI developer assistant built into the ubean Vue meta-framework DevTools.
+You help developers scaffold pages, APIs, middleware, layouts, cron jobs, plugins, and manage environment variables.
+You can also inspect the project structure, list resources, and read configuration.
+
+Available resource types for creation: page, api, layout, middleware, cron, plugin
+- page: Vue page component under src/pages/
+- api: API route handler under src/api/
+- layout: Layout component under src/layouts/
+- middleware: Middleware under src/middleware/
+- cron: Scheduled task under src/server/crons/
+- plugin: Plugin under src/plugins/
+
+When creating resources, always use the create_resource tool and confirm the path with the user if ambiguous.
+Be concise and helpful. Use code examples when relevant.
+
+When the user asks about the current project, use the list_resources or get_project_info tools to get up-to-date information.
+Do not guess resource paths — always verify with tools first.`;
+let toolCallCounter = 0;
+function nextToolId() {
+	return `call_${++toolCallCounter}`;
+}
+function createAiServer(crud, getInfo, onStreamChunk) {
+	function getToolDefinitions() {
+		return [
+			{
+				name: "list_resources",
+				description: "List all resources of a given type in the project",
+				parameters: {
+					type: "object",
+					properties: { type: {
+						type: "string",
+						description: "Type of resource to list",
+						enum: [
+							"pages",
+							"apis",
+							"layouts",
+							"middlewares",
+							"crons",
+							"all"
+						]
+					} },
+					required: ["type"]
+				}
+			},
+			{
+				name: "create_resource",
+				description: "Create a new resource (page, api, layout, middleware, cron, plugin)",
+				parameters: {
+					type: "object",
+					properties: {
+						type: {
+							type: "string",
+							description: "Type of resource to create",
+							enum: [
+								"page",
+								"api",
+								"layout",
+								"middleware",
+								"cron",
+								"plugin"
+							]
+						},
+						path: {
+							type: "string",
+							description: "Route path (e.g., \"about\", \"users/[id]\", \"auth\")"
+						},
+						method: {
+							type: "string",
+							description: "HTTP method for API routes",
+							enum: [
+								"GET",
+								"POST",
+								"PUT",
+								"PATCH",
+								"DELETE"
+							]
+						},
+						schedule: {
+							type: "string",
+							description: "Cron schedule expression (e.g., \"0 0 * * *\" for daily at midnight)"
+						}
+					},
+					required: ["type", "path"]
+				}
+			},
+			{
+				name: "delete_resource",
+				description: "Delete a resource (creates backup by default)",
+				parameters: {
+					type: "object",
+					properties: {
+						type: {
+							type: "string",
+							description: "Type of resource to delete",
+							enum: [
+								"page",
+								"api",
+								"layout",
+								"middleware",
+								"cron",
+								"plugin"
+							]
+						},
+						path: {
+							type: "string",
+							description: "Resource path"
+						},
+						force: {
+							type: "boolean",
+							description: "Permanently delete without backup"
+						}
+					},
+					required: ["type", "path"]
+				}
+			},
+			{
+				name: "get_project_info",
+				description: "Get project overview information (version, uptime, counts, config)",
+				parameters: {
+					type: "object",
+					properties: {}
+				}
+			},
+			{
+				name: "read_resource",
+				description: "Read the content of a resource file",
+				parameters: {
+					type: "object",
+					properties: {
+						type: {
+							type: "string",
+							description: "Resource type",
+							enum: [
+								"page",
+								"api",
+								"layout",
+								"middleware",
+								"cron",
+								"env",
+								"config"
+							]
+						},
+						path: {
+							type: "string",
+							description: "Resource path (not needed for env/config)"
+						}
+					},
+					required: ["type"]
+				}
+			},
+			{
+				name: "set_env",
+				description: "Set or update an environment variable",
+				parameters: {
+					type: "object",
+					properties: {
+						key: {
+							type: "string",
+							description: "Environment variable name"
+						},
+						value: {
+							type: "string",
+							description: "Environment variable value"
+						}
+					},
+					required: ["key", "value"]
+				}
+			}
+		];
+	}
+	async function executeToolCall(call) {
+		try {
+			const args = call.arguments;
+			switch (call.name) {
+				case "list_resources": {
+					const type = args.type;
+					const info = getInfo();
+					const result = {};
+					if (type === "pages" || type === "all") result.pages = info.pagesList?.map((p) => ({
+						path: p.path,
+						name: p.name,
+						file: p.filePath
+					})) || [];
+					if (type === "apis" || type === "all") result.apis = info.routes?.filter((r) => r.filePath).map((r) => ({
+						method: r.method,
+						path: r.path,
+						file: r.filePath
+					})) || [];
+					if (type === "layouts" || type === "all") result.layouts = info.layoutsList?.map((l) => ({
+						name: l.name,
+						path: l.path,
+						default: l.isDefault,
+						file: l.filePath
+					})) || [];
+					if (type === "middlewares" || type === "all") result.middlewares = info.middlewaresList?.map((m) => ({
+						path: m.path,
+						global: m.global,
+						file: m.filePath
+					})) || [];
+					if (type === "crons" || type === "all") result.crons = info.cronsList?.map((c) => ({
+						name: c.name,
+						schedule: c.schedule,
+						file: c.filePath
+					})) || [];
+					return {
+						toolCallId: call.id,
+						result
+					};
+				}
+				case "create_resource": {
+					const result = await crud.create({
+						type: args.type,
+						path: args.path,
+						method: args.method,
+						schedule: args.schedule,
+						force: false
+					});
+					return {
+						toolCallId: call.id,
+						result
+					};
+				}
+				case "delete_resource": {
+					const result = await crud.delete({
+						type: args.type,
+						path: args.path,
+						force: args.force || false
+					});
+					return {
+						toolCallId: call.id,
+						result
+					};
+				}
+				case "get_project_info": {
+					const info = getInfo();
+					return {
+						toolCallId: call.id,
+						result: {
+							version: info.version,
+							uptime: Date.now() - info.startTime,
+							pages: info.pages,
+							apiRoutes: info.apiRoutes,
+							middlewares: info.middleware,
+							layouts: info.layouts,
+							crons: info.crons,
+							presets: info.presets
+						}
+					};
+				}
+				case "read_resource": {
+					const result = await crud.read({
+						type: args.type,
+						path: args.path
+					});
+					return {
+						toolCallId: call.id,
+						result
+					};
+				}
+				case "set_env": {
+					const result = await crud.update({
+						type: "env",
+						key: args.key,
+						value: args.value
+					});
+					return {
+						toolCallId: call.id,
+						result
+					};
+				}
+				default: return {
+					toolCallId: call.id,
+					error: `Unknown tool: ${call.name}`
+				};
+			}
+		} catch (err) {
+			return {
+				toolCallId: call.id,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+	}
+	function parseCommand(input) {
+		const lower = input.trim().toLowerCase();
+		const createMatch = input.match(/^(?:create|add|new|make|generate|scaffold|g)\s+(?:a\s+)?(page|api|layout|middleware|cron|plugin)\s+(?:at\s+)?["']?([\w\-/[\].]+)["']?(?:\s+(?:with|using)\s+(?:method\s+)?(GET|POST|PUT|PATCH|DELETE))?(?:\s+(?:schedule|cron)?\s+["']?([*\d/\-,\s]+)["']?)?/i);
+		if (createMatch) {
+			const [, type, path, method, schedule] = createMatch;
+			const params = {
+				type: type.toLowerCase(),
+				path
+			};
+			if (method) params.method = method.toUpperCase();
+			if (schedule) params.schedule = schedule.trim();
+			return { toolCalls: [{
+				id: nextToolId(),
+				name: "create_resource",
+				arguments: params
+			}] };
+		}
+		const deleteMatch = input.match(/^(?:delete|remove|rm|del)\s+(?:the\s+)?(page|api|layout|middleware|cron|plugin)\s+(?:at\s+)?["']?([\w\-/[\].]+)["']?/i);
+		if (deleteMatch) {
+			const [, type, path] = deleteMatch;
+			return { toolCalls: [{
+				id: nextToolId(),
+				name: "delete_resource",
+				arguments: {
+					type: type.toLowerCase(),
+					path,
+					force: lower.includes("force") || lower.includes("permanent")
+				}
+			}] };
+		}
+		const listMatch = input.match(/^(?:list|show|ls|get)\s+(all|pages|apis?|layouts?|middlewares?|crons?)(?:\s*$)/i);
+		if (listMatch) {
+			let type = listMatch[1].toLowerCase();
+			if (type === "all") type = "all";
+			else if (type.startsWith("api")) type = "apis";
+			else if (type.startsWith("layout")) type = "layouts";
+			else if (type.startsWith("middleware")) type = "middlewares";
+			else if (type.startsWith("cron")) type = "crons";
+			else type = "pages";
+			return { toolCalls: [{
+				id: nextToolId(),
+				name: "list_resources",
+				arguments: { type }
+			}] };
+		}
+		if (/^(?:project\s+)?(?:info|status|overview|stats|about)$/i.test(input.trim())) return { toolCalls: [{
+			id: nextToolId(),
+			name: "get_project_info",
+			arguments: {}
+		}] };
+		if (/^(help|\?|commands|what can you do)/i.test(input.trim())) return { response: `I can help you with the following:
+
+**Create resources:**
+- \`create page about\` — Create a new page at /about
+- \`create api users with method POST\` — Create a POST API route
+- \`create cron daily-cleanup schedule "0 0 * * *"\` — Create a daily cron job
+- \`create layout admin\` — Create an admin layout
+
+**Delete resources:**
+- \`delete page about\` — Delete a page (with backup)
+- \`delete api users --force\` — Permanently delete an API
+
+**Inspect project:**
+- \`list pages\` / \`list apis\` / \`list all\` — List resources
+- \`project info\` — Show project overview
+
+**Environment:**
+- \`set env DATABASE_URL=postgres://...\` — Set environment variable
+
+You can also ask me questions in natural language, or configure a DeepSeek/OpenAI-compatible API key for more advanced AI assistance.` };
+		const setEnvMatch = input.match(/^(?:set\s+env|env\s+set|add\s+env)\s+(\w+)\s*=\s*(.+)$/i);
+		if (setEnvMatch) return { toolCalls: [{
+			id: nextToolId(),
+			name: "set_env",
+			arguments: {
+				key: setEnvMatch[1],
+				value: setEnvMatch[2].trim()
+			}
+		}] };
+		return null;
+	}
+	function formatToolResult(name, result) {
+		if (name === "list_resources") {
+			const r = result;
+			const lines = [];
+			for (const [key, items] of Object.entries(r)) {
+				lines.push(`**${key}** (${items.length}):`);
+				for (const item of items.slice(0, 20)) {
+					const obj = item;
+					const path = obj.path || obj.name || "";
+					const extra = obj.method ? ` [${obj.method}]` : obj.default ? " (default)" : "";
+					lines.push(`  - ${path}${extra}`);
+				}
+				if (items.length > 20) lines.push(`  ... and ${items.length - 20} more`);
+				lines.push("");
+			}
+			return lines.join("\n");
+		}
+		if (name === "create_resource") {
+			const r = result;
+			if (r.success && r.created?.length) return `✅ Created successfully:\n${r.created.map((f) => `  - ${f}`).join("\n")}`;
+			if (r.errors?.length) return `❌ Failed: ${r.errors.join(", ")}`;
+			if (r.skipped?.length) return `⚠️ Skipped (already exists, use --force to overwrite):\n${r.skipped.map((f) => `  - ${f}`).join("\n")}`;
+			return JSON.stringify(result, null, 2);
+		}
+		if (name === "delete_resource") {
+			const r = result;
+			if (r.success && r.deleted?.length) return `🗑️ Deleted successfully:\n${r.deleted.map((f) => `  - ${f}`).join("\n")}`;
+			if (r.errors?.length) return `❌ Failed: ${r.errors.join(", ")}`;
+			return JSON.stringify(result, null, 2);
+		}
+		if (name === "get_project_info") {
+			const r = result;
+			const uptimeMs = r.uptime;
+			const s = Math.floor(uptimeMs / 1e3);
+			const m = Math.floor(s / 60);
+			const h = Math.floor(m / 60);
+			const uptime = h > 0 ? `${h}h ${m % 60}m` : m > 0 ? `${m}m ${s % 60}s` : `${s}s`;
+			return `**Project Info:**
+- Version: ${r.version}
+- Uptime: ${uptime}
+- Pages: ${r.pages}
+- API Routes: ${r.apiRoutes}
+- Middlewares: ${r.middlewares}
+- Layouts: ${r.layouts}
+- Cron Jobs: ${r.crons}
+- Presets: ${r.presets.join(", ") || "none"}`;
+		}
+		if (name === "set_env") {
+			const r = result;
+			if (r.success) return "✅ Environment variable set successfully.";
+			return `❌ Failed: ${r.errors?.join(", ") || "Unknown error"}`;
+		}
+		if (name === "read_resource") {
+			const r = result;
+			if (r.error) return `❌ ${r.error}`;
+			if (r.content) return `\`\`\`\n${r.content}\n\`\`\``;
+			if (r.data) return `\`\`\`json\n${JSON.stringify(r.data, null, 2)}\n\`\`\``;
+			return "(empty)";
+		}
+		return JSON.stringify(result, null, 2);
+	}
+	function convertToCoreMessages(messages) {
+		return messages.filter((m) => m.role !== "tool" || m.toolCallId).map((m) => {
+			if (m.role === "assistant" && m.toolCalls?.length) return {
+				role: "assistant",
+				content: [...m.content ? [{
+					type: "text",
+					text: m.content
+				}] : [], ...m.toolCalls.map((tc) => ({
+					type: "tool-call",
+					toolCallId: tc.id,
+					toolName: tc.name,
+					input: tc.arguments
+				}))]
+			};
+			if (m.role === "tool") return {
+				role: "tool",
+				content: [{
+					type: "tool-result",
+					toolCallId: m.toolCallId,
+					toolName: "tool",
+					output: {
+						type: "json",
+						value: typeof m.content === "string" ? m.content : JSON.parse(m.content)
+					}
+				}]
+			};
+			return {
+				role: m.role,
+				content: m.content
+			};
+		});
+	}
+	async function buildAiSdkTools() {
+		const ai = await import("ai");
+		const defs = getToolDefinitions();
+		const tools = {};
+		for (const def of defs) tools[def.name] = ai.tool({
+			description: def.description,
+			inputSchema: ai.jsonSchema(def.parameters),
+			execute: async (args) => {
+				const result = await executeToolCall({
+					id: nextToolId(),
+					name: def.name,
+					arguments: args
+				});
+				return result.error ? { error: result.error } : result.result;
+			}
+		});
+		return tools;
+	}
+	async function chat(options) {
+		const { messages, apiKey, apiBase, model, requestId } = options;
+		const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+		if (!lastUserMsg) return { message: {
+			role: "assistant",
+			content: "Hello! I am ubean Assistant. Type \"help\" to see what I can do.",
+			timestamp: Date.now()
+		} };
+		const parsed = parseCommand(lastUserMsg.content);
+		if (parsed?.response) return { message: {
+			role: "assistant",
+			content: parsed.response,
+			timestamp: Date.now()
+		} };
+		if (parsed?.toolCalls && parsed.toolCalls.length > 0) {
+			const toolResults = [];
+			for (const call of parsed.toolCalls) {
+				const result = await executeToolCall(call);
+				toolResults.push(result);
+			}
+			const responseParts = [];
+			for (let i = 0; i < parsed.toolCalls.length; i++) {
+				const call = parsed.toolCalls[i];
+				const tr = toolResults[i];
+				if (tr.error) responseParts.push(`❌ Error executing ${call.name}: ${tr.error}`);
+				else responseParts.push(formatToolResult(call.name, tr.result));
+			}
+			return {
+				message: {
+					role: "assistant",
+					content: responseParts.join("\n\n"),
+					toolCalls: parsed.toolCalls,
+					timestamp: Date.now()
+				},
+				toolResults
+			};
+		}
+		const resolvedApiKey = apiKey || process.env.DEEPSEEK_API_KEY || process.env.UBEAN_AI_API_KEY || process.env.OPENAI_API_KEY;
+		const resolvedApiBase = apiBase || process.env.UBEAN_AI_API_BASE || "https://api.deepseek.com/v1";
+		const resolvedModel = model || process.env.UBEAN_AI_MODEL || "deepseek-chat";
+		if (resolvedApiKey) try {
+			return await callLlmApi({
+				messages,
+				apiKey: resolvedApiKey,
+				apiBase: resolvedApiBase,
+				model: resolvedModel,
+				requestId
+			});
+		} catch (err) {
+			return { message: {
+				role: "assistant",
+				content: `I didn't understand that command. Type "help" to see available commands.\n\n(LLM API error: ${err instanceof Error ? err.message : String(err)})`,
+				timestamp: Date.now()
+			} };
+		}
+		return { message: {
+			role: "assistant",
+			content: `I didn't understand that command. Type "help" to see what I can do.\n\nTip: For natural language assistance, configure a DeepSeek or OpenAI-compatible API endpoint:\n\n\`\`\`ts\n// ubean.config.ts\nexport default defineConfig({\n  devtools: {\n    ai: {\n      apiKey: process.env.DEEPSEEK_API_KEY,\n      apiBase: 'https://api.deepseek.com/v1',\n      model: 'deepseek-chat'\n    }\n  }\n});\n\`\`\`\n\nOr set the \`DEEPSEEK_API_KEY\` environment variable.`,
+			timestamp: Date.now()
+		} };
+	}
+	async function callLlmApi(options) {
+		const { messages, apiKey, apiBase, model, requestId } = options;
+		const [{ streamText, stepCountIs }, { createOpenAICompatible }] = await Promise.all([import("ai"), import("@ai-sdk/openai-compatible")]);
+		const aiModel = createOpenAICompatible({
+			baseURL: apiBase,
+			name: apiBase.includes("deepseek") ? DEEPSEEK_PROVIDER_NAME : "ubean-ai",
+			apiKey
+		}).chatModel(model);
+		const coreMessages = convertToCoreMessages(messages);
+		const tools = await buildAiSdkTools();
+		const result = streamText({
+			model: aiModel,
+			system: SYSTEM_PROMPT,
+			messages: coreMessages,
+			tools,
+			stopWhen: stepCountIs(5)
+		});
+		let accumulated = "";
+		const streamToolCalls = [];
+		const streamToolResults = [];
+		let streamError;
+		if (requestId && onStreamChunk) {
+			try {
+				for await (const part of result.fullStream) switch (part.type) {
+					case "text-delta":
+						accumulated += part.text;
+						onStreamChunk({
+							requestId,
+							text: accumulated,
+							done: false
+						});
+						break;
+					case "tool-call":
+						streamToolCalls.push({
+							id: part.toolCallId,
+							name: part.toolName,
+							arguments: part.input
+						});
+						onStreamChunk({
+							requestId,
+							text: accumulated,
+							done: false,
+							toolCalls: [...streamToolCalls]
+						});
+						break;
+					case "tool-result":
+						streamToolResults.push({
+							toolCallId: part.toolCallId,
+							result: part.output
+						});
+						onStreamChunk({
+							requestId,
+							text: accumulated,
+							done: false,
+							toolCalls: [...streamToolCalls],
+							toolResults: [...streamToolResults]
+						});
+						break;
+					case "error":
+						streamError = part.error instanceof Error ? part.error.message : String(part.error);
+						break;
+				}
+			} catch (err) {
+				streamError = err instanceof Error ? err.message : String(err);
+			}
+			if (streamError) {
+				onStreamChunk({
+					requestId,
+					text: accumulated,
+					done: true,
+					error: streamError
+				});
+				return {
+					message: {
+						role: "assistant",
+						content: accumulated || `Error: ${streamError}`,
+						toolCalls: streamToolCalls.length ? streamToolCalls : void 0,
+						timestamp: Date.now()
+					},
+					toolResults: streamToolResults.length ? streamToolResults : void 0
+				};
+			}
+		} else try {
+			for await (const _ of result.fullStream) {
+				if (_.type === "text-delta") accumulated += _.text;
+				if (_.type === "tool-call") streamToolCalls.push({
+					id: _.toolCallId,
+					name: _.toolName,
+					arguments: _.input
+				});
+				if (_.type === "tool-result") streamToolResults.push({
+					toolCallId: _.toolCallId,
+					result: _.output
+				});
+				if (_.type === "error") streamError = _.error instanceof Error ? _.error.message : String(_.error);
+			}
+		} catch (err) {
+			streamError = err instanceof Error ? err.message : String(err);
+		}
+		return {
+			message: {
+				role: "assistant",
+				content: accumulated || (streamError ? `Error: ${streamError}` : ""),
+				toolCalls: streamToolCalls.length ? streamToolCalls : void 0,
+				timestamp: Date.now()
+			},
+			toolResults: streamToolResults.length ? streamToolResults : void 0
+		};
+	}
+	return {
+		getToolDefinitions,
+		executeToolCall,
+		chat,
+		parseCommand,
+		formatToolResult
+	};
+}
+//#endregion
+//#region src/server/crud.ts
+const SCAFFOLD_TYPES = [
+	"page",
+	"api",
+	"layout",
+	"middleware",
+	"reuse"
+];
+const SCAFFOLD_TYPE_SET = new Set(SCAFFOLD_TYPES);
+function createCrudServer(options) {
+	const { cwd, hooks, getEnv, setEnv, getConfig, onFileChange, scaffoldOps } = options;
+	if (!scaffoldOps) throw new Error("[ubean:devtools] scaffoldOps is required for CRUD server. Make sure to pass scaffold functions via ubeanDevtoolsPlugin options.");
+	const fs = scaffoldOps.createFsOps(cwd);
+	/**
+	* Determine the correct base directory for a scaffold type, taking the
+	* project's `dir` config into account. Returns an absolute path.
+	*
+	* For the 'api' type:
+	*   1. Use `config.dir.routes` (default 'routes') relative to srcDir.
+	*   2. If that directory doesn't exist, fall back to src/routes.
+	*
+	* For other types, the scaffold function's built-in defaults are used.
+	*/
+	function getBaseDirForType(type) {
+		if (type !== "api") return void 0;
+		const config = getConfig?.() ?? {};
+		const dir = config.dir ?? {};
+		const rawSrcDir = config.srcDir || "src";
+		const srcDir = isAbsolute(rawSrcDir) ? rawSrcDir : resolve(cwd, rawSrcDir);
+		const primaryDir = join(srcDir, dir.routes || "routes");
+		if (existsSync(primaryDir)) return primaryDir;
+		const fallbackDir = join(srcDir, "routes");
+		if (existsSync(fallbackDir)) return fallbackDir;
+		return primaryDir;
+	}
+	function normalizeResult(scaffoldRes) {
+		return {
+			success: !(scaffoldRes.errors && scaffoldRes.errors.length > 0),
+			created: scaffoldRes.created,
+			deleted: scaffoldRes.deleted,
+			restored: scaffoldRes.restored,
+			skipped: scaffoldRes.skipped,
+			errors: scaffoldRes.errors
+		};
+	}
+	async function notifyChange() {
+		if (onFileChange) await onFileChange();
+	}
+	async function create(params) {
+		const { type, path, method, schedule, content, force } = params;
+		if (hooks) await hooks.runHook("beforeCreate", {
+			type,
+			path,
+			content
+		});
+		try {
+			let result;
+			if (SCAFFOLD_TYPE_SET.has(type)) {
+				const baseDir = getBaseDirForType(type);
+				const scaffoldRes = await scaffoldOps?.scaffold({
+					cwd,
+					type,
+					path,
+					method,
+					force,
+					dry: false,
+					...baseDir ? { baseDir } : {}
+				});
+				if (content && scaffoldRes?.created?.length) await fs.writeFile(scaffoldRes.created[0], content);
+				result = normalizeResult(scaffoldRes || {});
+			} else if (type === "cron") {
+				const cronDir = "src/server/crons";
+				const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+				const filePath = join(cronDir, normalizedPath.endsWith(".ts") ? normalizedPath : `${normalizedPath}.ts`);
+				if (await fs.exists(filePath) && !force) result = {
+					success: false,
+					skipped: [filePath],
+					errors: ["File already exists"]
+				};
+				else {
+					const cronContent = content || `import { defineScheduled } from 'ubean';
+
+export default defineScheduled({
+  schedule: '${schedule || "* * * * *"}',
+  async run() {
+    console.log('Cron job running');
+  }
+});
+`;
+					await fs.writeFile(filePath, cronContent);
+					result = {
+						success: true,
+						created: [filePath]
+					};
+				}
+			} else if (type === "plugin") {
+				const pluginDir = "src/plugins";
+				const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+				const fileName = normalizedPath.endsWith(".ts") ? normalizedPath : `${normalizedPath}.ts`;
+				const filePath = join(pluginDir, fileName);
+				if (await fs.exists(filePath) && !force) result = {
+					success: false,
+					skipped: [filePath],
+					errors: ["File already exists"]
+				};
+				else {
+					const pluginContent = content || `import { definePlugin } from 'ubean';
+
+export default definePlugin({
+  name: '${fileName.replace(/\.ts$/, "").replace(/[^\w]/g, "-")}',
+  setup() {
+    console.log('Plugin loaded');
+  }
+});
+`;
+					await fs.writeFile(filePath, pluginContent);
+					result = {
+						success: true,
+						created: [filePath]
+					};
+				}
+			} else result = {
+				success: false,
+				errors: [`Unsupported resource type: ${type}`]
+			};
+			if (hooks) await hooks.runHook("afterCreate", {
+				type,
+				path,
+				content
+			});
+			if (result.success) await notifyChange();
+			return result;
+		} catch (err) {
+			return {
+				success: false,
+				errors: [err instanceof Error ? err.message : String(err)]
+			};
+		}
+	}
+	async function read(params) {
+		const { type, path } = params;
+		try {
+			if (type === "env") {
+				if (getEnv) return {
+					success: true,
+					data: getEnv()
+				};
+				return {
+					success: false,
+					error: "Env not available"
+				};
+			}
+			if (type === "config") {
+				if (path) {
+					if (!await fs.exists(path)) return {
+						success: false,
+						error: `File not found: ${path}`
+					};
+					return {
+						success: true,
+						content: await fs.readFile(path)
+					};
+				}
+				if (getConfig) return {
+					success: true,
+					data: getConfig()
+				};
+				return {
+					success: false,
+					error: "Config not available"
+				};
+			}
+			if (!path) return {
+				success: false,
+				error: "Path is required for file read"
+			};
+			if (SCAFFOLD_TYPE_SET.has(type) || type === "cron" || type === "plugin") {
+				if (!await fs.exists(path)) return {
+					success: false,
+					error: `File not found: ${path}`
+				};
+				return {
+					success: true,
+					content: await fs.readFile(path)
+				};
+			}
+			return {
+				success: false,
+				error: `Unsupported resource type: ${type}`
+			};
+		} catch (err) {
+			return {
+				success: false,
+				error: err instanceof Error ? err.message : String(err)
+			};
+		}
+	}
+	async function update(params) {
+		const { type, path, key, content, value } = params;
+		if (hooks) await hooks.runHook("beforeUpdate", {
+			type,
+			path,
+			key,
+			content,
+			value
+		});
+		try {
+			let result;
+			if (type === "env") if (!key) result = {
+				success: false,
+				errors: ["Key is required for env update"]
+			};
+			else if (!setEnv || !getEnv) result = {
+				success: false,
+				errors: ["Env not available"]
+			};
+			else {
+				const env = { ...getEnv() };
+				if (value !== void 0) env[key] = value;
+				else delete env[key];
+				setEnv(env);
+				result = {
+					success: true,
+					updated: [`env:${key}`]
+				};
+			}
+			else if (type === "config") if (!path) result = {
+				success: false,
+				errors: ["Path is required for config file update"]
+			};
+			else if (!await fs.exists(path)) result = {
+				success: false,
+				errors: [`File not found: ${path}`]
+			};
+			else {
+				await fs.writeFile(path, content || "");
+				result = {
+					success: true,
+					updated: [path]
+				};
+			}
+			else if (!path) result = {
+				success: false,
+				errors: ["Path is required for file update"]
+			};
+			else if (SCAFFOLD_TYPE_SET.has(type) || type === "cron" || type === "plugin") if (!await fs.exists(path)) result = {
+				success: false,
+				errors: [`File not found: ${path}`]
+			};
+			else {
+				await fs.writeFile(path, content || "");
+				result = {
+					success: true,
+					updated: [path]
+				};
+			}
+			else result = {
+				success: false,
+				errors: [`Unsupported resource type: ${type}`]
+			};
+			if (hooks) await hooks.runHook("afterUpdate", {
+				type,
+				path,
+				key,
+				content,
+				value
+			});
+			if (result.success) await notifyChange();
+			return result;
+		} catch (err) {
+			return {
+				success: false,
+				errors: [err instanceof Error ? err.message : String(err)]
+			};
+		}
+	}
+	async function del(params) {
+		const { type, path, key, force } = params;
+		if (hooks) await hooks.runHook("beforeDelete", {
+			type,
+			path,
+			key
+		});
+		try {
+			let result;
+			if (type === "env") if (!key) result = {
+				success: false,
+				errors: ["Key is required for env delete"]
+			};
+			else if (!setEnv || !getEnv) result = {
+				success: false,
+				errors: ["Env not available"]
+			};
+			else {
+				const env = { ...getEnv() };
+				delete env[key];
+				setEnv(env);
+				result = {
+					success: true,
+					deleted: [`env:${key}`]
+				};
+			}
+			else if (!path) result = {
+				success: false,
+				errors: ["Path is required for file delete"]
+			};
+			else if (SCAFFOLD_TYPE_SET.has(type)) {
+				const baseDir = getBaseDirForType(type);
+				result = normalizeResult(await scaffoldOps?.deleteScaffold({
+					cwd,
+					type,
+					path,
+					force,
+					dry: false,
+					...baseDir ? { baseDir } : {}
+				}) || {});
+			} else if (type === "cron" || type === "plugin") if (!await fs.exists(path)) result = {
+				success: false,
+				errors: [`File not found: ${path}`]
+			};
+			else {
+				if (force) await fs.remove(path);
+				else await fs.createBackup(path, { removeOriginal: true });
+				result = {
+					success: true,
+					deleted: [path]
+				};
+			}
+			else result = {
+				success: false,
+				errors: [`Unsupported resource type: ${type}`]
+			};
+			if (hooks) await hooks.runHook("afterDelete", {
+				type,
+				path,
+				key
+			});
+			if (result.success) await notifyChange();
+			return result;
+		} catch (err) {
+			return {
+				success: false,
+				errors: [err instanceof Error ? err.message : String(err)]
+			};
+		}
+	}
+	async function restore(path) {
+		try {
+			for (const type of SCAFFOLD_TYPES) {
+				const baseDir = getBaseDirForType(type);
+				const scaffoldRes = await scaffoldOps?.recoverScaffold({
+					cwd,
+					type,
+					path,
+					dry: false,
+					...baseDir ? { baseDir } : {}
+				});
+				if (scaffoldRes?.restored?.length) {
+					await notifyChange();
+					return normalizeResult(scaffoldRes);
+				}
+			}
+			const backupPath = `${path}.bak`;
+			if (await fs.exists(backupPath)) {
+				await fs.copyFile(backupPath, path);
+				await fs.removeBackup(path);
+				await notifyChange();
+				return {
+					success: true,
+					restored: [path]
+				};
+			}
+			return {
+				success: false,
+				errors: [`No backup found for ${path}`]
+			};
+		} catch (err) {
+			return {
+				success: false,
+				errors: [err instanceof Error ? err.message : String(err)]
+			};
+		}
+	}
+	return {
+		create,
+		read,
+		update,
+		delete: del,
+		restore
+	};
+}
+//#endregion
+//#region src/server/terminal.ts
+/**
+* Terminal session manager — spawns shell processes and buffers output
+* for polling-based retrieval by the xterm.js frontend.
+*
+* On macOS/Linux, uses Python's `pty` module to create a real pseudo-terminal.
+* This gives the shell (bash/zsh) a proper TTY, enabling:
+*   - Input echo (characters appear as you type)
+*   - Line editing (arrow keys, Ctrl+A/E, etc.)
+*   - Tab completion
+*   - Full TUI apps (vim, htop, etc.)
+*
+* Python3 is pre-installed on macOS (via Xcode CLT) and most Linux distros.
+* If Python3 is not available, falls back to direct shell spawn without a PTY
+* (commands still execute, but without echo or line editing).
+*
+* On Windows, cmd.exe/PowerShell work natively with pipe stdio — no PTY needed.
+*/
+/**
+* Python one-liner that creates a PTY and spawns the given command.
+* `pty.spawn` handles fork/exec/relay: the child gets the PTY slave as its
+* controlling terminal, while the parent relays between its own stdin/stdout
+* and the PTY master. This gives the shell a real TTY with full interactive
+* features (echo, readline, TUI support).
+*/
+const PTY_SCRIPT = "import pty, sys; pty.spawn(sys.argv[1:])";
+let _pythonAvailable = null;
+function isPythonAvailable() {
+	if (_pythonAvailable !== null) return _pythonAvailable;
+	if (process.platform === "win32") {
+		_pythonAvailable = false;
+		return false;
+	}
+	try {
+		execSync("python3 --version", {
+			stdio: "ignore",
+			timeout: 3e3
+		});
+		_pythonAvailable = true;
+	} catch {
+		_pythonAvailable = false;
+	}
+	return _pythonAvailable;
+}
+/** Warning messages from bash/zsh when running -i without a real TTY (fallback only). */
+const TTY_WARNING_RE = /^(?:bash|zsh):\s+(?:cannot set terminal process group|no job control in this shell)/;
+function createTerminalServer() {
+	const sessions = /* @__PURE__ */ new Map();
+	function getDefaultShell() {
+		if (process.platform === "win32") return process.env.COMSPEC || "cmd.exe";
+		return process.env.SHELL || "/bin/bash";
+	}
+	/**
+	* Build the spawn command for the current platform.
+	*
+	* On macOS/Linux with Python3 available: wraps the shell in `python3 -c`
+	* with a `pty.spawn` script so the shell gets a real PTY. Without Python3,
+	* spawns the shell directly (degraded experience: no echo, no readline).
+	* On Windows: spawns cmd.exe/PowerShell directly (pipes work natively).
+	*/
+	function buildSpawnCommand(shell, shellArgs) {
+		if (process.platform === "win32") return {
+			command: shell,
+			args: shellArgs,
+			usingPty: false
+		};
+		if (isPythonAvailable()) return {
+			command: "python3",
+			args: [
+				"-c",
+				PTY_SCRIPT,
+				shell,
+				...shellArgs
+			],
+			usingPty: true
+		};
+		return {
+			command: shell,
+			args: shellArgs,
+			usingPty: false
+		};
+	}
+	function start(params) {
+		const id = randomUUID();
+		const { command, args, usingPty } = buildSpawnCommand(params.shell || getDefaultShell(), process.platform === "win32" ? [] : ["-i"]);
+		const cols = params.cols || 80;
+		const rows = params.rows || 24;
+		const proc = spawn(command, args, {
+			cwd: params.cwd,
+			env: {
+				...process.env,
+				TERM: "xterm-256color",
+				COLORTERM: "truecolor",
+				FORCE_COLOR: "1",
+				UBEAN_TERM_COLS: String(cols),
+				UBEAN_TERM_ROWS: String(rows),
+				LSCOLORS: "Gxfxcxdxbxegedabagacad",
+				LS_COLORS: "di=34:ln=36:so=35:pi=33:ex=32:bd=34:cd=34:su=41;37:sg=41;37:tw=42;37:ow=42;37"
+			},
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		const session = {
+			id,
+			proc,
+			cwd: params.cwd,
+			cols,
+			rows,
+			buffer: "",
+			exited: false,
+			exitCode: null
+		};
+		if (!usingPty && process.platform !== "win32") session.buffer += "\x1B[33m⚠ Terminal running without PTY (python3 not found).\r\n   Commands execute but input echo and line editing are disabled.\r\n   Install python3 for full terminal support.\x1B[0m\r\n\r\n";
+		proc.stdout?.on("data", (data) => {
+			session.buffer += data.toString();
+		});
+		proc.stderr?.on("data", (data) => {
+			const text = data.toString();
+			if (usingPty) session.buffer += text;
+			else {
+				const lines = text.split("\n").filter((line) => !TTY_WARNING_RE.test(line.trim()));
+				if (lines.length > 0) session.buffer += lines.join("\n");
+			}
+		});
+		proc.on("exit", (code) => {
+			session.exited = true;
+			session.exitCode = code;
+			session.buffer += `\r\n\x1b[2m[Process exited with code ${code}]\x1b[0m\r\n`;
+		});
+		proc.on("error", (err) => {
+			session.buffer += `\r\n\x1b[31m[Error: ${err.message}]\x1b[0m\r\n`;
+			session.exited = true;
+			session.exitCode = -1;
+		});
+		sessions.set(id, session);
+		return { sessionId: id };
+	}
+	function input(sessionId, data) {
+		const session = sessions.get(sessionId);
+		if (!session || !session.proc || session.exited) return false;
+		session.proc.stdin?.write(data);
+		return true;
+	}
+	function resize(sessionId, cols, rows) {
+		const session = sessions.get(sessionId);
+		if (!session) return false;
+		session.cols = cols;
+		session.rows = rows;
+		return true;
+	}
+	function poll(sessionId) {
+		const session = sessions.get(sessionId);
+		if (!session) return {
+			data: "",
+			exited: true,
+			exitCode: -1
+		};
+		const data = session.buffer;
+		session.buffer = "";
+		return {
+			data,
+			exited: session.exited,
+			exitCode: session.exitCode
+		};
+	}
+	function kill(sessionId) {
+		const session = sessions.get(sessionId);
+		if (!session) return false;
+		if (session.proc && !session.exited) try {
+			session.proc.kill("SIGTERM");
+		} catch {}
+		sessions.delete(sessionId);
+		return true;
+	}
+	function killAll() {
+		for (const id of sessions.keys()) kill(id);
+	}
+	return {
+		start,
+		input,
+		resize,
+		poll,
+		kill,
+		killAll
+	};
+}
+//#endregion
+//#region ../../node_modules/.pnpm/devframe@0.7.14_cac@7.0.0_srvx@0.11.22_typescript@6.0.3/node_modules/devframe/dist/define-BLWPsH6y.mjs
+function createDefineWrapperWithContext() {
+	return function defineRpcFunctionWithContext(definition) {
+		return definition;
+	};
+}
+//#endregion
+//#region ../../node_modules/.pnpm/@vitejs+devtools-kit@0.4.8_@voidzero-dev+vite-plus-core@0.2.6_cac@7.0.0_srvx@0.11.22_typescript@6.0.3/node_modules/@vitejs/devtools-kit/dist/index.js
+const defineRpcFunction = createDefineWrapperWithContext();
+//#endregion
+//#region src/node/rpc/ai.ts
+/**
+* AI RPC functions — `ubean:ai:tools`, `ubean:ai:chat`, and `ubean:ai:chat-stream`.
+*
+* `ubean:ai:chat` — non-streaming chat (returns full response).
+* `ubean:ai:chat-stream` — streaming chat; pushes chunks to the
+*   `ubean:ai:stream` sharedState key via the `onStreamChunk` callback
+*   wired in `createAiServer`. The client subscribes to that sharedState
+*   and filters by `requestId`.
+*/
+function createAiRpcFunctions(ai) {
+	return [
+		defineRpcFunction({
+			name: "ubean:ai:tools",
+			type: "query",
+			setup: () => ({ handler: () => ai.getToolDefinitions() })
+		}),
+		defineRpcFunction({
+			name: "ubean:ai:chat",
+			type: "action",
+			setup: () => ({ handler: (params) => ai.chat({
+				messages: params.messages,
+				apiKey: params.apiKey,
+				apiBase: params.apiBase,
+				model: params.model
+			}) })
+		}),
+		defineRpcFunction({
+			name: "ubean:ai:chat-stream",
+			type: "action",
+			setup: () => ({ handler: (params) => ai.chat({
+				messages: params.messages,
+				apiKey: params.apiKey,
+				apiBase: params.apiBase,
+				model: params.model,
+				requestId: params.requestId
+			}) })
+		})
+	];
+}
+//#endregion
+//#region src/node/rpc/crud.ts
+/**
+* CRUD RPC functions — `ubean:crud:create/read/update/delete/restore`.
+*
+* Each function delegates to the existing `createCrudServer` which
+* encapsulates all file-scaffolding, backup, and hook logic. The RPC
+* layer is purely a transport adapter.
+*/
+function createCrudRpcFunctions(crud) {
+	return [
+		defineRpcFunction({
+			name: "ubean:crud:create",
+			type: "action",
+			setup: () => ({ handler: (params) => crud.create(params) })
+		}),
+		defineRpcFunction({
+			name: "ubean:crud:read",
+			type: "query",
+			setup: () => ({ handler: (params) => crud.read(params) })
+		}),
+		defineRpcFunction({
+			name: "ubean:crud:update",
+			type: "action",
+			setup: () => ({ handler: (params) => crud.update(params) })
+		}),
+		defineRpcFunction({
+			name: "ubean:crud:delete",
+			type: "action",
+			setup: () => ({ handler: (params) => crud.delete(params) })
+		}),
+		defineRpcFunction({
+			name: "ubean:crud:restore",
+			type: "action",
+			setup: () => ({ handler: (path) => crud.restore(path) })
+		})
+	];
+}
+//#endregion
+//#region src/node/rpc/info.ts
+/**
+* Info RPC functions — `ubean:get-info` and `ubean:get-env`.
+*
+* In the sharedState model, `ubean:get-info` is a fallback for clients
+* that haven't subscribed to the `ubean:info` state yet. Most clients
+* should use `client.sharedState.get('ubean:info')` instead.
+*/
+function createInfoRpcFunctions(opts) {
+	return [defineRpcFunction({
+		name: "ubean:get-info",
+		type: "query",
+		setup: () => ({ handler: () => opts.state.value() })
+	}), defineRpcFunction({
+		name: "ubean:get-env",
+		type: "query",
+		setup: () => ({ handler: () => maskSensitiveEnv(opts.getEnvData()) })
+	})];
+}
+//#endregion
+//#region src/node/rpc/playground.ts
+/**
+* Playground RPC function — `ubean:playground:invoke`.
+*
+* Forwards an HTTP request to the Hono app in-process (no network
+* round-trip), mirroring the `internalFetch` / `callInternal` pattern
+* used elsewhere in ubean.
+*/
+function createPlaygroundRpcFunctions(opts) {
+	return [defineRpcFunction({
+		name: "ubean:playground:invoke",
+		type: "action",
+		setup: () => ({ handler: async (params) => {
+			const app = opts.getApp?.();
+			if (!app) return {
+				status: 503,
+				statusText: "Service Unavailable",
+				body: { error: "App not available" },
+				headers: {}
+			};
+			const url = `http://localhost${params.path}`;
+			const headers = new Headers(params.headers || { "Content-Type": "application/json" });
+			const hasBody = params.body !== void 0 && params.method !== "GET" && params.method !== "HEAD";
+			const req = new Request(url, {
+				method: params.method,
+				headers,
+				...hasBody ? { body: JSON.stringify(params.body) } : {}
+			});
+			const res = await app.fetch(req);
+			const resHeaders = {};
+			res.headers.forEach((v, k) => {
+				resHeaders[k] = v;
+			});
+			const contentType = res.headers.get("content-type") || "";
+			let body;
+			if (contentType.includes("application/json")) body = await res.json();
+			else body = await res.text();
+			return {
+				status: res.status,
+				statusText: res.statusText,
+				body,
+				headers: resHeaders
+			};
+		} })
+	})];
+}
+//#endregion
+//#region src/node/rpc/terminal.ts
+/**
+* Terminal RPC functions — `ubean:terminal:start/input/resize/poll/kill`.
+*
+* Delegates to `createTerminalServer` which manages shell processes and
+* output buffering. The client polls for output via `ubean:terminal:poll`.
+*/
+function createTerminalRpcFunctions(terminal) {
+	return [
+		defineRpcFunction({
+			name: "ubean:terminal:start",
+			type: "action",
+			setup: () => ({ handler: (params) => Promise.resolve(terminal.start(params)) })
+		}),
+		defineRpcFunction({
+			name: "ubean:terminal:input",
+			type: "action",
+			setup: () => ({ handler: (params) => Promise.resolve(terminal.input(params.sessionId, params.data)) })
+		}),
+		defineRpcFunction({
+			name: "ubean:terminal:resize",
+			type: "action",
+			setup: () => ({ handler: (params) => Promise.resolve(terminal.resize(params.sessionId, params.cols, params.rows)) })
+		}),
+		defineRpcFunction({
+			name: "ubean:terminal:poll",
+			type: "query",
+			setup: () => ({ handler: (params) => Promise.resolve(terminal.poll(params.sessionId)) })
+		}),
+		defineRpcFunction({
+			name: "ubean:terminal:kill",
+			type: "action",
+			setup: () => ({ handler: (params) => Promise.resolve(terminal.kill(params.sessionId)) })
+		})
+	];
+}
+//#endregion
+//#region src/node/rpc/index.ts
+/**
+* Returns an array of `defineRpcFunction` definitions. The return type is
+* intentionally loose (`any[]`) because the DTK `ctx.rpc.register()` accepts
+* definitions parameterized on `ViteDevToolsNodeContext`, and the exact
+* generic instantiation varies per function — the individual functions are
+* already type-checked at their definition site.
+*/
+function createAllRpcFunctions(deps) {
+	return [
+		...createInfoRpcFunctions({
+			state: deps.state,
+			getEnvData: deps.getEnvData
+		}),
+		...createCrudRpcFunctions(deps.crud),
+		...createAiRpcFunctions(deps.ai),
+		...createPlaygroundRpcFunctions({ getApp: deps.getApp }),
+		...createTerminalRpcFunctions(deps.terminal)
+	];
+}
+//#endregion
+//#region src/node/state.ts
+/**
+* SharedState management for the DTK integration.
+*
+* Replaces the old 3-second polling pattern: the server builds a
+* `DevToolsInfo` snapshot and pushes patches to all connected clients
+* via `ctx.rpc.sharedState`.
+*/
+/** SharedState key for the ubean devtools info snapshot. */
+const UBEAN_INFO_STATE_KEY = "ubean:info";
+/** Build a fresh `DevToolsInfo` from scan + config metadata. */
+function buildDevToolsInfo(opts) {
+	const { scan, configMeta, customTabs, ai, startTime, envData } = opts;
+	const rootDir = configMeta?.rootDir || "";
+	const srcDir = configMeta?.srcDir || (rootDir ? join(rootDir, "src") : "src");
+	const dirs = configMeta?.dir ?? {};
+	const srcRel = rootDir ? relative(rootDir, srcDir).replace(/\\/g, "/") || "src" : "src";
+	const routesDir = dirs.routes || "routes";
+	const pagesDir = dirs.pages || "pages";
+	const middlewareDir = dirs.middleware || "middleware";
+	const layoutsDir = dirs.layouts || "layouts";
+	const cronsDir = dirs.crons || "crons";
+	const routesPrefix = `${srcRel}/${routesDir}`;
+	const pagesPrefix = `${srcRel}/${pagesDir}`;
+	const middlewarePrefix = `${srcRel}/${middlewareDir}`;
+	const layoutsPrefix = `${srcRel}/${layoutsDir}`;
+	const cronsPrefix = `${srcRel}/${cronsDir}`;
+	const makeFilePath = (fullPath, relPath, prefix) => {
+		if (!fullPath) return "";
+		if (rootDir) {
+			const rel = relative(rootDir, fullPath).replace(/\\/g, "/");
+			if (rel && !rel.startsWith("..")) return rel;
+		}
+		return `${prefix}/${relPath.replace(/\\/g, "/")}`;
+	};
+	const routes = scan ? scan.apiRoutes.map((r) => ({
+		method: (r.method || "GET").toUpperCase(),
+		path: r.route,
+		filePath: makeFilePath(r.fullPath, r.relativePath, routesPrefix)
+	})) : [];
+	const defaultLayoutName = scan?.layouts.find((l) => l.isDefault)?.name;
+	const pagesList = scan ? scan.pages.filter((p) => !p.isReuse).map((p) => ({
+		path: p.route,
+		name: p.name,
+		filePath: makeFilePath(p.fullPath, p.relativePath, pagesPrefix),
+		layout: p.layout === false ? void 0 : p.layout || defaultLayoutName || void 0
+	})) : [];
+	const middlewaresList = scan ? scan.middlewares.map((m) => ({
+		path: m.global ? "*" : m.relativePath,
+		filePath: makeFilePath(m.fullPath, m.relativePath, middlewarePrefix),
+		global: m.global
+	})) : [];
+	const layoutsList = scan ? scan.layouts.map((l) => ({
+		name: l.name,
+		path: l.path,
+		filePath: makeFilePath(l.fullPath, l.relativePath, layoutsPrefix),
+		isDefault: l.isDefault
+	})) : [];
+	const cronsList = scan ? scan.crons.map((c) => ({
+		name: c.name,
+		filePath: makeFilePath(c.fullPath, c.relativePath, cronsPrefix)
+	})) : [];
+	return {
+		version: "0.0.1",
+		startTime,
+		config: configMeta ? {
+			preset: configMeta.preset,
+			rootDir: configMeta.rootDir,
+			srcDir: configMeta.srcDir,
+			dir: configMeta.dir
+		} : {},
+		env: maskSensitiveEnv(envData),
+		pages: pagesList.length,
+		apiRoutes: routes.length,
+		middleware: middlewaresList.length,
+		layouts: layoutsList.length,
+		crons: cronsList.length,
+		presets: configMeta ? [configMeta.preset] : [],
+		routes,
+		pagesList,
+		middlewaresList,
+		layoutsList,
+		cronsList,
+		customTabs,
+		openAPI: configMeta?.openAPI ?? { enabled: false },
+		database: configMeta?.database,
+		ai: {
+			enabled: !!(ai?.apiKey || process.env.DEEPSEEK_API_KEY || process.env.UBEAN_AI_API_KEY || process.env.OPENAI_API_KEY),
+			provider: ai?.apiBase?.includes("deepseek") ? "deepseek" : ai?.apiBase?.includes("anthropic") ? "anthropic" : "deepseek",
+			model: ai?.model || (ai?.apiBase?.includes("deepseek") || !ai?.apiBase ? "deepseek-chat" : ai.model)
+		}
+	};
+}
+/** Initial empty state (used before scan data arrives). */
+function emptyDevToolsInfo(startTime) {
+	return {
+		version: "0.0.1",
+		startTime,
+		config: {},
+		env: {},
+		pages: 0,
+		apiRoutes: 0,
+		middleware: 0,
+		layouts: 0,
+		crons: 0,
+		presets: [],
+		routes: [],
+		pagesList: [],
+		middlewaresList: [],
+		layoutsList: [],
+		cronsList: [],
+		customTabs: [],
+		ai: { enabled: false }
+	};
+}
+/**
+* Create or retrieve the `ubean:info` shared state.
+* Called once during `devtools.setup`.
+*/
+async function initSharedState(ctx, initialValue) {
+	return ctx.rpc.sharedState.get(UBEAN_INFO_STATE_KEY, { initialValue });
+}
+/**
+* Push a fresh `DevToolsInfo` into the shared state, triggering
+* patch-sync to all connected clients.
+*/
+function refreshSharedState(state, info) {
+	state.mutate((draft) => {
+		Object.assign(draft, info);
+	});
+}
+//#endregion
+//#region src/node/index.ts
+/**
+* Path to the pre-built client SPA. Resolved relative to the built server
+* bundle (`dist/index.mjs`), so this points to `dist/client/` at runtime.
+*/
+const CLIENT_DIST = resolve(dirname(fileURLToPath(import.meta.url)), "client");
+/**
+* Ubean DevTools as a Vite plugin.
+*
+* Registers a dock entry (iframe pointing at the pre-built SPA), hosts the
+* SPA's static assets, and wires up the type-safe RPC + sharedState used by
+* the SPA. This replaces the previous Hono-middleware-based transport with
+* the Vite DevTools Kit (DTK) birpc + shared-state machinery.
+*/
+function ubeanDevtoolsPlugin(options = { getCwd: () => process.cwd() }) {
+	return {
+		name: "ubean:devtools",
+		devtools: { async setup(ctx) {
+			console.log("[ubean:devtools] devtools.setup hook fired — DTK integration active");
+			ctx.views.hostStatic("/_devtools/", CLIENT_DIST);
+			const viteServer = ctx.viteServer;
+			if (viteServer?.middlewares) {
+				const serveConnectionMeta = (req, res) => {
+					const targetUrl = `${req.headers["x-forwarded-proto"] || "http"}://${req.headers.host || "localhost:9527"}/__devtools/__connection.json`;
+					fetch(targetUrl).then(async (metaRes) => {
+						const meta = await metaRes.json();
+						if (meta.websocket && typeof meta.websocket === "object") meta.websocket = {
+							...meta.websocket,
+							path: "/__devtools/__ws"
+						};
+						res.setHeader("Content-Type", "application/json");
+						res.end(JSON.stringify(meta));
+					}).catch(() => {
+						res.statusCode = 500;
+						res.setHeader("Content-Type", "application/json");
+						res.end(JSON.stringify({ error: "Failed to resolve connection meta" }));
+					});
+				};
+				viteServer.middlewares.use("/_devtools/__connection.json", serveConnectionMeta);
+				viteServer.middlewares.use("/__connection.json", serveConnectionMeta);
+			}
+			const SPA_BASE = "/_devtools/index.html";
+			const dockEntries = [
+				{
+					id: "ubean:overview",
+					title: "Overview",
+					icon: "lucide:layout-dashboard",
+					url: `${SPA_BASE}#/overview`,
+					order: 100
+				},
+				{
+					id: "ubean:pages",
+					title: "Pages",
+					icon: "lucide:file-text",
+					url: `${SPA_BASE}#/pages`,
+					order: 95
+				},
+				{
+					id: "ubean:api",
+					title: "API",
+					icon: "lucide:send",
+					url: `${SPA_BASE}#/api`,
+					order: 90
+				},
+				{
+					id: "ubean:middleware",
+					title: "Middleware",
+					icon: "lucide:layers",
+					url: `${SPA_BASE}#/middleware`,
+					order: 85
+				},
+				{
+					id: "ubean:crons",
+					title: "Crons",
+					icon: "lucide:clock",
+					url: `${SPA_BASE}#/crons`,
+					order: 80
+				},
+				{
+					id: "ubean:config",
+					title: "Config",
+					icon: "lucide:settings",
+					url: `${SPA_BASE}#/config`,
+					order: 75
+				},
+				{
+					id: "ubean:env",
+					title: "Env",
+					icon: "lucide:terminal",
+					url: `${SPA_BASE}#/env`,
+					order: 70
+				},
+				{
+					id: "ubean:api-docs",
+					title: "API Docs",
+					icon: "lucide:book-open",
+					url: `${SPA_BASE}#/api-docs`,
+					order: 65
+				},
+				{
+					id: "ubean:database",
+					title: "Database",
+					icon: "lucide:database",
+					url: `${SPA_BASE}#/database`,
+					order: 60
+				},
+				{
+					id: "ubean:terminal",
+					title: "Terminal",
+					icon: "lucide:square-terminal",
+					url: `${SPA_BASE}#/terminal`,
+					order: 58
+				},
+				{
+					id: "ubean:ai",
+					title: "AI",
+					icon: "lucide:sparkles",
+					url: `${SPA_BASE}#/ai`,
+					order: 55
+				}
+			];
+			for (const entry of dockEntries) ctx.docks.register({
+				id: entry.id,
+				title: entry.title,
+				icon: entry.icon,
+				type: "iframe",
+				url: entry.url,
+				category: "framework",
+				defaultOrder: entry.order
+			});
+			const startTime = Date.now();
+			const customTabs = options.getCustomTabs?.() ?? [];
+			const envData = snapshotEnv(options.getCwd());
+			const initialInfo = options.getScanResult ? buildDevToolsInfo({
+				scan: options.getScanResult(),
+				configMeta: options.getConfigMeta?.() ?? null,
+				customTabs,
+				ai: options.ai,
+				startTime,
+				envData
+			}) : emptyDevToolsInfo(startTime);
+			for (const tab of customTabs) ctx.docks.register({
+				id: `ubean:custom:${tab.id}`,
+				title: tab.label,
+				icon: tab.icon || "lucide:plugin",
+				type: "iframe",
+				url: tab.src,
+				category: "framework",
+				defaultOrder: 50
+			});
+			const state = await initSharedState(ctx, initialInfo);
+			const aiStreamState = await ctx.rpc.sharedState.get("ubean:ai:stream", { initialValue: {
+				requestId: "",
+				text: "",
+				done: true
+			} });
+			const hooks = createDevToolsHooks();
+			const crud = createCrudServer({
+				cwd: options.getCwd(),
+				hooks,
+				scaffoldOps: options.scaffoldOps,
+				getEnv: () => envData,
+				setEnv: (env) => {
+					Object.keys(envData).forEach((k) => delete envData[k]);
+					Object.assign(envData, env);
+				},
+				getConfig: () => options.getConfigMeta?.() ?? {},
+				onFileChange: async () => {
+					if (options.triggerRescan) await options.triggerRescan();
+				}
+			});
+			const fns = createAllRpcFunctions({
+				state,
+				getEnvData: () => envData,
+				crud,
+				ai: createAiServer(crud, () => state.value(), (chunk) => {
+					aiStreamState.mutate(() => chunk);
+				}),
+				terminal: createTerminalServer(),
+				getApp: options.getApp
+			});
+			for (const fn of fns) ctx.rpc.register(fn);
+			const refresh = () => {
+				const info = options.getScanResult ? buildDevToolsInfo({
+					scan: options.getScanResult(),
+					configMeta: options.getConfigMeta?.() ?? null,
+					customTabs: options.getCustomTabs?.() ?? [],
+					ai: options.ai,
+					startTime,
+					envData
+				}) : initialInfo;
+				refreshSharedState(state, info);
+			};
+			options.registerRefresh?.(refresh);
+		} }
+	};
+}
+/**
+* Parse a single .env file and return the key/value pairs.
+* - Ignores blank lines and `#` comments.
+* - Strips surrounding single/double quotes from values.
+*/
+function parseEnvFile(filePath) {
+	if (!existsSync(filePath)) return {};
+	let content;
+	try {
+		content = readFileSync(filePath, "utf-8");
+	} catch {
+		return {};
+	}
+	const env = {};
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const eqIndex = trimmed.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = trimmed.slice(0, eqIndex).trim();
+		let value = trimmed.slice(eqIndex + 1).trim();
+		const hashIndex = value.search(/\s+#.*$/);
+		if (hashIndex !== -1 && !value.startsWith("\"") && !value.startsWith("'")) value = value.slice(0, hashIndex).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		env[key] = value;
+	}
+	return env;
+}
+/**
+* Snapshot env vars relevant to the ubean app.
+*
+* Instead of dumping all of `process.env` (which includes noisy system vars
+* like PATH, HOME, SHELL, LANG, TERM, etc.), we only collect:
+*   1. Vars defined in .env / .env.local / .env.development / .env.development.local
+*   2. UBEAN_* prefixed vars from process.env (framework/CLI vars set by shell)
+*
+* Values from process.env override .env file values (shell overrides take
+* precedence), matching Vite's env loading semantics.
+*/
+function snapshotEnv(cwd) {
+	const envFiles = [
+		".env",
+		".env.local",
+		".env.development",
+		".env.development.local"
+	];
+	const env = {};
+	for (const file of envFiles) Object.assign(env, parseEnvFile(resolve(cwd, file)));
+	for (const [key, value] of Object.entries(process.env)) if (typeof value === "string" && (key in env || key.startsWith("UBEAN_"))) env[key] = value;
+	return env;
+}
+//#endregion
+//#region src/define-tab.ts
+const customTabs = [];
+function defineDevToolsTab(tab) {
+	const exists = customTabs.findIndex((t) => t.id === tab.id);
+	if (exists !== -1) customTabs[exists] = tab;
+	else customTabs.push(tab);
+	return tab;
+}
+function getCustomTabs() {
+	return [...customTabs];
+}
+function clearCustomTabs() {
+	customTabs.length = 0;
+}
+//#endregion
+export { UBEAN_INFO_STATE_KEY, buildDevToolsInfo, clearCustomTabs, createAiServer, createAllRpcFunctions, createCrudServer, createDevToolsHooks, createTerminalServer, defineDevToolsTab, defineRpcFunction, emptyDevToolsInfo, getCustomTabs, maskSensitiveEnv, ubeanDevtoolsPlugin };