devframe 0.8.2 → 0.9.0-beta.2

package/dist/constants.d.mts

@@ -1,7 +1,4 @@
 //#region src/constants.d.ts
-declare const DEVFRAME_MOUNT_PATH = "/__devframe/";
-declare const DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH = "/__devframe";
-declare const DEVFRAME_DIRNAME = "__devframe";
 declare const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
  * Global key holding the serializable connection prepared by
@@ -16,7 +13,23 @@ declare const DEVFRAME_CONNECTION_KEY = "__DEVFRAME_CONNECTION__";
  * both HTTP and WS, and a host server (Vite, etc.) can mount the WS upgrade
  * handler here without colliding with its own routes (HMR, asset serving).
  */
-declare const DEVFRAME_WS_ROUTE = "__devframe_ws";
+declare const DEVFRAME_WS_ROUTE = "__ws";
+/**
+ * Route the SSE RPC endpoint is bound to, relative to a devframe's base
+ * path. A single method-dispatched route: `GET` opens the event stream
+ * (server→client), `POST` carries RPC frames (client→server). Sits next to
+ * `__connection.json` so the deployed SPA reaches it on the same origin it
+ * loaded from — the transport for hosts and proxies where the WebSocket
+ * upgrade isn't available.
+ */
+declare const DEVFRAME_SSE_ROUTE = "__sse";
+/**
+ * Request header carrying the SSE session id on every RPC `POST`. The
+ * server mints the id as the stream's first event (`event: session`);
+ * the client echoes it here so the POST joins that stream's birpc
+ * channel. Mirrors birpc's own SSE helpers for wire compatibility.
+ */
+declare const DEVFRAME_SSE_SESSION_HEADER = "x-birpc-session";
 /**
  * Route the Streamable-HTTP MCP endpoint is bound to, relative to a
  * devframe's base path. Sits next to `__connection.json` and the WS route
@@ -68,9 +81,9 @@ declare const ANONYMOUS_RPC_PREFIX = "anonymous:";
 /**
  * Whether `name` is callable before a connection is trusted, i.e. it starts
  * with {@link ANONYMOUS_RPC_PREFIX}. Used by the resolver gate in
- * `startHttpAndWs` (via an `authorize` function) and by host adapters that
+ * the RPC server binding (via an `authorize` function) and by host adapters that
  * implement their own transport.
  */
 declare function isAnonymousRpcMethod(name: string): boolean;
 //#endregion
-export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MCP_ROUTE, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };
+export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_SSE_ROUTE, DEVFRAME_SSE_SESSION_HEADER, DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };

package/dist/constants.mjs

@@ -1,7 +1,4 @@
 //#region src/constants.ts
-const DEVFRAME_MOUNT_PATH = "/__devframe/";
-const DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH = "/__devframe";
-const DEVFRAME_DIRNAME = "__devframe";
 const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 /**
 * Global key holding the serializable connection prepared by
@@ -16,7 +13,23 @@ const DEVFRAME_CONNECTION_KEY = "__DEVFRAME_CONNECTION__";
 * both HTTP and WS, and a host server (Vite, etc.) can mount the WS upgrade
 * handler here without colliding with its own routes (HMR, asset serving).
 */
-const DEVFRAME_WS_ROUTE = "__devframe_ws";
+const DEVFRAME_WS_ROUTE = "__ws";
+/**
+* Route the SSE RPC endpoint is bound to, relative to a devframe's base
+* path. A single method-dispatched route: `GET` opens the event stream
+* (server→client), `POST` carries RPC frames (client→server). Sits next to
+* `__connection.json` so the deployed SPA reaches it on the same origin it
+* loaded from — the transport for hosts and proxies where the WebSocket
+* upgrade isn't available.
+*/
+const DEVFRAME_SSE_ROUTE = "__sse";
+/**
+* Request header carrying the SSE session id on every RPC `POST`. The
+* server mints the id as the stream's first event (`event: session`);
+* the client echoes it here so the POST joins that stream's birpc
+* channel. Mirrors birpc's own SSE helpers for wire compatibility.
+*/
+const DEVFRAME_SSE_SESSION_HEADER = "x-birpc-session";
 /**
 * Route the Streamable-HTTP MCP endpoint is bound to, relative to a
 * devframe's base path. Sits next to `__connection.json` and the WS route
@@ -68,11 +81,11 @@ const ANONYMOUS_RPC_PREFIX = "anonymous:";
 /**
 * Whether `name` is callable before a connection is trusted, i.e. it starts
 * with {@link ANONYMOUS_RPC_PREFIX}. Used by the resolver gate in
-* `startHttpAndWs` (via an `authorize` function) and by host adapters that
+* the RPC server binding (via an `authorize` function) and by host adapters that
 * implement their own transport.
 */
 function isAnonymousRpcMethod(name) {
 	return name.startsWith(ANONYMOUS_RPC_PREFIX);
 }
 //#endregion
-export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MCP_ROUTE, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };
+export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_KEY, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MCP_ROUTE, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_SSE_ROUTE, DEVFRAME_SSE_SESSION_HEADER, DEVFRAME_VIEWER_ORIGIN_QUERY_PARAM, DEVFRAME_VIEWER_ORIGIN_TOKEN_QUERY_PARAM, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };

package/dist/{context-CBg8iRbQ.mjs → context-C33rR7n0.mjs}

@@ -1,5 +1,5 @@
 import { n as randomToken } from "./crypto-token-XCqTSMg9.mjs";
-import { t as createStorage } from "./storage-CTNVbuFB.mjs";
+import { t as createStorage } from "./storage-BcmVEJRc.mjs";
 import { n as revokeAuthToken, t as revokeActiveConnectionsForToken } from "./revoke-DZbJ7Cl0.mjs";
 import { join } from "pathe";
 //#region src/node/hub-internals/context.ts

package/dist/{context-DoSozfvx.d.mts → context-CSCwoABx.d.mts}

@@ -1,4 +1,4 @@
-import { b as DevframeNodeContext, ht as SharedState } from "./devframe-mQ4qZAuo.mjs";
+import { gt as SharedState, x as DevframeNodeContext } from "./devframe-Bdd9YXTy.mjs";
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {
   trusted: Record<string, {

package/dist/{host-h3-D2hYZvDK.mjs → context-Du11TLcO.mjs}

@@ -2,242 +2,14 @@ import { t as devframeReporter } from "./diagnostics-reporter-CsIG85Q5.mjs";
 import { t as diagnostics } from "./diagnostics-hwjXp_UV.mjs";
 import { RpcFunctionsCollectorBase } from "./rpc/index.mjs";
 import { defineRpcFunction } from "./index.mjs";
-import { t as diagnostics$1 } from "./diagnostics-D7wM2cwM.mjs";
-import { i as createEventEmitter, n as createSharedState, r as nanoid, t as createStorage } from "./storage-CTNVbuFB.mjs";
+import { t as diagnostics$1 } from "./diagnostics-DLYH5oD3.mjs";
+import { i as createEventEmitter, n as createSharedState, r as nanoid, t as createStorage } from "./storage-BcmVEJRc.mjs";
+import { t as DevframeAgentHost } from "./host-agent-CpbAoqBx.mjs";
 import { defineDiagnostics } from "nostics";
 import { isatty } from "node:tty";
 import { formatWithOptions, inspect } from "node:util";
 import { existsSync } from "node:fs";
 import { join } from "pathe";
-import process$1 from "node:process";
-import { homedir } from "node:os";
-//#region src/node/agent-args.ts
-/**
-* Map the args payload an agent surface receives (MCP sends an object
-* keyed `arg0`/`arg1`/…, matching the schema the adapter advertises) onto
-* a handler's positional parameters. Shared by the agent host's RPC
-* bridge and the hub's command-derived tools so the coercion cannot
-* drift between them.
-*
-* - an array passes through as-is
-* - `null`/`undefined` become a zero-argument call
-* - with declared schemas, each schema reads its own `argN` key, in order
-* - without schemas, `arg0`/`arg1`/… keys are collected when present
-* - an empty object becomes a zero-argument call
-* - anything else follows the {@link AgentArgsFallback}
-*
-* @experimental
-*/
-function coerceAgentPositionalArgs(args, schemas, fallback = "wrap") {
-	if (Array.isArray(args)) return args;
-	if (args === void 0 || args === null) return [];
-	if (typeof args === "object") {
-		const obj = args;
-		if (schemas && schemas.length) return schemas.map((_, i) => obj[`arg${i}`]);
-		if ("arg0" in obj) {
-			const out = [];
-			let i = 0;
-			while (`arg${i}` in obj) {
-				out.push(obj[`arg${i}`]);
-				i++;
-			}
-			return out;
-		}
-		if (Object.keys(obj).length === 0) return [];
-	}
-	return fallback === "drop" ? [] : [args];
-}
-//#endregion
-//#region src/node/host-agent.ts
-/**
-* Framework-neutral host aggregating the agent-exposed surface of a
-* devframe. Auto-discovers RPC functions with an `agent` field from
-* `ctx.rpc.definitions`, and accepts plugin-registered tools /
-* resources via `registerTool` / `registerResource`.
-*
-* @experimental
-*/
-var DevframeAgentHost = class {
-	context;
-	events = createEventEmitter();
-	tools = /* @__PURE__ */ new Map();
-	resources = /* @__PURE__ */ new Map();
-	providers = /* @__PURE__ */ new Set();
-	_rpcUnsubscribe;
-	constructor(context) {
-		this.context = context;
-		this._rpcUnsubscribe = context.rpc.onChanged(() => {
-			this.events.emit("agent:manifest:changed");
-		});
-	}
-	registerTool(input) {
-		this._validateToolId(input.id);
-		const tool = this._projectTool(input);
-		this.tools.set(tool.id, {
-			tool,
-			handler: input.handler
-		});
-		this.events.emit("agent:tool:registered", tool);
-		this.events.emit("agent:manifest:changed");
-		return { unregister: () => this.unregisterTool(tool.id) };
-	}
-	unregisterTool(id) {
-		const existed = this.tools.delete(id);
-		if (existed) {
-			this.events.emit("agent:tool:unregistered", id);
-			this.events.emit("agent:manifest:changed");
-		}
-		return existed;
-	}
-	registerToolProvider(provider) {
-		this.providers.add(provider);
-		this.events.emit("agent:manifest:changed");
-		const notifyChanged = () => {
-			if (this.providers.has(provider)) this.events.emit("agent:manifest:changed");
-		};
-		return {
-			notifyChanged,
-			unregister: () => {
-				if (this.providers.delete(provider)) this.events.emit("agent:manifest:changed");
-			}
-		};
-	}
-	registerResource(input) {
-		if (this.resources.has(input.id)) throw diagnostics$1.DF0016({ id: input.id });
-		const resource = {
-			id: input.id,
-			name: input.name,
-			description: input.description,
-			mimeType: input.mimeType ?? "application/json",
-			uri: input.uri ?? `devframe://resource/${encodeURIComponent(input.id)}`
-		};
-		this.resources.set(resource.id, {
-			resource,
-			read: input.read
-		});
-		this.events.emit("agent:resource:registered", resource);
-		this.events.emit("agent:manifest:changed");
-		return { unregister: () => this.unregisterResource(resource.id) };
-	}
-	unregisterResource(id) {
-		const existed = this.resources.delete(id);
-		if (existed) {
-			this.events.emit("agent:resource:unregistered", id);
-			this.events.emit("agent:manifest:changed");
-		}
-		return existed;
-	}
-	list() {
-		const rpcTools = this._collectRpcTools();
-		const plainTools = Array.from(this.tools.values()).map((t) => t.tool);
-		const resources = Array.from(this.resources.values()).map((r) => r.resource);
-		const seen = new Set([...rpcTools, ...plainTools].map((t) => t.id));
-		const providerTools = [];
-		for (const { tool } of this._collectProviderTools()) {
-			if (seen.has(tool.id)) continue;
-			seen.add(tool.id);
-			providerTools.push(tool);
-		}
-		return {
-			tools: [
-				...rpcTools,
-				...plainTools,
-				...providerTools
-			],
-			resources
-		};
-	}
-	getTool(id) {
-		const plain = this.tools.get(id);
-		if (plain) return plain.tool;
-		const rpc = this._collectRpcTools().find((t) => t.id === id);
-		if (rpc) return rpc;
-		return this._collectProviderTools().find((t) => t.tool.id === id)?.tool;
-	}
-	getResource(id) {
-		return this.resources.get(id)?.resource;
-	}
-	async invoke(id, args) {
-		const plain = this.tools.get(id);
-		if (plain?.handler) return await plain.handler(args);
-		const rpcDef = this._findRpcDefinition(id);
-		if (rpcDef) {
-			const positional = coerceAgentPositionalArgs(args, rpcDef.args, "wrap");
-			return await this.context.rpc.invokeLocal(id, ...positional);
-		}
-		const provided = this._collectProviderTools().find((t) => t.tool.id === id);
-		if (provided) return await provided.input.handler(args);
-		throw new Error(`[devframe/agent] tool "${id}" not found`);
-	}
-	async read(id) {
-		const entry = this.resources.get(id);
-		if (!entry) throw new Error(`[devframe/agent] resource "${id}" not found`);
-		return await entry.read();
-	}
-	/** @internal */
-	_dispose() {
-		this._rpcUnsubscribe?.();
-		this._rpcUnsubscribe = void 0;
-	}
-	_validateToolId(id) {
-		if (this.tools.has(id)) throw diagnostics$1.DF0015({ id });
-		if (this.context.rpc.definitions.get(id)?.agent) throw diagnostics$1.DF0015({ id });
-	}
-	_projectTool(input) {
-		if (!input.description || typeof input.description !== "string") throw diagnostics$1.DF0014({ name: input.id });
-		return {
-			id: input.id,
-			kind: "tool",
-			title: input.title ?? input.id,
-			description: input.description,
-			safety: input.safety ?? "action",
-			tags: input.tags,
-			args: input.args,
-			inputSchema: input.inputSchema,
-			outputSchema: input.outputSchema,
-			examples: input.examples
-		};
-	}
-	/** Query every registered provider, projecting inputs to serializable tools. */
-	_collectProviderTools() {
-		const out = [];
-		for (const provider of this.providers) for (const input of provider()) out.push({
-			input,
-			tool: this._projectTool(input)
-		});
-		return out;
-	}
-	_collectRpcTools() {
-		const out = [];
-		for (const [name, def] of this.context.rpc.definitions) {
-			const agent = def.agent;
-			if (!agent) continue;
-			if (!agent.description || typeof agent.description !== "string") throw diagnostics$1.DF0014({ name });
-			const type = def.type ?? "query";
-			const safety = agent.safety ?? inferSafety(type);
-			out.push({
-				id: name,
-				kind: "rpc",
-				title: agent.title ?? name,
-				description: agent.description,
-				safety,
-				tags: agent.tags,
-				rpcName: name,
-				examples: agent.examples
-			});
-		}
-		return out;
-	}
-	_findRpcDefinition(id) {
-		const def = this.context.rpc.definitions.get(id);
-		if (def?.agent) return def;
-	}
-};
-function inferSafety(type) {
-	if (type === "static" || type === "query") return "read";
-	return "action";
-}
-//#endregion
 //#region src/node/host-diagnostics.ts
 var DevframeDiagnosticsHost = class {
 	context;
@@ -1217,7 +989,7 @@ const debugBroadcast = createDebug("devframe:rpc:broadcast");
 * Concrete implementation backing `ctx.rpc`. Internal: consumers should
 * depend on the structural {@link RpcFunctionsHost} type, never this class.
 * Its `@internal` members (`_rpcGroup`, `_asyncStorage`,
-* `_emitSessionDisconnected`) are wired by `startHttpAndWs` and must not
+* `_emitSessionDisconnected`) are wired by `createContextRpcServer` and must not
 * widen the public surface.
 *
 * @internal
@@ -1550,26 +1322,4 @@ async function createHostContext(options) {
 	return context;
 }
 //#endregion
-//#region src/node/host-h3.ts
-/**
-* h3-backed {@link DevframeHost} — used by the standalone CLI adapter.
-*/
-function createH3DevframeHost(options) {
-	const workspaceRoot = options.workspaceRoot ?? process$1.cwd();
-	return {
-		mountStatic(base, distDir) {
-			return options.mount?.(base, distDir);
-		},
-		resolveOrigin() {
-			return options.origin;
-		},
-		getStorageDir(scope) {
-			const namespace = `.${options.appName}/devframe`;
-			if (scope === "workspace") return join(workspaceRoot, ".devframe");
-			if (scope === "project") return join(workspaceRoot, "node_modules", namespace);
-			return join(homedir(), namespace);
-		}
-	};
-}
-//#endregion
-export { DevframeViewHost as a, createRpcSharedStateServerHost as c, coerceAgentPositionalArgs as d, createNodeSettings as i, DevframeDiagnosticsHost as l, createHostContext as n, DevframeServicesHostImpl as o, createScopedNodeContext as r, createRpcStreamingServerHost as s, createH3DevframeHost as t, DevframeAgentHost as u };
+export { createHostContext as t };

package/dist/dev-BEveeA5H.mjs

@@ -0,0 +1,233 @@
+import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
+import { t as diagnostics } from "./diagnostics-DLYH5oD3.mjs";
+import { t as createHostContext } from "./context-Du11TLcO.mjs";
+import { i as resolveMcpConnectionMeta, n as resolveBasePath, r as resolveDevServerPort, t as normalizeBasePath } from "./_shared-CttmCMBi.mjs";
+import { t as createH3DevframeHost } from "./host-h3-CzCZwtuV.mjs";
+import { i as normalizeHttpServerUrl, n as resolveInstanceRegister, t as createInstanceShell } from "./instance-shell-KRdee1QF.mjs";
+import { t as open } from "./open-Dz4V4irZ.mjs";
+import { mountStaticHandler } from "./utils/serve-static.mjs";
+import { createServer } from "node:http";
+import { resolve } from "pathe";
+import process from "node:process";
+import { joinURL, withBase } from "ufo";
+import { H3, toNodeHandler } from "h3";
+//#region src/adapters/initiate.ts
+const INSTANCE_INTERNALS = /* @__PURE__ */ new WeakMap();
+/** @internal */
+function getInstanceInternals(handler) {
+	return INSTANCE_INTERNALS.get(handler) ?? {};
+}
+/**
+* Serve a devframe through one framework-agnostic, web-standard handler —
+* the SPA, `__connection.json` discovery, the WebSocket RPC endpoint, the
+* auth gate, and the optional MCP route, all under a single mount base.
+* Mount `handler` on any framework's catch-all route (or `nodeMiddleware` on
+* a connect stack) and the devframe is live inside that app.
+*
+* The factory is synchronous and kicks off initialization eagerly;
+* `handler`/`nodeMiddleware` await readiness internally. Nothing binds a port
+* on its own: the WebSocket resolves in precedence order — `ws.port` (pinned
+* side-car) > `server` (shared upgrade at `<base>__ws`) > `ws.sidecar`
+* (auto-port side-car) > the host driving upgrades itself through
+* {@link DevframeInstance.attach} — while `ws.url`, when set, overrides the
+* advertised* endpoint (the tunnel pattern) and on its own hands the whole
+* transport to an external server. `__connection.json` reflects whichever
+* combination is active.
+*/
+function initDevframe(def, options) {
+	const base = normalizeBasePath(options.base);
+	const distDir = options.distDir === false ? void 0 : options.distDir ?? def.cli?.distDir;
+	const app = options.app ?? new H3();
+	const shell = createInstanceShell({
+		base,
+		app,
+		host: options.host ?? def.cli?.host ?? "localhost",
+		origin: options.origin,
+		auth: options.auth !== void 0 ? options.auth : def.cli?.auth,
+		server: options.server,
+		ws: options.ws ?? def.cli?.ws,
+		sse: options.sse ?? def.cli?.sse,
+		allowedOrigins: options.allowedOrigins,
+		destroyUnmatchedUpgrades: options.destroyUnmatchedUpgrades,
+		onPeerConnect: options.onPeerConnect,
+		onPeerDisconnect: options.onPeerDisconnect,
+		register: resolveInstanceRegister(options.register, {
+			id: def.id,
+			name: def.name
+		}),
+		resolveSidecarPort: (sidecarHost) => resolveDevServerPort(def, { host: sidecarHost }),
+		onMetaUnavailable: () => {
+			throw diagnostics.DF0054({ id: def.id });
+		},
+		async init(api) {
+			const h3Host = createH3DevframeHost({
+				origin: () => api.origin() ?? "http://localhost",
+				appName: def.id,
+				mount: (mountBase, dir) => {
+					mountStaticHandler(app, mountBase, dir);
+				}
+			});
+			const hostImpl = options.getStorageDir ? {
+				...h3Host,
+				getStorageDir: options.getStorageDir
+			} : h3Host;
+			const context = await createHostContext({
+				cwd: process.cwd(),
+				mode: "dev",
+				host: hostImpl
+			});
+			const setupInfo = { flags: options.flags ?? {} };
+			await def.setup(context, setupInfo);
+			const mcpOption = options.mcp ?? def.cli?.mcp;
+			const mcpMeta = resolveMcpConnectionMeta(def, mcpOption);
+			let mcpDispose;
+			if (mcpMeta) {
+				const mcpConfig = mcpOption === true || mcpOption === void 0 ? {} : mcpOption;
+				const mcpPath = joinURL(base, mcpMeta.path);
+				let mountMcpHttp;
+				try {
+					({mountMcpHttp} = await import("./http-DLr_cJZ7.mjs").then((n) => n.t));
+				} catch (error) {
+					const reason = error instanceof Error ? error.message : String(error);
+					throw diagnostics.DF0017({
+						transport: "http",
+						reason,
+						cause: error
+					});
+				}
+				mcpDispose = mountMcpHttp(app, context, mcpPath, {
+					serverName: `${def.id} (devframe)`,
+					serverVersion: def.version ?? "0.0.0",
+					exposeSharedState: true,
+					allowedOrigins: mcpConfig.allowedOrigins
+				}).dispose;
+			}
+			return {
+				context,
+				...mcpMeta ? { mcp: mcpMeta } : {},
+				...mcpDispose ? { dispose: mcpDispose } : {}
+			};
+		},
+		mount(_context, meta) {
+			app.use(joinURL(base, DEVFRAME_CONNECTION_META_FILENAME), () => meta);
+			if (distDir) mountStaticHandler(app, base, resolve(distDir));
+		}
+	});
+	const instance = {
+		base: shell.base,
+		handler: shell.handler,
+		nodeMiddleware: shell.nodeMiddleware,
+		attach: shell.attach,
+		handleUpgrade: shell.handleUpgrade,
+		ready: shell.ready,
+		context: shell.context,
+		connectionMeta: shell.connectionMeta,
+		close: shell.close
+	};
+	INSTANCE_INTERNALS.set(instance, shell.internals);
+	return instance;
+}
+//#endregion
+//#region src/adapters/dev.ts
+/**
+* Start a devframe dev server for a {@link DevframeDefinition} —
+* h3 + WebSocket RPC + (optionally) the author's SPA mounted at the
+* resolved base path.
+*
+* When `distDir` is omitted (and `def.cli?.distDir` is unset) the
+* server runs in **bridge mode**: only `__connection.json` and the WS
+* endpoint are mounted, with no SPA mount. The SPA is expected to be
+* hosted elsewhere (e.g. by a parent Vite/Nuxt dev server) — see
+* `viteDevBridge({ devMiddleware })`.
+*
+* Returns the underlying {@link StartedServer} handle so callers can
+* close it gracefully (SIGINT, hot-reload, test teardown).
+*
+* Use this directly when integrating devframe into an existing CLI
+* framework (commander, yargs, hand-rolled CAC). For the all-in-one
+* `dev` / `build` / `mcp` shell, reach for {@link createCac} instead.
+*/
+async function createDevServer(def, options = {}) {
+	const host = options.host ?? def.cli?.host ?? "localhost";
+	const requestedPort = options.port ?? await resolveDevServerPort(def, { host });
+	const flags = options.flags ?? {};
+	const basePath = options.basePath ? normalizeBasePath(options.basePath) : resolveBasePath(def, "standalone");
+	const app = options.app ?? new H3();
+	const server = createServer(toNodeHandler(app));
+	try {
+		await new Promise((resolveListen, rejectListen) => {
+			const onError = (error) => rejectListen(error);
+			server.once("error", onError);
+			server.listen(requestedPort, host, () => {
+				server.removeListener("error", onError);
+				resolveListen();
+			});
+		});
+	} catch (error) {
+		throw diagnostics.DF0052({
+			host,
+			port: requestedPort,
+			reason: error instanceof Error ? error.message : String(error),
+			cause: error
+		});
+	}
+	const address = server.address();
+	const port = typeof address === "object" && address ? address.port : requestedPort;
+	const origin = normalizeHttpServerUrl(host, port);
+	const devframe = initDevframe(def, {
+		base: basePath,
+		distDir: options.distDir,
+		app,
+		server,
+		host,
+		origin,
+		ws: options.ws,
+		sse: options.sse,
+		auth: flags.auth === false ? false : options.auth,
+		mcp: options.mcp,
+		flags,
+		onPeerConnect: options.onPeerConnect,
+		onPeerDisconnect: options.onPeerDisconnect,
+		register: true,
+		destroyUnmatchedUpgrades: true
+	});
+	try {
+		await devframe.ready;
+	} catch (error) {
+		await new Promise((resolveClose) => server.close(() => resolveClose()));
+		throw error;
+	}
+	const internals = getInstanceInternals(devframe);
+	const transport = internals.started;
+	await options.onReady?.({
+		origin,
+		port,
+		app
+	});
+	await maybeOpenBrowser(def, flags, `${origin}${basePath}`, options.openBrowser, internals.authHandler);
+	return {
+		origin,
+		port,
+		app,
+		ws: transport.ws,
+		rpcGroup: transport.rpcGroup,
+		connectionMeta: transport.connectionMeta,
+		async close() {
+			await devframe.close();
+			await new Promise((resolveClose) => server.close(() => resolveClose()));
+		}
+	};
+}
+async function maybeOpenBrowser(def, flags, origin, override, authHandler) {
+	const flagsOpen = flags.open;
+	const cliOpen = def.cli?.open;
+	const resolved = override ?? flagsOpen ?? cliOpen;
+	if (resolved === void 0 || resolved === false) return;
+	const target = typeof resolved === "string" ? withBase(resolved, origin) : origin;
+	const authorizedTarget = authHandler?.buildOpenUrl?.(target) ?? target;
+	try {
+		await open(authorizedTarget);
+	} catch {}
+}
+//#endregion
+export { getInstanceInternals as n, initDevframe as r, createDevServer as t };