@weapp-sqlite/devtools 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,451 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+const require_protocol = require("./protocol-Cl3y675u.cjs");
+const require_client = require("./client.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+node_path = __toESM(node_path, 1);
+let node_process = require("node:process");
+node_process = __toESM(node_process, 1);
+let node_url = require("node:url");
+let _vitejs_devtools = require("@vitejs/devtools");
+let _vitejs_devtools_kit_node = require("@vitejs/devtools-kit/node");
+let devframe = require("devframe");
+let devframe_node_auth = require("devframe/node/auth");
+let vite = require("vite");
+let node_buffer = require("node:buffer");
+let node_crypto = require("node:crypto");
+let ws = require("ws");
+//#region src/broker.ts
+const RUNTIME_PATH = "/__weapp-sqlite/runtime";
+function errorResult(code, message) {
+	return {
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	};
+}
+function validOrigin(origin) {
+	if (!origin) return true;
+	try {
+		const url = new URL(origin);
+		return [
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		].includes(url.hostname) || url.protocol === "https:" && url.hostname === "servicewechat.com";
+	} catch {
+		return false;
+	}
+}
+function validOwnerId(value) {
+	return value === void 0 || require_protocol.isIdentifier(value);
+}
+/** broker 只路由到拥有数据库的 runtime，不会在 Node 端打开数据库副本。 */
+function createSqliteDevtoolsBroker(options = {}) {
+	const token = (0, node_crypto.randomBytes)(32).toString("hex");
+	const peers = /* @__PURE__ */ new Map();
+	const owners = /* @__PURE__ */ new Map();
+	const sockets = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	const server = new ws.WebSocketServer({
+		noServer: true,
+		maxPayload: require_protocol.SQLITE_DEVTOOLS_MAX_MESSAGE_BYTES,
+		perMessageDeflate: false
+	});
+	let detach;
+	let closed = false;
+	function changed() {
+		for (const listener of listeners) listener();
+	}
+	function remove(peer) {
+		for (const pending of peer.pending.values()) {
+			clearTimeout(pending.timer);
+			pending.resolve(errorResult("SQLITE_DEVTOOLS_DISCONNECTED", "Runtime disconnected. The operation was not retried; its outcome may be unknown."));
+		}
+		peer.pending.clear();
+		if (peers.get(peer.descriptor.id) === peer) {
+			peers.delete(peer.descriptor.id);
+			owners.delete(peer.descriptor.id);
+			changed();
+		}
+	}
+	server.on("connection", (socket) => {
+		if (closed || sockets.size >= 32) {
+			socket.close(1008, "Runtime capacity reached");
+			return;
+		}
+		sockets.add(socket);
+		let peer;
+		const authTimer = setTimeout(() => socket.close(1008, "Authentication timed out"), 5e3);
+		socket.on("error", () => {
+			socket.terminate();
+		});
+		socket.on("close", () => {
+			clearTimeout(authTimer);
+			sockets.delete(socket);
+			if (peer) remove(peer);
+		});
+		socket.on("message", (bytes, binary) => {
+			try {
+				const frame = Array.isArray(bytes) ? node_buffer.Buffer.concat(bytes) : bytes instanceof ArrayBuffer ? node_buffer.Buffer.from(bytes) : bytes;
+				if (binary || !peer && frame.byteLength > 32768) throw new Error("Invalid frame");
+				const message = JSON.parse(frame.toString());
+				if (!require_protocol.isRecord(message)) throw new Error("Invalid frame");
+				if (!peer) {
+					if (message.type !== "hello" || message.protocol !== 1 || typeof message.token !== "string" || message.token.length !== token.length || !(0, node_crypto.timingSafeEqual)(node_buffer.Buffer.from(message.token), node_buffer.Buffer.from(token)) || !require_protocol.isRecord(message.runtime) || !require_protocol.isIdentifier(message.runtime.id) || !require_protocol.isIdentifier(message.runtime.label) || !require_protocol.isIdentifier(message.runtime.platform) || !require_protocol.validDatabaseNames(message.databases)) throw new Error("Invalid authentication");
+					const old = peers.get(message.runtime.id);
+					if (old) {
+						remove(old);
+						old.socket.close(1e3, "Runtime replaced");
+					}
+					peer = {
+						socket,
+						descriptor: {
+							id: message.runtime.id,
+							label: message.runtime.label,
+							platform: message.runtime.platform,
+							databases: [...message.databases],
+							sessionId: (0, node_crypto.randomUUID)(),
+							connectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+							readOnly: options.allowWrite !== true
+						},
+						pending: /* @__PURE__ */ new Map()
+					};
+					clearTimeout(authTimer);
+					peers.set(peer.descriptor.id, peer);
+					socket.send(JSON.stringify({
+						type: "ready",
+						sessionId: peer.descriptor.sessionId,
+						allowWrite: options.allowWrite === true
+					}));
+					changed();
+					return;
+				}
+				if (peers.get(peer.descriptor.id) !== peer || message.sessionId !== peer.descriptor.sessionId) throw new Error("Stale runtime session");
+				if (message.type === "databases" && require_protocol.validDatabaseNames(message.databases)) {
+					peer = {
+						...peer,
+						descriptor: {
+							...peer.descriptor,
+							databases: [...message.databases]
+						}
+					};
+					peers.set(peer.descriptor.id, peer);
+					changed();
+					return;
+				}
+				if (message.type !== "result" && message.type !== "release-result" || !require_protocol.isIdentifier(message.requestId) || !require_protocol.isRecord(message.result)) throw new Error("Invalid runtime response");
+				const pending = peer.pending.get(message.requestId);
+				if (!pending) return;
+				const result = message.result;
+				if (result.ok === true) require_protocol.decodeSqliteDevtoolsValue(result.value);
+				else if (result.ok !== false || !require_protocol.isRecord(result.error) || !require_protocol.isIdentifier(result.error.code) || typeof result.error.message !== "string" || result.error.message.length > 4096) throw new Error("Invalid runtime response");
+				clearTimeout(pending.timer);
+				peer.pending.delete(message.requestId);
+				pending.resolve(result);
+			} catch {
+				socket.close(1008, "Invalid SQLite runtime protocol");
+			}
+		});
+	});
+	return {
+		token,
+		path: RUNTIME_PATH,
+		listRuntimes(ownerId) {
+			if (!validOwnerId(ownerId)) throw new require_protocol.SqliteDevtoolsError("SQLITE_DEVTOOLS_INVALID_REQUEST", "Invalid SQLite DevTools panel owner.");
+			if (ownerId) for (const runtime of peers.values()) {
+				const runtimeOwners = owners.get(runtime.descriptor.id) ?? /* @__PURE__ */ new Set();
+				runtimeOwners.add(ownerId);
+				owners.set(runtime.descriptor.id, runtimeOwners);
+			}
+			return [...peers.values()].map((peer) => ({
+				...peer.descriptor,
+				databases: [...peer.descriptor.databases]
+			}));
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		async invoke(input) {
+			try {
+				if (!require_protocol.isRecord(input) || !require_protocol.isIdentifier(input.runtimeId) || !require_protocol.isIdentifier(input.sessionId) || !require_protocol.isIdentifier(input.databaseName) || !require_protocol.isSqliteDevtoolsMethod(input.method) || input.method === "close") throw new require_protocol.SqliteDevtoolsError("SQLITE_DEVTOOLS_INVALID_REQUEST", "Unknown SQLite runtime, database, or method.");
+				const args = require_protocol.decodeSqliteDevtoolsValue(input.args);
+				if (!Array.isArray(args) || args.length > 8) throw new require_protocol.SqliteDevtoolsError("SQLITE_DEVTOOLS_INVALID_REQUEST", "SQLite arguments must be an array.");
+				const peer = peers.get(input.runtimeId);
+				if (!peer || peer.descriptor.sessionId !== input.sessionId || peer.socket.readyState !== ws.WebSocket.OPEN) return errorResult("SQLITE_DEVTOOLS_DISCONNECTED", "The selected runtime session is no longer connected.");
+				if (!peer.descriptor.databases.includes(input.databaseName)) return errorResult("SQLITE_DEVTOOLS_DATABASE_CLOSED", "The selected database is no longer registered.");
+				if (options.allowWrite !== true && require_protocol.isSqliteDevtoolsWriteMethod(input.method)) return errorResult("SQLITE_DEVTOOLS_READ_ONLY", "This SQLite DevTools host is read-only.");
+				if (peer.pending.size >= 64) return errorResult("SQLITE_DEVTOOLS_BUSY", "Too many pending SQLite operations.");
+				const requestId = (0, node_crypto.randomUUID)();
+				const frame = JSON.stringify({
+					...input,
+					type: "request",
+					requestId
+				});
+				if (node_buffer.Buffer.byteLength(frame) > 16777216) return errorResult("SQLITE_DEVTOOLS_PAYLOAD_LIMIT", "SQLite operation exceeds the message limit.");
+				return await new Promise((resolve) => {
+					const timer = setTimeout(() => {
+						peer.pending.delete(requestId);
+						resolve(errorResult("SQLITE_DEVTOOLS_TIMEOUT", "SQLite operation timed out. It was not retried; its outcome may be unknown."));
+					}, options.requestTimeoutMs ?? 3e4);
+					peer.pending.set(requestId, {
+						resolve,
+						timer
+					});
+					peer.socket.send(frame, (error) => {
+						if (error) {
+							remove(peer);
+							peer.socket.terminate();
+						}
+					});
+				});
+			} catch (error) {
+				return {
+					ok: false,
+					error: require_protocol.serializeDevtoolsError(error)
+				};
+			}
+		},
+		async releaseSession(input) {
+			try {
+				if (!require_protocol.isRecord(input) || !require_protocol.isIdentifier(input.runtimeId) || !require_protocol.isIdentifier(input.sessionId) || !validOwnerId(input.ownerId)) throw new require_protocol.SqliteDevtoolsError("SQLITE_DEVTOOLS_INVALID_REQUEST", "Unknown SQLite runtime session.");
+				const ownerId = input.ownerId;
+				if (ownerId) {
+					const runtimeOwners = owners.get(input.runtimeId);
+					if (!runtimeOwners?.has(ownerId)) return {
+						ok: true,
+						value: require_protocol.encodeSqliteDevtoolsValue(void 0)
+					};
+					runtimeOwners.delete(ownerId);
+					if (runtimeOwners.size > 0) return {
+						ok: true,
+						value: require_protocol.encodeSqliteDevtoolsValue(void 0)
+					};
+					owners.delete(input.runtimeId);
+				}
+				const peer = peers.get(input.runtimeId);
+				if (!peer || peer.descriptor.sessionId !== input.sessionId || peer.socket.readyState !== ws.WebSocket.OPEN) return errorResult("SQLITE_DEVTOOLS_DISCONNECTED", "The selected runtime session is no longer connected.");
+				if (peer.pending.size >= 64) return errorResult("SQLITE_DEVTOOLS_BUSY", "Too many pending SQLite operations.");
+				const requestId = (0, node_crypto.randomUUID)();
+				const frame = JSON.stringify({
+					type: "release",
+					sessionId: peer.descriptor.sessionId,
+					requestId
+				});
+				if (node_buffer.Buffer.byteLength(frame) > 16777216) return errorResult("SQLITE_DEVTOOLS_PAYLOAD_LIMIT", "SQLite session release exceeds the message limit.");
+				return await new Promise((resolve) => {
+					const timer = setTimeout(() => {
+						peer.pending.delete(requestId);
+						resolve(errorResult("SQLITE_DEVTOOLS_TIMEOUT", "SQLite debug session release timed out."));
+					}, options.requestTimeoutMs ?? 3e4);
+					peer.pending.set(requestId, {
+						resolve,
+						timer
+					});
+					peer.socket.send(frame, (error) => {
+						if (error) {
+							remove(peer);
+							peer.socket.terminate();
+						}
+					});
+				});
+			} catch (error) {
+				return {
+					ok: false,
+					error: require_protocol.serializeDevtoolsError(error)
+				};
+			}
+		},
+		attach(httpServer) {
+			if (closed || detach) throw new Error("SQLite runtime broker is already attached or closed.");
+			const upgrade = (request, socket, head) => {
+				if (request.url?.split("?")[0] !== RUNTIME_PATH) return;
+				if (closed || !validOrigin(request.headers.origin)) {
+					socket.destroy();
+					return;
+				}
+				server.handleUpgrade(request, socket, head, (client) => {
+					server.emit("connection", client, request);
+				});
+			};
+			httpServer.on("upgrade", upgrade);
+			detach = () => {
+				httpServer.off("upgrade", upgrade);
+			};
+		},
+		async close() {
+			if (closed) return;
+			closed = true;
+			detach?.();
+			for (const peer of peers.values()) remove(peer);
+			for (const socket of sockets) socket.terminate();
+			await new Promise((resolve) => {
+				server.close(() => resolve());
+			});
+			listeners.clear();
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+function createSqliteDevtoolsDevframe(options = {}) {
+	const broker = createSqliteDevtoolsBroker(options);
+	let unsubscribe;
+	let disposing;
+	return {
+		definition: (0, devframe.defineDevframe)({
+			id: require_protocol.SQLITE_DEVTOOLS_SCOPE,
+			name: "SQLite",
+			version: "0.1.0",
+			packageName: "@weapp-sqlite/devtools",
+			importMetaUrl: require("url").pathToFileURL(__filename).href,
+			homepage: "https://github.com/weapp-sqlite/weapp-sqlite",
+			description: "查看与调试 Web 和小程序运行时中的 SQLite 数据库。",
+			icon: "ph:database-duotone",
+			capabilities: {
+				dev: true,
+				build: false
+			},
+			clientAssets: options.clientAssets ?? (0, node_url.fileURLToPath)(new URL("./client/", require("url").pathToFileURL(__filename).href)),
+			async setup(ctx) {
+				const scope = ctx.scope(require_protocol.SQLITE_DEVTOOLS_SCOPE);
+				scope.rpc.register((0, devframe.defineRpcFunction)({
+					name: "list-runtimes",
+					type: "query",
+					jsonSerializable: true,
+					handler: broker.listRuntimes
+				}));
+				scope.rpc.register((0, devframe.defineRpcFunction)({
+					name: "invoke",
+					type: "action",
+					jsonSerializable: true,
+					handler: broker.invoke
+				}));
+				scope.rpc.register((0, devframe.defineRpcFunction)({
+					name: "release-session",
+					type: "action",
+					jsonSerializable: true,
+					handler: broker.releaseSession
+				}));
+				unsubscribe?.();
+				unsubscribe = broker.subscribe(() => {
+					scope.rpc.broadcast({
+						method: "state-updated",
+						args: [broker.listRuntimes()],
+						event: true
+					}).catch(() => {});
+				});
+			}
+		}),
+		broker,
+		dispose() {
+			return disposing ??= (async () => {
+				unsubscribe?.();
+				unsubscribe = void 0;
+				await broker.close();
+			})();
+		}
+	};
+}
+function createSqliteDevtoolsPlugin(controller) {
+	return {
+		...(0, _vitejs_devtools_kit_node.createPluginFromDevframe)(controller.definition),
+		apply: "serve",
+		configureServer(server) {
+			if (!server.httpServer) throw new Error("SQLite DevTools requires an HTTP server for its runtime bridge.");
+			controller.broker.attach(server.httpServer);
+			server.httpServer.once("close", () => {
+				controller.dispose();
+			});
+		},
+		async closeServer() {
+			await controller.dispose();
+		},
+		async closeBundle() {
+			await controller.dispose();
+		}
+	};
+}
+/** 创建独立开发宿主；调用方负责其 watcher 与退出生命周期。 */
+async function startSqliteDevtoolsServer(options = {}) {
+	const controller = createSqliteDevtoolsDevframe(options);
+	const assets = controller.definition.clientAssets;
+	if (typeof assets !== "string" || !(0, node_fs.existsSync)(node_path.default.join(assets, "index.html"))) {
+		await controller.dispose();
+		throw new Error("SQLite DevTools client is missing. Build @weapp-sqlite/devtools first.");
+	}
+	let server;
+	try {
+		const devtoolsPlugins = await (0, _vitejs_devtools.DevTools)({
+			builtinDevTools: false,
+			clientAuth: true,
+			allowedOrigins: [],
+			mcp: false
+		});
+		server = await (0, vite.createServer)({
+			configFile: false,
+			root: options.cwd ?? node_process.default.cwd(),
+			publicDir: false,
+			appType: "custom",
+			clearScreen: false,
+			logLevel: "silent",
+			plugins: [...devtoolsPlugins, createSqliteDevtoolsPlugin(controller)],
+			server: {
+				host: "127.0.0.1",
+				port: options.port ?? 0,
+				strictPort: options.port !== void 0 && options.port !== 0,
+				watch: { ignored: ["**/*"] }
+			}
+		});
+		await server.listen();
+		const address = server.httpServer?.address();
+		if (!address || typeof address === "string") throw new Error("SQLite DevTools could not resolve its listening port.");
+		const origin = `http://127.0.0.1:${address.port}`;
+		let closing;
+		const activeServer = server;
+		return {
+			url: (0, devframe_node_auth.buildOtpAuthUrl)(`${origin}/__weapp-sqlite/`, (0, devframe_node_auth.refreshTempAuthCode)()),
+			runtimeEndpoint: `ws://127.0.0.1:${address.port}${controller.broker.path}`,
+			runtimeToken: controller.broker.token,
+			close() {
+				return closing ??= controller.dispose().finally(() => activeServer.close());
+			}
+		};
+	} catch (error) {
+		await controller.dispose();
+		await server?.close();
+		throw error;
+	}
+}
+//#endregion
+exports.connectDevtoolsClient = require_client.connectDevtoolsClient;
+exports.createSqliteDevtoolsDevframe = createSqliteDevtoolsDevframe;
+exports.createSqliteDevtoolsPlugin = createSqliteDevtoolsPlugin;
+exports.startSqliteDevtoolsServer = startSqliteDevtoolsServer;

package/dist/index.d.cts

@@ -0,0 +1,64 @@
+import { c as SqliteDevtoolsInvocation, d as SqliteDevtoolsResult, l as SqliteDevtoolsMethod, p as SqliteDevtoolsRuntimeDescriptor, u as SqliteDevtoolsReleaseSession } from "./protocol-BhfjLrSe.cjs";
+import { SqliteDevtoolsClient, connectDevtoolsClient } from "./client.cjs";
+import { Server } from "node:http";
+//#region src/broker.d.ts
+interface SqliteDevtoolsBrokerOptions {
+  readonly allowWrite?: boolean;
+  readonly requestTimeoutMs?: number;
+}
+//#endregion
+//#region src/index.d.ts
+declare module 'devframe' {
+  interface DevframeRpcServerFunctions {
+    'weapp-sqlite:list-runtimes': (ownerId?: string) => SqliteDevtoolsRuntimeDescriptor[];
+    'weapp-sqlite:invoke': (input: SqliteDevtoolsInvocation) => Promise<SqliteDevtoolsResult>;
+    'weapp-sqlite:release-session': (input: SqliteDevtoolsReleaseSession) => Promise<SqliteDevtoolsResult>;
+  }
+  interface DevframeRpcClientFunctions {
+    'weapp-sqlite:state-updated': (runtimes: SqliteDevtoolsRuntimeDescriptor[]) => void;
+  }
+}
+export interface CreateSqliteDevtoolsDevframeOptions extends SqliteDevtoolsBrokerOptions {
+  readonly clientAssets?: string;
+}
+export declare function createSqliteDevtoolsDevframe(options?: CreateSqliteDevtoolsDevframeOptions): {
+  definition: import("devframe").DevframeDefinition;
+  broker: {
+    token: string;
+    path: string;
+    listRuntimes(ownerId?: string): SqliteDevtoolsRuntimeDescriptor[];
+    subscribe(listener: () => void): () => void;
+    invoke(input: unknown): Promise<SqliteDevtoolsResult>;
+    releaseSession(input: unknown): Promise<SqliteDevtoolsResult>;
+    attach(httpServer: Server): void;
+    close(): Promise<void>;
+  };
+  dispose(): Promise<void>;
+};
+export type SqliteDevtoolsDevframe = ReturnType<typeof createSqliteDevtoolsDevframe>;
+/** 认证与 Origin 策略由 Vite DevTools 宿主持有，runtime broker 另用专用凭证。 */
+/** Vite-compatible subset; keeps the public declaration independent of Vite's server internals. */
+export interface SqliteDevtoolsPlugin {
+  readonly name: string;
+  readonly apply: 'serve';
+  readonly configureServer: (server: {
+    readonly httpServer?: unknown;
+  }) => void;
+  readonly closeServer: () => Promise<void>;
+  readonly closeBundle: () => Promise<void>;
+}
+export declare function createSqliteDevtoolsPlugin(controller: SqliteDevtoolsDevframe): SqliteDevtoolsPlugin;
+export interface StartSqliteDevtoolsServerOptions extends CreateSqliteDevtoolsDevframeOptions {
+  readonly cwd?: string;
+  readonly port?: number;
+}
+export interface SqliteDevtoolsServer {
+  readonly url: string;
+  readonly runtimeEndpoint: string;
+  readonly runtimeToken: string;
+  close: () => Promise<void>;
+}
+/** 创建独立开发宿主；调用方负责其 watcher 与退出生命周期。 */
+export declare function startSqliteDevtoolsServer(options?: StartSqliteDevtoolsServerOptions): Promise<SqliteDevtoolsServer>;
+//#endregion
+export { type SqliteDevtoolsClient, type SqliteDevtoolsInvocation, type SqliteDevtoolsMethod, type SqliteDevtoolsReleaseSession, type SqliteDevtoolsRuntimeDescriptor, connectDevtoolsClient };

package/dist/index.d.mts

@@ -0,0 +1,64 @@
+import { c as SqliteDevtoolsInvocation, d as SqliteDevtoolsResult, l as SqliteDevtoolsMethod, p as SqliteDevtoolsRuntimeDescriptor, u as SqliteDevtoolsReleaseSession } from "./protocol-BhfjLrSe.mjs";
+import { SqliteDevtoolsClient, connectDevtoolsClient } from "./client.mjs";
+import { Server } from "node:http";
+//#region src/broker.d.ts
+interface SqliteDevtoolsBrokerOptions {
+  readonly allowWrite?: boolean;
+  readonly requestTimeoutMs?: number;
+}
+//#endregion
+//#region src/index.d.ts
+declare module 'devframe' {
+  interface DevframeRpcServerFunctions {
+    'weapp-sqlite:list-runtimes': (ownerId?: string) => SqliteDevtoolsRuntimeDescriptor[];
+    'weapp-sqlite:invoke': (input: SqliteDevtoolsInvocation) => Promise<SqliteDevtoolsResult>;
+    'weapp-sqlite:release-session': (input: SqliteDevtoolsReleaseSession) => Promise<SqliteDevtoolsResult>;
+  }
+  interface DevframeRpcClientFunctions {
+    'weapp-sqlite:state-updated': (runtimes: SqliteDevtoolsRuntimeDescriptor[]) => void;
+  }
+}
+export interface CreateSqliteDevtoolsDevframeOptions extends SqliteDevtoolsBrokerOptions {
+  readonly clientAssets?: string;
+}
+export declare function createSqliteDevtoolsDevframe(options?: CreateSqliteDevtoolsDevframeOptions): {
+  definition: import("devframe").DevframeDefinition;
+  broker: {
+    token: string;
+    path: string;
+    listRuntimes(ownerId?: string): SqliteDevtoolsRuntimeDescriptor[];
+    subscribe(listener: () => void): () => void;
+    invoke(input: unknown): Promise<SqliteDevtoolsResult>;
+    releaseSession(input: unknown): Promise<SqliteDevtoolsResult>;
+    attach(httpServer: Server): void;
+    close(): Promise<void>;
+  };
+  dispose(): Promise<void>;
+};
+export type SqliteDevtoolsDevframe = ReturnType<typeof createSqliteDevtoolsDevframe>;
+/** 认证与 Origin 策略由 Vite DevTools 宿主持有，runtime broker 另用专用凭证。 */
+/** Vite-compatible subset; keeps the public declaration independent of Vite's server internals. */
+export interface SqliteDevtoolsPlugin {
+  readonly name: string;
+  readonly apply: 'serve';
+  readonly configureServer: (server: {
+    readonly httpServer?: unknown;
+  }) => void;
+  readonly closeServer: () => Promise<void>;
+  readonly closeBundle: () => Promise<void>;
+}
+export declare function createSqliteDevtoolsPlugin(controller: SqliteDevtoolsDevframe): SqliteDevtoolsPlugin;
+export interface StartSqliteDevtoolsServerOptions extends CreateSqliteDevtoolsDevframeOptions {
+  readonly cwd?: string;
+  readonly port?: number;
+}
+export interface SqliteDevtoolsServer {
+  readonly url: string;
+  readonly runtimeEndpoint: string;
+  readonly runtimeToken: string;
+  close: () => Promise<void>;
+}
+/** 创建独立开发宿主；调用方负责其 watcher 与退出生命周期。 */
+export declare function startSqliteDevtoolsServer(options?: StartSqliteDevtoolsServerOptions): Promise<SqliteDevtoolsServer>;
+//#endregion
+export { type SqliteDevtoolsClient, type SqliteDevtoolsInvocation, type SqliteDevtoolsMethod, type SqliteDevtoolsReleaseSession, type SqliteDevtoolsRuntimeDescriptor, connectDevtoolsClient };